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. For on-disk database layouts, see Data And File Formats.

Runtime Flow

The current runtime flow is:

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:

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:

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 RUNs 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.