Running DOS Door Games

#How it works

When a caller opens a DOS door, their own browser boots a small FreeDOS machine, the game plays in the same terminal as the rest of your board, and the game's files stay on your board, served one read and one write at a time. You keep a plain PHP host. The caller needs a current browser and nothing else.

#Turning it on

The whole system ships switched off. Console, Settings, Access, check DOS doors, save. A DOS Doors page appears in the console. While the switch is off there is no console page, no menu action, and nothing served; callers cannot tell the feature exists.

#Try the shipped test door first

ATDT ships a tiny door called testdoor that exercises every part of the machinery: the boot, the network drive, the drop file, a file write, a record lock, and typing. Prove your board with it before installing anything real.

• DOS Doors page, press Scan dosdoors/ folder. The test door registers.
• Menus page: add an item to a menu with the DOSDOOR action and argument testdoor (the argument field offers every registered door).
• Call your own board and press the key. You should see a FreeDOS boot go by, then the door's banner, then DROPFILE OK, WRITE OK, and LOCK OK. Type a little, press Q, and you are back at your menu.

If all four lines say OK, every real door will work the same way.

Since 1.7.3 the test door also answers D, which drops DTR and proves the hangup road end to end: a DOS program dropping the modem-control line ends the call on the spot, with carrier-off mirrored back into the machine first, so the program sees the NO CARRIER it expects while it saves on its way out.

#Installing a real door

A DOS door is a folder dropped into dosdoors/ off the BBS root, right next to doors/ where your PHP doors live:

Copy the game's directory into files/ just as it came from the original install or the registration package: the program, its data files, its ANSI screens, everything. Then write dosdoor.json beside it:

Field by field

Scan again after any manifest change; the Scan re-reads titles, node caps, and minutes from the manifest. A folder with a broken manifest is skipped and the Scan tells you exactly what is wrong with it, by name.

One trap worth naming: batch files

The game always runs at the root of drive D:, so a batch file must stay relative. Copies that come out of DOSBox-era collections often hardcode paths (C:\LORD\LORD.EXE) or guard the launch line with IF EXIST C:\.... On the board's drive there is no C:, the guard is silently false, and the door ends the moment it starts without a word on any screen. Strip the drive letters and the guards: LORD.EXE /N%1 is the whole idea.

To see exactly what a live door's batch file contains, open the door's Maintenance page and TYPE START.BAT at a real prompt (21.5). Or set the manifest command to TYPE START.BAT temporarily, Scan, and enter with diagnostics on: the mirror shows you the file as the machine sees it.

Most doors also need their own setup program run once (node count, BBS type, registration). That runs from the console too, against the live game, no DOSBox required.

#How daily maintenance runs

New in 1.7.2. Some doors expect a maintenance program to run once a day: TradeWars 2002's EXTERN is not optional, and Usurper's daily sweep matters too. ATDT never runs DOS on the server, so a maintenance program cannot ride a server cron the way native door hooks do. Instead the board arms the duty at midnight, board time, and the next machine to enter runs it, which is how a BBS event worked in 1993.

• The first caller who enters the door alone after board midnight runs the command on the way in. They see a note ("The door runs its daily maintenance first; the game follows"), then the program's own output, then the game. On a warm door the whole thing usually takes seconds.
• The moment the command finishes, the board stamps the day. Only one entry a day pays the toll; everyone after enters straight into the game.
• An abandoned run is retried. If the caller's browser closes mid-run, the duty passes to the next caller who enters alone, after a ten minute grace. Door programs keep their own "already ran today" records, so a retried run is safe.
• On a busy multi-node door the duty waits for a moment when someone is alone. If a full day passes without a completed run, the SysOp log gets one line saying maintenance is pending, and you can run it from the console instead (21.6).

#The console page

Per door you control:

Daily minutes are per caller per door. A caller who runs out is let go gently and can come back tomorrow; the count resets at your board's midnight. Node caps count only live seats: a browser that closed frees its seat, and any record locks it held, within ninety seconds, with no cleanup on your part.

#Maintenance: the door's own tools, no DOSBox

Nearly every classic door ships a setup program beside the game: LORDCFG.EXE, a player editor, a node configurator. Those are local DOS programs that draw on the machine's own screen and read its own keyboard, which used to mean copying the game into DOSBox, configuring it there, and copying the results back. The console now does it in place.

Click maintain on a door's row. The page boots the same FreeDOS machine callers get, in your tab, with the door's live game directory on D:\ and one difference: the machine's screen and keyboard face you instead of riding a phone line. Type the program to run (LORDCFG.EXE), press Boot the machine, and drive the tool exactly as you would have on real hardware. When the program exits you land at a real DOS prompt on D:\ and can keep working: DIR, TYPE START.BAT, COPY, DEL, another tool. Leaving the command blank gets you a DIR and the prompt straight away.

Two screens: the machine's own, and the door's line

New in 1.7.2. The page shows the machine's DOS screen (batch files, config tools, the prompt) and, beside it, the door's line: a real terminal showing what a caller would see. A door game run by hand talks on the serial line exactly as it does for a caller, so it appears on the door's line, and that screen also answers the door's ANSI probes. Click a screen to type there; the highlighted border shows which one is live.

This is the way to run a door's daily maintenance by hand, watch it, and answer its prompts, or to play-test as node 0 without tying up a caller seat.

The Run the daily maintenance button

When a door's manifest names a maintenance command (21.4), the page shows a second button that boots the machine, runs exactly that command on the live game drive, and stamps the day when it finishes, so callers skip it until tomorrow. The page shows when maintenance last completed. The ordinary command box still works for config tools, installers, and a bare DOS prompt.

Worth knowing before you lean on it:

• Changes are live immediately. You are editing the directory callers play in, not a copy. On a busy door, disable it first and let the seats drain; maintenance works fine on a disabled door, which is exactly when you want to be in there.
• Reset undoes maintenance work. Reset reseeds the live directory from files/, so a change made here lives only in the live game until you also copy the changed files back into dosdoors/<slug>/files/ on the server. Do that and the change survives resets too.
• Installers work; aim them at D:\. A door that ships as an installer (TradeWars 2002 is the classic case) goes into files/ as it came. Scan, open maintenance, run the installer, and give it D:\ as the target directory. Afterwards, copy the installed tree from the live directory back into files/, so a future Reset reseeds the installed game and not the bare installer.
• The keyboard is the machine's. Keys typed on the page go to DOS; the command box stays a normal text box. If keys seem to go nowhere, click the black screen once. Ctrl+C means what DOS thinks it means.
• The machine dozes when idle. A quiet minute stops it to spare your laptop; any key or click wakes it where it left off.
• The seat lasts up to eight hours and shows in Seats in use as node 0, where it can be disconnected like any other seat. A closed tab frees it by itself within ninety seconds.

Config tools and installers are local programs, exactly what this page is for. Running the game itself here works too, but on node 0 most doors drop to their local or SysOp mode; to see what a caller sees, enter the door from the board like anyone else.

#What the machine provides

Every door node boots the same FreeDOS floppy: about 605 KB of conventional memory free (XMS loaded, kernel high), the network drive on D:, and a FOSSIL driver on COM1. That covers both kinds of door ever written: the ones that drive the serial port directly and the ones that refuse to run without a FOSSIL. Neither needs any configuration on your part; if a door offers a FOSSIL or internal choice in its own setup, either works.

#Known door quirks

Doors that misbehave in a way that is theirs, not yours, collected so nobody debugs them twice. The DOS door page keeps the running list and the ready-made packages; this is the worked example.

LORD 4.07 and 4.08: two traps, both LORD's

The newest full LORD package on the official site, 4.07, has known problems with FreeDOS based and emulated environments, which this machine is. Versions 4.02a through 4.06 have neither problem.

First trap: 4.07's LORDCFG.EXE halts with "This version of LordCfg is not meant for your version of Lord." The same package does it under DOSEMU and OS/2 on a plain local drive, so it is LORD's bug, not your files and not this machine (DOSBox passes only because it pretends to be MS-DOS 5). The community 4.08 patch fixes it: apply it over the 4.07 install in files/, keep the live drive in step, and LORDCFG runs.

Second trap: even at 4.08, the game's "internal" com mode dies the instant it opens the drop file, silently, no message on any screen. The 4.0x rewrite of LORD's com layer pokes the UART in a way emulated hardware does not love. The fix is one setting: in LORDCFG, Configure Nodes, set every node to use the FOSSIL driver instead of internal com. This machine ships its own FOSSIL on COM1, and with it LORD 4.08 runs perfectly, title screen to gameplay. While you are in LORDCFG the first time, let it create LORD.DAT when it offers; the game will not start without one.

A manifest that serves LORD 4.x well, worked out on a live rig:

The .OVR matters most (LORD reads its overlay constantly), and the big text .DATs listed are content, not state, so declaring them static keeps first reads off the wire at the moment the door opens. Leave the session list empty: LORD's INFO.n files are how its nodes see each other, so they belong on the shared drive.

Usurper

Usurper reads its 2 MB overlay file over the board drive constantly unless started with its /X switch, and its daily maintenance has its own list of traps: the wrong switch never exits, a misplaced USUTEXT.DAT stops an unattended run at "[Press a key]", and a deleted DATE.DAT punishes the next caller with a half-hour wait. All of it is measured and written down in USURPER.md in the doors folder, next to the engine's README, and the full install guide is on this site.

#Multiple callers in one game

Doors written for multi-node boards coordinate through DOS record locking, the same calls that worked under SHARE.EXE on a LAN. ATDT arbitrates those locks on the server, so two nodes can never tear the same player file, and reads that follow a lock always see the latest write. Anything advertised as multi-node in its day will behave. Set max_nodes to what the game's documentation supports; for a single-node door set it to 1 and callers queue naturally, and the board tells them every node is in use.

#What callers experience

They press a menu key. Their tab spends about two seconds booting FreeDOS (there is a first-visit download of about 2.5 MB for the emulator, cached by the browser after that). Then the door plays in the same screen, same font, same colors as the rest of your board. Arrow keys, function-key-free door menus, ANSI art, and cursor tricks all work; ANSI music is quietly swallowed rather than printed as garbage.

Leaving: every door's own quit path works normally and returns the caller to your menu. A door that hangs up on its own, by dropping DTR, is noticed the moment it happens as of 1.7.3; before that the line idled until the batch file behind the game reached its exit marker, which can be a long silence. If a door wedges, Ctrl+] pressed three times hangs it up; the game sees its carrier drop, exactly like a caller hanging up a phone, and gets a moment to save before the machine goes away. Closing the tab is also always safe.

#What it costs your server

Almost nothing. The emulation happens in the caller's browser; your server answers small file requests, the same order of work as serving any busy screen. Everything is standard PHP, no processes, no daemons, shared hosting included. Boards that never flip the switch serve not a single byte of any of it.

#Where things live, for the record

Back up data/ and you have backed up every game world. The doors themselves reinstall from their folders; the state directory is the part that holds your callers' characters.

↑ Back to the top