Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
85 lines (63 loc) · 2.79 KB

ARCHITECTURE.md

File metadata and controls

85 lines (63 loc) · 2.79 KB
Raw

GZEngine architecture

Responsibilities

In scope (gzengine-core.wasm):

  • Advance simulation by dt or fixed tic (35 Hz classic)
  • Mobj thinkers, sector specials (GZDoom semantics)
  • Line activation, switches, doors, platforms, crushers
  • Player cmd → movement/weapons (when enabled)
  • Monster AI (incremental corpus)
  • Export GZTICK snapshots and patch buffers for the renderer

Out of scope:

  • WebGL/WebGPU draw calls
  • Texture upload, BSP draw order generation (renderer)
  • HUD, menu, music playback (host / doom-wad-lab)
  • Full ZScript mod compatibility on day one (fixture-driven later)

WASM ABI (draft)

C-style exports for minimal JS boundary crossing:

gze_create();
gze_destroy();
gze_load_gzstate(uint8_t* gzstate, int len);  // initial world from doom-wad-core / GZDoom
gze_set_player_cmd(int forward, int side, int buttons, int angle);
gze_tick(int tics);                            // advance N tics
gze_export_gztick(uint8_t** out, int* len);    // full snapshot for parity tests
gze_drain_patches(uint8_t** out, int* len);    // renderer-facing deltas since last drain
gze_get_last_error();

Renderer consumes gze_drain_patches — sector floor/ceil deltas, thing spawn/move/remove, light changes — without importing the full mobj graph.

Parity loop

GZDoom fork:
  -dumpgzstate map.gzstate     # t=0 baseline (shared with renderer)
  -dumpgztick N out.gztick      # after N tics + fixed input log

WASM engine:
  load gzstate → replay input log → tick N → export gztick

Node:
  diffGztick(gzdoom, wasm) === identical

Extraction from GZDoom

Source of truth: gzdoom-project (your fork). Strip order:

  1. p_setup / level load — reuse GZSTATE import instead of re-parsing WAD in WASM initially
  2. p_tick, P_Ticker, thinkers
  3. p_map, P_UseLines, specials
  4. p_mobj, states, P_SpawnMissile, …
  5. d_player, p_pspr
  6. p_enemy (corpus monsters)
  7. p_acs (ACS VM)
  8. ZScript VM (isolated crate, optional compile feature)

Build with Emscripten (-sMODULARIZE, -sALLOW_MEMORY_GROWTH). No GL linkage in engine crate.

Testing pyramid

Tier Target
Unit GZTICK codec, patch merge, fixed-point helpers
Tick fixtures 10 → 100 → 1000 deterministic scenarios
Demo slice demo1.lmp first 300 tics (input replay)
Engine+render patches applied → renderer frame diff (doom-wad-lab)

100% line coverage of GZDoom is not a project goal.
100% fixture corpus pass rate is.

Testing

Doc Scope
TESTING.md This repo — GZTICK codec, planned tick corpus
../../docs/TESTING.md Workspace-wide guide
../gzdoom-project/docs/PARITY-TOOLS.md -dumpgztick (planned)