# markmoxon/elite-source-code-bbc-master architecture

> Architecture diagram of the GitHub repository markmoxon/elite-source-code-bbc-master, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/markmoxon/elite-source-code-bbc-master
- Repository: https://github.com/markmoxon/elite-source-code-bbc-master

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================================================
    %% Build + Artifact Pipeline (6502 Elite for BBC Master)
    %% =========================================================

    Dev["Developer Workstation"]:::external

    subgraph REPO["Repository (ordered pipeline folders 1->5)"]
        direction TB

        subgraph SRC["1) Source Inputs (1-source-files/)"]
            direction TB
            SRC_CODE["elite-source.asm<br/>(main game code, entry TT170)"]:::source
            SRC_DATA["elite-data.asm<br/>(game data)"]:::source
            SRC_LOADER["elite-loader.asm<br/>(loader/setup/copy-protection)"]:::source
            SRC_DISC["elite-disc.asm<br/>(disc structures/content)"]:::source
            SRC_OPTS["elite-build-options.asm<br/>(variant/options macros)"]:::source
            SRC_README["elite-readme.asm<br/>(embedded build/readme metadata)"]:::source
            SRC_FONTS["fonts/*.bin<br/>(binary includes)"]:::asset
            SRC_IMAGES["images/*.bin<br/>(binary includes)"]:::asset
        end

        subgraph TOOLS["2) Build Tooling (2-build-files/)"]
            direction TB
            WIN_MAKE_EXE["make.exe<br/>(Windows convenience)"]:::tool
            PY_CHECKSUM["elite-checksum.py<br/>(checksum logic/patch)"]:::tool
            PY_DECRYPT["elite-decrypt.py<br/>(debug/optional)"]:::tool
            PY_CRC["crc32.py<br/>(verify vs reference)"]:::tool
        end

        subgraph OUT["3) Assembled Output (3-assembled-output/)"]
            direction TB
            OUT_BCODE["BCODE.bin<br/>(protected)"]:::output
            OUT_BDATA["BDATA.bin<br/>(protected)"]:::output
            OUT_M128["M128Elt.bin<br/>(protected)"]:::output
            OUT_BCODE_U["BCODE.unprot.bin"]:::output
            OUT_BDATA_U["BDATA.unprot.bin"]:::output
            OUT_COMPILE["compile.txt<br/>(addresses/labels log)"]:::artifact
        end

        subgraph REF["4) Reference Binaries (4-reference-binaries/)"]
            direction TB
            REF_SNG47["sng47/<br/>known-good truth set"]:::reference
            REF_COMPACT["compact/<br/>known-good truth set"]:::reference
        end

        subgraph DISCS["5) Compiled Game Discs (5-compiled-game-discs/)"]
            direction TB
            SSD_SNG47["elite-master-sng47.ssd"]:::disc
            SSD_COMPACT["elite-master-compact.ssd"]:::disc
        end

        subgraph ORCH["Orchestration"]
            direction TB
            MK["Makefile<br/>(canonical pipeline)"]:::orchestrator
            BAT["make.bat<br/>(Windows wrapper)"]:::orchestrator

            CFG["Build flags / knobs:<br/>variant={sng47, compact}<br/>encrypt={yes, no}<br/>match={yes, no}<br/>verify={yes, no}<br/>commander={max, ...}<br/>b2={yes, no}"]:::config
        end
    end

    subgraph EXT["External Dependencies / Targets"]
        direction TB
        BEEBASM["BeebAsm<br/>(assembler executable)"]:::external
        PYTHON["Python runtime"]:::external
        DISC_BUILDER["Disc image packaging<br/>(Makefile rules)"]:::process
        B2["b2 emulator<br/>(optional auto-load)"]:::external
        HW["BBC Master hardware<br/>(6502 target)"]:::external
    end

    %% ----------------------------
    %% Pipeline Flow (top-to-bottom)
    %% ----------------------------
    Dev -->|"invokes"| MK
    Dev -->|"invokes (Windows)"| BAT
    BAT -->|"uses"| WIN_MAKE_EXE
    BAT -->|"calls"| MK

    MK -->|"reads flags"| CFG

    %% Assemble stage
    MK -->|"runs"| BEEBASM
    SRC_CODE -->|"assembled with"| BEEBASM
    SRC_DATA -->|"assembled with"| BEEBASM
    SRC_LOADER -->|"assembled with"| BEEBASM
    SRC_DISC -->|"assembled with"| BEEBASM
    SRC_OPTS -->|"controls conditionals"| BEEBASM
    SRC_README -->|"embedded metadata"| BEEBASM
    SRC_FONTS -->|"includes"| BEEBASM
    SRC_IMAGES -->|"includes"| BEEBASM

    BEEBASM -->|"emits"| OUT_BCODE
    BEEBASM -->|"emits"| OUT_BDATA
    BEEBASM -->|"emits"| OUT_M128
    BEEBASM -->|"emits"| OUT_COMPILE

    %% Match/noise injection (byte-accurate reproduction)
    MK -->|"if match=yes<br/>inject workspace noise"| OUT_BCODE
    MK -->|"if match=yes<br/>inject workspace noise"| OUT_BDATA
    MK -->|"if match=no<br/>skip noise injection"| OUT_BCODE_U
    MK -->|"if match=no<br/>skip noise injection"| OUT_BDATA_U

    %% Post-processing: checksum/encryption
    MK -->|"runs"| PYTHON
    PYTHON -->|"executes"| PY_CHECKSUM
    PYTHON -->|"executes (optional)"| PY_DECRYPT

    OUT_BCODE -->|"if encrypt!=no<br/>checksum patch"| PY_CHECKSUM
    OUT_BDATA -->|"if encrypt!=no<br/>checksum patch"| PY_CHECKSUM
    PY_CHECKSUM -->|"updates in-place"| OUT_BCODE
    PY_CHECKSUM -->|"updates in-place"| OUT_BDATA

    %% Verification stage (CRC compare vs reference)
    PYTHON -->|"executes"| PY_CRC
    OUT_BCODE -.->|"if verify!=no<br/>CRC32 compare"| PY_CRC
    OUT_BDATA -.->|"if verify!=no<br/>CRC32 compare"| PY_CRC
    OUT_M128 -.->|"if verify!=no<br/>CRC32 compare"| PY_CRC

    CFG -->|"variant=sng47 selects"| REF_SNG47
    CFG -->|"variant=compact selects"| REF_COMPACT
    REF_SNG47 -.->|"truth set"| PY_CRC
    REF_COMPACT -.->|"truth set"| PY_CRC

    %% Packaging stage: create SSD
    MK -->|"packages"| DISC_BUILDER
    OUT_BCODE -->|"input"| DISC_BUILDER
    OUT_BDATA -->|"input"| DISC_BUILDER
    OUT_M128 -->|"input"| DISC_BUILDER
    CFG -->|"commander affects<br/>included save/commander content"| DISC_BUILDER

    DISC_BUILDER -->|"variant=sng47"| SSD_SNG47
    DISC_BUILDER -->|"variant=compact"| SSD_COMPACT

    %% Run stage
    SSD_SNG47 -->|"b2=yes auto-load"| B2
    SSD_COMPACT -->|"b2=yes auto-load"| B2
    SSD_SNG47 -->|"write/load"| HW
    SSD_COMPACT -->|"write/load"| HW

    %% =========================================================
    %% Click events (from component mapping)
    %% =========================================================
    click SRC_CODE "https://github.com/markmoxon/elite-source-code-bbc-master/blob/main/1-source-files/main-sources/elite-source.asm"
    click SRC_DATA "https://github.com/markmoxon/elite-source-code-bbc-master/blob/main/1-source-files/main-sources/elite-data.asm"
    click SRC_LOADER "https://github.com/markmoxon/elite-source-code-bbc-master/blob/main/1-source-files/main-sources/elite-loader.asm"
    click SRC_DISC "https://github.com/markmoxon/elite-source-code-bbc-master/blob/main/1-source-files/main-sources/elite-disc.asm"
    click SRC_OPTS "https://github.com/markmoxon/elite-source-code-bbc-master/blob/main/1-source-files/main-sources/elite-build-options.asm"
    click SRC_README "https://github.com/markmoxon/elite-source-code-bbc-master/blob/main/1-source-files/main-sources/elite-readme.asm"
    click SRC_FONTS "https://github.com/markmoxon/elite-source-code-bbc-master/tree/main/1-source-files/fonts/"
    click SRC_IMAGES "https://github.com/markmoxon/elite-source-code-bbc-master/tree/main/1-source-files/images/"

    click MK "https://github.com/markmoxon/elite-source-code-bbc-master/tree/main/Makefile"
    click BAT "https://github.com/markmoxon/elite-source-code-bbc-master/blob/main/make.bat"
    click WIN_MAKE_EXE "https://github.com/markmoxon/elite-source-code-bbc-master/blob/main/2-build-files/make.exe"

    click PY_CHECKSUM "https://github.com/markmoxon/elite-source-code-bbc-master/blob/main/2-build-files/elite-checksum.py"
    click PY_DECRYPT "https://github.com/markmoxon/elite-source-code-bbc-master/blob/main/2-build-files/elite-decrypt.py"
    click PY_CRC "https://github.com/markmoxon/elite-source-code-bbc-master/blob/main/2-build-files/crc32.py"

    click OUT_BCODE "https://github.com/markmoxon/elite-source-code-bbc-master/blob/main/3-assembled-output/BCODE.bin"
    click OUT_BDATA "https://github.com/markmoxon/elite-source-code-bbc-master/blob/main/3-assembled-output/BDATA.bin"
    click OUT_M128 "https://github.com/markmoxon/elite-source-code-bbc-master/blob/main/3-assembled-output/M128Elt.bin"
    click OUT_BCODE_U "https://github.com/markmoxon/elite-source-code-bbc-master/blob/main/3-assembled-output/BCODE.unprot.bin"
    click OUT_BDATA_U "https://github.com/markmoxon/elite-source-code-bbc-master/blob/main/3-assembled-output/BDATA.unprot.bin"
    click OUT_COMPILE "https://github.com/markmoxon/elite-source-code-bbc-master/blob/main/3-assembled-output/compile.txt"

    click REF_COMPACT "https://github.com/markmoxon/elite-source-code-bbc-master/tree/main/4-reference-binaries/compact/"
    click REF_SNG47 "https://github.com/markmoxon/elite-source-code-bbc-master/tree/main/4-reference-binaries/sng47/"

    click SSD_COMPACT "https://github.com/markmoxon/elite-source-code-bbc-master/blob/main/5-compiled-game-discs/elite-master-compact.ssd"
    click SSD_SNG47 "https://github.com/markmoxon/elite-source-code-bbc-master/blob/main/5-compiled-game-discs/elite-master-sng47.ssd"

    %% =========================================================
    %% Styles (color is required)
    %% =========================================================
    classDef source fill:#d6ecff,stroke:#1c5d99,stroke-width:1px,color:#0b2545
    classDef asset fill:#cfefff,stroke:#2a7bbd,stroke-width:1px,color:#0b2545
    classDef orchestrator fill:#e6e6e6,stroke:#4c4c4c,stroke-width:1px,color:#1a1a1a
    classDef tool fill:#ededed,stroke:#6b6b6b,stroke-width:1px,color:#1a1a1a
    classDef process fill:#fff2cc,stroke:#b38300,stroke-width:1px,color:#4a3200
    classDef output fill:#dff5e1,stroke:#1b7f3a,stroke-width:1px,color:#0f3d1f
    classDef artifact fill:#dff5e1,stroke:#1b7f3a,stroke-width:1px,color:#0f3d1f
    classDef reference fill:#eadcff,stroke:#6b3fa0,stroke-width:1px,color:#2f0f4a
    classDef disc fill:#c9f7f0,stroke:#00796b,stroke-width:1px,color:#003d36
    classDef external fill:#ffe0b2,stroke:#b85c00,stroke-width:1px,color:#4a2600
    classDef config fill:#ffd6e7,stroke:#b03060,stroke-width:1px,color:#4a1026
```
