# godzilla.sfx Synthesized sound effects + 4-layer adaptive music for the Godzilla in San Francisco game. All audio is pure-Luau DSP rendered to 22050 Hz 16-bit mono PCM WAV files under `/zero/source/godzilla/audio/<name>.wav` by `M.ensureAssets()` (idempotent; skips files that already exist). Playback spawns temporary entities carrying the builtin `Audio` component; nothing it plays is saved into the scene. ## API - `M.ensureAssets(): boolean` — synthesize every missing WAV. Edit mode only (VFS writes are locked in play mode). Returns true when every file exists. - `M.play(name, opts?): string` — one-shot playback, returns the entity id. `opts = { volume?, pitch?, pos = {x,y,z}?, loop? }`. Spatial when `pos` is given. Loops (`loop = true`) must be stopped by despawning the returned entity id. - `M.tick(dt)` — reaps finished one-shots and crossfades music layer volumes. The game calls this every frame. - `M.musicStart()` / `M.musicStop()` — spawn/despawn the 4 looping music layers (calm / tense / battle / frenzy; same length, tempo, and key so they stack). - `M.musicSetThreat(level, frenzy)` — level 0..5 + frenzy boolean map to per-layer target volumes; `M.tick` lerps live volumes toward the targets. - `M.setVolumes({ master?, sfx?, music? })` — 0..1 gains multiplied into every Audio component volume this module manages, applied live to running loops and music. ## Sounds `roar, swipe, grab, throw, stomp, step, tail, crumble, breath_charge, breath_loop, explosion, tank_fire, jet_pass, missile, rotor, cannon, siren, chime, combo, frenzy, gameover, splash` plus music layers `music_calm, music_tense, music_battle, music_frenzy` (6.4 s seamless loops, 75 BPM, D minor). `breath_loop`, `rotor`, and `siren` are seamless-loopable (exact-period oscillators + crossfaded noise).

# godzilla.kaiju Builds the Godzilla voxel model (visual only). No AI, no physics — the game moves the `GODZILLA` root kinematically and rotates the part entities to animate. ## API ```luau local K = require("@root::godzilla.kaiju") local g = K.spawn({ 0, 0, 0 }) -- g = { root = id, parts = { body, head, tail, armL, armR, legL, legR } } K.setBreathGlow(true) -- electric-blue spike + mouth glow K.setBreathGlow(true, { 1, 0.3, 0.1 }) -- custom color K.setBreathGlow(false) K.despawn() ``` - `spawn(pos)` despawns any existing `GODZILLA` first, then rebuilds. `pos` is the ground point (array or `{x,y,z}` map). - `setBreathGlow(on, color?)` returns `true` when a spawned Godzilla was updated, `false` when nothing is spawned. ## Model ~28.5 m tall, facing +z, ground at y=0. Seven `VoxelShape` parts (all `blockSize = 0.5`) parented to the root; each part's pivot sits at its joint so the game can rotate part entities directly: | part | grid (voxels) | pivot | joint | |---|---|---|---| | body | 24 x 28 x 20 | bottom-center | hip (y 10..24) | | head | 12 x 10 x 16 | bottom-center | neck top (y 23.5) | | tail | 12 x 20 x 30 | `{0,0,1}` (hip end) | hip, droops to ~2 m | | armL/armR | 8 x 14 x 12 | top-center | shoulder | | legL/legR | 12 x 22 x 16 | top-center | hip | Charcoal gray-green skin (#2e3b34), lighter belly plate bands, pale bone dorsal fins in a large central row plus two smaller side rows down neck-back-tail, amber eyes, deep open jaw with teeth and a dark-red mouth. ## Breath glow The voxel mesh renders with one shared material, so the glow is built from small emissive `Model` cubes parented to the parts at the spike tips (9 on the body, 3 on the tail) and inside the mouth, hidden by default. `setBreathGlow` shows/hides them; each color gets a cached `gz_kaiju_glow_<r>_<g>_<b>` pbr material (created on demand via `Material.Create`, landing at `/zero/source/<name>.material`).

# gameui Pure widget-tree builders for every Godzilla screen. Each function takes a plain data table (`ctx`) and returns a zui tree for `ui.registerScreen`/`ui.updateScreen`. No engine calls, no state — all state lives in `godzilla.game`. Exports: `M.menu(ctx)`, `M.mapsel(ctx)`, `M.settings(ctx)`, `M.extras(ctx)`, `M.custom(ctx)`, `M.pause(ctx)`, `M.results(ctx)`, `M.hud(ctx)`, `M.flash(ctx)`. Callback ids all start with `gz_` and are handled by `godzilla.game`'s `onCallback`.

# godzilla.units Military unit voxel models + stat tables (visual only). No AI, no physics bodies — the game moves unit roots kinematically; jets and helis fly at `M.STATS[kind].alt`. ## API ```luau local U = require("@root::godzilla.units") local t = U.spawn("tank", { 100, 0, 50 }) -- t = { id = rootId, kind = "tank", parts = { body, turret } } U.STATS.tank -- { hp = 80, speed = 6, range = 120, dps = 6, score = 200 } U.despawnAll() ``` - Roots are named `unit_<kind>_<n>`. Every model faces +z at spawn. - `parts.body` is always present; `parts.turret` (tank, warship), `parts.turret2` (warship aft turret), and `parts.rotor` (heli) are separate VoxelShape entities parented to the root so the game can rotate them (turret yaw, rotor spin). - `despawnAll()` removes tracked units and sweeps any `unit_<kind>_<n>` roots left from before a module hot reload. ## Kinds | kind | size | blockSize | look | hp | speed | range | dps | score | alt | |---|---|---|---|---|---|---|---|---|---| | infantry | 2 m | 0.25 | olive rifleman, helmet | 10 | 3 | 40 | 1 | 25 | - | | tank | 6 m | 0.5 | tracked hull + rotatable turret/barrel | 80 | 6 | 120 | 6 | 200 | - | | jet | 12 m | 0.5 | gray swept-wing fighter | 60 | 45 | 200 | 10 | 350 | 60 | | heli | 10 m | 0.5 | cabin + tail boom + spinnable rotor part | 70 | 15 | 140 | 8 | 300 | 35 | | warship | 60 m | 1.5 (turrets 1.0) | navy destroyer, fore + aft turret parts | 600 | 4 | 400 | 20 | 2000 | - | | mech | 18 m | 0.75 | gunmetal bipedal walker, emissive red eye | 500 | 5 | 150 | 18 | 1500 | - | | spotter | 3 m | 0.25 | radar truck, tall antenna, emissive orange marker | 40 | 8 | 0 | 0 | 400 | - | The mech eye and spotter marker are small always-on emissive `Model` cubes (`gz_unit_red_eye` / `gz_unit_orange_marker` pbr materials, created on demand at `/zero/source/<name>.material`).

# godzilla.city Builds the stylized San Francisco map for the Godzilla rampage game and owns its destructible registry. Everything spawns under one root entity named `CITY` (spawned `temporary`, so the map never persists into scene saves — the game rebuilds it each session). Map content: bay water west + north, Golden Gate Bridge at x ≈ -300 (two international-orange towers, 10 destructible deck segments, main cables + hangers), downtown tower grid (x 50..350, z -150..150, 41 towers, 30–120 m), Transamerica Pyramid, Coit Tower (on a hill), Alcatraz island + cellhouse, ~150 pastel painted-lady low-rises, asphalt street grid, and 41 dynamic vehicles (35 cars + 6 cable cars). ## API ```luau local city = require("godzilla.city") city.build() -- builds the map under CITY; idempotent; edit mode -- only; returns the CITY root entity id city.clear() -- despawns CITY (debris included) + resets registry city.registry() -- { [rootEntityId] = def }; treat as read-only city.ownerOf(entityId) -- segment/child entity id -> registry root id (or nil) city.damage(rootId, amt) -- apply damage; returns DamageResult (nil for -- unknown root ids) city.landmarks() -- { { id, name, score, roots } } city.tick(dt) -- reaps expired debris/dust; the game MUST call -- this every frame (debris auto-despawns ~20 s, -- dust ~3 s, with no background tasks) ``` `def = { kind = "building"|"landmark"|"vehicle", name, score, hp, maxHp, segments = { entityId } (bottom-up), landmark?, pos = { x, y, z }, alive = number }` (`alive` = still-standing segment count, maintained by `damage`). `DamageResult = { destroyed, score (0 until destroyed), debris = { entityId }, name, landmark? }`. ## Damage model - Partial damage knocks the top remaining segment(s) off as short-lived dynamic debris boxes and darkens the surviving segments via Model tint. - Reaching 0 hp collapses the root: all segments despawn, 3–6 dynamic debris boxes (`debris_*`, grabbable) and a dust burst spawn, and the full score is returned once. - Debris/dust lifetimes are driven purely by `M.tick(dt)` — no spawned tasks — so the game owns the frame loop. ## Scores Filler houses 100–300 · downtown towers 500–2500 (by height) · vehicles 50–150 · each bridge deck segment 1500 · each bridge tower 5000 (all bridge roots share `landmark = "golden_gate"`) · Coit 4000 (`coit`) · Alcatraz 5000 (`alcatraz`) · Transamerica Pyramid 8000 (`transamerica`). ## Budget & materials ~560 static entities + 41 dynamic vehicles (limit 1200/60). 15 shared materials (`gz_*`), created once via `Material.create`; dark-glass towers carry warm/cool emissive window tints for the golden-hour read. Material assets live at `/zero/source/gz_*.material` — the engine's material destination is the source root and names must match `^[A-Za-z][A-Za-z0-9_]*$`, so they are namespaced by the `gz_` prefix. `ensureMaterials` guards each create with `Material.exists`, so rebuilds reuse the registered materials. ## Notes - The registry lives in the module instance, not on the entities. After a hot-reload of this module while CITY stands, `build()` adopts the existing CITY but the registry is empty — call `clear()` then `build()` to recover (`registry()` returning an empty table while `CITY` exists is the signal). - `damage()` returns nil for an id that is not a registry root. - `damage()` darkens surviving segments via `Model:setTint`; debris initial velocity uses `Physics:setVelocity`. Both only show motion in play mode.