ATDT BBS INSTALL - THE MATRIX v0.3.3

Current build: v0.3.3, with progressive level-up credit rewards.
Read IDENTITY.TXT before updating; preserve live DATA and MATRIX.CFG.

=========================================
Created by Xendrome - https://www.dosbbs.com

This guide is for ATDT BBS 1.7.x DOS Doors.
Reference: https://www.atdtbbs.com/manual/dos-doors/

IMPORTANT: ATDT IS NOT A DOS BBS
--------------------------------
ATDT is a PHP-based BBS. A DOS door is not installed into a traditional DOS
BBS door directory on the web server. When a caller opens a DOS door, the
caller's browser boots a small FreeDOS machine. ATDT presents the door's live
game directory to that machine as drive D:, generates the requested drop file,
and bridges the door's serial/FOSSIL I/O back into the caller's terminal.

For that reason, DO NOT use INSTALL.BAT to install The Matrix into ATDT.
INSTALL.BAT and GETINST.EXE are included for conventional DOS/FreeDOS BBS
installations. ATDT uses the dosdoors/ package layout described below.

BEFORE INSTALLING A REAL DOOR
-----------------------------
1. In the ATDT console, open Settings -> Access.
2. Enable DOS doors and save. The DOS Doors console page will appear.
3. ATDT ships a test door named testdoor. Scan the dosdoors/ folder, add a menu
   item with action DOSDOOR and argument testdoor, and verify its DROPFILE,
   WRITE and LOCK tests succeed before installing The Matrix.

ATDT DIRECTORY LAYOUT
---------------------
Create this structure under the ATDT BBS root:

  dosdoors/
    matrix/
      dosdoor.json
      files/
        MATRIX.EXE
        COMMONS.EXE
        EDITOR.EXE
        MATRIX.CFG
        TEXT.DAT
        ENEMIES.DAT
        ENEMIES.BAK
        ENEMIES.TXT
        MATRIX.MAP
        DATA/
        DISPLAY/
        ...the rest of the MATRIX folder contents...

Use the package this way:

  * Copy the package-root dosdoor.json to:
      dosdoors/matrix/dosdoor.json

  * Copy the CONTENTS of the package MATRIX/ folder to:
      dosdoors/matrix/files/

Do not copy SOURCE/ or DOCS/ into the ATDT door's files/ directory.
Do not copy install.bat or GETINST.EXE into files/; ATDT does not use them.

THE INCLUDED dosdoor.json
-------------------------
The supplied manifest is:

  api       1
  slug      matrix
  title     The Matrix
  command   MATRIX.EXE
  dropfile  DOOR.SYS
  max_nodes 4
  minutes   60

Change max_nodes or minutes if desired. After changing dosdoor.json, use
Scan dosdoors/ folder again so ATDT rereads the manifest.

The manifest deliberately marks only fixed content as static/cached:

  *.EXE
  *.ANS
  TEXT.DAT
  ENEMIES.TXT
  *.MAP
  DISPLAY/README.TXT
  DATA/README.TXT

MATRIX.CFG, ENEMIES.DAT, ENEMIES.BAK and all live DATA files are intentionally
NOT static. They can change and must be shared by every node. Lock files, TMP
files, player records, WORLD.DAT, NEWS.DAT and COMMONS.MSG are also left
unlisted so ATDT treats them as shared game state.

There is intentionally no session list. The Matrix uses its lock/temp files to
coordinate shared multi-node state, so those files must not be isolated into a
per-caller session tree.

There is no maintenance command because The Matrix does not require a separate
daily maintenance program.

REGISTERING THE DOOR
--------------------
1. Open the ATDT DOS Doors console page.
2. Click Scan dosdoors/ folder.
3. Confirm that "The Matrix" / slug "matrix" registers without a manifest
   error.
4. Open the Menus page and add a menu item with:

     Action:   DOSDOOR
     Argument: matrix

ATDT generates a fresh GAP-style DOOR.SYS for each caller. The Matrix defaults
to reading DOOR.SYS, so the manifest command is simply:

  MATRIX.EXE

Do not use a hard-coded C: path or DOS BBS node path. ATDT runs the game with
the live door directory at the root of D:.

FIRST-TIME CONFIGURATION
------------------------
Use ATDT's Maintenance function instead of copying the door into DOSBox or
trying to run EDITOR.EXE on the PHP host:

1. In DOS Doors, open Maintain for The Matrix.
2. Enter this command:

     EDITOR.EXE

3. Boot the machine.
4. The maintenance machine's local DOS screen and keyboard are connected to
   your browser. Configure the BBS name, SysOp name, economy/gameplay settings,
   enemies, and any other desired options.
5. Exit EDITOR.EXE when finished.

Changes made in Maintenance affect the LIVE game immediately. If you later use
ATDT's Reset game state function, ATDT reseeds the live game from
 dosdoors/matrix/files/. Therefore, after making permanent configuration or
enemy changes, also preserve the resulting MATRIX.CFG / ENEMIES.DAT /
ENEMIES.BAK in the shipped files/ tree before any future reset.

WHAT ATDT STORES WHERE
----------------------
The package under dosdoors/matrix/files/ is the install/seed copy.
The live shared game state is stored by ATDT under:

  data/doorstore/dos/matrix/

Unlisted files are shared state. Every caller sees the same player database,
world, Commons wall, configuration and enemy catalog. ATDT arbitrates DOS
record locking between simultaneous nodes.

Back up ATDT's data/ directory to protect the live game world and players.

WARNING ABOUT RESET GAME STATE
------------------------------
ATDT's Reset game state command wipes the live Matrix directory and reseeds it
from dosdoors/matrix/files/. This starts the game state over. Do NOT use Reset
as a routine upgrade step when you need to preserve existing players/world data.
Back up data/ before any reset.

PERFORMANCE / DIAGNOSTICS
-------------------------
The included manifest marks the door's fixed executables, ANSI screens and
TEXT.DAT as static so ATDT can cache them in the caller's browser instead of
re-reading unchanged content across the mapped DOS drive. Mutable game files
remain shared.

ATDT's Diagnostics option records recent file operations and timings. If the
door ever feels slow, enable Diagnostics and inspect which files are being read
repeatedly. Only files that truly never change during play should be added to
static.

The Matrix v0.3.3 also contains its own DOS-side I/O optimizations for ATDT:
block reads for ANSI files, indexed TEXT.DAT access, reduced redundant saves,
and elimination of redundant physical DOS commit operations.

MULTIPLE CALLERS
----------------
The Matrix uses shared DATA files plus lock files and is designed for multi-node
operation. The supplied manifest allows 4 simultaneous callers. Adjust
max_nodes if desired and Scan dosdoors/ again after changing the manifest.

The caller needs only a current browser. ATDT supplies FreeDOS, drive D:,
DOOR.SYS, COM1 and a FOSSIL driver automatically.

UPGRADING TO v0.3.3
-------------------
Read UPGRADE.TXT before applying this package to an existing ATDT installation.
Replace the three game/editor executables and the updated gambling/help screens
with every node closed; preserve the live DATA files and configuration. Do not
use Reset game state. The supplied manifest does not change in this release.
Player locks no longer expire: after a forced termination, close every node
before removing any leftover DATA\*.LCK. No automatic lock-deletion job is safe.

GAMBLING DAILY-LIMIT UPDATE (INCLUDED IN v0.3.3)
---------------------------------------------------
Oracle's Numbers gives seven HIGHER/LOWER guesses. Each player may accept
three wagers per DOS calendar day by default. The wager and used-play count
are saved together before guessing, including when the caller disconnects or
cancels afterward. Cancelling at the wager prompt consumes no game or credits.
Re-entering the door does not restore used plays. The allowance refreshes on
the next calendar day, including while remaining inside Commons. Moving the
clock backward does not grant another allowance for an earlier date.

MATRIX.CFG: CommonsDailyGames=3 (0 disables gambling plays; range 0-100).
EDITOR.EXE: main option 9, Zion Commons settings, option 6.
Existing configurations without this key default to three. Keep your live
configuration; save it through the updated editor to write the new key.
With the default 1,000-credit maximum wager and 2x net-win multiplier, the
maximum gambling profit is 6,000 credits per player per day. SysOp changes to
limits, wager sizes or multipliers change that ceiling.

The player record now includes an independent gambling date and used count.
Older player records convert automatically without resetting character progress.
Update MATRIX.EXE, COMMONS.EXE and EDITOR.EXE together with every node stopped.
Do not run older binaries against converted records. World records are unchanged.
The splash version is v0.3.3, centered beneath THE MATRIX.

