How markmoxon/elite-source-code-bbc-master works
Project type & purpose (what you’re diagramming)
Key outcomes the project produces:
• Assembled binaries (BCODE.bin, BDATA.bin, M128Elt.bin and unprotected variants)
• Variant-specific, byte-accurate verification vs known-good reference binaries
• Final bootable disc image (elite-master-sng47.ssd or elite-master-compact.ssd)
• Optional workflows: “flicker-free”, “music”, “econet”, etc. via branches (important for “variant/hack” callouts)
• Source inputs → assembly → post-processing (encrypt/checksum) → verification → disc image packaging → emulator/hardware run
• The “variant knobs” (variant=, encrypt=, match=, verify=, commander=) that change flows and outputs.
Source inputs (1-source-files/)
• main-sources/elite-source.asm — main game code (entry point TT170)
• main-sources/elite-data.asm — game data
• main-sources/elite-loader.asm — loader + setup + copy protection handling
• main-sources/elite-disc.asm — disc-related content/structures (implied by name)
• main-sources/elite-build-options.asm — compile-time switches/macros for variants and options
• main-sources/elite-readme.asm — build/readme assembly metadata (likely embedded text)
• fonts/*.bin, images/*.bin — binary assets included into build
Build tooling (2-build-files/)
• make.exe (Windows convenience)
• Python scripts:
• elite-checksum.py — adjusts/produces checksum logic (must be updated if code moves)
• elite-encrypt.py / elite-decrypt.py — protection/encryption transformations
• crc32.py — verification against reference binaries
Build outputs (3-assembled-output/)
• Built binaries (BCODE.bin, BDATA.bin, M128Elt.bin) and “unprot” variants
• compile.txt — build log w/ addresses and label info (important artifact for debugging/traceability)
Reference “truth set” (4-reference-binaries/)
• Per-variant reference outputs (sng47/…, compact/…) used for byte-accurate matching
Final distributable artifacts (5-compiled-game-discs/)
• Disc images: elite-master-sng47.ssd, elite-master-compact.ssd
Orchestration
• Makefile — canonical pipeline definition (mac/linux + windows)
• make.bat — windows entrypoint wrapper with tool path configuration
What the README adds (relationships + important patterns)
• BeebAsm is the assembler dependency (external executable not in the repo).
• Variant system:
• variant=sng47 (default) vs variant=compact
• Source contains conditional blocks keyed by _SNG47 / _COMPACT
• “Byte-accurate reproduction” is a first-class feature:
• match controls “workspace noise” inclusion (crucial for matching originals)
• Verification is explicit:
• crc32.py compares assembled output with reference binaries
• Encryption/checksum is part of build correctness (not just packaging):
• If code changes, checksum scripts may need updating or game hangs
• Optional “deploy to emulator” path:
• b2 target loads the generated SSD into the b2 emulator (external system)
External tools
• BeebAsm (assembler)
• Python runtime
Post-processing scripts
• checksum
• encrypt/decrypt
Outputs
• 3-assembled-output binaries (+ compile.txt)
Verification
• crc32.py + 4-reference-binaries/{variant}
Packaging
• Disc image builder step (likely Makefile rules) producing 5-compiled-game-discs/*.ssd
• b2 emulator auto-deploy
• real BBC Master hardware
• 1-source-files/* → (BeebAsm via Makefile) → 3-assembled-output/*.bin
• 3-assembled-output/*.bin → (elite-checksum / elite-encrypt) → protected outputs (and/or final form)
• 3-assembled-output/*.bin ↔ (crc32.py compares) ↔ 4-reference-binaries/<variant>/*.bin
• Final binaries → (packaging) → 5-compiled-game-discs/*.ssd
• .ssd → (b2 emulator | hardware)
• variant=sng47|compact influences:
• assembly conditionals (_SNG47, _COMPACT)
• which reference binaries set is used
• which .ssd name is produced
• encrypt=no bypasses encrypt/checksum transformations
• verify=no bypasses CRC comparison step
• match=no bypasses workspace noise injection (affects binary identity)
• commander=max changes included commander/save file content (packaging input)
This shows what the assembled artifacts *become* at runtime. Keep it accurate but high-level (you’re not diagramming every subroutine).
Main components:
• BBC Master machine
• 6502 CPU
• RAM / workspace
• Video output
• Input devices (keyboard, analogue joystick; Compact: digital joystick)
• Disc subsystem:
• DFS (typical)
• Compact variant: ADFS + directory selection + NMI workspace claim/release
• Disc image contents:
• Loader (elite-loader assembled output)
• Main code (BCODE)
• Data (BDATA)
• Possibly other small components (M128Elt.bin)
Relationships:
• Boot from disc → loader executes → sets up memory, performs protection/checksums (if enabled) → loads/initializes main code/data → enters main loop (entry TT170).
• Variant-specific edges:
• Compact: joystick read path changes; disc access menu changes (“Which Directory?”) and ADFS-specific memory constraints.
Inputs
• 1-source-files/main-sources/*.asm
• 1-source-files/fonts/*.bin
• 1-source-files/images/*.bin
Orchestration
• Makefile / make.bat (parameters bubble: variant/encrypt/match/verify/commander)
Assembly
• BeebAsm → emits initial binaries → 3-assembled-output/*.bin
• emits 3-assembled-output/compile.txt
Post-processing (conditional)
• elite-checksum.py (may patch/update checksums)
• elite-encrypt.py (if encrypt!=no)
• (optionally elite-decrypt.py for debug workflows)
Verification (conditional)
• crc32.py compares:
• 3-assembled-output/*.bin
• 4-reference-binaries/<variant>/*.bin
• produces “Match/No Match” report in console/log
Packaging
• build disc image → 5-compiled-game-discs/elite-master-<variant>.ssd
Run
• b2 emulator auto-load (optional)
• real hardware load