1450 lines
64 KiB
Markdown
1450 lines
64 KiB
Markdown
# FS2 — Apple II Flight Simulator II Architecture
|
||
|
||
This document describes the architecture of *Flight Simulator II* for the Apple II as
|
||
reconstructed from this disassembly. The original was written by Bruce Artwick / Sublogic
|
||
(1984). The build target here is the qkumba ProDOS port that reassembles byte-identical to
|
||
the shipped chunks via cc65.
|
||
|
||
Conventions used below:
|
||
|
||
* Hex addresses are written `$1234`; binary is `%01010101`.
|
||
* `Lxxxx` are raw labels from the disassembly; semantic names like `MainGameEntry` are
|
||
aliases we've added. Both resolve to the same byte address.
|
||
* Citations are `file:line` against `src/`.
|
||
* "ZP" = zero page (`$00..$FF`).
|
||
|
||
---
|
||
|
||
## Table of Contents
|
||
|
||
1. [System Overview](#1-system-overview)
|
||
2. [Boot & Initialization](#2-boot--initialization)
|
||
3. [Main Loop](#3-main-loop)
|
||
4. [Zero Page Atlas](#4-zero-page-atlas)
|
||
5. [Aircraft State Model](#5-aircraft-state-model)
|
||
6. [Physics](#6-physics)
|
||
7. [Scenery System](#7-scenery-system)
|
||
8. [3D Pipeline](#8-3d-pipeline)
|
||
9. [Rasterization](#9-rasterization)
|
||
10. [Instrument Panel](#10-instrument-panel)
|
||
11. [Engine Model](#11-engine-model)
|
||
12. [Input](#12-input)
|
||
13. [64K Patch Mechanism](#13-64k-patch-mechanism)
|
||
14. [WW1 Ace Mode](#14-ww1-ace-mode)
|
||
15. [Self-Modifying Tricks](#15-self-modifying-tricks)
|
||
16. [Mode Library](#16-mode-library)
|
||
17. [Known Unknowns](#17-known-unknowns)
|
||
|
||
---
|
||
|
||
## 1. System Overview
|
||
|
||
### 1.1 Memory Map
|
||
|
||
```
|
||
$0000-$00FF Zero page (control state + matrix + dispatcher cursor)
|
||
$0100-$01FF Stack
|
||
$0200-$25FF chunk4 (~9 KB: initial ZP data, instrument panel bitmaps,
|
||
pixel-list tables, message/digit renderer,
|
||
sin/cos tables, multiply primitives,
|
||
ProDOS read driver)
|
||
$2600-$3FFF Scratch / disk-load staging
|
||
$4000-$5FFF chunk1 (loading-panel hires page, displayed during boot)
|
||
$6000-$B3DF chunk5 (~21 KB: scenery interpreter, 3D pipeline,
|
||
rasterizer, instrument compositor,
|
||
key dispatch, main loop, boot init,
|
||
64K patch table)
|
||
$B3E0-$BFFF chunk5 tail / scenery RAM
|
||
$A800-$BFFF Live scenery bytecode area (overwritten as the dispatcher
|
||
walks; loader streams sections in via L1E03 cursor)
|
||
$C000-$CFFF I/O soft switches & slot ROM
|
||
$D000-$F3FF chunk3 (~8.5 KB: ATIS/COM message scroller, ADF model,
|
||
reality-mode + crash handler,
|
||
engine model w/ magnetos (64K),
|
||
scenery sector loader, hide/show panel
|
||
instruments, war report)
|
||
$F400-$F5FF Free / data
|
||
$F600-$FBFF chunk2 (~1.5 KB: course plotter, altimeter 10K-foot
|
||
hand, wind/turbulence, demo-mode 64K)
|
||
$FC00-$FFFF ROM (Apple II monitor / ProDOS)
|
||
+ language-card reset/IRQ vectors in 64K mode
|
||
```
|
||
|
||
The whole image links as a single segment in `src/asm.cfg` starting at `$4000` and is
|
||
sliced into the original disk chunks by `dd` in the Makefile. This matches the original
|
||
disk layout, where the loader pulls each chunk from a known sector range.
|
||
|
||
**Dead pad bytes.** The binary carries ~455 bytes of confirmed-unused filler:
|
||
* `Chunk2TrailingData` (132 bytes, `$FB7C..$FBFF`) at the tail of chunk2.
|
||
* Unnamed pad (208 bytes, `$D300..$D3CF`) at the head of chunk3.
|
||
* Unnamed pad (115 bytes, `$86CD..$873F`) between `HorizonANDMask` and
|
||
`TogglePauseRelay` in chunk5 — likely page-alignment padding.
|
||
|
||
All three contain the same repeating `$FF $FF $00 $00` 16-byte pattern with `$76`
|
||
at certain offsets. They are not referenced by any code, indirect pointer,
|
||
scenery dispatcher walk, or 64K patch — verified by exhaustive grep of all
|
||
source files and the patch table. They are 1984-era residue from the original
|
||
Sublogic assembler's output (likely leftover stack frames at the time the disk
|
||
image was authored).
|
||
|
||
### 1.2 Build Topology
|
||
|
||
| Chunk | Address Range | Size | Role |
|
||
|-------|---------------|-------|------|
|
||
| 1 | $4000-$5FFF | 8 KB | Loading-panel hires bitmap (data only) |
|
||
| 2 | $F600-$FBFF | 1.5 KB| Course plotter, altimeter 10K hand, wind, demo |
|
||
| 3 | $D300-$F3FF | 8.5 KB| Scenery loader, ATIS, engine model, fail/crash, COM messages |
|
||
| 4 | $0200-$25FF | 9 KB | Instrument render, pixel lists, math, message draw, disk I/O |
|
||
| 5 | $6000-$B3DF | 21 KB | Main game logic |
|
||
|
||
Chunks 4 and 5 are the engine; chunks 2 and 3 hold the slower / 64K-only systems and
|
||
get DMA'd in over the language card. Chunk 1 is just a splash bitmap.
|
||
|
||
### 1.3 48K vs 64K Modes
|
||
|
||
The game ships in two configurations:
|
||
|
||
* **48K mode** is what runs out of the box. Many features are stubs (no magnetos, no
|
||
ADF lookup, no separate fuel mixture, no course plotter, no ATIS, no day/night model).
|
||
Numerous routines in chunk5 are written as `NoOp` placeholders.
|
||
* **64K mode** uses the language card (`LCBANK2`). On boot, `ProbeLCMemory`
|
||
(`src/chunk5.s:12465`) detects extra RAM. If present, `Apply64KPatchTable`
|
||
(`src/chunk5.s:11486`) walks a 5-byte-entry patch table and overwrites ~30 sites in
|
||
the running code, swapping `NoOp` stubs and 48K simple paths for full-featured 64K
|
||
paths in chunks 2 and 3.
|
||
|
||
This is how the same disk image fits in both machines without runtime branches —
|
||
the patches are applied once at startup and never re-checked.
|
||
|
||
---
|
||
|
||
## 2. Boot & Initialization
|
||
|
||
### 2.1 Reset Vectors
|
||
|
||
The shipped binary doesn't ship hardware reset vectors. Boot is launched by ProDOS as
|
||
a binary at `$4000`. In 64K mode, `Apply64KPatchTable` writes `ResetInterruptHandler`
|
||
($AC15) into the language-card NMI/Reset/IRQ vectors at `$FFFA/$FFFC/$FFFE` so that
|
||
post-boot resets land back in the game (`src/chunk5.s:12536-12539`). Because bank 2
|
||
is selected when the write happens, the vectors persist past the boot sequence.
|
||
|
||
### 2.2 `ResetInterruptHandler` and `InitFromReset`
|
||
|
||
`ResetInterruptHandler` is two `jmp InitFromReset` instructions back-to-back
|
||
(`src/chunk5.s:11906`). `InitFromReset` (`src/chunk5.s:12082`) does:
|
||
|
||
1. `ldx #$3F / txs` — reset the stack.
|
||
2. `jsr LoaderNoOpSuccess` — open / handshake the disk loader (chunk4).
|
||
3. `jsr ReloadGameChunks` — re-pull chunk4 (sectors $00..$06 to $0200) and chunk5
|
||
(sectors $08..$19 to $6000). The 32 bytes at `LA7E0` (= the scenery dispatcher
|
||
entry point that chunk5 overwrites in its own image) are stashed via `LABCC` then
|
||
restored.
|
||
4. `jsr LoadIntroPanel` — pulls 8 KB of chunk1 (sectors $1A..$21) into hires page 1 at
|
||
`$4000`. This is the splash screen visible during the boot phase.
|
||
5. `jsr ProbeLCMemory` — 64K detection (see below).
|
||
6. `jsr SceneryCopyLoadedSection` (= `LA6F9`) — finalize the first scenery section.
|
||
7. `jsr InitZeroPage` + `jmp MainGameEntry`.
|
||
|
||
Boot failures land at `InitFailureExit` (`src/chunk5.s:12105`) which jumps to
|
||
`L1F89` = `SwapPagesWithStash` (chunk4) — a page-swap routine that stashes the
|
||
running aircraft state into a save region and then returns through the BRK /
|
||
Ctrl-Y / IRQ vector chain. On boot failure this effectively aborts back to
|
||
ProDOS while preserving the game state for a later resume.
|
||
|
||
### 2.3 64K Probe (`ProbeLCMemory`)
|
||
|
||
`ProbeLCMemory` (`src/chunk5.s:12465`) enables language-card bank 2 read/write by
|
||
reading the `LCBANK2` ($C083) soft switch twice (the standard idiom). It then writes
|
||
the X register through all 256 values into `$D000` and reads back to confirm
|
||
write-and-read both work. Any mismatch jumps to `LAE9E` (a bare RTS), leaving
|
||
`Has64K = 0`. On success the patch table is applied and `Has64K = 1`.
|
||
|
||
### 2.4 `MainGameEntry`
|
||
|
||
`MainGameEntry` (`src/chunk5.s:12109`) is the top-level game start:
|
||
|
||
1. `jsr Apply64KPatchTable` — no-op on 48K, runs the patch list on 64K.
|
||
2. `jsr InitGraphicsScreens` — sets the IIE soft switches for hires page 1
|
||
visible, double-buffer to page 2.
|
||
3. `jsr PromptColorOrBW` — color/monochrome prompt (only matters for the dither tables).
|
||
4. `jsr InitInstruments` — paints the static cockpit panel bitmaps.
|
||
5. `jsr InitInstrumentSaveBuffers` — captures the panel bitmap's hires bytes into the
|
||
per-instrument save buffers in chunk3 ($E800-$FC78); see §10.
|
||
6. `jmp MainLoopEntry`.
|
||
|
||
`MainLoopEntry` (= `L877F`, `src/chunk5.s:6660`) runs `PatchSlot_FrameSync` once
|
||
before falling into the regular `MainLoop`.
|
||
|
||
---
|
||
|
||
## 3. Main Loop
|
||
|
||
### 3.1 Frame Architecture
|
||
|
||
Each iteration of `MainLoop` (`src/chunk5.s:6661`) does roughly:
|
||
|
||
```
|
||
add #$0D to $33 (frame work-cost accumulator; rolls over slowly)
|
||
if EditModeFlag or ModeLibraryAction: jsr PatchSlot_PreMode
|
||
jsr PatchSlot_FrameSync
|
||
if SlewMode: jsr ApplySlewDeltas, else: jsr IntegratePhysicsStep
|
||
jsr ApplyWind (64K patch slot)
|
||
jsr LA60C (DrawATISMessage in 64K)
|
||
jsr LoadDispatcherPointer
|
||
jsr SetupViewProjection ; rebuild rotation matrix
|
||
ldx #$00 / lsr $089A (crash counter); bcc skip / lda $0899; bne skip; inx
|
||
jsr ShowSimpleCrashMessage ; 64K patches to HandleCrashOrSplash
|
||
jsr FlipPagesFillViewportRelay ; swap hires pages
|
||
jsr ProcessScenery ; the big one — see §7
|
||
jsr UpdateCoursePlotter ; 64K patch
|
||
jsr AnimateVOR2Needle
|
||
jsr DrawRPM
|
||
jsr DrawVOR1IndicatorChanges
|
||
jsr DrawVOR2IndicatorChanges
|
||
jsr IntegrateClimbRate
|
||
jsr MaybeDrawSlewOverlays
|
||
jsr UpdateTurnCoordinator
|
||
jsr DrawHeading
|
||
jsr DrawMagCompass
|
||
jsr UpdateInstrumentLights ; 64K patch
|
||
if WW1AceMode: jsr PatchSlot_Gunsight (draw gunsight overlay)
|
||
jsr DrawViewOverlays ; 64K patch
|
||
jsr UpdateAltimeterPose
|
||
jsr UpdateAirspeedDerivedValue
|
||
jsr HideOrShowInstruments ; 64K patch
|
||
if DemoMode: jsr DemoMode64K ; 64K patch
|
||
jsr ... (UpdateCounter dispatch)
|
||
jmp FinishMainLoop ; inc UpdateCounter; jmp MainLoop
|
||
```
|
||
|
||
### 3.2 `UpdateCounter` 4-phase dispatch
|
||
|
||
To amortize "slow" jobs across multiple frames, the loop's tail dispatches on the
|
||
low 2 bits of `UpdateCounter` (`src/chunk5.s:6731-6779`):
|
||
|
||
| UpdateCounter & $03 | Phase work |
|
||
|---------------------|------------|
|
||
| `00` | ComputeDayPhase, MaybeBootDOS, fuel-left gauge, ComputeWindComponents. Every 8th frame additionally: DrawDME, NAV1/NAV2 lookups, ADF lookup |
|
||
| `01` | fuel-right gauge, altimeter 10K hand, VOR1/VOR2 bearings, magnetic heading, ADF indicator |
|
||
| `10` | oil temperature, auto-trim + yaw decay |
|
||
| `11` | oil pressure, reality-mode hook, VOR/heading update (joins phase 01 tail) |
|
||
|
||
Each phase ends with either `CheckFlightEnvelope + UpdateSlipSkid + maybe joystick
|
||
calibration` (phases 00/10) or a timer rotate (phases 01/11), then `FinishMainLoop`.
|
||
|
||
### 3.3 `PatchSlot_*` Trampolines
|
||
|
||
Three 4-byte slots in chunk5 (`src/chunk5.s:11917-11933`) contain `jsr LoadSceneryFileN
|
||
/ brk brk brk` initially. Mode transitions (mode-library load, WW1 gunsight, etc.)
|
||
self-modify these slots — the `brk brk brk` padding gives room to widen the
|
||
`jsr` into a `jmp` with a different target, or to inline additional opcodes:
|
||
|
||
* `PatchSlot_PreMode` — pre-mode initialization, runs when entering edit mode
|
||
* `PatchSlot_Gunsight` — WW1 gunsight overlay
|
||
* `PatchSlot_FrameSync` — per-frame sync hook
|
||
|
||
The self-modify sites are at `$8758/$875B/$8761/$AA03` (see the comment block at
|
||
`src/chunk5.s:11912`).
|
||
|
||
---
|
||
|
||
## 4. Zero Page Atlas
|
||
|
||
The 6502 zero page is packed densely. Key allocations:
|
||
|
||
| Range | Purpose |
|
||
|-------|---------|
|
||
| `$08-$10` | V1 shadow (snapshot for re-chain across draws) |
|
||
| `$18-$1F` | xform-B accumulators (24-bit, 3 axes × hi/mid/lo) |
|
||
| `$21-$22` | Bresenham dx / dy |
|
||
| `$25-$27` | Polygon scan-fill max-edge / row-bounds / span column |
|
||
| `$28-$2A` | Altimeter angle bytes (1000s / 10000s / heading) |
|
||
| `$2D-$2E` | Cached-vertex pointer ($0140 + idx*8) |
|
||
| `$32-$33` | Frame work-cost accumulator |
|
||
| `$3E-$3F` | Message scroll dest pointer |
|
||
| `$4A-$52` | Section base (24-bit, 3 axes; signed) |
|
||
| `$53-$54` / `$EF-$F0` | Polygon scan-fill min/max X/Y |
|
||
| `$5A-$5D` | Aircraft world X (24-bit) |
|
||
| `$5E-$60` | Altitude (= world Y; $5F/$60 straddle the 8-bit boundary) |
|
||
| `$61-$65` | Aircraft world Z (24-bit) |
|
||
| `$66-$6B` | Section-relative origin offset = camera ZP image |
|
||
| `$6C-$6D` | Pitch (signed 16-bit) |
|
||
| `$6E-$6F` | Bank |
|
||
| `$70-$71` | Yaw |
|
||
| `$78-$89` | Active 3×3 rotation matrix (18 bytes, signed 16-bit per element) |
|
||
| `$8B-$8C` | Scenery dispatcher cursor |
|
||
| `$8E-$8F` | Hires row pointer |
|
||
| `$94-$95` | NeedlePosTable pointer (DrawIndicatorDialNeedle) |
|
||
| `$96-$97` | DrawIndicatorDialNeedle data pointer |
|
||
| `$98-$99` | TestSceneryRange bound |
|
||
| `$9A-$9B` / `$BA-$BB` | Hires row ptrs for the two pages |
|
||
| `$9E-$A2` | Pixel-list scratch |
|
||
| `$A5-$A8` | Loader src/dst pointers |
|
||
| `$A9-$AC` | Multiply scratch |
|
||
| `$AD` | Frame-stash flag (variant 6 of $07/$24) |
|
||
| `$B0-$B1` | Stashed X / Y across nested calls |
|
||
| `$B5` | Vertex output index in clip passes |
|
||
| `$B6-$B7` | Generic 16-bit scratch / Set3DigitString input |
|
||
| `$B8-$B9` | Set3DigitString string pointer |
|
||
| `$BE-$BF` | Compute-distance / Set3DigitString scratch |
|
||
| `$C2-$C5` | ScaleC2ByAX inputs |
|
||
| `$C6-$C7` | Cost accumulator |
|
||
| `$C9-$D2` | Vertex 1 (X/Y/Z hi+lo + outcode-shadow at $D1/$D2) |
|
||
| `$CA` | V1 outcode |
|
||
| `$CB-$D0` | V1 transformed coords |
|
||
| `$D3` | V2 outcode |
|
||
| `$D4-$D9` | V2 transformed coords |
|
||
| `$DA-$E2` | V2 snapshot for EmitClippedLine cleanup |
|
||
| `$E5` | Stream-emit cursor for xform-A |
|
||
| `$E6-$E7` | Pixel-list current position |
|
||
| `$E9` / `$EA` | Line endpoint 1 column / row (140-wide, 192-tall) |
|
||
| `$EB` / `$EC` | Line endpoint 2 column / row |
|
||
| `$F1-$F9` | Bresenham step state |
|
||
| `$FA` | `InputMode` |
|
||
| `$FB-$FD` | Instrument operational flags (3 bytes) |
|
||
| `$FE` | scratch |
|
||
|
||
Instrument operational flags `$FB/$FC/$FD` are bit-masks — bits set when the
|
||
corresponding gauge is operational. `HideOrShowInstruments` (chunk3) compares them
|
||
to the previous value and shows / hides each instrument's bitmap.
|
||
|
||
---
|
||
|
||
## 5. Aircraft State Model
|
||
|
||
The full aircraft state lives in two regions: zero page (high-frequency-access values
|
||
like position, attitude, velocities) and the `$08xx-$0Axx` "expanded state" region
|
||
in chunk4 (instrument values, key state, mode flags).
|
||
|
||
### 5.1 Position and orientation
|
||
|
||
* World position: `$5A-$65`, three signed 24-bit values (X, Y=Altitude, Z) in scenery
|
||
units. The unit is approximately 1/3 metre — used by the scenery system and
|
||
converted to/from metres at the boundaries.
|
||
* Attitude: `$6C-$71`, three signed 16-bit values (pitch, bank, yaw). The high byte
|
||
is the "byte angle" (0-256 = full circle), the low byte is sub-byte interpolation.
|
||
* `ViewDirection` (`$0A70`) — a 16-step view-around-the-aircraft index in $00..$0F.
|
||
Scaled ×16 into a byte angle and folded into yaw via `SetupViewProjection`.
|
||
|
||
### 5.2 Controls
|
||
|
||
| Name | Address | Meaning |
|
||
|------|---------|---------|
|
||
| `YokeHorizPos` (= `$09B0`) | $09B0 | Aileron position, signed |
|
||
| `YokeVertPos` | chunk4 | Elevator yoke position |
|
||
| `RudderPos` | chunk4 | Rudder position |
|
||
| `ElevatorTrim` | chunk4 | Trim setting (-84..+84) |
|
||
| `$0A5F` | | Flap position (0/32/64/...) |
|
||
| `$0A49` | | Mixture setting (0..7) |
|
||
| `$0A58` | | Carb heat (0=off, FF=on) |
|
||
| `PanelLights` | chunk4 | Instrument-light flag |
|
||
| `MagnetoState` | chunk4 | Magneto state (0=off, 1=L, 2=R, 3=both, 4=start) |
|
||
| `$0A6F` | | Throttle setting |
|
||
| `$0998` | | Fuel tank select |
|
||
|
||
### 5.3 Derived values
|
||
|
||
| Name | Address | Meaning |
|
||
|------|---------|---------|
|
||
| `Airspeed` (= `L0A11`) | $0A11 | 16-bit; high byte drives RPM curves + stall envelope |
|
||
| `$0990` | | Smoothed RPM displayed on tachometer |
|
||
| `$0843` | | Climb rate (signed 16-bit) |
|
||
| `$0A36/$0A37` | | Climb-rate indicator smoothed value |
|
||
| `$0830/$0831` | | Magnetic-compass smoothed angle |
|
||
| `$0A15/$0A16` | | Raw heading (16-bit, signed turn rate) |
|
||
| `$2A` | | Final compass byte for display |
|
||
|
||
---
|
||
|
||
## 6. Physics
|
||
|
||
### 6.1 IntegratePhysicsStep
|
||
|
||
`IntegratePhysicsStep` (`src/chunk5.s:8908`) is called every frame in non-slew mode.
|
||
It:
|
||
|
||
1. Reads `$09A5-$09A8` (body-velocity X/Z) and `$09D5/$09D6` (Y).
|
||
2. Adds the world-frame velocity components to `$5A-$65` (position). The world-frame
|
||
components are computed earlier in `ComputeFlightDerivedValues` by multiplying the
|
||
body velocity by the inverse rotation matrix.
|
||
3. If altitude `$5F/$60` would go below ground ($0000/$03), clamps it.
|
||
4. If the aircraft just touched down (`$089E` non-zero), calls
|
||
`ClampAltitudeOnTouchdown` to recompute altitude from climb rate.
|
||
5. Updates the live pitch/bank/yaw at `$6C-$71` by integrating angle deltas.
|
||
6. Sets `OnGroundFlag` based on the altitude clamp.
|
||
7. Triggers crash codes ($0834) when ground contact happens with bad pitch / bank.
|
||
|
||
### 6.2 ComputeFlightDerivedValues
|
||
|
||
Called near the top of the loop (`src/chunk5.s:8545`). Recomputes ~15 derived
|
||
quantities from the live pitch/bank/yaw and airspeed:
|
||
|
||
* sin(pitch), cos(pitch), sin(bank), cos(bank) via `L1763` / `L1778` (chunk4 trig).
|
||
* Rudder authority gauge.
|
||
* Body-frame X/Z velocity contributions (`$0A19-$0A1C`).
|
||
* Stall envelope: when the airspeed-derived term `$09AC` enters the danger band,
|
||
lights the fault state `$08B6` / `$0899`.
|
||
* Climb rate (`$0A0F/$0A10`) from pitch/bank/airspeed scale chain.
|
||
* Turn rate (`$09CD/$09CE`).
|
||
* Magnetic compass slew via `$08B2/$08B3`.
|
||
* Sideslip wrap: if the sideslip integrator at `$09AD` crosses ±90°, flips signs of
|
||
`$09AE/$09B0/$09E5` to keep the indicator symmetric.
|
||
|
||
### 6.3 IntegrateClimbRate
|
||
|
||
`IntegrateClimbRate` (`src/chunk5.s:8843`) slews the climb-rate needle and altitude
|
||
by 0/±1/±2 units per frame. The inner step (`ICR_Step`) compares climb rate against
|
||
the needle target, picks a +1/-1/0 nudge, and applies the OPPOSITE nudge to
|
||
altitude — so when the climb rate is +N, the needle moves up AND altitude increases.
|
||
The function uses a clever `jsr ICR_Step / fall-through to ICR_Step` trick to run
|
||
the step twice per call, giving 2 ticks of integration per frame.
|
||
|
||
A `beq L89A9` jump in the middle handles the "climb rate exactly matches the
|
||
needle" case as a 0-nudge shortcut.
|
||
|
||
### 6.4 UpdateAutoTrimAndYaw
|
||
|
||
Per-frame (`src/chunk5.s:9227`) — pulls `$09AF/$09B0` (yaw integrator) toward zero
|
||
by 5 units when the rudder is centred, clamping at zero. Also runs bomb-drop
|
||
housekeeping via `$0838`.
|
||
|
||
### 6.5 Wind (64K)
|
||
|
||
`ApplyWind` (chunk2) is patched into the main loop via `P64K_B`. It picks one of
|
||
three wind layers (`WindLayer1/2/3`) based on altitude, multiplies by the wind
|
||
direction's sin/cos, and adds to the body velocity. Skipped entirely in 48K mode.
|
||
|
||
### 6.6 CheckFlightEnvelope
|
||
|
||
Tests airspeed and attitude for stall/g-load violations and sets crash codes.
|
||
|
||
---
|
||
|
||
## 7. Scenery System
|
||
|
||
The scenery system is the biggest single piece of the codebase. It consists of a
|
||
disk-backed loader (chunk3), a paged scenery RAM area (`$A800-$BFFF`), and a
|
||
bytecode interpreter (chunk5 `ProcessScenery`) that walks per-section streams of
|
||
~70 different opcodes.
|
||
|
||
### 7.1 File Format Overview
|
||
|
||
A scenery file is a sequence of "sections". Each section is a contiguous stream of
|
||
opcode-bytes. Opcodes consume variable-length payloads (1 to 14+ bytes). Some
|
||
opcodes are flow-control (jump, sub-invoke, range cull); some emit vertices and
|
||
draws; some carry per-section frame data (offsets and axis permutations).
|
||
|
||
Sections live in scenery RAM at `$A800-$BFFF`. The dispatcher cursor `$8B/$8C`
|
||
walks forward through this region until it hits a stream-end opcode or an opcode
|
||
≥ `$46` (invalid → end). Many sections call into others via `$0B` JumpRelative or
|
||
`$18` SubInvoke.
|
||
|
||
### 7.2 Loader
|
||
|
||
The scenery loader is in chunk3 (~`$D3xx-$D5xx`). Key entry points:
|
||
|
||
* `SceneryLoaderEntry1..7` (chunk3 `$DA-..` block) — public callable thunks.
|
||
* `SceneryReadFixed` — read N pages (256-byte units) into the buffer at L1E03,
|
||
advancing the L1E03 destination cursor.
|
||
* `SceneryReadUntilC0` — read bytes until the source pointer crosses into ROM space.
|
||
* `SceneryEnsureOpen` — initialize / re-open the disk read stream.
|
||
* `ComputeBlockFromSector` / `FetchSectorFromDisk` — chunk4 helpers.
|
||
|
||
The loader has two coupled state cells: `L1E01` (16-bit sector counter) and
|
||
`L1E03/L1E04` (destination pointer, advanced by every successful read). Multiple
|
||
in-flight loads share these by save/restore at the loader entries.
|
||
|
||
`LoadSceneryFile0..4` (chunk5 `$AB37`) each load a different per-purpose section
|
||
(world geometry, default scenery, etc.) by setting L1E01/L1E03 from the descriptor
|
||
words `LA60F..LA619`.
|
||
|
||
### 7.3 Dispatcher
|
||
|
||
`ProcessScenery` (`src/chunk5.s:1245`) is invoked per frame. It:
|
||
|
||
1. Sets `$8B/$8C` to the section entry from `LA7E0` (a 16-bit address).
|
||
2. Calls `SceneryInterpreterEntry` → `SceneryInterpreterStep` to fetch the next
|
||
opcode.
|
||
3. `SceneryDispatch` (`asl A / lda SceneryOpcodeTable,X / jmp (L00A5)`) jumps to
|
||
the handler. Each handler advances `$8B/$8C` past the record's bytes and tail-
|
||
jumps back to `SceneryInterpreterEntry`.
|
||
4. Continues until an opcode byte with bit 7 set, or ≥ `$46`. Both terminate the
|
||
pass.
|
||
|
||
### 7.4 Opcode Table
|
||
|
||
`SceneryOpcodeTable` (`src/chunk5.s:1158`) is 70 16-bit pointers covering opcodes
|
||
`$00..$45`. Opcodes above $45 are stream-end markers.
|
||
|
||
#### Vertex emit
|
||
| Op | Handler | Len | Summary |
|
||
|----|---------|-----|---------|
|
||
| $00 | SceneryOpEmitV1XformAndPlot | 7 | Xform-A on V1, plot single pixel. (1 opcode + 6-byte XYZ stream → TransformVertex80C5 internally advances +7.) |
|
||
| $01 | SceneryOpEmitV1Xform80C5 | 7 | Xform-A on V1, no draw (line start) |
|
||
| $02 | SceneryOpEmitV2Xform80C5 | 7 | Xform-A on V2 → EmitClippedLine V1→V2 |
|
||
| $40 | SceneryOpEmitV1Xform7EBC | 5 | Xform-B (XZ only) on V1. (1 opcode + 4-byte XZ stream → TransformVertex7EBC internally advances +5.) |
|
||
| $41 | SceneryOpEmitV2Xform7EBC | 5 | Xform-B on V2 → EmitClippedLine |
|
||
|
||
#### Vertex cache (8-byte slots at $0140 + idx*8)
|
||
| Op | Handler | Len | Summary |
|
||
|----|---------|-----|---------|
|
||
| $31 | SceneryOpRefreshCachedXform80C5 | 8 | Xform-A, write back to cache slot. (Opcode + 1-byte vtx-idx via SetVertexPointerFromStream/L6987 + 6-byte xform-A stream.) |
|
||
| $32 | SceneryOpVertexCachedV1 | 2 | Load cached V1 (opcode + 1-byte vtx-idx via L6987). |
|
||
| $33 | SceneryOpVertexCachedV2 | 2 | Load cached V2 → EmitClippedLine |
|
||
| $35 | SceneryOpVertexCachedDraw | 2 | Load cached V1 + plot pixel |
|
||
| $42 | SceneryOpRefreshCachedXform7EBC | 6 | Xform-B, write back to cache slot. (Opcode + 1-byte vtx-idx + 4-byte xform-B stream.) |
|
||
|
||
#### Curve
|
||
| Op | Handler | Len | Summary |
|
||
|----|---------|-----|---------|
|
||
| $2B | SceneryOpEmitCurve | 9 | Two-vertex curve → 8 segments via midpoint subdivision. xform-B reads 4 bytes for V1, `dec $8B` re-reads, xform-B reads 4 bytes for V2 (= 5 - 1 + 5 = 9 total inc. opcode). |
|
||
|
||
#### Frame setup
|
||
| Op | Handler | Len | Summary |
|
||
|----|---------|-----|---------|
|
||
| $07 | SceneryOpEnterLocalFrame | 14 | Set local frame $66..$6B from stream; 5 axis-permutation variants in L6BB0 |
|
||
| $24 | SceneryOpPushOriginWithStash | 8 | Same as $07 but stashes prior frame for `$AD` flag |
|
||
|
||
#### Cull / branch
|
||
| Op | Handler | Len | Summary |
|
||
|----|---------|-----|---------|
|
||
| $04 | SceneryOpCullByOutcodeList | 4+N | AND outcodes of listed vertex indices; cull if all share half-plane. Length = 4 (header) + N (list bytes, terminated by sentinel). |
|
||
| $0B | SceneryOpJumpRelative | — | Tail-jumps to SceneryJumpToFetched; sets cursor from inline 16-bit target |
|
||
| $13 | SceneryOpJumpIfBeyondXY | — | TestSceneryRangePair on XY; passes ⇒ jump, else continue |
|
||
| $14 | SceneryOpJumpIfBeyondXYZ | — | Same shape, 3 axes |
|
||
| $20 | SceneryOpCullIfOutside1 | 9 | Read target + run TestSceneryRange once |
|
||
| $21 | SceneryOpCullIfOutside2 | 15 | Two range tests |
|
||
| $22 | SceneryOpCullIfOutside3 | 21 | Three range tests |
|
||
| $23 | SceneryOpJumpIfBitsClear | 7 | jump if `(mask1 & *ptr) == 0 && (mask2 & *(ptr+1)) == 0` |
|
||
| $28 | SceneryOpJumpIfWordCompare | 8 | 3 sub-modes (eq, signed-lt, alt-lt) compares 16-bit values at two ptrs |
|
||
|
||
Failure path for `$20..$22` pops to a saved jump target via
|
||
`TestSceneryRangeReject → L00A5`. Success uses fixed advance.
|
||
|
||
#### Data / records
|
||
| Op | Handler | Len | Summary |
|
||
|----|---------|-----|---------|
|
||
| $03 | SceneryOpCall64K_2 | 6 | 48K: skip; 64K: tail-call SceneryRotatedTransform (chunk3) |
|
||
| $05 | SceneryOpADFRecord | 9 | 48K: skip; 64K: patched to JMP LookupADFStation |
|
||
| $0E | SceneryOpCall64K | — | 48K: rts; 64K: chunk3 callback |
|
||
| $1A | SceneryOpWriteWord | 5 | `*dst = *src` (16-bit), dst+src ptrs inline |
|
||
| $1D | SceneryOpNAVRecord | 11 | NAV station; checks $08F3 then matches frequency |
|
||
| $1E | SceneryOpCOMRecord | inline | COM/airport record; length byte at offset 1 |
|
||
| $25 | SceneryOpStoreImmWord | 5 | `*dst = imm16`; dst ptr (2 bytes) + 2 literal bytes (= 4-byte payload + opcode). |
|
||
| $29 | SceneryOpCopyToD2 | 1 | Two branches: line-emit (copy V2 → shadow) or polygon-fill |
|
||
|
||
#### Misc
|
||
| Op | Handler | Len | Summary |
|
||
|----|---------|-----|---------|
|
||
| $06 | SceneryOpDrawLine | 5 | Reads 4 raw screen-coord bytes into `$E9..$EC` and tail-jumps to `DrawColorLine` (HUD-style overlay; bypasses 3D pipeline). |
|
||
| $09 / $0A | SceneryOpSkip3 | 3 | Pure skip |
|
||
| $0D | SceneryOpHeader | 6 | Section-header + demand-load trigger. Latches 5 inline payload bytes into `$08E5..$08E9` (scale/range/tile-delta/slot index), and (when bit 7 of `$08E9` is clear) cumulatively advances the saved section-base cursor `$08E7` by the current cursor `$8B`. Masks `$08E9` to slot index 0..3 then calls `SceneryHeaderLoadIfMiss` via L8776: on a cache miss invalidates newer slots and DMA-fetches the section bytecode from disk via `SceneryHeaderRunSection`; on a cache hit returns immediately. |
|
||
| $0E | SceneryOpCall64K | 0 | 48K: `rts` immediately (= `SceneryOpReturn`); 64K: tail-jumps `SceneryOp64KCallback` (chunk3). No advance — pops the dispatcher recursion. |
|
||
| $11 | SceneryOpSkip1 | 1 | Pure 1-byte no-op. |
|
||
| $12 | SceneryOpSetColor | 2 | Inline byte indexes `ToHiresColorTable` (16 entries) to pick 1-of-8 hires colours, then calls `SetPixelDrawMode` to patch the 4 line/span ORA/AND opcode + 4 operand sites. |
|
||
| $18 | SceneryOpSubInvoke | 3 | Push cursor+3; jump to relative target; recurse `SceneryInterpreterStep`. |
|
||
| $19 | SceneryOpReturn | 0 | `rts` — pops one level of recursion. |
|
||
| $1B | SceneryOpModeWhite | 1 | Restores the line drawer to day mode: writes `STY $B1` ($84 $B1) at `DCLYMajorSaveByte` and `LDA (HiresRowPtr),Y` ($B1 $8E) at `DCLXMajorReadByte`, then `SetPixelDrawMode #$03` (HIRES_WHITE1). |
|
||
| $1C | SceneryOpDayOnly | 1 | If `$083C & $01` (= day phase) → skip; else patches `DCLYMajorSaveByte` to `BPL +$2E` ($10 $2E) and `DCLXMajorReadByte` to `BPL +$16` ($10 $16), then `SetPixelDrawMode #$01` (HIRES_VIOLET). The BPL offsets jump past the actual paint store so night-only objects don't render. |
|
||
| $2F | SceneryOpResetState | 1 | **Arms** polygon mode: `$2C = $FF`, `$B5 = 0`. Pairs with `$29` polygon-end. Falls through into `$11 SceneryOpSkip1` for the advance. The "Reset" name is misleading. |
|
||
|
||
Invalid opcodes (`$08, $0C, $0F, $10, $15, $16, $17, $1F, $26, $27, $2A, $2C, $2D,
|
||
$2E, $30, $34, $36-$3F, $43, $44, $45`) all use `SceneryOpInvalid` which calls
|
||
`L1F89` (`SwapPagesWithStash`) with `A = $90`, then falls through into
|
||
`SceneryDispatch` with whatever value L1F89 left in A — an in-engine recovery
|
||
fallback rather than a hard reset. The state-stash side effect preserves the
|
||
in-progress aircraft state through any fault.
|
||
|
||
**Stream end** (`SceneryStreamEnd`, `src/chunk5.s:1267`) fires not only on opcode
|
||
bytes with bit 7 set (= ≥ `$80`) but ALSO on any opcode in `[$46..$7F]` — these
|
||
neither dispatch nor return because the dispatcher's `cmp #$46 / bmi
|
||
SceneryDispatch` discards them. `SceneryStreamEnd` clears the three "lookup in
|
||
progress" mirrors (`$090A` / `$08F3` / `$08A9`) and `rts`s.
|
||
|
||
### 7.5 Sub-Invoke and Recursive Sections
|
||
|
||
`SceneryOpSubInvoke` ($18) pushes the post-record cursor and recurses
|
||
`SceneryInterpreterStep` to walk a child section. On return, the cursor is restored
|
||
and the parent stream continues. A depth counter at `$08B5` is decremented on
|
||
return so a nested section is treated identically to the top-level dispatch.
|
||
|
||
### 7.6 Section Coordinate Frame
|
||
|
||
Each section runs with a base origin at `$4A-$52` (24-bit) and a camera offset at
|
||
`$66-$6B` (16-bit-per-axis = base + cam-pos delta). The `$07`/`$24` opcodes update
|
||
this frame from inline stream bytes. Each axis pair `$66/$67`, `$68/$69`, `$6A/$6B`
|
||
holds the (cam_axis - section_anchor) delta that vertex transforms subtract from
|
||
each emitted vertex.
|
||
|
||
The five variants of `$07/$24` (encoded in the first byte of the record) permute
|
||
axes differently:
|
||
* L6CCE — 4× asl/rol cascade producing a halved frame
|
||
* L6C6E — byte combine: hi of scratch[i-1] with lo of scratch[i+1]
|
||
* L6C89 — cascade with scratch hi byte
|
||
* L6C53 — direct copy
|
||
* L6D28 — alternate axis order
|
||
|
||
These variants let a single bytecode encode the same scenery section at multiple
|
||
scales / orientations.
|
||
|
||
---
|
||
|
||
## 8. 3D Pipeline
|
||
|
||
### 8.1 Coordinate Frames
|
||
|
||
Three frames in play:
|
||
|
||
1. **World** — the absolute coordinate frame; aircraft `$5A-$65` lives here.
|
||
2. **Scenery-section** — translated by the section anchor, optionally permuted by
|
||
`$07/$24` variant.
|
||
3. **Camera-relative** — vertices after `TransformVertex` subtracts `$66-$6B`. This
|
||
is what's projected.
|
||
|
||
### 8.2 Matrix Setup (`SetupViewProjection`)
|
||
|
||
`SetupViewProjection` (`src/chunk5.s:203`) builds the 3×3 rotation matrix at
|
||
`$78..$89` from inputs:
|
||
|
||
* Yaw (`$70/$71`, 16-bit signed)
|
||
* Pitch (`$6C/$6D`)
|
||
* Bank (`$6E/$6F`)
|
||
* `ViewDirection` (`$0A70`, 4-bit index — scaled ×16 into the yaw)
|
||
|
||
The matrix is computed via 9 calls to `chunk4 L177B` (cosine table interpolation
|
||
with sub-byte fraction) followed by `ScaleC2ByC4` multiplies (16-bit signed). The
|
||
matrix elements end up scaled differently per column (`$L6301` applies col 0 >>= 1
|
||
and col 2 >>= 2) to keep multiply results in a known range — the renderer's
|
||
projection compensates.
|
||
|
||
The matrix at `$78..$89` is in *column-major* layout when the source uses it
|
||
multiplied as `(dx,dy,dz) * M`. Conceptually:
|
||
|
||
```
|
||
$78 $79 $7A $7B $7C $7D (row 0: cos(yaw)*cos(bank) etc)
|
||
$7E $7F $80 $81 $82 $83 (row 1: sin(pitch)*sin(yaw) etc)
|
||
$84 $85 $86 $87 $88 $89 (row 2: -sin(yaw)*cos(pitch) etc)
|
||
```
|
||
|
||
(The exact symbolic expansion depends on the rotation convention — see
|
||
`port/src/chunk5Setup.c` in the C port for the bit-perfect implementation.)
|
||
|
||
### 8.3 Vertex Transform
|
||
|
||
Two flavours, picked per opcode:
|
||
|
||
**`TransformVertex7EBC` (xform-B)** — 4-byte stream (X-hi/X-lo/Z-hi/Z-lo only;
|
||
Y comes from the section base). Used for ground-plane sceneries (buildings, runway
|
||
edges). Inputs: stream bytes − `$66/$6A` (X/Z camera-axis delta). Output: 9 multiply-
|
||
add steps using the 9 matrix coefficients.
|
||
|
||
**`TransformVertex80C5` (xform-A)** — 6-byte stream (full XYZ). Used for sceneries
|
||
with vertical detail (towers, mountains). Same matrix multiply but reads Y from
|
||
the stream.
|
||
|
||
Both transforms:
|
||
1. Read the delta bytes from `($8B),y`.
|
||
2. Subtract `$66-$6B` to get camera-relative coordinates.
|
||
3. Auto-scale: if any |hi byte| ≥ $40, halve all 3 axes and increment `$2F`
|
||
(scale exponent). Repeats until the smallest fits.
|
||
4. Multiply by the 3×3 matrix at `$78..$89` via the chunk4 `ScaleC2ByC4` primitive.
|
||
5. Apply `L8234` range-check halve to keep the projected result in -127..127.
|
||
6. Store at `$D4-$D9` (V2) or `$CB-$D0` (V1).
|
||
|
||
The 6-iteration shift-and-add multiply at `L1818` (chunk4) is the inner kernel; we
|
||
have a bit-perfect C port at `port/src/chunk5Transform.c`.
|
||
|
||
### 8.4 Vertex Cache
|
||
|
||
A 32-slot ring at `$0140` (each slot 8 bytes) caches transformed vertices for
|
||
re-use across multiple line draws — a common scenery encoding where one vertex
|
||
participates in 5+ edges. The opcodes for the cache:
|
||
|
||
* `$31`/`$42` (RefreshCachedXform) — transform a new vertex and write to slot.
|
||
* `$32`/`$33` (VertexCachedV1/V2) — load a slot into V1 or V2 for the next emit.
|
||
* `$35` (VertexCachedDraw) — load slot into V1 and plot a single pixel.
|
||
|
||
The "slot valid" flag is the high bit of byte 7 of each slot ($DB-relative for V2,
|
||
$D2-relative for V1).
|
||
|
||
### 8.5 Frustum Clipping
|
||
|
||
A 6-plane Cohen-Sutherland-style outcode is computed per vertex by
|
||
`ClassifyVertex1` / `ClassifyVertex2`:
|
||
|
||
| Bit | Plane |
|
||
|-----|-------|
|
||
| $80 | z < 0 (behind viewer) |
|
||
| $40 | x + z < 0 (right edge) |
|
||
| $20 | z - x < 0 (left edge) |
|
||
| $10 | y + z < 0 (bottom) |
|
||
| $08 | z - y < 0 (top) |
|
||
|
||
Outcodes go to `$CA` (V1) / `$D3` (V2). The `EmitClippedLine` routine then:
|
||
|
||
1. ANDs the two outcodes; if non-zero, both ends share a clip plane → cull.
|
||
2. ORs them; if non-zero, at least one is outside → call `ClipBothVerticesToFrustum`.
|
||
3. Calls `ClipVertex2ToFrustum` if just V2 is outside.
|
||
4. Projects to screen via `ProjectV1ToScreen` / `ProjectV2ToScreen` and emits
|
||
the line via `DrawColorLine`.
|
||
5. After the draw, restores V1 from V2's shadow at `$DB` so the next emit can
|
||
chain off the same endpoint without re-transforming.
|
||
|
||
`HalveBothVertices` is the overflow-recovery path: if a per-axis subtract during
|
||
clipping overflows, halve both endpoints (preserves the line direction) and retry.
|
||
|
||
### 8.6 Sutherland-Hodgman for Polygon Fill
|
||
|
||
When a polygon (= sequence of vertex emits closed by `$29`) is detected, the
|
||
clipper runs 4 passes across all stored vertices:
|
||
|
||
* **Pass 1** (Left, plane Z-X=0): `PrimVerts → SecVerts`
|
||
* **Pass 2** (Top, plane Z-Y=0): `SecVerts → PrimVerts`
|
||
* **Pass 3** (Right, plane X+Z=0): `PrimVerts → SecVerts`
|
||
* **Pass 4** (Bottom, plane Y+Z=0): `SecVerts → PrimVerts`
|
||
|
||
Each pass walks the polygon vertices in order. For each edge (V[i] → V[i+1]):
|
||
* If both inside the plane: emit V[i] to output.
|
||
* If V[i] inside, V[i+1] outside: emit V[i] then the clipped intersection.
|
||
* If V[i] outside, V[i+1] inside: emit the clipped intersection.
|
||
* If both outside: emit nothing.
|
||
|
||
The 4 passes share `$B4` (sticky outcode of last-classified vertex), `$B5` (output
|
||
count), `X` (input index, counts down), `Y` (output index, counts up). After all
|
||
4 passes the polygon is in `PrimVerts` ready for `PolygonScanFill_ProjectVertices`.
|
||
|
||
### 8.7 Perspective Projection
|
||
|
||
`ProjectVertex` (`src/chunk5.s:5151`) does the two perspective divides (X/Z and Y/Z)
|
||
that turn camera-relative coords into screen pixels:
|
||
|
||
1. Look up the X / Y axis perspective table (`kPerspXTable` at $7D80 / `kPerspYTable`
|
||
at $7E00) via a self-modified `LDA L7D77,X` (chunk5.s:5219). The table maps a
|
||
7-bit signed quotient → final screen-pixel offset.
|
||
2. `PerspectiveDivide` does the divide: 7-bit signed quotient = numerator (X or Y)
|
||
/ denominator (Z). The algorithm is 8 unrolled iterations of shift-subtract,
|
||
interleaved across two paths (PosPath / NegPath) — each iteration's branch
|
||
crosses to the opposite path at the same iteration index. The resulting
|
||
quotient ends up in `L00A5` as a sequence of "stayed on this path" bits.
|
||
|
||
The early-out paths handle |num| = |denom| (unity) and num + denom = 0 (negative
|
||
unity) without entering the loop.
|
||
|
||
---
|
||
|
||
## 9. Rasterization
|
||
|
||
### 9.1 Polygon Fill (`PolygonScanFillSetup`)
|
||
|
||
After clipping, the polygon goes through:
|
||
|
||
1. **`PolygonScanFill_ProjectVertices`** — projects each clipped vertex to screen
|
||
via `ProjectVertex`, stashes screen-X in `SecVertXHi` and screen-Y in
|
||
`SecVertYHi`, tracks min/max row + column across all vertices, and adds an
|
||
estimated work cost to `$32/$33`.
|
||
|
||
2. **`PolygonScanFill_BuildEdgeList`** — for each consecutive vertex pair, computes
|
||
the screen-Y delta. Three cases:
|
||
* delta = 0 → horizontal edge (handled by `PolygonScanFill_HorizEdge`, which
|
||
folds consecutive horizontal edges into a single $FF-marked span).
|
||
* delta < 0 → edge runs upward; encode top vertex first.
|
||
* delta > 0 → edge runs downward; encode top vertex first.
|
||
|
||
The per-edge state is stored back into `PrimVerts[x]`:
|
||
* `PrimVertXLo` = top screen row
|
||
* `PrimVertXHi` = row count - 1
|
||
* `PrimVertYHi` = top screen column
|
||
* `PrimVertZLo/ZHi` = column delta per row (signed Q8.8)
|
||
* `PrimVertYLo` = byte-bit half-row adjust flag
|
||
|
||
3. **`PolygonScanFill_SetupRowEmit`** — sets `$25 = max edge index`, `$B1 = top row`,
|
||
then runs the per-row scan loop.
|
||
|
||
4. **`PolygonScanFill_RowTop`** — for each row from top to bottom, walks all edges
|
||
`(X = $25 down to 0)`:
|
||
* If the edge crosses the current row, capture its X intercept into the sort
|
||
buffer at `L7889` (a self-modified `STA $02,X` site).
|
||
* If `PrimVertXHi` has the $FF horizontal-edge sentinel, call `DrawColorSpan`
|
||
for the captured horizontal span directly.
|
||
|
||
5. **`PolygonScanFill_SortIntercepts`** — bubble-sort the captured X values in
|
||
`$02..$0F` so spans emit left-to-right.
|
||
|
||
6. **`PolygonScanFill_EmitSpansLoop`** — for each consecutive pair of sorted
|
||
intercepts, call `DrawColorSpan` to emit the filled span.
|
||
|
||
7. **`PolygonScanFill_NextRow`** — `inc $B1`, loop.
|
||
|
||
### 9.2 `DrawColorLine` (Bresenham)
|
||
|
||
Standard Bresenham with two interesting wrinkles:
|
||
|
||
* **8-quadrant via swap + sign** — ensure `X1 ≤ X2` by swapping endpoints, then
|
||
derive |dx|, |dy|. The Y-step direction is encoded by self-modifying the
|
||
`INC $EA` / `DEC $EA` opcode at `DCLYMajorRowStep` based on whether Y2 > Y1.
|
||
* **Pick major axis** — if |dy| > |dx| use Y-major (paint one pixel per row, step
|
||
X conditionally); else X-major (paint one per column, step Y conditionally).
|
||
|
||
The inner Y-major and X-major loops each have 4 self-modified mask sites
|
||
(`L7982/L7A26/L7A2E/L7A9A`) and 3 self-modified OR sites (`L7976/L7A1A/L7A8E`) that
|
||
`SetPixelDrawMode` rewrites to swap between ORA / AND / EOR plus the even/odd
|
||
colour mask tables.
|
||
|
||
Two paint sites (`DCLYMajorSaveByte`, `DCLXMajorReadByte`) get patched to `BPL <skip>`
|
||
at night by `SceneryOpDayOnly` — when scenery defines day-only objects, those
|
||
ops are turned into no-ops via the BPL trick.
|
||
|
||
### 9.3 `DrawColorSpan`
|
||
|
||
`DrawColorSpan` (`src/chunk5.s:4283`) emits a horizontal span:
|
||
* Inputs: `A` = width in colour pixels (0..139), `$27` = right edge.
|
||
* Setup: compute byte-offset + bit-position for the right edge via
|
||
`AltColorPixelToByteTable` and `PixelToBitNumberTable`.
|
||
* Right-edge pixel loop: paint pixels one at a time until aligned on a byte boundary.
|
||
* Byte-mode middle: fill whole bytes via `DCSEnterByteMode`.
|
||
* Left-edge cleanup: paint the remaining 1..7 pixels.
|
||
|
||
The 4 self-mod sites at `L7921/L7922/L792D/L792E` rewrite the ORA mask table per
|
||
colour mode.
|
||
|
||
### 9.4 `PlotColorPixel`
|
||
|
||
Single-pixel toggle with self-modified ORA/AND at `L7976/L7983` and self-modified
|
||
operand at `L7977/L7984`.
|
||
|
||
### 9.5 Apple II Hires Layout
|
||
|
||
The Apple II hires screen is 280 pixels wide × 192 rows. Each byte holds 7 pixels
|
||
+ 1 colour-phase bit. The renderer uses a 140-pixel "colour pixel" model where:
|
||
|
||
* Each colour pixel is one of 4 hues (black, magenta, blue, white) depending on
|
||
byte and bit position.
|
||
* `OrMaskTable1/2` and `AndMaskTable1/2` are the masks for each colour group.
|
||
* `HiresTableLo/Hi` provides per-row hires page-1 base addresses (320 bytes ×
|
||
192 entries).
|
||
* `HiresPageDelta` is the difference (always $20) between page 1 and page 2 bases.
|
||
|
||
Page flipping is achieved by writing $20 to `HiresPageDelta` (page 1 visible,
|
||
draw on page 2) or $E0 (= -$20) for the reverse. `FlipPagesFillViewport` swaps
|
||
pages each frame.
|
||
|
||
---
|
||
|
||
## 10. Instrument Panel
|
||
|
||
### 10.1 Per-Instrument Strategy
|
||
|
||
Every instrument uses the same pattern:
|
||
|
||
1. Read the current value (e.g. RPM, throttle position).
|
||
2. Compare against the "last drawn" cell (one cell per instrument: chunk4
|
||
`LastDrawnElevatorPos`, `LastDrawnAileronPos`, `LastDrawnSlipSkid`,
|
||
`LastDrawnRudderPos`, `LastDrawnThrottle`, `LastDrawnFlaps`, `LastDrawnTrim`,
|
||
`LastDrawnMixture`, `LastDrawnFuelLeft`, `LastDrawnFuelRight`,
|
||
`LastDrawnOilTemp`, `LastDrawnOilPressure`).
|
||
3. If unchanged → RTS.
|
||
4. Else: redraw the OLD value (XOR mode → undraws it) then redraw the NEW value
|
||
(XOR mode → draws it).
|
||
5. Store new value to the "last drawn" cell.
|
||
|
||
The XOR mode for redraws is achieved by `SetPixelDrawMode #$83` which patches the
|
||
line drawer to EOR mode.
|
||
|
||
Most instruments are operational gates: a bit in `$FB/$FC/$FD` indicates the
|
||
instrument is working. Cleared bits cause `HideOrShowInstruments` (chunk3) to
|
||
paint over the gauge with the static panel background.
|
||
|
||
### 10.2 `DrawIndicatorDialNeedle` (chunk4)
|
||
|
||
The shared needle-painter for round dial instruments (airspeed, vertical-speed,
|
||
ADF, RPM). Takes:
|
||
* `A` = position byte (0..$57 for full sweep)
|
||
* `X` = needle index (0=alt1, 1=alt2, 2=airspeed, 3=vertical, 4=ADF)
|
||
|
||
Algorithm:
|
||
|
||
1. Pick the pixel-list table based on `IndicatorDialNeedleStyle[X]` (thin or thick).
|
||
2. Pick the dial-quadrant from the position byte:
|
||
* 0..$15: upper-left (`DIN_UpperLeft`, X increments, Y decrements)
|
||
* $16..$2B: upper-right (`DIN_UpperRight`, X decrements, Y decrements)
|
||
* $2C..$41: lower-left (`DIN_LowerLeft`, X decrements, Y increments)
|
||
* $42..$57: lower-right (`DIN_LowerRight`, X increments, Y increments)
|
||
3. Configure the inner pixel-emit loop's 4 self-modified opcode sites
|
||
(`L1A01/L1A04/L1A32/L1A38`) for the chosen quadrant via the
|
||
`SetUpForINX/DEX/INC/DEC` helpers.
|
||
4. Walk the pixel list, XOR-ing each pixel into the hires page.
|
||
|
||
The pixel-list format is a sentinel-terminated stream of (X-step, count) pairs.
|
||
|
||
### 10.3 Update*Indicator Family (chunk4)
|
||
|
||
Each of these is a thin wrapper that:
|
||
* Compares the new value against the per-instrument "last drawn" cell
|
||
* Calls a per-instrument inner `Draw` helper twice (old XOR-undraw, new XOR-draw)
|
||
* Stores the new value
|
||
|
||
The inner helpers each prep `(X, Y)` for a position and dispatch to one of:
|
||
* `DrawAileronOrRudderIndicator` (PLAileronAndRudderIndicators pixel list)
|
||
* `DrawFTM_Helper` (PLFlapsTrimMixtureIndicator — flaps/trim/mixture share)
|
||
* `DrawFuelOrOilGauge` (PLFuelAndOilGauges)
|
||
* `DrawSlipSkidIndicator` (PLSlipSkidIndicator)
|
||
* `DrawElevatorControlPositionIndicator` (PLElevatorControlPositionIndicator)
|
||
* `DrawThrottleIndicator` (PLThrottleIndicator)
|
||
|
||
### 10.4 Artificial Horizon (`UpdateArtificialHorizon`, chunk5)
|
||
|
||
Repaints the artificial-horizon area from the current bank ($6F) and pitch ($6D):
|
||
|
||
1. Fills the upper $1F rows with the "top half" colour (orange when upright, blue
|
||
when inverted).
|
||
2. If |pitch| ≥ $20 the horizon line is off-screen — just apply bezel masks.
|
||
3. Looks up the per-pitch slope offset in `ArtHorizonSlopeTable` (a 34-byte signed
|
||
LUT), multiplies by sin(bank), and derives the two horizon endpoints
|
||
(column, row) in `$E9/$EA` and `$EB/$EC`.
|
||
4. Self-modifies `DrawSkyGroundRow` to jump to `AltDrawSkyGroundRow` and invokes
|
||
`FillMixedViewportRows` to rasterise the slanted horizon line via Bresenham.
|
||
5. Fills the area below the horizon with the "bottom half" colour.
|
||
6. Applies the round-bezel `ApplyArtificialHorizonMask` to clip to a circle.
|
||
|
||
### 10.5 Turn Coordinator (`UpdateTurnCoordinator`, chunk5)
|
||
|
||
Computes a 16-step tilt index from $09CD/$09CE (turn rate). The tilt becomes a
|
||
4-element delta lookup in `$0DE0,X` (X = A*4), which gives two `DrawColorLine`
|
||
strokes mirrored around the centre (12, 166).
|
||
|
||
Per-page snapshots at `$0A40` (page 1) / `$0A41` (page 2) cache the previous
|
||
tilt; on page-flip, only the new page is repainted. The chunk5 dispatch table
|
||
exposes `DrawTurnCoordinatorAndSnapshot` (`$6015` trampoline) so external code
|
||
can force a redraw on the active page.
|
||
|
||
### 10.6 Magnetic Compass and Heading
|
||
|
||
`UpdateMagneticHeading` (`$0A15/$0A16` raw → `$2A` byte) reduces the raw 16-bit
|
||
heading by modulo $58 and clamps to ±$09 to track turn rate. `DrawHeading`
|
||
slews the displayed value at `$08B2/$08B3` toward 0 with rate-dependent steps,
|
||
then formats as a 3-digit string via `Set3DigitString`.
|
||
|
||
### 10.7 Altimeter
|
||
|
||
`UpdateAltimeterPose` (`src/chunk5.s:10022`) computes three altimeter hands from
|
||
altitude (`$5F/$60` + `$099E` correction term):
|
||
|
||
1. Multiplies by $24F4 (= ~0.144) to scale altitude to dial angle.
|
||
2. Modulo $0370 reduce by repeated subtract (full revolution).
|
||
3. Multiplies by $0CCC and adds $16 → 10,000-foot hand at `$29`.
|
||
4. Modulo $58 reduce → 1,000-foot hand at `$28`.
|
||
5. The 100-foot hand uses the chunk2 `UpdateAltimeter10K` routine.
|
||
|
||
### 10.8 Radios
|
||
|
||
| Radio | Mode | Storage |
|
||
|-------|------|---------|
|
||
| COM | 4 digits, 118.0-135.0 | `str_com1` |
|
||
| NAV1 / NAV2 | 4 digits, 108.0-117.0 | `str_nav1` / `str_nav2`; `$0A63` picks which to edit |
|
||
| VOR1 / VOR2 OBS | 3 digits, 000-359 | `VOR1ObsCourse` / `VOR2ObsCourse`; `$0A71` picks |
|
||
| ADF | 3 digits, kHz | `str_adf_frequency` (chunk3) |
|
||
| Transponder | 4 octal digits | `str_xpndr` |
|
||
| DME | 3 digits, distance | `str_dme` |
|
||
| OMI | 2 marker chars | `str_omi` |
|
||
|
||
The key handlers (`KeyDecrease` / `KeyIncrease` / `Select1` / `Select2`) dispatch
|
||
on `InputMode` ($FA) which holds the currently-edited instrument. See §12.
|
||
|
||
NAV1/NAV2 lookup is gated by `$08F4` (per-instrument enable bits). When a frequency
|
||
changes, `RequestNAV1Lookup` / `RequestNAV2Lookup` clears the active flag and arms
|
||
a fresh scenery scan for the new frequency. The scenery interpreter's `$1D`
|
||
NAVRecord opcodes carry the per-station data; on a match the station coords land
|
||
in `$08F9-$0900`.
|
||
|
||
VOR distance and bearing are computed in `ComputeStationDistance` (great-circle
|
||
approximation: max + min*~0.5 via a 16-bit multiply) and `ComputeVORBearing`
|
||
(distance-derivative scaled into a clamped deflection). The clamped deflection is
|
||
3-state: $00 (out of range, zeros indicator), $01 (saturated), $02 (on-radial).
|
||
|
||
### 10.9 ATIS Message Scroll (64K)
|
||
|
||
`DrawATISMessage` (chunk3) and the digit-formatting machinery at `LB148-LB337`
|
||
(chunk5) compose the rolling ATIS message displayed on the COM radio:
|
||
|
||
```
|
||
OHARE INTERNATIONAL AIRPORT
|
||
INFORMATION BRAVO 13:00 ZULU
|
||
WEATHER - VISIBILITY
|
||
10 - TEMPERATURE 53 -
|
||
WIND 00 AT 0 - ALTIMETER
|
||
29.95 - LANDING AND DEPARTING
|
||
RUNWAY 04 - ADVISE CONTROLLER...
|
||
```
|
||
|
||
A byte $80+ in the message stream encodes a fragment lookup via
|
||
`ChunkOffsetTable`. The digit-formatting pipeline handles airport-specific values
|
||
(wind, temp, visibility, ceiling, runway, time) with leading-zero suppression.
|
||
|
||
### 10.10 Engine Gauges
|
||
|
||
* **RPM** (`DrawRPM`) — formats `$0990` as 2 digits + '0' or '5' (even/odd RPM
|
||
bucket).
|
||
* **CHT / Oil Temperature** — slow-slewed targets in chunk3
|
||
`UpdateEngineWithMagneto`. The slew uses 8-bit fraction accumulators at
|
||
`CHTSlewFraction` / `OilTempSlewFraction`.
|
||
* **Fuel tanks L/R** — slow-slewed gauges driven by the fuel-burn accumulator at
|
||
`$0992-$0994` (left) / `$0995-$0997` (right).
|
||
|
||
---
|
||
|
||
## 11. Engine Model
|
||
|
||
### 11.1 48K Engine (`UpdateSimpleEngine`)
|
||
|
||
`UpdateSimpleEngine` (`src/chunk5.s:10887`) is the baseline:
|
||
|
||
1. Picks RPM curve from throttle (`$0A6F`).
|
||
2. Clamps to fuel-tank-available: if the selected tank is empty (X register loaded
|
||
from `$0994` left or `$0997` right is zero), RPM target = 0.
|
||
3. Applies a Reality Mode idle floor of $0D.
|
||
4. Every 32 ticks, burns fuel from the selected tank by the throttle-scaled rate.
|
||
5. Pegs CHT / oil temp to a fixed value ($05) — no dynamic gauge update.
|
||
|
||
In 64K mode this is patched to `JMP UpdateEngineWithMagneto` (chunk3).
|
||
|
||
### 11.2 64K Engine (`UpdateEngineWithMagneto`, chunk3)
|
||
|
||
The full engine has five phases:
|
||
|
||
1. **RPM curve selection** — combines throttle, carb-heat penalty (`$0A58`),
|
||
prop-spinup offset (`EngineSpinupCounter` after restart), mixture-fault clamp
|
||
(`$0991 & $03` = lean fault), and single-magneto degradation. Result is a curve
|
||
index into `RPMCurveIdle` (when engine off) or `RPMCurveRun`.
|
||
|
||
2. **Reality-mode idle floor** — same $0D floor as the 48K version.
|
||
|
||
3. **CHT gauge** (`$099C`) — target from engine state + mixture fault. Slews by $0A
|
||
per call (when enabled by `$FC & $40`).
|
||
|
||
4. **Oil temp gauge** (`$099D`) — same shape as CHT, slews by $64.
|
||
|
||
5. **Fuel consumption** — every 32 ticks, burns from the selected tank.
|
||
WW1 Ace mode multiplies the burn rate by 4 (via `txa / asl / asl`). The
|
||
left-tank-fault flag `$0991 & $04` clamps the burn to 0.
|
||
|
||
The magneto state (`MagnetoState` 0=off / 1=left / 2=right / 3=both / 4=start)
|
||
gates the engine-running check; bits in `LeftMagnetoOn` / `RightMagnetoOn` are
|
||
the actual electrical flags (cleared on failure).
|
||
|
||
---
|
||
|
||
## 12. Input
|
||
|
||
### 12.1 Key Buffer
|
||
|
||
`ReadKeyBuffer` / `WriteKeyBuffer` (`src/chunk5.s:7063`) implement an 8-slot key
|
||
ring buffer at `KeyBuffer`. The hardware keystroke is read in
|
||
`MaybeProcessKey` (`src/chunk5.s:7196`); the high bit drives a self-modified
|
||
`jmp ($0000)` dispatch through `KeyTable`.
|
||
|
||
`KeyTable` (chunk4) is a 32-entry table of 16-bit addresses; the index is
|
||
`(key - '`') * 2`. Keys A-Z, 0-9 and the major punctuation each map to a
|
||
specific handler:
|
||
|
||
| Key | Handler |
|
||
|-----|---------|
|
||
| `,` | KeyDecrease |
|
||
| `.` | KeyIncrease |
|
||
| `1` | Select1 (also magnetos: off) |
|
||
| `2` | Select2 (magnetos: right) |
|
||
| `3` | MagnetosLeft |
|
||
| `4` | SelectRadarView (magnetos: both) |
|
||
| `5` | Select3DView (magnetos: start) |
|
||
| `8` | SlewPitchUp |
|
||
| `9` | SlewPitchDown |
|
||
| `W` | DeclareWar |
|
||
| `Z` | SlewResetAngles |
|
||
| `X` | DropBomb |
|
||
| `Y` | FlapsUp |
|
||
| `N` | FlapsDown |
|
||
| `V` | TrimUp |
|
||
| `R` | TrimDown |
|
||
| `K` | ExitDemoMode |
|
||
| `S` | SaveModeToLibrary |
|
||
| `+` | ReadModeFromLibrary |
|
||
| `Q` | CoursePlotting |
|
||
| `Space` | BrakesOrGuns |
|
||
| `/` | ToggleThrottle |
|
||
| Ctrl+A | ADF |
|
||
| Ctrl+B | AltimeterAdjust |
|
||
| Ctrl+C | ComRadio |
|
||
| Ctrl+D | HeadingAdjust |
|
||
| Ctrl+F | FuelTankSelect |
|
||
| Ctrl+H | LessThrottle |
|
||
| Ctrl+I | CarbHeat |
|
||
| Ctrl+L | ToggleLights |
|
||
| Ctrl+M | MagsAndMixture |
|
||
| Ctrl+N | NavRadio |
|
||
| Ctrl+P | TogglePause |
|
||
| Ctrl+T | TransponderOrTransferParams |
|
||
| Ctrl+U | MoreThrottle |
|
||
| Ctrl+V | VORS |
|
||
| Ctrl+X | Transponder |
|
||
|
||
### 12.2 Paddles / Joystick
|
||
|
||
`ReadPaddles` (`src/chunk5.s:7100`) implements the classic Apple II paddle-read by
|
||
triggering `PTRIG` ($C070) and polling `PADDL0/PADDL1` until each discharges. The
|
||
result is `(X, Y) = (paddle0_count, paddle1_count)`. If paddle 0 saturates (X
|
||
wraps to 0), the routine pops its return address and returns to the caller's
|
||
caller — a "paddle saturated, abort the calling context" signal.
|
||
|
||
`ScalePaddleValue` clamps to ±127 with overflow saturation.
|
||
`CalibrateJoystickIfButtonDown` reads the paddle button to detect calibration mode.
|
||
|
||
### 12.3 `InputMode` State Machine
|
||
|
||
`InputMode` ($FA) holds the currently-edited instrument / control:
|
||
|
||
| Value | What's being edited |
|
||
|-------|---------------------|
|
||
| $02 | Radar View (Zoom Out / In) |
|
||
| $03 | Magnetos / Mixture (1/2/3 keys, chunk3 mixture patch) |
|
||
| $04 | COM Radio upper digits |
|
||
| $05 | COM Radio lower digits |
|
||
| $06 | NAV Radio upper digits (`$0A63` picks NAV1/NAV2) |
|
||
| $07 | NAV Radio lower digits |
|
||
| $08-$0B | Transponder digit 0..3 |
|
||
| $0C | VOR OBS course (`$0A71` picks VOR1/VOR2) |
|
||
| $0D-$0F | ADF frequency digit 0..2 (chunk3 patch path) |
|
||
| $10 | Fuel Tank Select |
|
||
|
||
`KeyDecrease` / `KeyIncrease` route ±1 to the corresponding handler via the
|
||
appropriate digit-edit routine (`DecComOrNavLowerDigits`, `DecNavDigits`,
|
||
`IncComOrNavLowerDigits`, `IncNavDigits`). Each handler updates the in-memory
|
||
frequency / position, then calls the relevant `Draw*` routine.
|
||
|
||
---
|
||
|
||
## 13. 64K Patch Mechanism
|
||
|
||
### 13.1 PatchTable Structure
|
||
|
||
`PatchTable` (`src/chunk5.s:11486`) is a flat 5-byte-per-entry table:
|
||
|
||
```
|
||
.addr address-to-patch
|
||
.byte $20 (JSR) or $4C (JMP)
|
||
.addr destination
|
||
```
|
||
|
||
Followed by `.word $0000` as a sentinel.
|
||
|
||
### 13.2 Apply64KPatchTable
|
||
|
||
`Apply64KPatchTable` (chunk5) walks the table after the 64K probe succeeds. For
|
||
each entry it writes 3 bytes at the patch site (replacing the JSR/JMP opcode +
|
||
target). Many patch sites are `JSR NoOp` stubs in 48K mode — patched into
|
||
real JSRs.
|
||
|
||
### 13.3 Patched Hooks
|
||
|
||
| Hook | 48K version | 64K target |
|
||
|------|-------------|------------|
|
||
| ADF | NOP NOP NOP | JMP ADFKeyboardHook (chunk3) |
|
||
| P64K_1 | JSR NoOp | JSR RequestADFStationLookup |
|
||
| SceneryOpADFRecord | LDA #$09 (= skip 9 bytes) | JMP LookupADFStation |
|
||
| P64K_2 | JSR NoOp | JSR UpdateADFIndicator |
|
||
| KeyDecrease | LDA InputMode | JSR KeyDecreasePatch |
|
||
| KeyIncrease | LDA InputMode | JSR KeyIncreasePatch |
|
||
| P64K_3 | JSR NoOp | JSR DrawViewOverlays |
|
||
| P64K_4 | JSR NoOp | JSR UpdateAltimeter10K |
|
||
| P64K_5 | JSR NoOp | JSR RealityModeHook |
|
||
| P64K_6 | JSR NoOp | JSR UpdateInstrumentLights |
|
||
| LA55A (UpdateSimpleEngine) | LDA $0A6F (start of 48K engine) | JMP UpdateEngineWithMagneto |
|
||
| P64K_7 | JMP DrawMessageWhite | JMP DrawMagnetoStateHook |
|
||
| ApplyMagnetoState | LDY #$00 | JMP SetMagnetoFromA |
|
||
| SelectRadarView | (48K body) | JMP SelectRadarViewPatch |
|
||
| Select3DView | (48K body) | JMP Select3DViewPatch |
|
||
| P64K_8 | JSR NoOp | JSR HideOrShowInstruments |
|
||
| L1EAD/L1EB0/...L1EC1 (chunk4 thunks) | JMP $20XX | JMP SceneryLoaderEntry1..7 |
|
||
| CoursePlotting | (rts) | JMP CoursePlottingMenu |
|
||
| P64K_9 | JSR NoOp | JSR UpdateCoursePlotter |
|
||
| P64K_A | NOP | JSR DrawSlewOverlays |
|
||
| LA60C | (NOPs) | JMP DrawATISMessage |
|
||
| L6026 | RTS | JMP UpdateCOMMessageChunks |
|
||
| LA5E1 (ComputeDayPhase48K) | LDX #$01 | JMP ComputeDayPhase |
|
||
| L87A5 | JSR NoOp | JSR ApplyWind |
|
||
| P64K_B | JSR NoOp | JSR ComputeWindComponents |
|
||
| P64K_C | JSR DemoMode48K | JSR DemoMode64K |
|
||
| L87BE (ShowSimpleCrashMessage) | (full body) | JSR HandleCrashOrSplash |
|
||
|
||
After patching, the patch table also writes language-card vectors and the
|
||
`Has64K = 1` flag, then completes init.
|
||
|
||
---
|
||
|
||
## 14. WW1 Ace Mode
|
||
|
||
WW1 Ace is a dogfight mode bundled with the simulator. Most of the *logic* lives
|
||
in a special scenery file loaded via `LoadSceneryFile1` (= `PatchSlot_PreMode`),
|
||
so this code base only contains the *engine* hooks.
|
||
|
||
### 14.1 Mode Entry
|
||
|
||
`WW1AceMode` (chunk4 single byte) is non-zero when the mode is active. The
|
||
disassembled code does not explicitly set this — it's enabled by either the
|
||
mode-library load (`+` key / `ReadModeFromLibrary`) bringing in a WW1 mode
|
||
preset, or by scenery-load code in chunk3.
|
||
|
||
The `W` key (`DeclareWar`, `src/chunk5.s:8180`) sets `WarDeclared` — a separate
|
||
gate that, combined with `WW1AceMode != 0`, enables enemy AI.
|
||
|
||
### 14.2 Per-Enemy State
|
||
|
||
Six enemies at offsets:
|
||
|
||
```
|
||
$A972 Enemy 1 (header + state, 28 bytes)
|
||
$A98E Enemy 2
|
||
$A9AA Enemy 3
|
||
$A9C6 Enemy 4
|
||
$A9E2 Enemy 5
|
||
$A9FE Enemy 6
|
||
```
|
||
|
||
Stride is $1C (28 bytes). The status byte at offset +0 is documented in the war
|
||
report messages as:
|
||
* `0` = SHOT DOWN
|
||
* `1` = RETURNING OR HOME
|
||
* `2` = ATTACKING
|
||
|
||
The rest of the 28-byte record (position, velocity, attack timer) is read/written
|
||
by scenery bytecode we don't disassemble. The engine just exposes the storage.
|
||
|
||
### 14.3 Bomb Drop
|
||
|
||
`DropBomb` (X key, `src/chunk5.s:8281`) requires:
|
||
* `WW1AceMode != 0`
|
||
* `WW1AceBombsStr != '0'` (= "BOMBS: 5" string has digits left)
|
||
* `$0A56/$0A57` (= bomb timer) is zero (no bomb currently falling)
|
||
|
||
When triggered, decrements the bomb count digit and copies the current altitude
|
||
high bytes into `$0A54/$0A55` as the bomb fall timer. `TickBombTimer`
|
||
(`src/chunk5.s:12671`) is called per frame to decrement the timer and redraw
|
||
"Time on target" digits at `$A87B`.
|
||
|
||
### 14.4 Gun Fire
|
||
|
||
`FireGuns` (= L90B2, `src/chunk5.s:8390`) is the in-air branch of `BrakesOrGuns`
|
||
(Space key). When `WW1AceMode` is active and `$0A54/$0A55` (overloaded as bullet
|
||
count when no bomb is falling) is non-zero, sets a 3-tick gun-burst counter at
|
||
`$0A60`.
|
||
|
||
`PatchSlot_Gunsight` is called every frame from `MainLoop` when
|
||
`WW1AceMode != 0`. The 64K patch table rewrites it to draw the gunsight overlay
|
||
on the viewport.
|
||
|
||
### 14.5 War Report
|
||
|
||
`ShowWarReport` (chunk3) is triggered by `$08C8`. It composes a damage summary:
|
||
|
||
* Kills: `$0898` (3-digit) → `str_enemy_shot_down`
|
||
* Bomb hits: `$A81B` → `str_bomb_hits`
|
||
* Damage taken: `$08A4` → `str_damage_by_enemy`
|
||
* Each enemy's status digit at `$A972..$A9FE` → `str_enemyN_status`
|
||
|
||
Then `ClearViewportsToBlack` + `DrawMultiMessage(msg_war_report)` + 9 follow-up
|
||
messages + `TogglePauseRelay` (= pauses the sim until any key).
|
||
|
||
The war-report trigger flag `$08C8` is set in exactly one in-binary site:
|
||
`TrimDown` (the R key handler, `src/chunk5.s:8478`) does `inc $08C8`. This is
|
||
likely a debug / developer-mode trigger — pressing R while flying in WW1 mode
|
||
forces the war report. Otherwise the flag is set by scenery bytecode when a
|
||
kill / mission-end event occurs.
|
||
|
||
### 14.6 Scoring Display
|
||
|
||
`WW1AceScore` (chunk4) holds the current score; `WW1AceScoreStr`
|
||
("SCORE:000" in the bomb-bay overlay) is the displayed value. `WW1AceBombsStr`
|
||
("BOMBS: 5") is the bomb count.
|
||
|
||
When `$0838 == $02` (= respawn with reload), `ResetAircraftSystems`
|
||
(`src/chunk5.s:9035`) reloads `$0A54 = $64` (bombs) and `WW1AceBombsStr = '5'`.
|
||
|
||
**Kill detection, score updates, bomb-hit detection, and enemy AI all happen
|
||
inside the scenery bytecode for the WW1 mode** — they're not in this
|
||
disassembly. We verified this by grepping for every absolute address in the
|
||
$A972..$AA19 range and the $0898 / $A81B / $08C8 cells across all four chunks +
|
||
complete.s. The binary contains zero writes to the per-enemy state table; only
|
||
`ShowWarReport` reads enemy status bytes (offset 0 of each 28-byte slot), and
|
||
no in-binary code increments kills (`$0898`) or bomb hits (`$A81B`). The
|
||
`$1A SceneryOpWriteWord` and `$25 SceneryOpStoreImmWord` opcodes are the
|
||
mechanism — scenery files in WW1 mode carry inline destinations pointing at
|
||
these cells.
|
||
|
||
---
|
||
|
||
## 15. Self-Modifying Tricks
|
||
|
||
The original makes extensive use of self-modifying code for performance. The most
|
||
notable patterns:
|
||
|
||
### 15.1 Self-Modified Opcode Sites
|
||
|
||
Routines like `DrawColorLine`, `DrawColorSpan`, `PlotColorPixel`, and
|
||
`DrawIndicatorDialNeedle` have ~20 self-modified opcode bytes between them. The
|
||
modifications are done by `SetPixelDrawMode` (= colour selection) and by the
|
||
`SceneryOpDayOnly` / `SceneryOpModeWhite` opcodes (= day/night switching).
|
||
|
||
Common patterns:
|
||
* INC/DEC swap for step direction (`L7A06`, `L7A74` in DrawColorLine).
|
||
* ORA/AND swap for additive vs masked colour writes.
|
||
* STY/LDA → BPL skip for "skip this paint at night".
|
||
* INX/DEX swap for pixel-step direction in `DrawIndicatorDialNeedle`.
|
||
|
||
### 15.2 Self-Modified Operand Sites
|
||
|
||
`L7889` in `PolygonScanFill_EdgeIntercept` is `STA $02,X` whose operand byte is
|
||
also a *counter* incremented each iteration — the address-byte advance and the
|
||
buffer-write are folded into one. `L7977/L7984` in `PlotColorPixel` are operand
|
||
bytes pointing into the colour mask tables.
|
||
|
||
`L7D77/L7D78` in `PerspectiveDivide` rewrites the absolute-address byte of the
|
||
lookup-table fetch so the same code serves both the X-projection and Y-projection
|
||
divides — the only difference is which 128-byte table is read.
|
||
|
||
### 15.3 Byte-Overlap Tricks
|
||
|
||
Several places use the 6502 trick where a single byte is read both as a 1-byte
|
||
opcode (when entered earlier) and as an operand (when entered at the byte's
|
||
address). Documented sites:
|
||
|
||
* **LA2E9 / LA2EA in `ClampVORDeflection`** — the byte `$E0` at LA2E9 starts a
|
||
`CPX #$FE` instruction whose operand is the byte `$FE` that's also the opcode
|
||
of `INC $0E90,X` when read from LA2EA.
|
||
|
||
* **LB14E in `ClearATISScrollRegion`** — `.byte $AD` is the opcode for `LDA abs`.
|
||
When entered before LB150 the byte stream reads as a clean "lda $0978 / and #$7F /
|
||
sta $0978" sequence; when entered AT LB150 the same bytes read as "ora #$29 /
|
||
.byte $7F / sta $0978".
|
||
|
||
* **`.byte $F0 $3A` in `IntegrateClimbRate`** — at $896D the byte stream encodes
|
||
`beq L89A9` (= the rts at the end of the routine) but the disassembler can't
|
||
emit it as `beq` because $89A9 isn't a label at disassembly time. We've
|
||
documented this and converted it to `beq L89A9` (still byte-identical).
|
||
|
||
* **`.byte $85` in `SceneryFindSectionByDefault`** — the byte `$85` is `STA zp`
|
||
whose operand is the next byte. Entered before, reads as `lda #$00 / sta $20 /
|
||
.byte $92 / .byte $A7 / jmp LA773`. Used to pre-zero `LAA52` before falling
|
||
into the search loop.
|
||
|
||
### 15.4 "JSR self then fall-through" pattern
|
||
|
||
`IntegrateClimbRate` uses the trick `L8956: jsr L8959 / L8959: ldy #$00 / ...`.
|
||
The `jsr L8959` executes the body once, then the RTS returns to L8959+3 — but
|
||
because L8959 is immediately after the JSR, control falls through into the same
|
||
body for a second execution. The end result: the inner step runs twice per call
|
||
with no loop counter.
|
||
|
||
### 15.5 Day/Night Patching
|
||
|
||
`SceneryOpDayOnly` ($1C) writes `BPL <skip>` opcodes at two paint sites in
|
||
`DrawColorLine`. Day-only scenery objects (cars, runway lights) emit
|
||
`SceneryOpDayOnly` before drawing themselves and `SceneryOpModeWhite` after —
|
||
during night frames, the BPL skips suppress the actual byte writes, so the
|
||
object isn't visible. During day frames the opcodes are still STY/LDA so the
|
||
draw works normally. The trick avoids any per-pixel branch on the day/night flag.
|
||
|
||
---
|
||
|
||
## 16. Mode Library
|
||
|
||
`ModeLibraryAction` (chunk4 `$0381`, single byte: `1 = read`, `2 = save`) is a
|
||
*deferred-action flag*, not an immediate I/O trigger. The mechanism:
|
||
|
||
1. `+` key (`ReadModeFromLibrary`, `src/chunk5.s:8360`) → `ldx #$01 / stx
|
||
ModeLibraryAction`.
|
||
2. `S` key (`SaveModeToLibrary`, `src/chunk5.s:8366`) → `ldx #$02 / stx
|
||
ModeLibraryAction`.
|
||
3. At the top of `MainLoop` (`src/chunk5.s:6788-6791`), the check
|
||
`lda EditModeFlag / ora ModeLibraryAction / beq :+ / jsr PatchSlot_PreMode`
|
||
fires the pre-mode hook on any frame where either flag is non-zero.
|
||
4. `PatchSlot_PreMode` (`src/chunk5.s:11917`) is `jsr LoadSceneryFile1` (=
|
||
load the scenery file at descriptor `LA611` = sector `$0625`) with 3 BRK
|
||
pads for runtime widening.
|
||
5. The loaded scenery file contains the actual save / load implementation as a
|
||
sequence of `$1A SceneryOpWriteWord` / `$25 SceneryOpStoreImmWord` opcodes
|
||
that read or write the aircraft state cells. The action discrimination
|
||
(read vs save) happens inside that scenery bytecode by reading
|
||
`ModeLibraryAction`.
|
||
|
||
There is **no disk-IO code in chunks 2-5 that implements the library save** —
|
||
all serialization is the scenery bytecode reading/writing through standard
|
||
scenery opcodes. The "mode library" is therefore really just a slot in a
|
||
specifically-organized scenery file that the engine can read in or rewrite by
|
||
re-running the same scenery section after the in-RAM state has been mutated.
|
||
|
||
The original disassembly comment about `$8758/$875B/$8761/$AA03` self-modifying
|
||
the patch slot was speculative or stale — those addresses contain unrelated
|
||
JMP aliases and ASCII text ("OR M..." for "OR MONITOR"), no slot rewrite code
|
||
is present in the shipped binary.
|
||
|
||
---
|
||
|
||
## 17. Known Unknowns
|
||
|
||
After the research passes in §1-16, the remaining open questions are short:
|
||
|
||
### 17.1 WW1 Ace Enemy AI
|
||
|
||
The 6-enemy state table at `$A972..$A9FE` is updated entirely by scenery
|
||
bytecode (verified: zero in-binary writes). Kill detection, attack patterns,
|
||
position updates, and score increments live in a WW1-specific scenery file
|
||
loaded via `PatchSlot_PreMode → LoadSceneryFile1`. To fully reverse-engineer
|
||
the dogfight logic would require disassembling that scenery file's opcode
|
||
stream — outside the scope of the binary disassembly.
|
||
|
||
### 17.2 Some Opcode Edge Cases
|
||
|
||
A few scenery-data records (the COM `$1E` variable-length records, the curve
|
||
subdivision counters in `$2B`) only fully make sense when seen with real
|
||
scenery byte streams. The handlers in chunk5 are byte-faithful to the source,
|
||
but their exact intended payload formats would benefit from cross-referencing
|
||
with the on-disk scenery files.
|
||
|
||
### 17.3 Easter Eggs
|
||
|
||
`TrimDown` (R key) does `inc $08C8` which triggers `ShowWarReport`. This
|
||
appears to be either a developer test-bind or an intentional easter egg.
|
||
Similarly, `WarDeclared` gets transitioned to `3` in an unreached code block
|
||
at `src/chunk5.s:12590` annotated "unused???" — possibly an aborted
|
||
post-war or game-over screen.
|
||
|
||
---
|
||
|
||
## Appendix A: Reading the Disassembly
|
||
|
||
The source files under `src/`:
|
||
|
||
* `complete.s` — top-level glue; defines absolute-address symbols
|
||
* `chunk2.s` / `chunk3.s` / `chunk4.s` / `chunk5.s` — disk chunks
|
||
* `macros.inc` — utility macros (LDAX, STAX, ADD16, etc.)
|
||
* `asm.cfg` — ca65 linker config (single MAIN segment)
|
||
|
||
To build:
|
||
|
||
```
|
||
export PATH=/tmp/cc65/bin:$PATH # cc65 toolchain
|
||
make # assemble all chunks
|
||
make validate # diff against orig/ for byte-identical
|
||
```
|
||
|
||
`make validate` is the gold standard — any change must keep it passing.
|
||
|
||
## Appendix B: References to External Material
|
||
|
||
* The original Sublogic Flight Simulator II user manual (1984) documents the
|
||
keyboard mapping, modes, and aircraft model. Many of our key-handler names
|
||
derive from manual terminology.
|
||
* `qkumba/a2stuff/fs2/` on GitHub is the upstream of this disassembly — qkumba's
|
||
ProDOS port re-packages the original FS2 binary into a ProDOS-bootable image
|
||
and the disassembly source we're working from.
|
||
* `port/` (in this repo) is the partial C re-port — when in doubt about an
|
||
algorithm's bit-exact behaviour, the C port's `chunk5Transform.c`,
|
||
`chunk5Setup.c`, etc. are bit-perfect oracles.
|