The door guide

01How a door runs on ATA

Everything happens on the caller's own machine, the DOS PC running in their browser:

1. The caller picks the door from the board's menu.
2. The board writes its drop file (DOOR.SYS, DORINFO1.DEF or PCBOARD.SYS, depending on the package) and runs the batch file or program its menu entry names.
3. The batch file changes to the door's folder and starts the door for the caller's line.
4. The door reads the drop file, talks to the caller through the machine's FOSSIL serial driver, and reads and writes its own files on the board drive.
5. When the caller quits, the door ends, the batch file returns, and the board takes the caller back where they left off.

Three things are ATA's and worth knowing:

• The line number is in the environment. Every batch ATA starts for a caller's machine begins with SET NODE=<n>, and a door started by the board inherits it. So one door batch reads %NODE% and serves every line; nothing on the board's menu has to carry the number. (GAP runs doors with an environment of its own; its section says how its batch learns the line.)
• Each line's drop file stays on that caller's machine. Two callers in the same door at once never see each other's drop file.
• The jail decides what a door may write. A caller's machine may change only the files ATA's rules for that board allow. A door lives in a door folder: D:\DOORS is one from the start, so a door in its own folder under it (D:\DOORS\LORD, D:\DOORS\BRE) can save its game, and the console's Settings page adds others. In a door folder a logged-on caller's machine may change the door's data; its programs, overlays and setup files change only from your console. LORD gets a few rules of its own in a door folder's LORD folder (D:\DOORS\LORD): its program list and node files stay yours, and the small batch it writes for an in-game module is allowed for the caller's own line. Chapter 7 has the details.

02Before you start

Get LORD. You need LORD 4.07 (lord407.zip) and the community FreeDOS patch for it (lord407patch.zip). The patch replaces three files of the 4.07 release (LORD.EXE, LORD.OVR and LORDCFG.EXE) with builds that run under FreeDOS, which is what ATA's machine runs; without it LORDCFG does not run at all. Some players know the patched game as "LORD 4.08", because the patched build says 4.08 in places. It is the same game. Wherever this guide says to put the 4.07 release in place, replace those three files with the patch's first, then carry on exactly as written. You only do this once.

Know where D: is. The board drive is the folder data/doorstore/dos/board inside your ATA folder. The console's DOS page prints its full path on your host. Everything you upload there appears on every machine's D: drive at once, same folder layout. Doors go in its DOORS folder, which the machine sees as D:\DOORS and which the install made for you, empty (an install updated from a release before 0.1.66 makes it the first time the new version runs): each door in a folder of its own, so LORD goes in DOORS/LORD, which the machine sees as D:\DOORS\LORD.

Use your host's file manager or FTP to upload files, in binary mode, with DOS names in capital letters (LORD.EXE, not lord.exe).

Use the console's DOS page to run LORD's configuration program and the board's own editors. Separate batch lines with & when a program must run from its own folder: CD \DOORS\LORD & LORDCFG.

Quiet lines. Set doors up while nobody is calling. Several of the editors below save only when you leave them through their own exit; leaving by closing the browser tab loses the edits.

03LORD: the steps every board shares

3.1Unpack LORD into D:\DOORS\LORD

1. lord407.zip holds an inner LORD.ZIP. Unzip that inner LORD.ZIP on your computer.
2. Unzip lord407patch.zip and rename its three files to capitals: LORD.EXE, LORD.OVR, LORDCFG.EXE. Put them over the release's files of the same names.
3. Upload the whole folder into the board drive's DOORS folder as LORD (so LORD.EXE is at data/doorstore/dos/board/DOORS/LORD/LORD.EXE on your host, and at D:\DOORS\LORD\LORD.EXE on the machine).

3.2START.BAT

LORD runs through its own START.BAT, which loops back into LORD when a player enters an in-game module. Its first lines are placeholders for your drive and folder:

REM C:
REM cd \LORD

Change them to:

D:
CD \DOORS\LORD

Edit the file on your computer before uploading, or with your host's file manager. Keep DOS line endings.

3.3LORDCFG

On the DOS page, type CD \DOORS\LORD & LORDCFG in the command box and press Boot.

1. The first time, LORDCFG offers "(A) Create a NEW LORD.DAT". Take it.
2. Choose the node setup ("(S)etup Nodes with BBS") and set node 1:
   • BBS Name: your board's name.
   • BBS Software: the drop file your board writes. Your board's section in chapter 4 names the entry: (9) DOORSYS for DOOR.SYS, (5) RBBS16+ or (1) QBBS for DORINFO1.DEF, (4) PCBoard15 for PCBOARD.SYS.
   • Path To Drop File: the folder your board writes the drop file into for that line. Chapter 4 gives it per board, with a trailing backslash. Type the colon slowly if LORDCFG drops it.
   • Fossil/Internal: Using Regular Fossil Driver. This is the setting that matters most: LORD's own serial routines cannot find a port on ATA's machine and stop at "Opening DOOR.SYS"; the machine's FOSSIL driver works.
   • Locked Port Speed: Port Not Locked.
   • Comport: Read Standard Com Port From The Drop File.
   • The setup ATA tested also answers No to "Send Open Comports Command?", "Send Reset Comports Command?" and "Use direct screen writes?".
3. Do the same for every line your board runs: node 2, node 3 and so on, each with its own drop file path where the board uses one per line. LORD refuses a line that has no node file of its own ("configuration file is missing"), so a line without one has no game.
4. Leave LORDCFG through its own menu ("Exit the program"). LORDCFG saves only on a clean exit.

The result is one plain text file per line, NODE1.DAT, NODE2.DAT and so on, in Seth Able's node format, made to be edited by hand. The lines that matter:

BBSTYPE DOORSYS
FOSSIL
BBSDROP d:\renegade\temp1\

BBSTYPE is the drop file type, FOSSIL (with no ; in front) is the Regular Fossil choice, and BBSDROP is the drop file folder. If your board writes the same file name on every line (DORINFO1.DEF for all nodes), LORDCFG offers to read DORINFO1.DEF for all nodes, and adds the keyword ALLNODES. For six lines you can make NODE1.DAT in LORDCFG and copy it to NODE2.DAT to NODE6.DAT on your host, changing only the BBSDROP folder where it differs per line and the node number in the file's first line.

3.4The wrapper batch

Every board in chapter 4 runs LORD through a small batch file of yours. It always reads like this:

@ECHO OFF
D:
CD \DOORS\LORD
CALL START.BAT %NODE%
CD \<the board's folder>

CALL matters: START.BAT is a batch file, and a batch started without CALL never returns to the one that started it, so the board would never get the caller back. %NODE% is the caller's line number, set by ATA. The last line returns to the folder the board runs from. Chapter 4 gives each board's exact file and folder. Keep DOS line endings.

3.5What players see

A caller picks LORD from the board's menu and LORD greets them; a new player makes a warrior. Q at LORD's main menu (and Y) returns them to the board. LORD keeps one world for the whole board: callers on different lines meet in the same town and fight the same dragon. LORD runs its own daily reset when the first player of a new day enters; ATA lets exactly that day stamp in LORD.DAT be written by a player and nothing else in that file.

04LORD, board by board

Each section gives: the drop file and LORDCFG setting, the wrapper batch, how to put LORD on the board's menu with the package's own tools, any package setting a door needs, what changes with more than one line, and how a caller gets there. Everything here has been set up and played on ATA, on a real call, with the exception named under Fido.

Each board's steps are on its own page, under its chapter from the manual:

• Asgard-86
• Citadel-86e
• Fido v12 (no doors: the package has no door command)
• GAP 6.6
• The Major BBS 6.25 (LORD, Galactic Empire and Legends of Kyrandia)
• Maximus 3.01
• PCBoard 15.3
• QuickBBS 2.849
• RBBS-PC 17.4
• RemoteAccess 2.62
• Renegade 1.40
• Searchlight BBS 5.1
• Spitfire 3.7
• T.A.G. 2.7d2
• Telegard 3.09
• TriBBS 11.6
• VBBS 6.14a
• Virtual Advanced 2.10

05The Major BBS: LORD, Galactic Empire and Legends of Kyrandia

The Major BBS runs doors on a second computer, and its game modules run as one shared world for every line. All three, step by step, are on The Major BBS page. The two module kits, Galactic Empire for ATA and Kyrandia for ATA, are on the download page.

06A door's daily maintenance

Many doors want a program run once a day. LORD does its own when the first player of the day enters, so it needs nothing. A door that wants a separate maintenance run gets it from ATA's NIGHTLY duty (manual, section 10): add its lines to ATA\NIGHTLY.BAT on the console's Events page, above the "Nightly duties done" line. Usurper is the classic example:

D:
CD \DOORS\USURPER
USURPER.EXE /HMAINT /X
ECHO Usurper maintenance errorlevel %ERRORLEVEL% >> \ATA\NIGHTLY.LOG
CD \

/HMAINT runs the maintenance and exits (/FMAINT would run it and then sit in the game's menu forever, holding the duty machine). /X keeps Usurper's 2 MB overlay file in memory; without it the game reads that file over the board drive hundreds of times a second and never finishes. Test a maintenance line with Run now in DOS first, and raise the Events page's caller-road time limit if the run is long (Usurper's takes ten to thirty minutes).

Rules for any maintenance line: the program must exit by itself, must never wait for a key, and should append its own output to the duty's log with >>.

07Other doors

Your board's package runs the doors it was written to run, and the package side of installing another door is exactly what this guide did for LORD: the door in its own folder, its configuration pointed at the board's drop file and the FOSSIL, a batch file, and a menu entry or door record in the package's own tool. Chapter 4's sections are that road for each package; the batch and the menu entry name the new door's folder instead of \DOORS\LORD.

ATA's part is the door folder. A caller's machine may change only the files ATA's rules for the board allow, and a door must save its players. On every board that runs doors, D:\DOORS is a door folder from the start, and the install makes it, empty. Put each door in a folder of its own inside it:

D:\DOORS\BRE        Barren Realms Elite
D:\DOORS\TW2002     TradeWars 2002
D:\DOORS\USURPER    Usurper

On your host that is the DOORS folder inside the board drive (data/doorstore/dos/board/DOORS; the console's DOS page prints the full path).

What the rules in a door folder do:

• A logged-on caller's machine may change the door's data: its player files, its world files, its scores, anything the door writes while someone plays. That is what playing a door is. Nobody reads the folder before logon.
• Programs and overlays never change from a caller's machine: .COM, .EXE, .BAT, .OVR, .OVL and .DLL files change only from your console's DOS page or a SysOp seat. A caller cannot plant or alter a program another caller's machine, or your own console, would run.
• The protected files never change from a caller's machine either. Each door folder has a list of them, *.CFG *.CTL *.INI to begin with, because that is where most doors keep their setup. A door's setup can name programs it runs (an archiver, an editor, in-game modules), and a member who could rewrite it would choose what the next player's machine runs.

On the Settings page, under Door folders, you can:

• Change a folder's protected files. Add any file the door keeps its setup in or that names a program, by name or pattern: BRE.DAT, *.LST, or a path inside the folder such as BRE\IGMS.DAT. A name without a folder counts in every subfolder.
• Add another door folder at the top of the drive, for a door that wants its own (BRE makes D:\BRE a door folder). The board's own folder, ATA's folders and another package's folder name cannot be door folders; the page says why. Neither can D:\LORD, which needs none: see "LORD at D:" at the end of this chapter.
• Remove a folder. Its files stay where they are; callers can still read them, and nothing in it can be saved from a caller's machine any more.

Two things to know about doors in general:

• A door that writes its own setup file while it runs (rare, but some do) is refused at that write: its protected list is too wide for it. The console's log names the file as a security line. Take that name, or its pattern, off the folder's protected list.
• A door that writes a batch file while it runs cannot do it in a door folder: no caller's machine may create a program. LORD is the one exception, by name: it writes DO<n>.BAT for a player entering an in-game module, and a folder called LORD directly inside a door folder (D:\DOORS\LORD, not deeper) allows that one batch for the caller's own line, keeps LORD's program list (3RDPARTY.DAT, IGMSEC.INI) and node files yours, and lets a player's machine change only the day stamp in LORD.DAT. Those are the rules ATA measured for LORD on every board.

LORD at D:. Earlier releases of this guide put LORD in D:\LORD, and a LORD already there keeps working: it keeps the rules ATA measured for LORD (its in-game module batch for the caller's own line, its program list and node files yours, only the day stamp in LORD.DAT from a player's machine), and its programs and overlays, in any subfolder too, change only from your console. What it does not get is a door folder's protected list: an in-game module's own .CFG, .CTL or .INI in D:\LORD is a player's machine's to change. If you add in-game modules that keep setup files of their own, move LORD to D:\DOORS\LORD first (move the folder, then change CD \LORD to CD \DOORS\LORD in START.BAT and in your board's LORD batch).

If a door is in a folder that is not a door folder, it loads and then cannot save; the console's log says so in one line naming the folder and this page.

08When a door does not work

• The caller picks the door and the menu just comes back. The menu entry names a batch that is not there (check the spelling and the folder), or, on Renegade, Swap Shell Function is off.
• SYSTEM MALFUNCTION on Renegade when the game is picked. %N in the menu command's Options line. Remove it; the batch reads %NODE%.
• LORD stops at "Opening DOOR.SYS". The node file has ;FOSSIL (commented out) instead of FOSSIL: set Fossil/Internal to Using Regular Fossil Driver in LORDCFG.
• LORD says its configuration file is missing. That line has no NODE<n>.DAT. Set the node up in LORDCFG, or copy NODE1.DAT to NODE<n>.DAT and fix its drop path.
• LORD cannot find its drop file. The BBSDROP folder in that line's node file is not where the board writes it. Chapter 4 gives each board's folder per line.
• LORD starts in local mode and waits at the machine's keyboard. It was started as node 0: the batch passed an empty line number. On GAP, use the ATANODE batch in 4.4.
• The door runs but the caller never gets the board back. The batch starts START.BAT without CALL.
• Citadel-86e: the caller is back at the room prompt before LORD says anything. #swap-spawn 1 is missing, or the configuration was not compiled with CONFG after the change.
• T.A.G.: LORD never loads. The program data lacks its leading ~.
• QuickBBS: the caller is hung up on when the door starts. The menu item is Type 7; use Type 15 and the QBCALL.BAT loop.
• Spitfire: the call ends when the door is picked. The line's ATACALL.BAT has no errorlevel loop, or the line's own copy in D:\SF\NODE<n> was not changed.
• TriBBS: the door menu redraws itself. The line's own BATCH folder lacks LORD.BAT.
• The Major BBS: the caller picks the door and nothing happens. D:\GHOST\DOORPC\<NAME>.BAT is missing or misspelled. GHOST stops at an error the caller cannot see, and the caller waits until the door's time limit ends it.
• The Major BBS: the door never ends. Its batch does not start GHOST COM1 38400 again at the end.
• The Major BBS: E GALEMP says the door is busy or nothing happens. The world is not offered: ATAWORLD.CFG is missing from its folder, its door= word is not the door record's name, its words before the = are not lower case, or module= names a DLL that is not beside it.
• The Major BBS: a module world never starts ("The game could not start here"). A file the module opens is missing from its WORLDS folder, or its .DAT is a Btrieve file ATA cannot read; the console's log names the file.
• The Major BBS: a Kyrandia player's progress is lost at x. The descriptor lacks exit=hangup. Add it, then Reset the world once nobody is playing.
• The door loads but nothing it saves is kept (security lines in the console's log). The door is not in a door folder: move it into one under D:\DOORS, or add its folder under Door folders on the Settings page. The log's line "D:is not a door folder" names it.
• A door in a door folder is refused one file (a security line naming it). That file matches the folder's protected list. If the door itself writes it while it runs, take it off the list on the Settings page; if it is the door's setup, leave it protected and change it from the DOS page.