# Atari Mutineer Core Programmers Guide

Atari Mutineer is a set of standalone Atari BASIC programs loaded with `RUN`.
MMS owns resident communications and session state so each BASIC module can be
discarded and reloaded without losing the caller.

For the full boot/module data flow, see [Runtime Architecture](RUNTIME_ARCHITECTURE.md).
For on-disk database layouts, see [Data And File Formats](DATA_FORMATS.md).

## Runtime Flow

The current runtime flow is:

```text
RUNBBS -> APPMGR -> WFC -> CORE
CORE -> MESGAREA / FILEBASE / SYSOP / DOORS / XFER
```

Responsibilities:

- `RUNBBS`: initializes MMS and requests the wait-for-call app.
- `APPMGR`: resolves stable app keys through `MMSAPPS.DAT`, writes MMS app state, prints `Loading <name> ...`, and runs the target module.
- `WFC`: wait-for-call dashboard, login/register flow, user DB, caller append, and session commit.
- `CORE`: top-level menu, static text commands, mode toggles, caller listing, feedback, goodbye, and module dispatch.
- `MESGAREA`: message-base menu and Q/S/R/E/K commands.
- `FILEBASE`: file-area menu, list/download/upload/info, and XMODEM dispatch.
- `DOORS`: catalog-driven door menu and external BASIC door launch.
- `SYSOP`: sysop yell/chat path.
- `XFER`: XMODEM send/receive using raw MMS transfer calls.
- `INIT`, `FILEMGR`, `MSGMGR`: offline setup and maintenance.

## Application Registry

The editable registry is `source/config/MMSAPPS.CFG`; the packed runtime file
is `MMSAPPS.DAT`.

Each row contains:

```text
handle,key,return,type,flags,access,route,term,name,path
```

Current stable keys:

- `$0001`: WFC.
- `$0010`: CORE.
- `$0020`: DOORS.
- `$0030`: MESGAREA.
- `$0040`: FILEBASE.
- `$0050`: SYSOP.
- `$0060`: XFER.

MMS stores compact runtime handles, but semantic identity lives in the registry.
Modules dispatch by writing the requested stable key into handoff bytes `+90/+91`
and running `APPMGR`.

## Module Contract

Every online module follows the same pattern:

1. Validate handoff magic/version.
2. Restore caller handle, secondary identity, access level, user number, modes,
   and session time.
3. Call `MMS_MOPEN` to reattach without dropping carrier.
4. Call `MMS_RESUME_SWITCH`.
5. Reopen `E:` and `K:`.
6. Check carrier at prompt/input boundaries.
7. Save handoff and return through `APPMGR`.

Modules should not assume BASIC variables survive `RUN`. Any state required
after a module switch must live in MMS handoff bytes, disk files, or the app
registry.

## User And Access Model

Users are stored in fixed 128-byte records:

- `USERS.DAT`: user records.
- `USERS.IDX`: normalized handle index.
- `NEXTUSER.DAT`: next user number.
- `ACL.CFG`: per-level session and daily time limits.

Registration asks for full name, handle, email, password, and confirmation.
The first registered user becomes access level `9`; later self-registered users
become level `1`. Level `0` is denied access.

Session identity uses the handle as `N$`; email is stored as secondary identity
and in caller history. Access level is restored from `SS+123`.

`WFC` reads Altirra/APETIME RTIME8-compatible clock registers at `$D5B8` and
uses `ACL.CFG` to reserve session time.

## Message Bases

Runtime message commands operate on configured `MESG?.MET/DAT/IDX` files.
`SS+97` remembers the selected message base during the current session.

Message metadata fields include version, base ID, name, short name, access
level, DAT path, IDX path, next message number, and active count. Message
records include status, number, from, to, subject, kill password, date, time,
line count, and body lines.

`MSGMGR` is the offline maintenance tool for creating, verifying, deleting,
undeleting, and compacting message bases.

## File Areas

Runtime file commands operate on configured `FILE?.MET/DAT/IDX` files.
Metadata stores the area name, view/download/upload levels, DAT/IDX paths,
upload path, next file number, and active count.

`FILEBASE` builds uploaded file paths by appending the normalized filename
to the configured upload path. Text transfers use normal CIO; XMODEM transfers
dispatch to `XFER` through handoff bytes.

`FILEMGR` is the offline maintenance tool for creating, verifying, deleting,
undeleting, and compacting file areas.

## Door Module

`DOORS` reads `DOORS.CFG`, skips blank/comment lines, parses:

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

Accessible entries are displayed according to the caller access level. Launching
a door appends filename to path, stores transient door data in handoff bytes,
calls `MMS_PREP_SWITCH`, and `RUN`s the configured BASIC program. Missing door
programs return `DOOR UNAVAILABLE.` without dropping carrier.

## Text Assets

Caller-facing text is edited under `source/textfiles/ascii/` and
`source/textfiles/atascii/`, then staged into the ATR by the packager. Current
BASIC modules open the packaged text files by filename, such as `MAINMNU`,
`FILESMNU`, `MESGMNU`, `DOORMNU`, `WELC`, `BULL*`, and `INFO`.

## Known Implementation Notes

The current packaged ATR uses root-level `D1:` files. A directory-based ATR
layout is planned separately and requires coordinated changes to packaging,
`MMSAPPS.CFG`, BASIC file paths, and inspectors.

Production communication uses the MMS HATABS build. D: and P: HATABS wrappers
are guarded probe features and should not be treated as stable runtime behavior
unless their dedicated tests pass.