diff --git a/HISTORY.md b/HISTORY.md index 00a54913..d516ec3e 100644 --- a/HISTORY.md +++ b/HISTORY.md @@ -30,7 +30,9 @@ Geographic League, VWE's fiction). Pods booted via `BOOTPOD.BAT`, pulled game builds from the server share **`\\vgl_code\podbay`**, and each developer had a named update script: Chris, Gabe, Edo, Joanna, Jordan, Milo, Kiwi, Shroom, Splotch, Bernoulli, and Golden (the golden/release build, default -game BT). The boot configuration documents the pod peripherals: Thrustmaster +game BT). Several match the published team credits (see "The team" in +[README.md](README.md)): Chris Brewer, Gabe Underwood, Joanna Mason, and +Jordan Weisman. The boot configuration documents the pod peripherals: Thrustmaster controls, a 640x480x16 gauge display, a plasma display on COM2, intercom, and SVGA-or-NTSC main video output. diff --git a/README.md b/README.md index d69f2005..635101f1 100644 --- a/README.md +++ b/README.md @@ -133,6 +133,51 @@ INI-style calibration files (`.XST/.CAM/.BAK`) defining viewing extents and camera offsets ("head offset") for the cockpit's main display, including a `[LAB_ONLY]` configuration. +## The team + +From a published VWE BattleTech credits page (scan supplied to this archive, +July 2026). The roster matches the 1994–1996 source in this tree — see the +cross-references below the table. + +| Role | Name(s) | +|------|---------| +| Producer and Designer | Jordan Weisman | +| Art Director | David McCoy | +| Technical Director | J.M. Albertson | +| Audio Director | Eric Huffman | +| Corporate Director of Technology | Bill Redmann | +| **Software Engineers** | | +| — Framework and Simulation Design | J.M. Albertson | +| — Secondary/Auxiliary Screens and Low Level I/O | Chris Brewer | +| — Low Level I/O Design and Programming | Marek Ciolek | +| — Framework and 3D Video Rendering | Greg Corson | +| — Animation Simulations and Tools | Jerry Edsall | +| — Macintosh Design and Programming | Garth Hermanson | +| — Framework and 3D Audio System | Eric Huffman | +| — Simulation Code and Cameras | Joanna Mason | +| — Graphics Research and Art Tools | Ken Olsen | +| — Simulation Code and 'Mech Internal Systems | Gabe Underwood | +| **Artists & Animators** | | +| — 3D Art and Animations | Tom Burlington, Duane Molitor, David McCoy, Lex Story | +| — Allen Workshop 2D Art | Victor Bonilla, Tom Peters | +| Software Tools Group Leader | Ken Olsen | +| Sound Samples/Designs | Bing McCoy, Tom Effinger, Eric Huffman | + +Cross-references to this tree: + +- `// Author:` headers in `CODE/` name four of the credited engineers: + **J.M. Albertson** (MUNGA math/debug bricks — `LINE`, `SPHERE`, `DEBUG*`), + **Jerry Edsall** (`TOOL`, `FILEUTIL`, the BT/RP `*TOOL` modules), + **Ken Olsen** (`NAMELIST`, `NOTATION` template containers), and + **Eric Huffman** (`CSTR`, `MEMREG`, `SCHAIN`). +- The pod-lab per-developer update scripts on the recovered developer drive + (see [HISTORY.md](HISTORY.md)) are named Chris, Gabe, Joanna, and Jordan — + matching **Chris Brewer**, **Gabe Underwood**, **Joanna Mason**, and + **Jordan Weisman**. +- **Garth Hermanson**'s "Macintosh Design and Programming" credit fits the + venue side: the operator console the pods connect to was a Macintosh + application. + ## Provenance - Copyright (C) 1994–1996 Virtual World Entertainment, Inc. All rights diff --git a/context/README.md b/context/README.md new file mode 100644 index 00000000..90a84866 --- /dev/null +++ b/context/README.md @@ -0,0 +1,125 @@ +# Context index — all project documentation + +A single map of every hand-written `.md` in this repo, grouped by area with a +one-line description and a link. Use it to find the right note without grepping. + +> **Scope:** project-authored docs only. ~70 vendored/third-party READMEs (the +> DOSBox-X fork under [`emulator/src/`](../emulator/src/), SDL2, libpng, +> libpdcurses, freetype) are intentionally omitted — they document upstream +> libraries, not this project. + +> **Keeping this current:** the linked list below is generated. Run +> `context/gen-index.sh` to check for drift (new/removed docs) and +> `context/gen-index.sh --write` to regenerate it. Hand-written descriptions are +> preserved across regenerations; only the block between the AUTOGEN markers is +> touched, so edit descriptions freely — just keep them inside that block. + +--- + + +## Orientation + +- [HISTORY.md](../HISTORY.md) — provenance of the recovered developer drive ("Glaze"/`sda4`) that sits alongside the release tree. +- [README.md](../README.md) — repo overview: source + content for Tesla:BattleTech and Tesla:Red Planet (Release 4.10). + +## Emulator — plan, phases & operations + +- [emulator/ENV-VARS.md](../emulator/ENV-VARS.md) — environment variables for both the pod (game) and host (emulator). +- [emulator/LAUNCH.md](../emulator/LAUNCH.md) — pod launch cheat-sheet (all commands, non-elevated PowerShell). +- [emulator/PHASE0-RESULTS.md](../emulator/PHASE0-RESULTS.md) — Phase 0: baseline DOS boot test (complete). +- [emulator/PHASE1-RESULTS.md](../emulator/PHASE1-RESULTS.md) — Phase 1: interface discovery via a VPX link-adapter logging build (complete). +- [emulator/PHASE2-PROGRESS.md](../emulator/PHASE2-PROGRESS.md) — Phase 2: boot-protocol emulation — handshake, i860 download, FIFO transport. +- [emulator/PHASE3-PROGRESS.md](../emulator/PHASE3-PROGRESS.md) — Phase 3: render backend (3a/3b/3c command decode + bridge). +- [emulator/PLAN.md](../emulator/PLAN.md) — master implementation plan for running unported DOS BattleTech/Red Planet under VPX emulation. + +## Emulator — subsystems + +- [emulator/CAMERA-REVIEW-NOTES.md](../emulator/CAMERA-REVIEW-NOTES.md) — how the games did Live Cam & Mission Review (spool replay, host roles). +- [emulator/GAUGE-NOTES.md](../emulator/GAUGE-NOTES.md) — the cockpit gauge / secondary-display path (5 mono MFDs + color radar). +- [emulator/NET-NOTES.md](../emulator/NET-NOTES.md) — networking subsystem recon & bring-up plan for pod boot/mesh. +- [emulator/RENDER-HARNESS.md](../emulator/RENDER-HARNESS.md) — FLYK + the VWETEST diagnostic suite as a render harness. +- [emulator/RENDERER-COLLAB.md](../emulator/RENDERER-COLLAB.md) — shared working log for the two renderer efforts (VPX/Division backend). +- [emulator/RIO-NOTES.md](../emulator/RIO-NOTES.md) — RIO cockpit-controls passthrough tuning (COM1 input board). +- [emulator/SOUND-NOTES.md](../emulator/SOUND-NOTES.md) — audio subsystem recon & plan (AWE32/SOS clock, faithful bring-up). +- [emulator/VDB-NOTES.md](../emulator/VDB-NOTES.md) — the VWE Video Distribution Board: one framebuffer → six cockpit displays. + +## Emulator — deployment & ports + +- [emulator/DEPLOYMENT-PLAN.md](../emulator/DEPLOYMENT-PLAN.md) — network-agnostic pod-bay deployment (pcap bridge, two-IP design, mesh). +- [emulator/EGRESS-HOLD-FIX-PLAN.md](../emulator/EGRESS-HOLD-FIX-PLAN.md) — egress-hold / floor-lighting investigation (CLOSED, won't-fix; findings kept). +- [emulator/XP-PORT-PLAN.md](../emulator/XP-PORT-PLAN.md) — one archive from Windows XP → Windows 11 (back-burnered fleet plan). + +## Emulator — devices & support files + +- [emulator/deploy/README.md](../emulator/deploy/README.md) — install-side artifacts for the self-contained, air-gapped pod install. +- [emulator/net-boot/README.md](../emulator/net-boot/README.md) — files the pod mounts as `D:` when booting the networked path. +- [emulator/pod-launch/README.md](../emulator/pod-launch/README.md) — the supervising launch entry-point for both DOSBox titles. +- [emulator/rio-firmware/README.md](../emulator/rio-firmware/README.md) — RIO cockpit I/O board firmware dump (v4.2). +- [emulator/rio-firmware/RIOv4_2-ANALYSIS.md](../emulator/rio-firmware/RIOv4_2-ANALYSIS.md) — RIO v4.2 firmware RE: the protocol-wedge analysis. +- [emulator/roms/README.md](../emulator/roms/README.md) — card ROM dumps (AWE32 1MGM sample ROM, etc.). +- [emulator/vpx-device/README.md](../emulator/vpx-device/README.md) — VPX + AWE32 emulated-hardware sources for the DOSBox-X integration. +- [emulator/vpx-device/serialport/README.md](../emulator/vpx-device/serialport/README.md) — modified DOSBox-X serial passthrough (RIO latency options). + +## Emulator — VelociRender firmware decompilation + +- [emulator/firmware-decomp/FPGA-RECONSTRUCTION.md](../emulator/firmware-decomp/FPGA-RECONSTRUCTION.md) — reconstructing the VelociRender in hardware (FPGA design note). +- [emulator/firmware-decomp/GPU-RETARGET.md](../emulator/firmware-decomp/GPU-RETARGET.md) — GPU-compute retarget: the DOSBox-renderer shipping path. +- [emulator/firmware-decomp/HARDWARE-ARCHITECTURE.md](../emulator/firmware-decomp/HARDWARE-ARCHITECTURE.md) — the card's hardware architecture, reconstructed for emulation (+ photo inventory). +- [emulator/firmware-decomp/IG-SHADING-MODEL.md](../emulator/firmware-decomp/IG-SHADING-MODEL.md) — the IG-board shading model, ground truth distilled from shipped libDPL. +- [emulator/firmware-decomp/IGC-ENCODING-DERIVATION.md](../emulator/firmware-decomp/IGC-ENCODING-DERIVATION.md) — IGC instruction-word encoding derived from EOF.C ↔ EOF.S (Tier-1 decoder). +- [emulator/firmware-decomp/M4-LIVE-SEAM.md](../emulator/firmware-decomp/M4-LIVE-SEAM.md) — M4: the live DOSBox seam design note. +- [emulator/firmware-decomp/M4B-RESULTS.md](../emulator/firmware-decomp/M4B-RESULTS.md) — M4b: offline end-to-end renderer-chain results. +- [emulator/firmware-decomp/M5-TEXTURING.md](../emulator/firmware-decomp/M5-TEXTURING.md) — M5: faithful texturing, the last mile to recognizable frames. +- [emulator/firmware-decomp/MICROCODE-DECODE-NOTES.md](../emulator/firmware-decomp/MICROCODE-DECODE-NOTES.md) — PXPL5 IGC micro-code decode working notes (ground/sky path). +- [emulator/firmware-decomp/PVISION-IMPLEMENTATION-GUIDE.md](../emulator/firmware-decomp/PVISION-IMPLEMENTATION-GUIDE.md) — implementing IR / "Predator" vision in a VelociRender renderer. +- [emulator/firmware-decomp/README.md](../emulator/firmware-decomp/README.md) — decompilation reference hub (make this the authoritative VelociRender answer). +- [emulator/firmware-decomp/i860-encoding.md](../emulator/firmware-decomp/i860-encoding.md) — i860 instruction encoding, validated against our own object files. + +## Emulator — render bridge + +- [emulator/render-bridge/COCKPIT-CAGE-NOTES.md](../emulator/render-bridge/COCKPIT-CAGE-NOTES.md) — cockpit cage, glances, and the "black rear view" (canopy/twist forensics). +- [emulator/render-bridge/DEATH-SEQUENCE-NOTES.md](../emulator/render-bridge/DEATH-SEQUENCE-NOTES.md) — death-sequence camera findings. + +## dpl3-revive — DPL3 renderer port & format specs + +- [dpl3-revive/README.md](../dpl3-revive/README.md) — porting the VWE DPL3 renderer (BattleTech / Red Planet). +- [dpl3-revive/patha/CAPTURE.md](../dpl3-revive/patha/CAPTURE.md) — capturing real FLYK.EXE link traffic (Path A validation). +- [dpl3-revive/spec/B2Z_FORMAT.md](../dpl3-revive/spec/B2Z_FORMAT.md) — the DIV-BIZ2 (`.B2Z`/`.V2Z`) binary geometry format. +- [dpl3-revive/spec/MAP_FORMAT.md](../dpl3-revive/spec/MAP_FORMAT.md) — `.MAP` game maps and `.MOD` game objects (playable worlds). +- [dpl3-revive/spec/SCN_FORMAT.md](../dpl3-revive/spec/SCN_FORMAT.md) — `.SCN` scene format (from FLYK.C). +- [dpl3-revive/spec/SPL_FORMAT.md](../dpl3-revive/spec/SPL_FORMAT.md) — `.SPL` camera-path spline format (from SPLINE.C). +- [dpl3-revive/spec/SVT_FORMAT.md](../dpl3-revive/spec/SVT_FORMAT.md) — `.SVT` texture format (from DPL_LOAD.C `load_svt()`). +- [dpl3-revive/spec/VELOCIRENDER_PROTOCOL.md](../dpl3-revive/spec/VELOCIRENDER_PROTOCOL.md) — the VelociRender wire protocol (run the original binary unmodified). + +## restoration — scene re-renders + +- [restoration/README.md](../restoration/README.md) — modern re-renderings of the Division dVS scenes recovered from the Glaze drive. + +## restoration — RIO firmware & hardware + +- [restoration/rio-firmware/README.md](../restoration/rio-firmware/README.md) — RIO board firmware (owner-facing entry point). +- [restoration/rio-firmware/RIOv4_2-ANALYSIS.md](../restoration/rio-firmware/RIOv4_2-ANALYSIS.md) — RIO v4.2 firmware RE: protocol-wedge analysis. +- [restoration/rio-firmware/wedge-explained.md](../restoration/rio-firmware/wedge-explained.md) — plain-language "why the stick died mid-battle" for pod owners. +- [restoration/rio-hardware/README.md](../restoration/rio-hardware/README.md) — RIO cockpit hardware: boards, schematics, GAL dump. +- [restoration/rio-hardware/display-board-1408.md](../restoration/rio-hardware/display-board-1408.md) — Display Board 1408 outputs and what the RIO shows on it. +- [restoration/rio-hardware/gal/README.md](../restoration/rio-hardware/gal/README.md) — U7 GAL20V8A decode: the recovered RIO memory map. + +## restoration — source410 reconstruction + +- [restoration/source410/BT/BTCNSL.NOTES.md](../restoration/source410/BT/BTCNSL.NOTES.md) — BTCNSL reconstruction notes. +- [restoration/source410/BT/BTPLAYER.NOTES.md](../restoration/source410/BT/BTPLAYER.NOTES.md) — BTPLAYER reconstruction notes (ctor/Make/experience level). +- [restoration/source410/BT/BTSCNRL.NOTES.md](../restoration/source410/BT/BTSCNRL.NOTES.md) — BTSCNRL reconstruction notes. +- [restoration/source410/BT/MECH-LAYOUT.md](../restoration/source410/BT/MECH-LAYOUT.md) — MECH.HPP staging worksheet (the mech-family working ledger). +- [restoration/source410/BT/MECH.NOTES.md](../restoration/source410/BT/MECH.NOTES.md) — MECH.CPP/.HPP reconstruction notes. +- [restoration/source410/BT/MECHSUB.NOTES.md](../restoration/source410/BT/MECHSUB.NOTES.md) — MECHSUB reconstruction notes. +- [restoration/source410/BT/NAMEFILT.NOTES.md](../restoration/source410/BT/NAMEFILT.NOTES.md) — NAMEFILT reconstruction notes. +- [restoration/source410/BT/SENSOR.NOTES.md](../restoration/source410/BT/SENSOR.NOTES.md) — SENSOR reconstruction notes. +- [restoration/source410/BT/SEQCTL.NOTES.md](../restoration/source410/BT/SEQCTL.NOTES.md) — SEQCTL reconstruction notes. +- [restoration/source410/BT/STAGED-HEADERS.NOTES.md](../restoration/source410/BT/STAGED-HEADERS.NOTES.md) — the 13 headers that closed the tree's compile (shared notes). +- [restoration/source410/BT_L4/BTL4.NOTES.md](../restoration/source410/BT_L4/BTL4.NOTES.md) — BTL4.CPP reconstruction notes (launch path). +- [restoration/source410/BT_L4/BTL4APP.NOTES.md](../restoration/source410/BT_L4/BTL4APP.NOTES.md) — BTL4APP.CPP reconstruction notes (12/12 functions). +- [restoration/source410/MUNGA/ALARM.NOTES.md](../restoration/source410/MUNGA/ALARM.NOTES.md) — ALARM.HPP reconstruction notes. +- [restoration/source410/MUNGA/BACKFILLS.NOTES.md](../restoration/source410/MUNGA/BACKFILLS.NOTES.md) — engine header backfills, shared per-file evidence. +- [restoration/source410/MUNGA/VDATA.NOTES.md](../restoration/source410/MUNGA/VDATA.NOTES.md) — VDATA.HPP: the first engine-side header backfill. +- [restoration/source410/README.md](../restoration/source410/README.md) — overview of the missing-source reconstruction effort. + diff --git a/context/gen-index.sh b/context/gen-index.sh new file mode 100644 index 00000000..05203ff7 --- /dev/null +++ b/context/gen-index.sh @@ -0,0 +1,172 @@ +#!/usr/bin/env bash +# +# gen-index.sh — keep context/README.md's documentation index in sync with the repo. +# +# context/gen-index.sh # CHECK: report drift, exit 1 if the index is stale +# context/gen-index.sh --write # rewrite the AUTOGEN block in context/README.md +# context/gen-index.sh --help +# +# Only the region between the AUTOGEN markers in context/README.md is touched; +# the hand-written header/scope note above it is left alone. Descriptions that +# already exist in the index are PRESERVED (matched by path); files that are new +# to the tree get a stub description pulled from their first heading/lead line, +# ready for you to polish. Vendored/third-party trees are excluded, matching the +# index's stated scope. +# +# Run it from anywhere; it locates the repo via this script's own path. +set -euo pipefail + +ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +cd "$ROOT" +INDEX="context/README.md" +BEGIN='' +END='' + +MODE="check" +case "${1:-}" in + --write) MODE="write" ;; + ""|--check) MODE="check" ;; + -h|--help) sed -n '3,17p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; + *) echo "unknown option: $1 (try --help)" >&2; exit 2 ;; +esac + +# --- ordered sections: a path lands in the FIRST section whose regex matches --- +TITLES=( + "Orientation" + "Emulator — plan, phases & operations" + "Emulator — subsystems" + "Emulator — deployment & ports" + "Emulator — devices & support files" + "Emulator — VelociRender firmware decompilation" + "Emulator — render bridge" + "dpl3-revive — DPL3 renderer port & format specs" + "restoration — scene re-renders" + "restoration — RIO firmware & hardware" + "restoration — source410 reconstruction" +) +REGEX=( + '^(README|HISTORY)\.md$' + '^emulator/(PLAN|PHASE[0-9].*|LAUNCH|ENV-VARS)\.md$' + '^emulator/(VDB-NOTES|GAUGE-NOTES|SOUND-NOTES|NET-NOTES|RIO-NOTES|CAMERA-REVIEW-NOTES|RENDER-HARNESS|RENDERER-COLLAB)\.md$' + '^emulator/(DEPLOYMENT-PLAN|XP-PORT-PLAN|EGRESS-HOLD-FIX-PLAN)\.md$' + '^emulator/(vpx-device|pod-launch|net-boot|deploy|roms|rio-firmware)/' + '^emulator/firmware-decomp/' + '^emulator/render-bridge/' + '^dpl3-revive/' + '^restoration/README\.md$' + '^restoration/rio-' + '^restoration/source410/' +) + +# --- the doc set (same filter as the index scope) --- +list_docs() { + git ls-files '*.md' '*.MD' \ + | grep -viE '/(vs|libpng|libpdcurses|sdl2|sdl2net|freetype)/' \ + | grep -viE '^emulator/src/(NOTES|\.github)/' \ + | grep -vxF "$INDEX" \ + | sort +} + +# --- preserved descriptions: parse the current AUTOGEN block, path -> desc --- +declare -A DESC +if [ -f "$INDEX" ]; then + in_block=0 + while IFS= read -r line; do + [ "$line" = "$BEGIN" ] && { in_block=1; continue; } + [ "$line" = "$END" ] && { in_block=0; continue; } + [ "$in_block" = 1 ] || continue + case "$line" in + "- ["*"](../"*")"*) + rest="${line#*](../}"; path="${rest%%)*}"; after="${rest#*)}" + after="${after#"${after%%[![:space:]]*}"}" # ltrim + after="${after#—}"; after="${after#-}" # drop leading em/hyphen dash + after="${after#"${after%%[![:space:]]*}"}" # ltrim again + [ -n "$after" ] && DESC["$path"]="$after" + ;; + esac + done < "$INDEX" +fi + +# --- stub description for a file new to the index --- +extract_desc() { + local f="$1" raw + raw="$(awk 'NR>1 && $0 !~ /^#/ && $0 !~ /^---/ && $0 !~ /^>/ && $0 !~ /^[[:space:]]*$/ {print; exit}' "$f")" + raw="$(printf '%s' "$raw" | sed -E 's/[`*]//g; s/[[:space:]]+/ /g; s/^ +//; s/ +$//')" + [ "${#raw}" -gt 140 ] && raw="${raw:0:137}..." + [ -n "$raw" ] && printf '%s' "$raw" || printf '(no description — add one)' +} + +# --- build the block body on stdout --- +gen_body() { + local docs; docs="$(list_docs)" + local -a remaining; mapfile -t remaining <<< "$docs" + + emit_section() { + local title="$1" re="$2"; shift 2 + local -a kept=() matched=() + local p + for p in "${remaining[@]}"; do + [ -z "$p" ] && continue + if [[ "$p" =~ $re ]]; then matched+=("$p"); else kept+=("$p"); fi + done + remaining=("${kept[@]}") + [ "${#matched[@]}" -eq 0 ] && return 0 + printf '\n## %s\n\n' "$title" + for p in "${matched[@]}"; do + local d="${DESC[$p]:-}"; [ -z "$d" ] && d="$(extract_desc "$p")" + printf -- '- [%s](../%s) — %s\n' "$p" "$p" "$d" + done + } + + local i + for i in "${!TITLES[@]}"; do + emit_section "${TITLES[$i]}" "${REGEX[$i]}" + done + + # anything unmatched still shows up — never silently dropped + local -a leftover=() + local p + for p in "${remaining[@]}"; do [ -n "$p" ] && leftover+=("$p"); done + if [ "${#leftover[@]}" -gt 0 ]; then + printf '\n## Uncategorized\n\n' + printf '%s\n' '> New locations the section rules do not cover yet — assign them in gen-index.sh.' + printf '\n' + for p in "${leftover[@]}"; do + local d="${DESC[$p]:-}"; [ -z "$d" ] && d="$(extract_desc "$p")" + printf -- '- [%s](../%s) — %s\n' "$p" "$p" "$d" + done + fi +} + +# --- current block body (between the markers) on stdout --- +current_body() { + awk -v b="$BEGIN" -v e="$END" ' + $0==b {inb=1; next} $0==e {inb=0} inb==1 {print} + ' "$INDEX" +} + +grep -qF "$BEGIN" "$INDEX" && grep -qF "$END" "$INDEX" || { + echo "error: AUTOGEN markers not found in $INDEX" >&2; exit 2; } + +NEW="$(gen_body)" + +if [ "$MODE" = "check" ]; then + if diff <(current_body) <(printf '%s\n' "$NEW") >/dev/null; then + echo "context index is current ($(list_docs | grep -c . ) docs)." + exit 0 + fi + echo "context index is STALE — run: context/gen-index.sh --write" >&2 + echo "--- diff (current -> generated) ---" >&2 + diff <(current_body) <(printf '%s\n' "$NEW") >&2 || true + exit 1 +fi + +# MODE=write: splice NEW between the markers, leave everything else intact +tmp="$(mktemp)" +awk -v b="$BEGIN" -v e="$END" -v body="$NEW" ' + $0==b {print; print body; skip=1; next} + $0==e {skip=0; print; next} + skip!=1 {print} +' "$INDEX" > "$tmp" +mv "$tmp" "$INDEX" +echo "wrote $INDEX ($(list_docs | grep -c . ) docs)."