Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,10 @@ Version numbers follow `MAJOR.MINOR.PATCH`; the 0.x series is under active devel

## 0.12.1 — Unreleased

- AI networks in RECOIL and MW3 use clickable circular node markers and directed triangles.

- MW3 source maps list a mission's valves in the World tree, one per name, each with what it does. A valve's card shows what sets it, its reactions and what waits on it, with links to the vehicles, route nodes and valves involved, and edits its starting value, computed inputs and reactions with pickers; rename, delete and new valves are single undoable changes that keep the files' comments and layout.
- Test valves runs a mission's valves in memory: set a valve and watch its timers, sounds, animations, vehicle changes and route gates follow, with the test's time, values and activity shown in the view, the tree and the card. Nothing is saved.
- zStudio is built on .NET 11 (included in `zStudio.exe`; nothing to install).
- AI networks in RECOIL and MW3 use clickable circular node markers and directed triangles. Valve-controlled routes remain visible with their simulated availability.

## 0.12.0 — 2026-11-08

Expand Down
6 changes: 5 additions & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
# Claude Code guidance

Claude Code follows the same project guidance as Codex. `AGENTS.md` is the single source of truth; keep instructions there rather than duplicating or diverging from them here.
Claude Code follows the same project guidance as Codex. `AGENTS.md` is the single source of truth; keep instructions there rather than duplicating or diverging from them here. Only rules that apply to Claude Code alone are stated below.

@AGENTS.md

## Claude Code only

- Before making any commit, run an adversarial Codex review (the `codex-review` skill) of all the uncommitted changes. Fix the issues Codex finds, then repeat the full review of all the uncommitted changes. Commit only when a review comes back with no issues found (owner decision).
11 changes: 11 additions & 0 deletions docs/agents/engine-evidence.md
Original file line number Diff line number Diff line change
Expand Up @@ -306,6 +306,17 @@ Static association discovery follows bound recipients separately from load-time
- `CALL_ANIMATION` binds `OPERAND_NODE` when its positive reference resolves; `AT_NODE`/`WITH_NODE` position rather than own. Runtime impact victims have no statically identified recipient.
- Discovery includes all sequence branches and cleanup without evaluating conditions or advancing time; it describes known assignments, not proof that a branch runs.

## MW3 valves and route conditions

- **Registry and loading** [U: [original 1.2 reconstruction](https://github.com/telltaleatheist/mw3-re/blob/715d6d6e24590ef54a83a257f67a965601795216/src/mech3/zrdrvalve.cpp), [registry](https://github.com/telltaleatheist/mw3-re/blob/715d6d6e24590ef54a83a257f67a965601795216/src/mech3/zai_valve.cpp)]: exact case-sensitive names create integer holders initially zero. Repeated records add reactions in file order. A record looks up tags recursively, builds sound, animation, scan_aim/scan_hit/scan_time/canleave, shutdown, destroy, setteam, attack_strategy, teleport, missionreset/abort/complete, update and delayupdate in that fixed order. The once tag overrides its ordinary counterpart. Initial value writes do not fire. A second compound holder conflicts and drops that record. Unknown tags are ignored, not removed from source.
- **Conditions and reactions** [U: same reader]: any_nonzero, any_zero, all_nonzero and all_zero compute from their namelist on every read; member changes fire the compound's reactions even when its computed value stays unchanged. Setting a holder fires only if the requested value differs from its current value; a compound ignores the write but still fires in that case. Actions compare against their own trigger integer; update fires its target regardless of value and delayupdate captures its source value on every firing.
- **Timers** [U: same registry]: native float due time is delay + current game time; a timer fires only when due is strictly less than now. Timer lists visit timers appended during their own tick. A composite slot keeps its identity when it shrinks to one timer, across later ticks; it is released only when empty. Each mission frame advances game time, updates the world, then ticks valve timers ([mission loop](https://github.com/telltaleatheist/mw3-re/blob/715d6d6e24590ef54a83a257f67a965601795216/src/mech3/mission.cpp)). When a lone timer creates more timers while completing, the retail dispatcher clears its replacement slot and loses those new timers. Upstream's optional repair is not original 1.2 behavior. Reentrant firing and recursive conditions require bounded diagnostic termination in an editor preview.
- **Route semantics** [U: [compiler](https://github.com/telltaleatheist/mw3-re/blob/715d6d6e24590ef54a83a257f67a965601795216/src/mech3/zainetedit.cpp), [reader](https://github.com/telltaleatheist/mw3-re/blob/715d6d6e24590ef54a83a257f67a965601795216/src/mech3/zrdrainet.cpp)]: node properties compile on each outgoing link in order. A valve tuple's first integer enables it; an omitted expected integer is one for the last nonnegative link, zero for the others. A union admits when any enabled term equals its expected integer (default one). Edge records have no XYZ, start with a from node followed by one or more target indices, and add their property chain to each matching authored link. valve_assign changes a value on traversal; it is not a passability test.
- **Animation binding** [U: [owner registry](https://github.com/telltaleatheist/mw3-re/blob/715d6d6e24590ef54a83a257f67a965601795216/src/mech3/zai_anim_owner.cpp)]: callback values 42 through 49 bind a node-name valve at zero through three uniquely parented ancestors. The binding is chosen while scanning the entry's normal sequences, excludes cleanup, and retains the first compatible valve. Even values set zero, odd values one. The callback handler uses the retained binding rather than resolving a new valve for each event. Native mission setup binds loaded definitions after vehicle/player placement and post-vehicle fixup, before starting the selected named entry; ON_STARTUP entries have already been marked running. Their first normal events share the post-placement world frontier ([setup](https://github.com/telltaleatheist/mw3-re/blob/715d6d6e24590ef54a83a257f67a965601795216/src/mech3/mission.cpp)). Mission startup can start range-gated callbacks. In c1, call_ramp attaches to the bramp healthy child at (-1850.06, -25.918423, -1606.5876), outside its 500-unit range of the initial player (-3200.9, -35.9, -1225.1); it starts held. Setting bramp to one wakes owens_01 and schedules truck/dialogue updates.
- **Vehicle triggers** [U: [vlist reader](https://github.com/telltaleatheist/mw3-re/blob/ffec5550795b5ec1b976b80ea5fc518611031fac/src/mech3/zrdraiv.cpp), [evaluation](https://github.com/telltaleatheist/mw3-re/blob/ffec5550795b5ec1b976b80ea5fc518611031fac/src/mech3/zai_brain.cpp)]: an `aiv.zrd` `vlist` entry has 16 or 17 items: the value flag (the valve is set to 1 or 0), ammo flag and threshold, hit flag, health flag and threshold, heat flag and threshold, inside-region flag, region name, in-sight flag and distance, near flag and distance, an unused flag, the valve name, and from 17 items the outside-region flag. Distances are stored in plain units (the reader squares them). Each frame an entry whose valve already is zero or nonzero as its value flag asks does nothing; otherwise the first condition that holds sets the valve, tested in this order: hit within the last second, heat at or above its threshold, health at or below, ammo at or below, the nearest enemy nearer than the near distance, the nearest enemy nearer than the in-sight distance with a clear line, then the region (inside, outside, or anywhere with both flags; no region or neither flag never holds). The player's record runs its list the same way.
- **Deploy and wait points** [U: [net compiler](https://github.com/telltaleatheist/mw3-re/blob/ffec5550795b5ec1b976b80ea5fc518611031fac/docs/ai.md)]: a node's `deploy` stores two valve names (items 1 and 3) and `mcbwait` one (item 1). zStudio lists them as places that name the valve and makes no further claim.
- **Action effects** [U: valve reader above]: shutdown's second operand is the power-down flag; zero wakes a mech. Teleport writes absolute position and yaw. Its get_vec3/get_float_value operands convert integer values to floats ([zReader](https://github.com/telltaleatheist/mw3-re/blob/715d6d6e24590ef54a83a257f67a965601795216/src/gamez/zreader/zreader.cpp)); value/trigger operands and delayupdate retain their raw words. Scans, canleave, team and strategy modify actor AI state. missionreset reports failure and creates nothing; missioncomplete has no effect in retail; missionabort calls the abort handler. Damage thresholds in targets.zrd retain raw float words (TargetRec::parse word_f in zrdraiv.cpp), and set their valves strictly below each threshold, highest first; death fires all remaining thresholds. Objective valve_change stores separate valve (name) and value (comparison word) fields.

## GameZ world format

- RECOIL worlds are GameZ version 15 in both releases and the September 1998 demo; version 13 in the demos built 21 July–12 August 1998 (read-only, read into the same model). Version 13 differs in two ways, established from every node of the ten version-13 demo worlds: node slots are 268 bytes (after the sphere, the cached box as eight corners in the parent's space — bottom face then top, each from minimum X and maximum Z — then model and child boxes and the activation pointer; the reader rebuilds the cached box from the flagged model/child boxes, otherwise maps the corners back through the matrix); Object3D records are 156 bytes (a translation after the scale, matrix and rest 12 bytes later; the matrix already carries the translation, so the reader drops it and shows it as `translate`). Version-28 animations bind to version 15 or 13. Version 200 and animation format 200 are zStudio's formats for reRECOIL v2, not the engine's: version 15 and format 28 with the fields that capped content widened ([version 200](../zbd-v200.md)).
Expand Down
2 changes: 1 addition & 1 deletion docs/agents/pr-watch.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# PR watch

`tools/pr-watch.ps1` watches one GitHub PR and notifies the owning agent conversation of new review feedback and of a qualifying review-bot approval. It is development tooling, separate from zStudio and its MCP server. Requirements: Windows, the .NET 10 SDK, an authenticated `gh.exe`; the Codex channel also needs a native Codex with the experimental App Server queue API. It never changes agent permissions or zStudio's MCP opt-in, and never edits files outside its state, fixes code, pushes, merges, tags or publishes.
`tools/pr-watch.ps1` watches one GitHub PR and notifies the owning agent conversation of new review feedback and of a qualifying review-bot approval. It is development tooling, separate from zStudio and its MCP server. Requirements: Windows, the .NET 11 SDK, an authenticated `gh.exe`; the Codex channel also needs a native Codex with the experimental App Server queue API. It never changes agent permissions or zStudio's MCP opt-in, and never edits files outside its state, fixes code, pushes, merges, tags or publishes.

## Commands

Expand Down
1 change: 1 addition & 0 deletions docs/agents/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ Tests that need data return early unless their variable is set, so the plain sui
| `ZSTUDIO_CORPUS` | absolute path of a RECOIL data folder (holding `interp.zbd`, `zrdr.zbd`, `m1\`); a relative path resolves against the test folder | archive, world, animation, keyframe, AI, resource and source-project corpus tests. `SourceProjectCorpusTests` reconstructs the release, checks every script is an SI script with its DKit messages and no `.zrd` holds animation definitions, exports, compares the archives with the shipped ones without their definitions, rebuilds every shipped animation entry and checks that unpacking the export is refused |
| `ZSTUDIO_MW3_CORPUS` | a MechWarrior 3 `zbd` folder | MW3/AI valve inspection and complete source reconstruction/export preservation; originals are hashed and never written |
| `ZSTUDIO_DEMO_CORPUS` | a RECOIL demo's `zbd` folder (July or August 1998, version-13 worlds) | every version-13 world reads without diagnostics and every rebuilt node box gives back the stored corners |
| `ZSTUDIO_MW3_SOURCE_PROJECT` | a reconstructed MW3 source project, read only | retail C1 valve startup/range, manual reaction and timer proof |
| `ZSTUDIO_SOURCE_PROJECT` | a reconstructed project (read only; `data` and `gamegen` are copied to a temporary folder) | the terrain conversion corpus test without reconstructing first |
| `ZSTUDIO_BLENDER` | Blender 5.2.x executable | `BlenderGraphTests`: installs the packaged extension in a factory-startup background Blender with a fresh user-resource folder, round-trips shared references, flags, zones and geometry, saves and reopens a `.blend` with its baseline cache missing; never touches the user's Blender preferences or windows |
| `ZSTUDIO_BLENDER_HELPER` | the package's `zStudio.exe`, with `zStudio-Blender-extension-<version>.zip` beside it (required with `ZSTUDIO_BLENDER`); locally an extracted copy, not `artifacts/zStudio-win-x64` | the helper the extension calls; run after packaging |
Expand Down
Loading