THE MATRIX v0.3.3 - SYSOP GUIDE

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

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.


FILES
-----
MATRIX.EXE    The BBS door game
COMMONS.EXE   Zion Commons social/betting companion launched by MATRIX.EXE
EDITOR.EXE    Local DOS SysOp configuration/player editor
MATRIX.CFG    Human-readable game configuration
TEXT.DAT      External caller-facing runtime-message catalog
MATRIX.BAK    Last verified configuration (created after saves)
MATRIX.TMP    Temporary configuration file (normally absent)
DISPLAY\       External caller display/menu directory
  MATRIX.ANS    Opening Matrix-code ANSI
  MAIN.ANS      Main Zion menu
  CREATE.ANS    New-character discipline menu
  STATUS.ANS    Operative Status
  VAULT.ANS     Zion Credit Vault
  MORPH*.ANS    Morpheus status/advancement menus
  FIELDMED.ANS  Field-medical choice
  COMBAT.ANS    Per-round combat commands
  JACKIN.ANS    Matrix connection / Sweep menu
  MISNWARN.ANS Zion mission risk/confirmation screen
  KEYMAKER.ANS  Rare Keymaker three-door encounter
  SPARRING.ANS  Resistance Sparring opponent menu
  TRAINING.ANS  Construct Training menu
  ARMORY.ANS    Zion Armory category menu
  WEAPONS.ANS   Weapon purchase-list shell
  ARMOR.ANS     Armor purchase-list shell
  SELLGEAR.ANS  Equipped gear resale screen
  MEDBAY.ANS    Zion Medical Bay menu
  COMMONS.ANS   Zion Commons main menu
  WALL.ANS      Operator Wall heading
  POST.ANS      Operator Wall posting prompt
  ACTIVE.ANS    Active Operatives heading
  RUMOR.ANS     Operator Rumor display
  GAMBLE.ANS    Oracle's Numbers betting screen
  HELP1.ANS     Help / How to Play page 1
  HELP2.ANS     Help / How to Play page 2
  HELP3.ANS     Help / How to Play page 3
  HELP4.ANS     Help / How to Play page 4
  HELP5.ANS     Help / How to Play page 5
  README.TXT    Display filenames and dynamic-token reference
ENEMIES.DAT   Active 20-enemy Matrix encounter catalog
ENEMIES.BAK   Previous/fallback enemy catalog
ENEMIES.TMP   Temporary enemy catalog file (normally absent)
ENEMIES.TXT   Human-readable default enemy list/reference
DATA\         Shared game database directory


EXTERNAL DISPLAY FILES
----------------------
All caller-facing menu/status/help ANSI files now live in DISPLAY\. This includes
the opening MATRIX.ANS and HELP1.ANS through HELP5.ANS. The menu files use dynamic
@TOKEN@ placeholders for values such as handle, credits, HP, equipment and world
status. See DISPLAY\README.TXT for the complete file and token reference.

You can edit colors, borders, wording and placement without replacing an EXE. Keep
command keys consistent with the game logic, keep classic caller screens at 80
columns, and do not add a screen clear to inline COMBAT.ANS or FIELDMED.ANS.

RUNTIME TEXT CATALOG
--------------------
TEXT.DAT contains most short runtime narration and result messages used by
MATRIX.EXE. Numeric IDs are part of the executable contract and must not be
renumbered. Each record is one physical line in ID=text form and should remain
under 255 bytes. The header comments in TEXT.DAT document ANSI/control escapes
and dynamic substitution tokens. Keep TEXT.DAT beside MATRIX.EXE.

EDITOR.EXE MAIN MENU
--------------------
1  BBS / access / feature switches
2  Daily limits / new-player / leveling
3  Medical Bay
4  Training economy
5  Combat / rewards / difficulty
6  Mission / PvP economy
7  World defaults / daily ranges
8  Armory prices / power / defense
9  Zion Commons / social / gambling
P  Player database editor
W  Current WORLD.DAT editor
E  Enemy catalog editor
D  Load factory defaults into memory
S  Save MATRIX.CFG now
Q  Save and exit
X  Exit without saving pending MATRIX.CFG changes

EXIT / SAVE BEHAVIOR
--------------------
The editor now shows either SAVED or UNSAVED CHANGES on the main screen.

S writes MATRIX.CFG but keeps the editor open.
Q saves pending MATRIX.CFG changes and exits.
X exits without saving pending MATRIX.CFG changes. If changes exist, you must
confirm the discard first.

Player records and WORLD.DAT are separate live-data editors. Their Save/Discard
commands apply immediately to those files and are not rolled back later by X
on the main menu.

SECTION EDITING
---------------
Selecting menu items 1 through 9 now displays every setting and its current
value for that section. Enter the number beside the one setting you want to
change. After the edit, the same section screen is redrawn with the new value.
Enter 0 to return to the main SysOp menu.

This field-by-field menu behavior is also used by the player editor and current
WORLD.DAT editor. You are never required to walk through every value in a
section just to change one setting.

MATRIX.CFG NOTES
----------------
MATRIX.CFG is key=value text. Lines beginning with ; or # are comments.
Unknown keys are ignored so future versions can add options safely.

Boolean settings use 1 for YES/ENABLED and 0 for NO/DISABLED.

The game clamps unsafe/out-of-range values when loading or saving the file.
EDITOR.EXE also constrains entries to supported ranges.

Changing daily limits does not magically add turns to a player who is already
mid-day. The new limits are applied on that player's next daily reset. To apply
them immediately to one player, use Player Editor -> Reset daily access.

World "Initial" settings apply when WORLD.DAT is first created. The daily min/
max values apply when a new game day is detected. Use Current WORLD.DAT editor
to change the running world immediately.

CONFIG GROUPS
-------------
BBS / ACCESS:
  BBSName, SysopName, GameName, IntroFile
  GameEnabled, AllowNewPlayers, EnablePvP, EnableOracle, EnableNews, EnableBank
  EnableCommons, EnableCommonsGambling

DAILY / NEW PLAYER:
  DailyMatrixRuns, DailyTrainingRuns, DailyMissionRuns, DailyPvPRuns
  DailyFullHeal
  StartingCredits, StartingMedPatches, StartingTraumaPacks
  StartingBaseStat, StartingSkillLevel
  MaxLevel, XPLevelFactor, XPBase

MEDICAL:
  HealCostPerPoint
  MaxMedPatches, MaxTraumaPacks
  MedPatchHeal
  TraumaPackHeal, TraumaPackFocus (legacy numeric keys; Trauma Packs now fully
  restore both meters regardless of these values)
  MedPatchCost, TraumaRefinePatches, TraumaRefineCost

TRAINING:
  TrainingBaseCost, TrainingPerLevel, FocusTrainingSurcharge
  Players see the calculated cost beside each Construct Training option.

COMBAT / REWARDS:
  DeathCreditLossPercent
  RandomEventChancePercent
  AgentChanceNormalPercent, AgentChanceMissionPercent
  SmithChanceNormalPercent, SmithChanceMissionPercent
  EnemyHPPercent, EnemyAttackPercent, EnemyDefensePercent
  RewardXPPercent, RewardCreditsPercent
  EscapeBaseChance, EscapeAgentPenalty, EscapeMinChance, EscapeMaxChance

MISSIONS / PVP:
  MissionBonusBase, MissionBonusPerLevel
  MissionXPBase, MissionXPPerLevel
  PvPStealPercent, PvPStealBaseCap, PvPStealCapPerLevel


ZION COMMONS:
  CommonsMaxWager
  CommonsWinMultiplier (net profit multiplier after solving Oracle's Numbers)
  CommonsMessagesShown (3-12 recent wall messages)

  COMMONS.EXE must be in the same directory as MATRIX.EXE. The shared operator
  wall is DATA\COMMONS.MSG and multi-node writes are serialized by COMMONS.LCK.
  It is append-only, so a failed post cannot truncate the existing conversation.
  Oracle's Numbers uses a 1-100 target with seven HIGHER/LOWER guesses and a default three-game daily limit.
  Default net win multiplier in v0.2.6 is 2.
  Gambling uses carried credits only; Zion Vault funds remain protected.
  Do not expose COMMONS.EXE directly as a BBS door; MATRIX.EXE launches it while
  transferring the character lock to Commons, then reacquiring and reloading
  the verified record on return. All three executables honor active locks.

WORLD:
  InitialMachineAlert, InitialSentinelActivity
  InitialAgentActivity, InitialZionStrength
  DailyMachineMin/Max, DailyAgentMin/Max, DailySentinelMin/Max

ARMORY:
  Weapon0Price through Weapon15Price
  Weapon0Power through Weapon15Power
  Armor0Price through Armor15Price
  Armor0Defense through Armor15Defense

  Item 0 is the free default (Unarmed / Street Clothes).
  Purchasable equipment is numbered 1 through 15.
  All Armory sales and replacement trade-ins return 50% of configured price
  (rounded down to a whole credit when necessary).



ENEMY CATALOG
-------------
Combat enemies live in ENEMIES.DAT rather than being hard-coded into MATRIX.EXE.
Use EDITOR.EXE -> E to browse all 20 records and change name, minimum level, base
Health, Attack, Defense, XP reward, credit reward, Agent status and Agent Smith
priority. The game automatically falls back to ENEMIES.BAK if ENEMIES.DAT cannot
be opened or has an invalid header.

Base enemy values are further modified at runtime by player-level scaling, Zion
mission bonuses, and the global EnemyHP/Attack/Defense and reward percentages in
MATRIX.CFG. Normal Matrix sweeps only use threats whose minimum level is at or
below the player's level. Zion missions may reach two levels above the player.

Enemy edits are saved independently of MATRIX.CFG. EDITOR.EXE writes ENEMIES.TMP,
validates it, preserves the current good DAT as ENEMIES.BAK, then promotes the
new catalog. Do not delete both ENEMIES.DAT and ENEMIES.BAK.

ZION CREDIT VAULT
-----------------
EnableBank controls whether players can access the vault. Vault balances live in
each player record. Matrix death penalties and PvP capture are intentionally
calculated only from carried credits; vault credits are never exposed to those
losses. The Player Editor can change either balance.

LEVEL ADVANCEMENT
-----------------
XP is cumulative, but levels are no longer granted automatically. Players must
visit Morpheus after meeting the configured XP requirement. MaxLevel,
XPLevelFactor and XPBase continue to control advancement thresholds.
The advancement result screen reports all actual stat/max gains and retained XP.

BACKUPS
-------
Keep MATRIX.BAK and DATA\*.BAK. They are the verified rollback copies used by
the recovery logic. Do not use cleanup jobs that indiscriminately delete BAK
files from the game directory.

MS-DOS 6.22 installer note:
INSTALL.BAT supports read-only source media such as CD-ROM. Use DOS 8.3
destination folder names with no spaces.

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.

OPERATIONAL RECOVERY
--------------------
Read UPGRADE.TXT for crash-lock cleanup and damaged-record recovery. Never
automatically delete locks by age. Stop all nodes before clearing crash locks.
Committed gambling stakes are forfeited on cancellation/disconnect. At the
default payout and wager cap, three daily games cap profit at 6,000 credits.
CommonsDailyGames configures the allowance; missing keys default to three.

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.
