Atari Mutineer Doors Programmers Guide

Doors are external Atari BASIC programs launched by the DOORS module from a catalog entry. Supported release doors are bundled in the 16MB BBS ATR.

Door Disk Layout

D1:>DOORS><GAME>>
  <GAME>.bas
  optional overlays and data
  DOOR.cfg
  README.txt
  TEXT/*.asc
  TEXT/*.ata

The 16MB Mutineer ATR includes the bundled door directories and catalog rows. Development builds may still produce isolated door images, but they are not release artifacts.

Catalog

Door catalog source rows are:

id, door name, filename, path, access level

Example:

3, Arena, ARENA, D1:>DOORS>ARENA>, 2

The path must end in >. The package/offline compiler validates this source, generates D1:>DATA>DOORCAT.DAT, and generates the visible DOORMNU files. At caller time, DOORS loads DOORCAT.DAT, filters rows by caller access, and runs the precomputed target path. A trapped missing target prints DOOR UNAVAILABLE. and returns to the menu.

Door catalog edits are offline work. After changing DOORS.CFG or adding a new DOOR.CFG row, rebuild the runtime door catalog before putting the BBS back online. Caller-facing launches use only the generic Opening Door... notice.

REMMS Door Contract

A supported caller-visible door must:

• discover RAPI, RPUB, and RSESS through $03E8;
• validate session magic/version;
• preserve caller identity, modes, access, user number, session deadline, and the current handoff byte at SS+97;
• call USR(ROPEN) and select host/both for a remote caller;
• use USR(RSTAT) at blocking input boundaries;
• use normal E:/K: or RTGET=RAPI+27 for terminal text;
• use RGET/RPUT only for deliberate raw or binary bytes;
• save its fields and clear POKE SS+98,0 before RUN "D1:>CORE>DOORS";
• return to WFC when session +87 is no longer 1.

Minimal entry:

1000 RAPI=PEEK(1004)+256*PEEK(1005):RPUB=PEEK(1006)+256*PEEK(1007):SS=PEEK(1010)+256*PEEK(1011)
1010 RMODE=RAPI+3:RROUTE=RAPI+6:ROPEN=RAPI+9:RSTAT=RAPI+15:RTGET=RAPI+27
1020 IF PEEK(SS)<>77 OR PEEK(SS+1)<1 OR PEEK(SS+1)>3 THEN RUN "D1:>CORE>WFC"
1030 R=USR(ROPEN):IF R<>0 THEN RUN "D1:>CORE>WFC"
1040 R=USR(RMODE,1):R=USR(RROUTE,2)
1050 OPEN #3,12,0,"E:":OPEN #4,4,0,"K:"
1060 PRINT #3;"HELLO FROM A REMMS DOOR"
1070 R=USR(RSTAT):IF PEEK(SS+87)<>1 THEN RUN "D1:>CORE>WFC"
1080 X=USR(RTGET):IF X=256 THEN 1070
1090 POKE SS+98,0:RUN "D1:>CORE>DOORS"

Local-only tools should use mode/route local and must not poll R:.

Door Development Checklist

• Keep the caller-facing program name short enough for the door catalog row.
• Store game data under the door's configured path, not in D1:>CORE>.
• Keep supported release door programs and data under D1:>DOORS>.
• Validate REMMS discovery and session version before touching caller I/O.
• Reopen REMMS with ROPEN,0 after entry from DOORS.
• Use mirrored route for active remote callers and local route for sysop-only setup tools.
• Keep long screens pager-friendly: 40 columns, explicit returns, and no terminal-specific cursor controls unless you provide ASCII and ATASCII paths.
• Use line-oriented text input for commands and forms; reserve raw RGET/RPUT for binary protocols.
• Before file writes, suspend the modem owner, write, close disk IOCBs, and resume before prompting again.
• Clear POKE SS+98,0 and return to D1:>CORE>DOORS after a normal game exit. DOORS reloads and displays DOORMNU on every return.
• Return to D1:>CORE>WFC after carrier loss, timeout, fatal REMMS failure, or a deliberate disconnect.

Caller-Facing Door Skeleton

1000 IF PEEK(1000)<>82 OR PEEK(1001)<>69 OR PEEK(1002)<>77 THEN RUN "D1:>CORE>WFC"
1010 RAPI=PEEK(1004)+256*PEEK(1005):RPUB=PEEK(1006)+256*PEEK(1007):SS=PEEK(1010)+256*PEEK(1011)
1020 RMODE=RAPI+3:RROUTE=RAPI+6:ROPEN=RAPI+9:RCLOSE=RAPI+12:RSTAT=RAPI+15
1030 RGET=RAPI+18:RPUT=RAPI+21:RTGET=RAPI+27:REVENT=RAPI+42:TBEGIN=RAPI+45:TEND=RAPI+48:RFAIL=RAPI+51
1040 IF PEEK(SS)<>77 OR PEEK(SS+1)<>7 THEN RUN "D1:>CORE>WFC"
1050 ONLINE=PEEK(SS+87):LOCAL=0:IF ONLINE=8 THEN LOCAL=1
1060 IF ONLINE=1 THEN R=USR(ROPEN,0):IF R<>0 THEN R=USR(RFAIL,6):RUN "D1:>CORE>WFC"
1070 IF ONLINE=1 THEN R=USR(RMODE,1):R=USR(RROUTE,2)
1080 IF LOCAL THEN R=USR(RMODE,0):R=USR(RROUTE,0)
1090 OPEN #3,12,0,"E:":OPEN #4,4,0,"K:"
1100 PRINT #3;"DOOR READY"
1110 REM GAME LOOP BEGINS HERE
8990 POKE SS+98,0:RUN "D1:>CORE>DOORS"

Use TBEGIN,1 for line input, TBEGIN,2 for masked input, and TBEGIN,3 for single-choice commands. A RTGET or REVENT result at or above 256 is a structured status, not a printable byte.

Door Prompts

Door prompts should match the rest of the BBS:

[ HH:MM:SS Door Command >

Use the caller's remaining session time from SS+126/+127. If the door has a game-specific prompt, keep the leading time-left block and put the game noun after it, for example:

[ HH:MM:SS Arena Command >>

Do not print fixed time/range placeholders. If a value is not real, omit it.

State And Files

Use a door-owned disk path for config, players, matches, scores, and display assets. Document every session scratch byte a door claims. SS+96 is used for door/transfer mode and SS+97 is shared by module handoffs, so save and restore them deliberately.

Do not clear the whole session block, change the online byte, or hang up the caller unless disconnect is an explicit door feature. Do not mix terminal-translated E: output with binary transfer payloads.

Suggested door files:

For mutable files, prefer fixed-size records or line-oriented records with a version/header line. Rebuildable indexes should contain enough information to recover from a partially deleted or compacted data file.

Bundled Doors

The maintained dungeon source, catalog filename, install path, and release artifact all use DUMJIN.

Tournament Arena

The bundled Arena caller program is a REMMS caller-facing door. It supports remote and local sessions, preserves the BBS session fields, routes input/output through the current REMMS API, returns normally to D1:>CORE>DOORS, and returns carrier loss to D1:>CORE>WFC.

Arena files:

The ARENA1.ovl and ARENA2.ovl programs are local sysop setup tools; they do not attach to the caller communications session.