DEAD AIR — game

A Godot project for DEAD AIR, Zach's open-source VR survival game. (Engine history: built on Redot LTS 26.2 through 2026-10-21; migrated to Godot — see docs/engine-migration.md for the decision record and the one-time cache-wipe step every existing checkout needs.) Started as a framework skeleton (directory layout, class names, signals, stubs); real systems land via design issues in dead-air/game-planning.

Status

Basic menu flow is in. The game boots into the Sandbox level's menu area: a persistent Game root owns the player rig and loads levels underneath it, and the same physical area serves as main menu, new-game starting area, and sandbox — modes redress it (MenuContent / StoryContent / SandboxContent groups). Menu is a world-space laser-pointer panel (mouse works too, in flat/desktop mode). Continue is present but disabled until save/load lands; locomotion is provisional (left-stick smooth + snap turn) pending the #19 locomotion decisions.

Headless check: tests/smoke_menu.gd (run with godot --headless --path . --script res://tests/smoke_menu.gd).

Pins

• Engine: Godot 4.6.3, standard build (NOT the .NET build) — pinned; upgrade only deliberately, after the test suites + a headset pass on the new version. No .NET SDK is required to open, run, or test this project. (Was Redot LTS 26.2 until the 2026-10-21 migration — docs/engine-migration.md.)
• Blender LTS 5.2.2 — for asset work.

Starting in VR

OpenXR starts only when asked: the editor's Play button passes --xr-mode on (Project Settings → Editor → Run → Main Run Args), and exported builds turn it on through xr/openxr/enabled.template. A plain command-line run (godot --path .) starts flat — add --xr-mode on for the headset. Why: Godot crashes inside the engine when a windowless (--headless) run starts OpenXR while a runtime such as SteamVR is open, and tools that build/check the project run that way. Flat runs also never parse the action map, so tools on older Godot versions don't trip over 4.6-only bindings.

Scripting rule

GDScript only. The project contains no C# and uses the standard Godot build. Adopting .NET is a project-wide switch (editor build, SDK, MSBuild, export templates — paid by every contributor for a subsystem-local benefit), so it requires a specific justification: a profiled compute-bound subsystem that lives in .NET data and crosses to the engine in bulk, or a named load-bearing NuGet library with no adequate GDScript/GDExtension alternative. Native hot kernels go to GDExtension, which works in the standard build.

Design source

The design record lives in dead-air/game-planning issues:

• #19 — base-layer primitives (Item → Health & Damage → Interaction → Inventory → Player Avatar → Health Display)
• #24 — development milestones / systems roadmap (render → movement → interactions → inventory → advanced movement → advanced interactions)
• #28 — save data format: versioned registry, uniform item tree, full snapshots, containers-as-items
• #5 / #20 / #31 — Two-track Observer narrative (Bakelite Phone) and tactical NPC AI via Hanzo AI (docs/hanzo-ai.md)

Hanzo AI integration (hanzo.ai)

DEAD AIR ships with a first-class Hanzo AI module (modules/hanzo/) targeting the canonical https://api.hanzo.ai/v1 gateway (HIP-0139 capabilities: models, decision via kai, chat via Zen 6 (zen6, zen6-flash, zen6-coder, zen6-max), audio via zen-voice -> AudioStreamMP3, and mcp 2026-07-28) with native TLS HTTPClient calls and deterministic offline fallback for headless CI and air-gapped VR play:

• Two-Track Narrative & Bakelite Phone (hanzo:bakelite_phone) — Answering or ignoring the Observer phone sets the with_observers / without_observers narrative track (game-planning#5, #20) and connects to hanzo:observer_prime (zen6).
• Tactical NPC AI (HanzoNPCBrain) — Attaches to NPCEntity (hanzo:corrupted_scout), listens to GameEvents (noise, shot_fired) and Health (damaged, died), and evaluates utility-scored states (patrol, investigate_noise, stalk, flank, attack, retreat, relay_signal) via /v1/decisions (kai).
• DebugBridge & MCP Tools — hanzo_status, hanzo_models, hanzo_decide, hanzo_chat, and hanzo_speech exposed over DebugBridge and addons/da_debug_bridge/mcp_server/server.py.

Full documentation: docs/hanzo-ai.md. Headless check: godot --headless --path . --script res://tests/hanzo_check.gd.

Packs and modules

DEAD AIR's content packages are called packs (not mods): the system is built for adding new content first; alteration is allowed but extension is the intent. Packs are .pck files mounted at startup that can shadow any base file at the same res:// path — the official release's licensed asset pack ships this way. The player model works the same: base arms are CC0 (modules/deadair/assets/player/arms/player_arms.glb), replaceable by a pack exported from Godot. Full details: docs/packs.md.

Everything is a module (Fabric-loader style): the base game is the deadair module (modules/deadair/module.json), and modules add items, tuning, levels, creatures, loot, missions, traders, dialogue and text through type-folder files and code entrypoints, with dependencies and version ranges instead of a load order. Modder guide: docs/modding.md. Example module: examples/example_module/. The loader core in loader/ has no game classes, so other Godot projects can reuse it.

Layout

• modules/deadair/src/core/ — item registry, save game, module helpers
• modules/deadair/src/items/ — item definitions and runtime instances
• modules/deadair/src/health/ — health component, damage info
• modules/deadair/src/interaction/ — grab points, grabbable, ranged grab
• modules/deadair/src/inventory/ — container volumes, snappers
• modules/deadair/src/player/ — XR rig, arms view model, stamina
• modules/deadair/src/ui/ — displays
• modules/deadair/src/input/ — controller backends and rig input
• modules/deadair/src/rig/ — rig chain discovery
• modules/deadair/types/ — element type scripts (item, level, rules, ...)
• modules/deadair/items/ / levels/ / rules/ / ... — base content elements
• modules/hanzo/ — Hanzo AI (hanzo.ai) module: agents/, items/, entities/, types/, and runtime AI systems (docs/hanzo-ai.md)
• loader/ — game-agnostic module loader core
• addons/ — Godot editor plugins (godot-xr-tools, da_debug_bridge). Not to be confused with game packs (content packs) — see docs/packs.md.
• examples/example_module/ — modder template (not loaded in a shipped game)
• data/levels/ / data/rules/ — kept as .gitkeep; content moved to modules/deadair/