iw4L/docs/GSC-RUNTIME.md

# GSC → IR → Bevy

Rust language, IR and host integration live under `sim::script`.
Gameplay policy belongs to loaded GSC; Rust supplies language and engine primitives.
The scripts own the match flow,
player connect/spawn/damage/killed, the in-game menus, and the sounds they play.

## Sources and installation

Matches support IW4 modes only (dm, war, dom, sd, sab, ctf, koth, dd).
T5 and IW5 maps supply entities and map declarations; their gameplay/UI scripts
are excluded. Menu/HUD layout and match flow stay IW4, with weapon and team icons
from the corresponding game. Objective models, materials, shaders and effects
come from the map's game, including the plant/defuse weapon viewmodels and animations.
`ObjectiveVisuals` binds IW4 names to those assets at
install; missing bindings or foreign objective assets refuse the transaction.
Common scene models are selected from retained IW4 source strings, table cells,
map entities and objective bindings, without a per-model capture allowlist.

`Program::load` compiles a `SourceResolver`. `FileSources` reads explicit files.
IW4 asset walks retain GSC RawFiles from common_mp and the map; map files override
common files. `ScriptSources` also keeps every string table (code_post_gfx_mp and
patch_mp, then common_mp, then the map, later zones winning) and the map's entity
string. Sources travel through the common/resident caches into PreparedMatch.
Session preflight compiles the mode and map modules and builds `LevelData` (parsed
entities, tables). The install transaction installs the program, runs
`codescripts/struct::initstructs` synchronously (it must not wait), spawns the map
entities, sets the `mapname` and `g_gametype` dvars and schedules the `Iw4Startup`
entries before authority ticks: the gametype `main`, the map `main` (if present), then
`_callbacksetup`'s `codecallback_startgametype`. Missing dependencies, unsupported
syntax, unresolved names and unbound natives fail the transaction.

Map entities: `worldspawn` is kept as level settings (`getnorthyaw`),
`script_struct` blocks become plain objects appended to `level.struct`, and every other
block, known classname or not, becomes a script entity with typed keys (`origin`,
`angles`, `angle` as yaw, integer `spawnflags`/`count`/`health`/`dmg`/`maxhealth`,
float `speed`/`radius`/`height`, strings otherwise). Every entity except a hud element
carries `classname`, `code_classname` (`script_vehicle` for any `script_vehicle*`) and a
zero `origin` and `angles` until something sets them. Entity numbers start at the first
non-client slot.
Names are normalized; traversal is rejected. The transaction announces its script
outcome on stdout for a controller: `gsc: installed …` with the program fingerprint
and module/function/native/entry counts once the world is published, `gsc: refused …
stage=compile|install|entry fault="…"` when the load stopped at the script.
`crates/approved_tests` records and asserts both.

Natives are linked against a `Catalog` of the game's builtins (generated into
`script/profile/iw4_catalog.rs`, split into function and method namespaces), not against the
registry. An unqualified call resolves to a function in the same file, then a builtin
in the call's namespace, then a unique include. Qualified names and `thread` calls
never resolve to builtins. A developer builtin used as a statement compiles to nothing
(arguments are not evaluated); using its value or referencing it fails the load.
`prof_begin`/`prof_end` statements compile to nothing. SHA-256 covers decompressed source bytes
after terminator removal. Fingerprints hash IR version 3 and each module's
`(site, realm)`; server modules of the IW4 and T5 realms are instantiated. Calls, `::f` references (script
`Function` or native `Builtin`), locals (per-function slots) and field names (symbol ids)
are resolved at load, and `install` binds native slots once.
UTF-8 and single-byte sources are supported; developer blocks are excluded.

## Language and scheduling

IR supports calls/references/indirect calls, receiver threads, locals, object fields,
arrays/index lvalues, constants, for/foreach/while, switch, conditional expressions,
waits and receiver-bound events. Localized strings and animation literals retain
separate value types. Values are `Int(i32)` and `Float(f32)`. The operator, cast, truth and
string-conversion rules are:
- int/int `/` yields a float. Division or `%` by zero yields zero and does not fault.
- `% & | ^ << >>` accept ints only.
- A type mismatch in `==` or a comparison is a runtime error.
- Only ints and floats have truth.
- Floats print with MSVC `%g`.
- Overlong int literals wrap.

Arrays copy on assignment and argument/event transfer; objects preserve aliases.
Foreach snapshots sorted keys.

Scheduling uses time buckets:
- The run loop pops the head of the current bucket.
- `wait` pushes to the head of its target bucket.
- `waittillframeend` pushes to the tail of the current bucket.
- `wait` counts server frames: an int is 20 frames per second, a float rounds
  `f * 20 + 0.5` down in f32, and a nonzero wait is at least one frame. A negative or
  too-long wait faults. `wait 0` resumes in the same frame, after the current thread yields.
- `thread f()` runs `f` inline until its first yield, then the spawner continues.
  Calls and thread calls share a limit of 31 frames across the running thread and the
  spawners suspended under it. An endon that fires on a suspended spawner unwinds it
  when control returns to it.

Events use one waiter list per program:
- Notify walks the waiters oldest-registration first and never runs script.
- Woken threads go to the head of the current bucket, so they resume newest first.
- `waittillmatch` skips non-matching payloads silently.
- `endon` is scoped to the registering frame. Firing it kills that frame and the frames above
  it. The caller resumes with `undefined`, or the thread ends if the root frame was killed.
- An endon registered before a waittill on the same event wins.

Deleting an entity ends the threads that `waittill` or `endon` on it, checked at the
start of each tick and before a thread resumes. A thread whose `self` is deleted keeps
running. The `delete` native sends `death` before retiring the entity. A deleted entity
keeps its fields until the frame ends, so `death` handlers can still read them; after that, references point at a
fieldless dead entity: field reads give `undefined`, writes land, `isdefined` is false
and the id is reclaimed by heap collection.

Runtime errors recover: the failed
operation leaves `undefined` in place of its results and the thread carries on. A failed
condition falls into the body, a failed switch takes the default, and a failed `foreach`
operand iterates nothing. Each site is logged once (`gsc: runtime_error at=… fault="…"`)
and counted. A thread that runs 16M instructions in one resumption is killed as a runaway
loop (level startup runs in one frame and needs over a million on the larger maps). A
panicking builtin is a runtime error of its caller. Array copies have bounds.
Heap collection follows globals and live threads, including cycles; natives must
keep persistent script values in script-owned roots rather than retain raw handles.

## Engine boundary and restoration

Natives are grouped by what they touch; the core three:
- `script/host/natives/iw4.rs`: dvars (`getdvar*` with an optional default for a missing dvar,
  `setdvar` storing a localized value as its reference, `setdvarifuninitialized`,
  `makedvarserverinfo`), precache and `loadfx` (allowed only while the first tick is
  loading), string helpers, presented client state (fog, vision, ambient).
- `script/host/natives/math.rs`: math in degrees, vectors, deterministic randomness (a runtime-owned
  xorshift seeded from the program fingerprint, so clones and replays draw the same
  numbers), substrings, and string tables (case-insensitive lookups, `""` or `-1` when
  missing).
- `script/host/natives/engine.rs`: entity queries and `spawn`, entity methods (origin, model,
  visibility, contents, link offsets, attachments), timed moves and rotations that
  notify `movedone`/`rotatedone`, radius-trigger `istouching`, `placespawnpoint`,
  hud elements, world traces against the map's clip, team scores and radar, match data,
  level settings, and weapon facts from the captured weapon table.

Argument reads live in `script/host/args.rs`, array helpers in `script/host/arrays.rs`,
and table lookup in `script/host/tables.rs`. All three use the one `Runtime`
(`arrays`, `next_object`, `tables`, `rng`). The compiler is `sim::script::compiler`:
`Token`/`lex` and the call, expression, assignment, and statement methods sit in child
modules, and `Parser` stays in the parent.

Sounds the scripts play (`playLocalSound`, `playSoundToPlayer`, `playSoundToTeam`)
reach the client. Effects, rumble and earthquakes validate their receiver and are
kept in `Runtime.presented` or dropped. In-game menus (team, class, escape, leave-game,
scoreboard header) and the IW4L frontend run from menuDefs through the same ordered
GPU menu pass. `crates/ui/menus/frontend.json` defines IW4L navigation and native
menu styling; frontend service commands connect it to session and master APIs.

Killstreak hardware:
- `spawnHelicopter` arms the vehicle with its VehicleDef `turretWeaponName` (captured
  from the zone, including weapon bodies loaded inline through the vehicle), so the
  gunner's `turret_fire` → `fireWeapon` loop needs no `setVehWeapon`. Turret and vehicle
  weapons with clip 0 or zero fire/raise times are valid combat rows.
- Sentry placement traces a ray to 42 + 5 units ahead,
  a ±30 box drop, normal ≥ 0.7, then four feet (17, 20, 10) traced 20 down that tilt the
  seat, failing when two miss. A failed placement keeps the fallback pose.
  `setContents(0)` makes the carried turret non-solid, so the traces skip it;
  `setContents` returns the previous contents for the restore pattern.
- `notifyOnPlayerCommand` notifies go out for every bound command, including
  `+actionslot N`; `+breath_sprint`, `+stance` (tap crouch, 300 ms hold prone) and
  `centerview` act on the client.
- The laptop map (`setminimap` frame, location selection with direction and yaw) draws
  from the map's compass corners.
- Entity allocation is shared by movers, grenades, missiles and dropped items. A full
  pool drops the new entity with a warning instead of ending the match. `radiusDamage`
  with an invalid area and `glassRadiusDamage` are no-ops.
- A dying player gets `death` (with the attacker) before `CodeCallback_PlayerKilled`;
  the stock scripts send it themselves only for faux death, so every
  player `endon( "death" )` thread depends on it.

The client draws a carried sentry at the authority's 20 Hz pose, not re-placed per
frame from the predicted player state.

The scripts drive the match phase. Every `level` notify is recorded as a signal, and
the simulation reads them after the scheduler each tick: `prematch_over` finishes the
prematch (movement unlocks), `exitlevel` moves to intermission. `map_restart` frees
the level's entities and hud elements, reloads the scripts and keeps the primitive
part of `game` (and `pers` when asked to persist).
Disconnect requests from transport are queued for an authority frame. The player
callback runs before Rust removes the player state and metadata; it can still read
the name, score and team while the scripts remove the player from their lists.
Scripts run and are checked only on authority frames (`try_step`/`step` with
`StepReason::AuthorityFrame`); prediction of new and replayed commands steps a
script-less world. Per-client script control constraints travel in snapshots and are
restored before prediction and command replay. Button-query natives sample raw commands
from the current authority frame, including presses between its first and last commands.
Clones preserve program, heap, threads and waits. Shutdown resets them. Restoring
snapshots into an installed authority VM rejects absent script state. Persistent
replay pinning/restoration and client-role lifecycle evidence are still missing.
Only terminal faults (exhausted identifiers, inconsistent IR) are sticky; they end the
match and return the host to the lobby. Earlier
writes are not rolled back.

## Remaining

A live bomb plant/defuse check. Native IW4L menus can create a private lobby,
select a map/mode, start a match and return to the frontend. Browser/public-lobby
actions are connected but still need multiplayer validation. Display mode/resolution, brightness, volume, VSync, shadows, depth of field and
bloom are bound to runtime settings and persisted locally. Surround output, voice/chat
settings, third-person camera and spectator restrictions remain incomplete. A true
dedicated server still runs on the listen runtime.