C64 Doors

Draft — This document was generated by AI and may not have been reviewed for accuracy.

C64 Doors are WebDoors that run Commodore 64 programs inside a jsc64 emulator embedded directly in the browser. They require no additional server-side components beyond PHP — no bridge, no DOSBox, no Node.js.

Table of Contents

• How It Works
• Creating a C64 Door
  • File Structure
  • index.php
  • webdoor.json
• Supported File Types
• Configuration Reference
• D64 Disk Images
• Enabling the Door

---

How It Works

Each C64 Door is a WebDoor whose index.php includes the shared _c64engine/player.php template. The engine:

1. Authenticates the user and checks the door is enabled.
2. Reads the game file (PRG, ROM, BIN, or D64) from the door's directory.
3. Base64-encodes the program bytes and embeds them directly in the HTML page.
4. Boots the jsc64 C64 emulator (Kernal, BASIC, and Character ROMs are in public_html/vendor/jsc64/js/assets/).
5. After the 2-second BASIC boot, writes the program bytes into emulated memory and executes them.

No API calls are made at runtime — the program data travels with the page load.

---

Creating a C64 Door

File Structure

public_html/webdoors/
└── mygame/
    ├── webdoor.json    ← door manifest
    ├── index.php       ← sets $c64Config, includes the engine
    └── mygame.prg      ← the game (or .d64, .rom, .bin)

Copy public_html/webdoors/_c64example/ as a starting point, rename the folder to your game's slug, and replace game.prg with your actual file.

index.php

<?php
$c64Config = [
    'door_id' => 'mygame',        // must match webdoor.json "id"
    'title'   => 'My C64 Game',   // shown in the loading spinner
    'prg'     => 'mygame.prg',    // file in the same directory as index.php
];
require __DIR__ . '/../_c64engine/player.php';

That's the entire index.php. The engine resolves prg relative to the door's own directory automatically.

webdoor.json

{
    "webdoor_version": "1.0",
    "game": {
        "id": "mygame",
        "name": "My C64 Game",
        "version": "1.0",
        "author": "Author Name",
        "description": "Short description shown in the games list.",
        "entry_point": "index.php"
    },
    "requirements": {
        "min_host_version": "1.0",
        "features": []
    },
    "config": {
        "credits_cost_per_session": 0
    }
}

game.id must match door_id in index.php. The folder name is conventionally the same value.

---

Supported File Types

The engine detects the file type from the extension and handles it automatically:

Extension	Handling
.prg	Standard C64 PRG — reads the 2-byte load address from the file header
.p00	P00 container — strips 26-byte header, then reads as PRG
.d64	C64 floppy disk image — extracts PRG files; loads the first one by default
.rom	Raw cartridge ROM — loaded at $8000 (32768)
.bin	Raw binary — loaded at $8000 (32768)
other	Treated as PRG (2-byte header read)

Use load_address in $c64Config to override the default for any extension (see Configuration Reference).

---

Configuration Reference

All keys for $c64Config:

Key	Type	Required	Description
door_id	string	Yes	Door identifier — must match webdoor.json id
title	string	Yes	Game title shown in the loading spinner
prg	string	One of these	Filename of a PRG/ROM/BIN in the door's directory
d64	string	One of these	Filename of a D64 in the door's directory
prg_path	string	One of these	Absolute path to a PRG/ROM/BIN
d64_path	string	One of these	Absolute path to a D64
prg_name	string	No	PRG name to auto-select from a D64 (default: first entry)
load_address	int	No	Override load address; file loaded as raw binary with no header

prg vs prg_path: Use prg for files that live next to index.php — it's the shortest form. Use prg_path only when the file lives outside the door's directory.

load_address example — loading a cartridge at a non-standard address:

$c64Config = [
    'door_id'      => 'mygame',
    'title'        => 'My Game',
    'prg'          => 'mygame.rom',
    'load_address' => 0xC000,   // override auto-detected \$8000 default
];

---

D64 Disk Images

A D64 door can contain a whole floppy's worth of programs. By default the engine loads the first PRG found in the disk directory. Use prg_name to select a specific one:

$c64Config = [
    'door_id'  => 'mygame',
    'title'    => 'My Game',
    'd64'      => 'mygame.d64',
    'prg_name' => 'LOADER',   // exact name as it appears in the D64 directory
];

PRG names in D64 images are uppercase — check them using the file preview in the BBS file browser, which shows the disk directory.

A .d64 file may also be passed via the prg key; the engine recognises the extension and handles it correctly.

---

Enabling the Door

C64 Doors are WebDoors and go through the same activation flow:

1. Drop the door folder into public_html/webdoors/.
2. In the BBS admin panel go to WebDoors and click Refresh.
3. Find the new door in the list and click Enable.
4. Adjust credits cost if desired and save.

The door will appear in the WebDoors section of the BBS for all logged-in users.