ATARI MUTINEERBBS

Documentation

Runtime Architecture

Reference material for Atari Mutineer BBS sysops, door authors, and runtime maintainers.

Runtime Architecture

This page explains how the packaged BBS boots, keeps state across Atari BASIC program loads, routes caller I/O, and dispatches modules. Source of truth: source/text/*.bas, source/config/MMSAPPS.CFG, mms/src/public.inc, and mms/src/constants.inc.

Boot Flow

Normal auto-start ATR:

AUTOEXEC.BAT
  -> D1:RHND850.COM
  -> D1:MMS.COM
  -> BASIC /I <<D1:AUTOGO
AUTOGO
  -> RUN "D1:>CORE>RUNBBS"
RUNBBS
  -> USR(MMS_INIT)
  -> request WFC in MMS handoff
  -> RUN "D1:>CORE>APPMGR"
APPMGR
  -> resolve requested stable key in MMSAPPS.DAT
  -> RUN requested module

Normal online flow:

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

Offline utilities are packaged under D1:>CORE> but are not part of the online handoff flow: INIT, FILEMGR, and MSGMGR.

Module Switching Contract

Online modules are standalone BASIC programs. A RUN discards BASIC variables, so persistent session state must live in MMS, disk files, or the app registry.

The common online-module entry pattern is:

  1. Discover MBASE from $03EC/$03ED.
  2. Validate handoff magic/version at SS=MBASE+$B0.
  3. Restore caller identity, modes, access level, user number, and session time.
  4. Call USR(MOPEN) to reattach R: without dropping carrier.
  5. Apply terminal modes through MMS_SERVICE.
  6. Call USR(MRESUME).
  7. Open E: and K: for caller I/O.
  8. Check MMS_CONN_STATE at prompt/input boundaries.
  9. Save handoff and return through APPMGR.

Modules dispatch by writing a requested stable app key into SS+90/+91, an optional return key into SS+92/+93, optional command data into command/handoff bytes, then running D1:>CORE>APPMGR.

Application Registry Data Flow

Editable source: source/config/MMSAPPS.CFG. Packed runtime file: D1:>DATA>MMSAPPS.DAT.

Each registry row contains:

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

Current stable keys:

Key Module Path
$0001 WFC D1:>CORE>WFC
$0010 CORE D1:>CORE>CORE
$0020 DOORS D1:>CORE>DOORS
$0030 MESGAREA D1:>CORE>MESGAREA
$0040 FILEBASE D1:>CORE>FILEBASE
$0050 SYSOP D1:>CORE>SYSOP
$0060 XFER D1:>CORE>XFER

APPMGR reads MMSAPPS.DAT, verifies the MAPR header, applies access checks, publishes app state into MMS public bytes, prints Loading <name> ..., and runs the target path.

MMS State Blocks

MMS publishes:

MMS_PUBLIC is for status, diagnostics, current app state, carrier state, and runtime settings like MMS_BAUD_CODE. MMS_COMMAND is a short argument/result block used by MMS_SERVICE. MMS_HANDOFF is the cross-RUN session block used by BASIC modules.

Caller I/O

Normal text I/O uses CIO:

OPEN #3,12,0,"E:"
OPEN #4,4,0,"K:"
PRINT #3;"TEXT"
GET #3,X

MMS HATABS owns the BBS communication layer and routes E:/K: behavior based on MMS route and terminal mode state. Raw transfers use MMS_RGET and MMS_RPUT through XFER after entering raw mode.

Carrier Handling

MMS keeps public connection state in MMS_CONN_STATE and fast handler-facing state in MMS_CARRIER_STATUS. Online modules check carrier at prompt and input boundaries:

R=USR(MSTAT):IF PEEK(MCONN)<>3 THEN RUN "D1:>CORE>WFC"

On hangup or carrier loss, modules return to WFC; they should not spin inside long prompt loops after carrier is gone.

Runtime Module Responsibilities