# Atari Mutineer Doors Programmers Guide

Door games are separate Atari BASIC programs that can be distributed apart from
the main BBS ATR. Mutineer launches them from `DOORS` using `DOORS.CFG`.

For the door catalog file format, see [Data And File Formats](DATA_FORMATS.md).
For door ATR packaging, see [Build And Packaging](BUILD_AND_PACKAGING.md).

## Door Package Layout

Use this source layout for a door game:

```text
source/doorgames/<GAME>/
  <GAME>.cfg
  <GAME>.bas
  <GAME1>.ovl
  <GAME>.dat
  TEXT/<FILENAME>.asc
  TEXT/<FILENAME>.ata
```

Only the main `.bas` file is required. Overlays, data files, and text files are
optional.

Build the Arena example:

```sh
make door-arena-atr
```

The package is written under `source/atr/doors/`.

## Door Catalog

The main BBS reads `DOORS.CFG` rows:

```text
id, door name, filename, path, access level
```

Example:

```text
1, Arena, ARENA, D3:>DOORS>ARENA>, 2
```

`DOORS` builds the run path by appending filename to path:

```text
D3:>DOORS>ARENA> + ARENA
```

The path must end in `>`. Filenames should be SDX-compatible 8.3 names.

## Runtime Contract

A door program must:

- Restore MMS state on entry if it needs caller I/O.
- Use normal CIO devices (`E:` and `K:`) for caller text and input.
- Check carrier at prompt boundaries.
- Preserve the current message base byte at `SS+97`.
- Return to the door menu with `RUN "D1:>CORE>DOORS"` in the current packaged ATR.

Door programs should not clear the MMS handoff unless they are intentionally
logging the caller off.

## MMS Session Rules

The caller identity, access level, user number, terminal modes, and session time
live in the MMS handoff block. `DOORS` saves transient door information in
reserved handoff bytes before launching a door. A door should avoid those bytes
unless it owns and documents them.

For normal text:

```basic
OPEN #3,12,0,"E:"
OPEN #4,4,0,"K:"
PRINT #3;"WELCOME TO THE DOOR"
GET #3,X
```

For binary transfer behavior, use a dedicated transfer module or MMS raw mode.
Do not mix terminal-translated I/O with binary payloads.

## Missing Door Handling

If a configured door file is missing, `DOORS` traps the failed `RUN`, prints
`DOOR UNAVAILABLE.`, restores the BBS session, and returns to the door menu. A
door package can therefore be optional for sysops.

## Packaging Notes

Keep the door's own config and data files inside the door package. The main BBS
only needs the `DOORS.CFG` row and any mounted disk/path required by that row.

The current door packager writes an install note explaining where to copy files
and what catalog row to add.

The Arena example lives under `source/doorgames/ARENA/` and is packaged with
`make door-arena-atr`.