The manual

#What it is

A door game was a program a bulletin board ran for a caller. The board answered the modem and took the caller's name, and when the caller picked a game from the menu, it handed the line to the door program along with a small text file saying who was calling. From there the door drew its screens down the modem line, and each caller played a few minutes a day against everyone else who called, until the game ended and the board took the line back.

The games kept their worlds in plain files beside the program.

ATO Doors is that board with only the doors left in it, the message bases gone and the file areas with them. No chat. What's left is a lobby full of games and an account to play them with, and everything that made a door game a door game is still here:

• The game is the original program its author shipped, byte for byte. ATO never patches a door.
• Each player gets a node and a daily allowance of minutes, and the door finds the player's name in a drop file, exactly as it expects.
• Where a door was written for it, several players can be in at once, each on their own node, all sharing the one world the game keeps in its files.
• The daily maintenance a door asks for runs once a day, the way a board's nightly event did.

You bring your own doors, as you always did. ATO ships none. Nothing installs on your computer or a player's, and no hosted service sits in the middle, since the site runs on hosting you already have.

#How it works

The machine is the browser. When a player opens a door, their browser boots a small FreeDOS machine right there on the page: the v86 emulator, booting a 1.4 MB floppy. A network drive, D:, brings the door's files to that machine, and the server serves it file by file. The game runs on the player's own processor, and its screen is drawn into a terminal on the page, exactly as a caller's terminal drew it over a modem.

The server holds the files and keeps score. Nothing DOS ever runs on it: PHP serves the door's files to the machines, takes their writes back, holds the record locks that keep two players from writing the same record at once, hands out nodes and minutes, and keeps the books. That's why it runs on shared hosting: all it needs is PHP and a cron tick, and the database is one file.

One live world per door. The first time anyone enters a door, ATO copies the door's files into a live directory under data/, and from then on that directory is the world, read and written by every player's machine over the drive. Program files, the .EXE and the rest you declare as static, are cached in the browser and never written, while the data files flow both ways.

Nodes. Each door hands out node numbers from 1 up to the count you allow for it. A player's machine gets its node in the drop file and in %NODE% on the command line, so a door that keeps one file per node keeps them apart. Your own machine, run from the panel, is node 0, and it never counts against the players' seats.

Minutes. Every door has a daily allowance of minutes per player, from its manifest or from your override, counting the time a seat is open. When it runs out, that door won't open again for the player until the site's day turns at midnight in your time zone, though the sysop has no limit.

The day. The site has a time zone, set at install and changeable on the Site page. Midnight there is when the daily minutes reset and a door's daily maintenance falls due, and since the DOS machines keep that clock too, a game's own idea of “today” agrees with yours.

The daily maintenance. Some doors need a program run once a day: TradeWars' EXTERN, say, or Usurper's sweep. LORD runs its own, and since nothing DOS runs on the server, each of these programs runs in a browser. The first player of the day runs a short sweep on the way in, and you run a long one from the panel's Night page (chapter 9 has the whole story).

When a door ends. The game quits, the machine drains its last writes to the server, the seat closes, and the player lands back on the door's page. A player who closes the tab mid-game has simply dropped carrier. The seat and its locks are freed within a minute and a half, and the minutes go on the ledger.

#What you need

On the host:

• PHP 8.1 or newer, with four things almost every shared host has: the PDO SQLite driver, the usual string functions, JSON and the zip extension. The installer checks for each one and says what's missing.
• A web server that serves .wasm files (the machine's CPU) as ordinary static files and honors the deny rule ATO plants in data/, which Apache with mod_rewrite, the common case, does as is.
• An outgoing mail account (SMTP), since new players confirm their address by email and the site writes to you when a door misses its maintenance.
• A cron job, every five minutes: every cPanel host has one, and the installer prints the exact line.
• HTTPS, which is optional. Without it, passwords and session cookies travel in the clear, and the Full screen keyboard lock only works on a secure page.

For players: a current desktop browser (Chrome, Edge, Firefox, Safari) and a keyboard. A phone will do for a look around; for play, a door wants eighty columns and real keys.

Disk and memory are small. The site is about a megabyte, and the database is a single SQLite file. Doors add their own.

#Installing

1. Unzip the package and upload the contents of its one folder, atodoors/, to where the site should live, either the root of a domain or a folder such as /atodoors/; from here on, that folder, the one holding index.php, is “the install”.
2. Check the two folders: data/ must be writable by PHP, which 755 or 775 does on nearly every host, and doors/ has to exist. The package carries both.
3. Open install.php in the browser. The environment check comes first: the PHP version, the extensions, whether data/ can be written, and whether the machine's files are in place, each line green or saying what to fix.
4. Name the site and its sysop: site name, tagline, your handle, your email and password, the time zone, and the site URL, which the installer guesses. Check it, since every link in every letter is built from it.
5. Set up outgoing mail (SMTP server, port, security, login, password and the From address), and the installer sends a test letter before it goes on, since new players can't confirm their address without mail.
6. Schedule the cron job. The last page gives the addresses of the lobby and the panel, with the cron line under them: paste that line into your host's scheduler now. It looks like this:

   */5 * * * * php /home/you/public_html/atodoors/cron.php key=...

   If your host's scheduler can only fetch a URL, the page shows the URL form too. The key is yours. The Site page shows it again.
7. Bring a door: install one (chapter 6), then press Scan on the panel's Doors page.

Once it's installed, install.php refuses to run again, so to start over from nothing, delete data/config.php first.

#Updating

An update is an overlay. Unzip the new package and upload the contents of its atodoors/ folder over the install, replacing files. Nothing else to do.

• data/ is yours: the database, every setting, your words and art, the live game worlds and the snapshots, none of it carried by the package except the deny rule, which is the same in every version.
• doors/ is yours too. The package brings back only the README that lives in it.
• The first page view after the upload brings the database up to the new version's schema by itself.
• Every stylesheet and script is linked with its file time in the address, so browsers fetch the new ones and keep caching the rest. When the boot floppy changes, each player's first entry after the update fetches it again, once per browser.

The installer won't run again on an installed site, so uploading it again does no harm.

#Installing doors

Where

Each door is its own folder in doors/, right off the install: doors/lord/ for Legend of the Red Dragon, say, or doors/usurper/ for Usurper. Never put a door anywhere under data/, because that's where ATO keeps the live worlds, and the Doors and Machine pages print that path only so you know where the live world is.

What

It holds two things:

doors/lord/
  dosdoor.json        the manifest
  files/              the game, exactly as it came

files/ is the door's own directory, exactly as you'd have installed it on a DOS board, with the program, its data files, its batch files and its configuration, plus anything you'd have written yourself for the board, such as a node file or a .CFG. ATO never changes a file in it.

The manifest

dosdoor.json is the same manifest ATDT BBS uses, so every door package made for ATDT installs here unchanged, and a manifest written here works there. A complete one:

{
  "api": 1,
  "slug": "lord",
  "title": "Legend of the Red Dragon",
  "command": "CALL START.BAT %NODE%",
  "dropfile": "DOOR.SYS",
  "static": ["*.EXE", "*.OVR", "*.DOC"],
  "session": ["TEMP*.*"],
  "max_nodes": 4,
  "minutes": 45,
  "maintenance": "",
  "jit": "on",
  "comport": 1,
  "blurb": "The dragon in the forest. Fight, flirt, and sleep in the inn.",
  "author": "Seth Able Robinson",
  "year": "1995",
  "maintenance_minutes": 0,
  "presets": [{"label": "LORDCFG", "command": "LORDCFG.EXE"}],
  "clear_when_empty": []
}

Key by key:

The rest are ATO's own. ATDT ignores them, and every one of them is easier to set on the Doors page.

Scan

Once the folder is in place, open the panel's Doors page and press Scan, and every folder with a valid manifest is registered. The page lists the doors it found new or changed, and names any it refused, with the reason. New doors register open. If you don't want players in one while you set it up, Close it on the Doors page.

Sorting a door's files

The rule of thumb: anything the game only ever reads is static, which means the program, its overlays, text screens and documentation. Anything it writes is data, and it goes over the wire, while a file it writes for one node and never shares is a session file.

When in doubt, leave a file out of both the static and the session lists. It will just travel over the wire every time, which is correct, only slower.

Doors with several players

A door that lets several players in at once must use DOS record locking. Every multi-node door did. ATO holds the locks on the server, and closing a file releases them. Sharing modes on open (SHARE) aren't enforced, so a door that relied on SHARE alone to keep two writers apart needs a lower node count.

Start a new door at one or two players, and play it with a friend. Raise it once it holds.

Recipes

For the doors the project knows, a recipe ships with ATO: what to put in files/, the quirks, the proven node count, how long the maintenance takes, and the one-click commands for the Machine page. The Doors page shows the matching recipe's card beside a door's settings. Recipes are optional. A manifest is all Scan asks for, and ATO 1.0.0 ships two recipes, one for Legend of the Red Dragon 4.07 and one for Usurper 0.24 (chapter 13 has what each says).

The live world

The first time anyone enters a door, files/ is copied to data/doorstore/dos/<slug>/, and from then on that copy is the world. Edit a file in files/ after that, and the game won't see it until you press Reset on the Doors page, which wipes the world and copies files/ again, taking every player's progress with it.

To change one line of a live config file without a Reset, use the Files page, which edits the world directly and keeps a dated copy of what it changed.

#The sysop panel

The panel is at admin/ under the install, and only the sysop account opens it.

The band across the top carries the site's name and the pages as tabs, with a strip of readouts under them that follow you from page to page. They show who's in the doors, the web lines in use, how many doors are open, the night's state, the cron job's last tick, and whether mail is set. Each readout is a lamp and a few words, and it links to its page. Green is live and red is a fault. Amber means it's waiting on someone.

#The player's side

Registering. A visitor picks a handle and a password, with the house rules right there on the form. The site sends a confirmation letter to the email address they give, and the account stays pending until someone presses the button in it. A player who lost the letter can ask for another, and you can also open an account by hand on the Accounts page.

The lobby. It opens with the masthead (your art or the site's name) and your welcome, and the doors come next, as cards. A card shows the title, blurb, author and year, and who's in it right now, or else what a closed door's card says. Below them sit who's on the line now and the last callers (members only, and hidden from visitors when the privacy switch is on), with your news last of all. The About page carries your About text and the house rules.

A door's page. The door's art, its blurb, your signed note, the rules of the house, who's in it now, and Play. A door closed to this player says why.

Playing. The play page is a terminal with a status line that shows the door, the player's node, the minutes left today, and how many are in the door right now. When the line opens, with the modem ceremony if it's on, the machine boots. On the first entry the game fetches, and a big door can take half a minute, though later entries are quick, since the program is cached; then the door greets the player as it greeted a caller.

The Keys card says what the keys do:

• Type as at a terminal. Arrow keys and Tab go to the door, but function keys don't, since none ever crossed a modem line.
• Paste types what was pasted, and dragging on the screen copies.
• Leave through the game's own quit so it saves. Ctrl+] three times drops carrier, the old-fashioned way, and the Hang up button does the same.
• Full screen hands the browser's own chords (Ctrl+W, Ctrl+T) to the game. Hold Esc to leave it.
• On a touch screen, a key row under the terminal carries Esc, the arrows, Tab and Enter, and the soft keyboard types into the door.

When the game ends, the page says it's saving, waits for the machine to finish its writes, says goodbye and returns to the door's page. One player can hold one line at a time, so opening a second door closes the first.

The account page. A player can change their password here, or their mailbox, which is confirmed by letter. The location the doors show for them is set here too, and so is the button that deletes the account.

#The Night: daily maintenance

A door's daily maintenance is a console program that rewrites the game's world, aging the players and settling the day's events. It trims the logs, too. On a DOS board it ran as a nightly event at midnight, but ATO has no DOS on the server, so it runs in a browser, on one of two roads you choose for each door.

The first caller's road

The first player of the day to enter the door alone draws the duty. Their machine runs the maintenance command ahead of the game, with the machine's screen mirrored into their terminal so they can watch it and answer a stray prompt, and when the program finishes, the game starts as it always did.

It's right for sweeps of a minute or two, and the Night page's ceiling, 4 minutes by default and up to 60, is the longest sweep this road should carry.

The sysop's road

Only you run it: from the Night page, with Run now, Run everything due now or the Night watch left on duty, or from the Machine page's Run the daily maintenance.

Long sweeps go here. Usurper's takes ten to thirty minutes on a populated world, and TradeWars' EXTERN has no first-caller road at all in the original.

How a run is bracketed

Either way, a snapshot comes first. Then the program runs on the live world with a done sentinel after it, and when the sentinel crosses the line, the day is stamped for that door and the seat ends.

A run can end without the sentinel because the tab closed or the program died. Or the budget runs out. Any of those puts the snapshot back and counts a failure, and after two in a row the Night page says so until you clear it. The machine's last screen goes into the Log, so you can read what the program said before it died.

One machine runs a given door's maintenance at a time: the duty is leased for an hour, and released the moment the seat that holds it is gone.

Cron's part

Nothing DOS runs on the server, so cron never runs maintenance. It keeps the books. It sweeps dead seats and lines, arms the day, warns in the Log when a door has gone a day without its maintenance, and sends you the letter about it when that setting is on.

Without cron the site still plays, but nobody gets told when a door misses its maintenance.

A door that stays silent

A door that stays silent on the Machine page while its maintenance runs is almost always printing on the machine's own screen, which is where a maintenance program talks, and both the Night and Machine pages show it. A game run by hand talks on the door's line, folded under the screen. Open it.

#Security, in plain words

The browser owns the machine

The game runs on the player's computer, so whatever the game can write to its shared files, a determined player can write with the seat's token. ATO fences that in:

• The door's program and configuration files you declare as static are read-only to players.
• Every path a machine asks for is jailed to the door's live directory, and a refusal is a security row in the Log.
• Snapshots and a Reset put a world back.
• The Doors page says all of this in plain words.

A door game's world was never a bank vault. ATO doesn't promise one.

Accounts

Passwords are stored only as hashes, and the letters that confirm an account or reset a password carry one-time links. Every form that changes anything carries a token against cross-site requests, and every terminal request carries a bearer token, issued to a logged-in browser. Logins are throttled after repeated failures, and after too many tries the panel locks for fifteen minutes.

The panel

Only the one account at level 255 opens it. A member who tries is turned away, and the attempt is logged with their address.

data/

Everything the site writes lives in data/, the game worlds included, and the package plants an Apache deny rule there, which the dashboard checks by fetching its own probe file and expecting a refusal.

Drop files

None carries a real password. The game sees a stand-in, and the record number is the account's number.

Bans

Addresses and prefixes are banned on the Site page, and a banned address can't register or log in. It can't open a line.

#Where things live

The install, folder by folder.

index.php, door.php, play.php, about.php     the lobby and the play page
account/                                      register, verify, login, settings, reset
admin/                                        the sysop panel
api.php                                       the terminal's and the machines' endpoint
cron.php                                      the scheduler's entry
install.php, check.php                        the installer and the host check
lib/                                          the site's code
assets/                                       stylesheets, scripts, fonts
machine/                                      the DOS machine: boot floppy, emulator, licenses
recipes/                                      what ATO knows about particular doors
doors/                                        your doors, one folder each
data/                                         yours, written by the site, denied to the web
  config.php                                  the database path and the site's keys
  <site>.sqlite                               the database
  doorstore/dos/<slug>/                       the live worlds
  snapshots/<slug>/                           world snapshots and the Files page's edit copies
  art/                                        the masthead and door art you uploaded
  logs/                                       the web server's view, when the host writes one

#When something goes wrong

Every page answers 500.

Open check.php. Nine times in ten the host is running an old PHP, and the fix is to switch the site to 8.1 or newer in the host's panel. The rest is permissions. Repair sets them.

The installer says the machine's files are missing.

Upload the whole package. machine/ has to come along, all of it.

No door can boot, and the terminal says the runtime didn't load.

The host is refusing .wasm files or serving them with the wrong type, which the dashboard's guards card will confirm, so ask the host to serve application/wasm for .wasm, or add the type in .htaccess yourself:

AddType application/wasm .wasm

New players never get their letter.

Outgoing mail isn't set, or the host blocks the SMTP port. The Site page sends a test letter and says what the server answered, and until mail works, you can open accounts by hand on the Accounts page.

The panel keeps saying the cron job has never run.

Either the scheduler isn't calling cron.php, or it's calling it without the key, so copy the line from the Site page exactly, and if the host's scheduler can only fetch a URL, use the URL form.

A door sits silent after booting.

On the Machine page, open the door's line under the screen, since a game run by hand talks there. If a player reports it, turn diagnostics on for the door and enter it yourself: the machine's DOS screen appears in the corner and usually names a file the door couldn't find. A Turbo Pascal door that hangs with nothing on either screen may need "jit": "off" in its manifest.

The lobby shows no doors.

Nothing is registered, or every door is closed, so press Scan on the Doors page, then Open the ones you want seen.

A maintenance run ends early.

The Night page counts it and puts the snapshot back. The machine's last screen is in the Log as words, with a runtime error's own line if the program printed one.

A sweep longer than the first-caller ceiling belongs on the sysop road. When a sweep always dies at the same step, on a world that has run many nights, the world's data is usually the cause; a Reset from the package files clears it, players included, so take a snapshot first and read the Log before you decide.

A player is stuck “in the door” after closing the tab.

The seat is swept on its own within a minute and a half. The dashboard's Disconnect does it now.

F5 in the middle of a game.

Function keys stay with the page while a door runs, so F5 no longer reloads it and loses the seat the way it once did. When a seat does drop, the game has saved whatever it had written, and the rest of that visit is gone, as it always was when a modem dropped carrier.

#Door packages the project vouches for

Every door package made for ATDT BBS installs here as is, and these two ship with a recipe, brought up on the project's own machines and proven with two players at once in a real browser.

Legend of the Red Dragon 4.07

1. Install the contents of LORD.ZIP into files/.
2. Lay the 4.07 FreeDOS patch over it, so that its LORD.EXE and LORD.OVR replace the originals already in files/.
3. Run the patch's LORDCFG.EXE once from the Machine page: node 1, drop file DOOR.SYS, the path D:\, and Fossil as the port.
4. The command is CALL START.BAT %NODE%, the same as in the manifest in chapter 6.

Two warriors in the forest at once, on nodes 1 and 2: proven.

Usurper 0.24

• The files. The 0.20e full release, with the 0.24 upgrade's 16-bit EDITOR.EXE, EDITOR.OVR, USURPER.EXE, USURPER.OVR and EDITOR32.HLP (beside EDITOR.HLP).
• USURP.CTL needs the FOSSIL keyword and BBSTYPE DOORSYS, or the door talks only to the local screen.
• /X on every command line. It keeps the two-megabyte overlay in memory, and without it the door reads the overlay over the wire hundreds of times a second and never greets.
• The daily maintenance is USURPER.EXE /HMAINT /X (never /FMAINT, which stays in the menu forever), and since it takes ten to thirty minutes, it belongs on the sysop's road.
• Setup. Copy USUTEXT.DAT into DATA\ so the maintenance never stops at a picture prompt, then reset the world once in the Editor (Alt+R, every stage), so DATA\VERSION.DAT exists.
• The online list. It's removed before the first seat of an empty door opens, so a player whose browser closed mid-game isn't told they're already online.

The demo board at atodoors.com runs these two and five more, each with its own art and notes: TradeWars 2002 with its EXTERN on the sysop road, The Pit, Drakeville, LORD II and Arrowbridge II. See what a finished board looks like before you build yours.

#Licenses and credits

ATO Doors is MIT licensed: use it, change it, pass it on, keep the notice.

The DOS machine is built from free software whose licenses ship in machine/LICENSES.txt: the v86 emulator, FreeDOS, the EtherDFS network drive and its server, the Crynwr packet driver, and ATO's own FOSSIL driver.

Web437 by VileR (CC BY-SA 4.0) is the terminal font, and the panel's type is Archivo by Omnibus-Type (SIL Open Font License). The door kernel is ATDT BBS's, the same code that runs doors on a full board.

The door games themselves are their authors'. ATO ships none, and never changes one.

#Glossary