THE MATRIX

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

Version 0.3.3 - COMPILED 16-BIT DOS BUILD
=========================================

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.

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

This package is ready to run under DOS/FreeDOS. No compiler is required.
It is an unofficial, non-commercial fan-made BBS door inspired by The Matrix.
It is not affiliated with or endorsed by Warner Bros. or the rights holders.

PACKAGE LAYOUT / QUICK INSTALL
------------------------------
The ZIP root is organized as follows:

  MATRIX\          Complete runnable game directory
    DATA\           Shared player/world data directory
    DISPLAY\        External ANSI/menu templates
  SOURCE\          Complete source/build tree; not required to run the game
  DOCS\            Package documentation
    README.TXT      General game/readme information
    SYSOP.TXT       SysOp configuration and administration reference
    CHGLOG.TXT      Version history
    BUILDINF.TXT    Compiled-build details
    ATDTINST.TXT    ATDT BBS DOS Doors installation guide
  dosdoor.json     Ready-to-use ATDT DOS Doors manifest
  install.bat      Conventional DOS/FreeDOS interactive installer launcher
  GETINST.EXE      DOS prompt helper used automatically by install.bat
  FILE_ID.DIZ      BBS file-index description

ATDT BBS USERS:
Do NOT run install.bat for an ATDT server installation. ATDT is a PHP BBS whose
caller's browser boots FreeDOS. Copy dosdoor.json to dosdoors/matrix/ and copy
the CONTENTS of MATRIX\ to dosdoors/matrix/files/, then follow
DOCS\ATDTINST.TXT. The supplied manifest launches MATRIX.EXE with a fresh
DOOR.SYS and marks fixed executable/ANSI/text assets static for ATDT caching.
Mutable configuration, enemy and DATA files remain shared.

CONVENTIONAL DOS/FREEDOS BBS USERS:
Run install.bat from the package root, enter a drive letter and DOS 8.3
destination path when prompted, then follow DOCS\SYSOP.TXT. The package may be
on writable storage or read-only media such as CD-ROM. GETINST.EXE creates its
temporary hand-off file only on the selected destination drive. install.bat
copies only the contents of MATRIX\; SOURCE\ and DOCS\ are not copied into the
live game directory.

RUNLOCAL.BAT and EDITGAME.BAT are no longer included. Launch MATRIX.EXE /LOCAL
manually for local testing and run EDITOR.EXE directly for configuration.

INCLUDED DATA INTEGRITY / GAMEPLAY FIXES
------------------------------------------------
- Player locks are no longer stolen after five minutes. Stale crash locks
  require offline SysOp cleanup; see UPGRADE.TXT.
- Shared world saves merge each session's changes under a lock; they do not
  replace another session's entire world snapshot. Daily world randomization
  is a single locked operation. Editor saves preserve unrelated world changes.
- Invalid DAT+BAK records and orphan TMP files stop character creation instead
  of silently starting a replacement character. World corruption also fails closed.
- Failed critical saves stop play with a clear warning; commit/close failures
  are checked. Existing editor save/retry behavior remains available.
- Disconnects leave numeric prompts, character selection, training, the
  medical bay and gear sales without endless loops.
- Commons takes its own player lock during the synchronous handoff, and the
  parent reacquires/reloads on return. Direct Commons launches honor locks too.
- Oracle's Numbers uses seven guesses and a daily play limit; wagers are saved
  and are not refunded on disconnect/cancellation.
- Re-entry no longer refills zero Focus. Percentage losses and reward additions
  use overflow-safe arithmetic and the established balance cap.
- Existing DOS player/world formats remain compatible. See UPGRADE.TXT before
  replacing a live installation. Do not reset game state.

INCLUDED DOS FILE-I/O / SAVE-LATENCY FIX
---------------------------------------------------
ATDTBBS testing exposed a second source of delay that was independent of the
FOSSIL serial path: the small DOS runtime was performing byte-at-a-time disk
reads for ANSI/TEXT.DAT files and multiple forced DOS commit operations for a
single save. On host-mapped/emulated DOS filesystems those operations can be
far more expensive than on a physical FAT disk.

v0.3.3 reads ANSI/display files in 256-byte blocks, indexes TEXT.DAT once per
session, and checks carrier periodically while rendering runtime text. Player
and world loaders now validate each record with one file open, and unchanged
player/world records are not rewritten merely because a menu path calls save.
The custom DOS stdio layer no longer turns both fflush() and fclose() into extra
physical disk commits; explicit _commit() calls retain one durable commit for
critical save operations. The verified-temp + backup + rename protection remains.

This directly targets pauses seen entering the Oracle, opening Sparring with P,
returning from Jack In with H, and quitting the door. No player/world/config,
enemy, TEXT.DAT, or DISPLAY file format changed.

NEW IN v0.2.9 - ATDT / FOSSIL INPUT-LATENCY FIX
------------------------------------------------
v0.2.8 attempted to use FOSSIL function 19h block writes to reduce remote-screen
overhead. Some virtual FOSSIL implementations, including the ATDTBBS environment
tested during development, can stall badly on that call. The result can be a
10-15 second delay before a menu key is even processed.

v0.2.9 removes FOSSIL block writes and restores the proven function 01h
character-output path. The safe v0.2.8 optimization is retained: ANSI/display
rendering checks carrier periodically instead of after every byte. Input polling
continues to use one status result per pass with a short 5 ms idle wait.

No player, world, configuration, enemy, runtime-text, or display format changed.
For ATDTBBS, v0.2.9 is the recommended replacement for v0.2.8.

NEW IN v0.2.7 - CONSTRUCT TRAINING MENU FLOW / ALIGNMENT
----------------------------------------------------------
Construct Training now remains open after a training purchase and redraws with
the updated carried credits and remaining daily uploads. Insufficient credits,
no remaining uploads, and invalid selections also stay inside Construct Training.
Press Q to return to the main Zion menu.

The four training rows now use fixed columns for the program name, trained skill,
and right-aligned credit price so the ANSI menu remains lined up consistently.

NEW IN v0.2.6 - ARMORY RESALE / TRADE-IN
-----------------------------------------
Equipped weapons and armor can now be sold manually from Zion Armory for 50%
of their configured full purchase price. Buying a replacement automatically
trades the currently equipped item for the same 50% credit before affordability
is checked. Half-credit fractions round down to a whole credit. The Armory purchase
screens show the current item's trade-in value.

Zion Commons factory defaults now set the Oracle's Numbers net win multiplier
to 2. Existing customized MATRIX.CFG files retain their configured value unless
replaced or reset to factory defaults in EDITOR.EXE.

NEW IN v0.2.5 - EXTERNAL DISPLAY / ANSI MENU SYSTEM
----------------------------------------------------
All caller-facing menus and status/help displays are now external ANSI templates
in the DISPLAY\ directory.  SysOps can change colors, wording, borders and screen
layout without recompiling MATRIX.EXE or COMMONS.EXE. Dynamic values are inserted
at runtime with readable @TOKEN@ placeholders.

DISPLAY contains MATRIX.ANS, HELP1.ANS through HELP5.ANS, the main Zion menu,
character creation, Operative Status, vault, Morpheus, field medical, combat,
Matrix connection, mission warning, Keymaker encounter, sparring, training, armory,
weapon/armor lists, Medical Bay, and all Zion Commons displays. DISPLAY\README.TXT documents every filename and
available token.

Bare display filenames are resolved in DISPLAY\ first, with a root-directory
fallback for compatibility with older installs. MATRIX.CFG can therefore continue
to use IntroFile=MATRIX.ANS while the actual file resides in DISPLAY\MATRIX.ANS.

IMPORTANT: Keep the DISPLAY directory with the game. Menu command keys are still
implemented by the executables; changing a label does not change the accepted key.

RUNTIME TEXT CATALOG (TEXT.DAT)
-------------------------------
Most short caller-facing runtime messages are now stored in TEXT.DAT instead of
being compiled into MATRIX.EXE. This includes combat narration, random Matrix
events, mission text, medical/vault/training results, Armory/Oracle/PvP messages
and Morpheus guidance. The game opens TEXT.DAT only when a message is needed, so
the catalog does not consume resident DOS memory.

TEXT.DAT uses numeric IDs that must not be renumbered. It supports escaped ANSI
(\e), CR/LF (\r and \n), literal backslashes, and safe @TOKEN@ substitution.
Comments inside TEXT.DAT document the generic @S1@/@S2@ and @N1@-@N4@ context
tokens. Keep TEXT.DAT in the same directory as MATRIX.EXE.

CURRENT v0.2.5 GAMEPLAY REFINEMENTS
-----------------------------------
The Zion Credit Vault now treats an entered amount of 1 as a shortcut for ALL:
Deposit + 1 deposits all carried credits, and Withdraw + 1 withdraws all vault
credits that can fit in the carried-credit balance.

Oracle's Numbers now chooses one number from 1 through 100. A wager gives the
player seven guesses, with a default three-game daily limit, with HIGHER/LOWER guidance after every miss. The existing
SysOp wager cap and net-profit multiplier still control the betting economy.

Zion Missions now display a high-risk confirmation screen before a mission is
consumed. The player may continue or abort safely. Normal Matrix Sweeps also have
a rare 3% chance to encounter the Keymaker. The Keymaker offers three doors; one
contains a level-scaled random credit cache while the other two have no penalty.

NEW IN v0.2.4 - 20-ENEMY MATRIX CATALOG
------------------------------------------
The Matrix encounter roster has expanded from 9 to 20 enemies. Threats unlock
progressively through the level range and still use the existing level scaling,
mission bonuses and SysOp HP/Attack/Defense/reward multipliers. Agent Smith is
now a late-game threat while earlier Agents and Exiles fill the progression gap.

Enemy records were moved out of MATRIX.EXE into ENEMIES.DAT. This keeps the
16-bit real-mode executable within its protected memory/stack limit and means
future enemy expansion does not require storing every enemy record in the EXE.
ENEMIES.BAK is used as a fallback if ENEMIES.DAT is missing or invalid.

EDITOR.EXE -> [E] Enemy catalog editor displays the roster in two pages and can
edit each enemy's name, minimum level, base HP, Attack, Defense, XP, credits and
Agent/Smith flags. Enemy edits use ENEMIES.TMP -> verified DAT with BAK rotation.

NEW IN v0.2.3 - ZION COMMONS / STATUS POWER & DEFENSE
----------------------------------------------------------
Operative Status now displays the configured Power value of the equipped weapon
and Defense value of the equipped armor. These values come directly from the
current MATRIX.CFG armory settings.

The main menu now includes Zion Commons, a shared social area implemented by
COMMONS.EXE. Players can read/post messages on a shared operator wall, play
Oracle's Numbers with carried credits, see characters with active BBS session
locks, and read random operator rumors/tips. Vault credits are never wagered.

EDITOR.EXE adds Zion Commons settings for enabling the area/betting, maximum
wager, successful-game profit multiplier, and number of recent messages displayed.
Existing MATRIX.CFG files automatically receive the new defaults when loaded.
No player/world database schema change was required.

IMPORTANT: COMMONS.EXE must remain in the same directory as MATRIX.EXE. The main
game launches it transparently and reloads the player's verified record when the
caller returns to Zion.

NEW IN v0.2.2 - EDITOR ALIGNMENT / MEDICAL REBALANCE
------------------------------------------------------
SysOp configuration screens now use fixed columns so option keys, labels and
values line up consistently. Section titles are centered inside the editor frame.

New default medical settings are 1 credit per stabilization point, 20 carried
Med Patches, 5 credits to fabricate a Med Patch, and 5 Med Patches plus 100
credits to refine a Trauma Pack. Trauma Packs now completely restore both Health
and Focus whenever used. Untouched v0.2.1 medical defaults migrate automatically.

NEW IN v0.2.1 - ADVANCEMENT DETAILS / TRAINING COSTS / TITLE CLEANUP
---------------------------------------------------------------------
Successful Morpheus advancement now reports every value that actually increased,
including attributes, maximum Health/Focus, Health/Focus restored, retained XP,
and the XP target for the next level. XP remains cumulative and is not spent.

Construct Training now prints the current credit price beside every training choice
before the player selects it. The visible game title is now simply The Matrix.

NEW IN v0.2.0 - CREDIT VAULT / MATRIX ENTRY / MORPHEUS ADVANCEMENT
------------------------------------------------------------------
The main menu now includes a Zion Credit Vault. Credits deposited in the vault
are stored in the player record separately from carried credits. Only carried
credits can be reduced after a Matrix defeat or captured by another player in
Resistance Sparring. Deposit and withdrawal operations are saved immediately.

Jacking into the Matrix no longer immediately starts an encounter. The first
screen inside the Matrix presents Sweep, Field Medical and Hardline choices. A
Matrix Run is consumed only when the player explicitly chooses Sweep.

Level advancement is now manual. Earning enough XP marks the character READY
for advancement, but does not automatically raise the level. Visit Morpheus
from the main menu to see the XP requirement and advance one level at a time.
Morpheus restores Health/Focus and gives a short piece of guidance after each
successful advancement.

Player records were upgraded to add Vault Credits. Existing v0.1.2-v0.1.9
characters are automatically migrated with a starting vault balance of zero.
The previous verified data file is protected during migration.

EDITOR.EXE now includes a Zion Credit Vault feature switch and lets the SysOp
edit both carried and vault credit balances in the Player Editor.

NEW IN v0.1.9 - EXPANDED ZION ARMORY
------------------------------------
The Zion Armory now has 15 purchasable weapons and 15 purchasable armor sets,
plus the existing Unarmed and Street Clothes defaults. Prices and combat values
escalate through the equipment tiers. Existing item IDs 1-6 for weapons and
1-4 for armor were preserved so existing player equipment remains compatible.

EDITOR.EXE now separates Armory Settings into Weapons and Armor lists. All 15
items in each category are displayed at once; choose an item number to edit its
Price and Power/Defense. Player Editor equipment selection also supports every
new item.

NEW IN v0.1.7 - IN-GAME HELP / HOW TO PLAY
---------------------------------------------
The main game menu now includes:

    [?] Help / How to Play

Help is five pages and pauses on every page. Use N or ENTER to go forward,
B (or P) to go back, and Q or ESC to return to the main game menu. The pages
explain the overall daily loop, every main-menu option, Matrix combat controls,
progression/equipment/medical systems, multiplayer features and beginner tips.

Help content is stored in DISPLAY\HELP1.ANS through DISPLAY\HELP5.ANS. They are
part of the external display system, so a SysOp can customize the wording or ANSI
layout without recompiling the door.

NEW IN v0.1.6 - SINGLE-SCREEN MATRIX SPLASH
------------------------------------------------
DISPLAY\MATRIX.ANS is now a strict single 80x25 screen. The splash includes its own
startup menu and the game no longer prints a version line or Press any key
prompt below the artwork.

    E or ENTER   Enter the Matrix
    Q            Quit to the real world / return to the BBS

The supplied ANSI contains exactly 25 visible rows, has no trailing CR/LF after
row 25, and keeps every row under 80 columns so it will not scroll an 80x25 DOS
terminal.

NEW IN v0.1.5 - POLISHED SYSOP CONTROL CENTER
------------------------------------------------
The main EDITOR.EXE screen is grouped into Configuration, Data Administration
and File Actions. It shows the active BBS/game identity and a clear SAVED or
UNSAVED CHANGES status line. Section screens use a consistent Matrix-style
header and short usage hints.

The main menu has two distinct exit paths:

    Q  Save and Exit
    X  Exit Without Saving

If X is selected while MATRIX.CFG has unsaved changes, EDITOR.EXE asks for
confirmation and discards only those pending configuration changes. Player
records and WORLD.DAT are separate live data files and are not rolled back by
X if they were previously saved.

The live WORLD.DAT editor has explicit Save and Discard actions, and the player
editor shows whether its in-memory record has been modified before you save or
discard it.

NEW IN v0.1.4 - MENU-BASED SYSOP EDITING
-----------------------------------------
Every editor section now opens as a numbered settings screen. All current
values in that section are displayed at once. Choose only the setting you want
to change, enter its new value, and the section redraws with the updated value.
You no longer have to step through every setting and press ENTER to keep the
ones you do not want to change.

The same interface is used inside the player editor: progression, attributes,
skills, equipment, medical inventory, daily access, lifetime/story values and
identity/class are all selectable field-by-field. Armory items also open a
small Price/Power or Price/Defense menu instead of forcing both values.

NEW IN v0.1.3 - SYSOP CONFIGURATION / EDITOR
--------------------------------------------
MATRIX.CFG now holds the SysOp-tunable game configuration. It is a normal
key=value text file and can be edited by hand, but EDITOR.EXE is the preferred
way to change it.

Run:

    EDITOR.EXE

The DOS SysOp editor can change:

  * BBS name, SysOp name, game title and opening ANSI filename
  * Game enabled/disabled, new-player access, PvP, Oracle and news switches
  * Daily Matrix runs, training, missions and PvP limits
  * Starting credits, starting medical inventory, base stats and skill level
  * Maximum level and XP progression factors
  * Medical Bay prices, healing amounts, carry limits and Trauma refinement
  * Training economy
  * Death penalty, encounter chance, Agent/Smith rates and combat difficulty
  * XP/credit reward multipliers and escape chances
  * Zion mission rewards and PvP credit-transfer rules
  * World defaults and daily activity ranges
  * Every armory weapon price/power and armor price/defense value
  * Current WORLD.DAT activity/strength values
  * Individual player records

PLAYER EDITOR
-------------
EDITOR.EXE scans DATA\P*.DAT and presents valid characters. It refuses to edit
a character that is currently locked by another node.

For a player it can edit:

  * Handle and class
  * Level, XP, credits, current/max HP and Focus
  * Strength, Speed, Focus Stat, Intelligence, Perception and Willpower
  * Kung Fu, Firearms and Hacking
  * Weapon and armor
  * Med Patch / Trauma Pack inventory
  * Remaining Matrix, training, mission and PvP turns
  * Oracle-use flag
  * Total kills, Agent kills, deaths, total earned credits and story stage
  * Full heal
  * Reset today's access to the current SysOp defaults

The BBS user ID is intentionally displayed but not editable because the player
filename is tied to that ID.

CONFIGURATION SAFETY
--------------------
EDITOR.EXE writes MATRIX.TMP first, reloads and validates it, rotates a valid
MATRIX.CFG to MATRIX.BAK, and only then promotes the new configuration. If the
live CFG is invalid, an existing valid BAK is preserved.

MATRIX.EXE also validates MATRIX.CFG at startup. If it is missing/corrupt but a
valid MATRIX.BAK exists, the backup is loaded and restored automatically. If
neither exists, safe defaults are created.

PLAYER / WORLD DATA SAFETY
--------------------------
Player records remain CRC-protected and older characters convert automatically
to include daily gambling usage. World records retain their existing format.

Data files continue to use verified TMP -> BAK -> DAT replacement. Zero-byte,
truncated, invalid-size, wrong-magic and bad-CRC DAT files are rejected and a
verified BAK is used when available. Invalid DAT files are never allowed to
replace a known-good BAK during a save.

OTHER GAMEPLAY FEATURES
-----------------------
  * ENTER is the default normal Attack key in combat
  * A successful Matrix fight keeps the connection active for another sweep
  * Med Patches and Trauma Packs can be carried and used in the field/combat
  * Medical supplies can be fabricated/refined in Zion
  * Six character classes
  * Matrix encounters and random events
  * Agent Brown, Agent Jones and Agent Smith
  * Zion missions, Oracle, training, armory and PvP sparring
  * Shared network news and world state
  * DOOR.SYS + FOSSIL INT 14h remote I/O
  * Built-in local ANSI rendering (ANSI.SYS is not required for /LOCAL)

CPU REQUIREMENT
---------------
The supplied MATRIX.EXE, COMMONS.EXE and EDITOR.EXE are MS-DOS MZ executables running in
16-bit real mode and use 80386+ instructions. A 386 or newer CPU/emulated CPU
is required.

SPLASH SCREEN
-------------
DISPLAY\MATRIX.ANS is a fixed 80x25 Matrix-code screen. Press E or ENTER to enter the game; press Q to return to the BBS.

NEWS AND MENU UPDATE (v0.3.3)
----------------------------
Zion Network News keeps events from the past ten days (240 hours), pruning
NEWS.DAT when news is viewed or added. The screen shows the latest 12 entries.
No background cleanup runs while the door is idle. Retention uses the DOS
system clock. NEWS.LCK serializes updates; NEWS.TMP/BAK protect replacement.
Menus now use bright white hotkeys and spaced, colored player status values.
Install the supplied MATRIX.EXE, COMMONS.EXE and EDITOR.EXE together, and copy
DISPLAY and TEXT.DAT (merge any local display/text customizations as needed).
Keep your live MATRIX.CFG, DATA and enemy files; no configuration edit is needed.

LEVEL ADVANCEMENT REWARD (v0.3.3)
-------------------------------
Each accepted advancement with Morpheus grants 250 x (new level - 1) carried
credits: level 2 gives 250, level 5 gives 1,000, level 10 gives 2,250.
The reward and new level save together. Existing credit caps apply.
Existing characters receive rewards for future advancements only. No player
format or live MATRIX.CFG change is required.
