Files
Neutron/docs/gameplay/shrink-targets.md
T

199 lines
12 KiB
Markdown

# Original 3SOL shrink targets
Status: recovered static binary/asset contract for a bounded first shrink interaction.
Original runtime verification, full soldier AI, and exact collision integration remain open.
Originals were read only; REA inspected generated hashed copies, never executed originals.
Run `python3 tools/binary/shrink_targets.py ../Original` to produce the guarded contract,
including PE-mapped **file offsets** for every address below. Saved output:
`artifacts/shrink-targets/source-contract.json`. Addresses in this note are preferred-base VAs.
## Evidence ledger
REA results, complete evidence, snapshots, and closed-session records are retained under
`artifacts/shrink-targets/`. REA observations are static analysis, not runtime traces.
| Question | REA Evidence ID | Saved directory |
|---|---|---|
| Shared Yokian construction | `ev_19d3441021faa1f39087a8e65e3b04df57315de2ee53f75b2e70fce2dc8a432d` | `rea-soldier/` |
| Shared Yokian update | `ev_c7d9d0bd6ea80f021689545e79baca422ca5b526d69c89d7ccf54c4ea2142a18` | `rea-soldier/` |
| Actual soldier construction | `ev_64b0152bae4f3a51a80c70f6470212b5c5cb9036e449d5eefe6129b35ace70c2` | `rea-soldier-bindings/` |
| Soldier model/texture loading | `ev_4e46100718fc9d13d99409941d2494de216d281317a04fd9e56ad33e1aa3e6ec` | `rea-soldier-bindings/` |
| Generic load caller | `ev_efdc2d429180a0cd692326a261bc274ac5cb0daf45ab167c0627a858acabf041` | `rea-soldier-bindings/` |
| Engine sequence selection | `ev_67aff8ee9529fa39014ae438e22e3dc52ecd2ce71d0886974d0682d6eea58f8b` | `rea-sequence/` |
| Engine endpoint/loop handling | `ev_e0d4f2ee9131d62ea289ea1aeb0f24b7de4a2bd696149309e9dfb2e3d14614df` | `rea-loop/` |
| Dynamic mode setter | `ev_8286c3d9b13f47f1e6fbf211d85636b54fb5ccb7cc7e55dd1e0f0366a7170b84` | `rea-mode-local-ipc/` |
| AIState property registration | `ev_aa47a422ce39fc5bf5bbca319fe3c37e27526299abeb9f6cdb9d065d46de9f50` | `rea-mode-local-ipc/` |
| Generic load/reset state | `ev_c448bb4062e760eb4bf3b09d39e630b130a8eafd377a27625a25b69ab7679a27` | `rea-mode-local-ipc/` |
The first mode-closure attempt (`rea-mode/00.json`) failed because the sandbox
blocked Ghidra's local Unix-socket bind. The successful invocation above used
local IPC permission; no provider/client configuration was changed. Its complete
Evidence and close/snapshot records are retained. The failed call is not used
as evidence for source behavior.
`Neutron.exe` SHA-256: `f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
`OMT2.dll` SHA-256: `3ec41ead011adf56387a6dbd4580e5b5a9721b5f8020c8a56420f42824354943`.
The helper guards eight bounded code ranges, decisive byte sites, vtable targets,
resource strings, and all three ASE hashes; it fails on an unexpected identity.
## Class ownership and initialization — recovered
`44A730` constructs shared **C3DYokian**, not the final soldier. Actual soldier
constructor `44BEE0..44C028` calls it at `44BF32`, then registers FourCC `3SOL`
at `44BFF5`. Soldier complete-object vtable is `4C1E64`, game-interface vtable
`4C19C4` at complete object `+C0`, and embedded morph vtable `4C1E14` at `+90`.
The generic model loader `40E270` dispatches complete slot `10C` at `40E331`,
reaching soldier loader `44C0B0..44C1BB`. Derived update `44C1C0` calls shared
Yokian update `44AA00` at `44C1C9`.
| Complete slot / callsite | Recovered binding |
|---|---|
| `D8` / `40D4A0` | Register model animation definition |
| `E0` / `40DD90` | Select named action; chooses HI/LO family |
| `E4` / `40DA30` | Select underlying sequence and copy loop flag |
| `10C` / `44C0B0` | Soldier model load |
At `44C19D` the soldier pushes float **90** into game-interface slot `110`
(`471240`, authored radius setter; live setter slot `264`). At `44C1AC` it
pushes float **1** into game-interface slot `100` (`4711E0`, authored factor;
live setter slot `254`). Live read slots `260`/`250` reach `471B30`/`471AF0`.
These are soldier body defaults; they do not establish the full collision solver.
## Model, texture, and authored shrink geometry — recovered
| Registration site | Action | Original ASE |
|---|---|---|
| `44C0C3/44C0C8` | `HIWALK` | `ASE/soldwalk.ASE` |
| `44C0DC/44C0E1` | `HISHRINK` | `ASE/soldshrink.ASE` |
| `44C0F0/44C0F5` | `HITALK` | `ASE/soldatak.ASE` |
| `44C104/44C109` | `HISTOP` | `ASE/soldatak.ASE` |
The loader compares scene FourCC against `VR01..VR08` at `44C121/44C128`.
For those scenes both texture indices 0 and 1 use `vryoksoldier.png`
(`44C133/44C144`, string `4F1950`). Supplied filename is
`png/VRyoksoldier.png`; portable lookup must ignore case. Other scenes bind
index 0 to `png/yoksold.png` (`44C14F`) and index 1 to `png/yoksoldtalk.png`
(`44C160`). Loader selects `WALK` with second argument 1 at `44C184`.
All three ASE clips have 190 vertices and 377 faces. `soldwalk` and
`soldshrink` have five samples at ticks `0,960,1920,2880,3840` (5 fps,
960 ticks/frame); `soldatak` has two samples (10 fps, 480 ticks/frame).
In existing ASE→OMT coordinates, shrinking sample Y bounds are:
| Tick | Minimum Y | Maximum Y | Height |
|---|---:|---:|---:|
| 0 | -55.6508 | 260.1789 | 315.8297 |
| 960 | -19.5291 | 208.5813 | 228.1104 |
| 1920 | -28.4904 | 156.9837 | 185.4741 |
| 2880 | -4.0918 | 105.3861 | 109.4779 |
| 3840 | -1.3301 | 53.7885 | 55.1186 |
This is actual morph deformation. A uniform quarter-scale soldier would be an
unsupported replacement. No extra uniform render scale was established in the
inspected source. The visual can retain original vertex units and authored root.
## Shrink, animation ownership, and expiry — recovered
Jimmy callback `42AC10` (investigated separately in `shrink-ray.md`) receives an
enemy game interface and subtracts `C0` to obtain the complete object. It selects
`SHRINK` with argument 0 at `42AC33`, selects mode 5 at `42AC50`, writes timer
complete `974 = 30` at `42AC68`, and writes flag complete `970 = true` at
`42AC8A`. The shared constructor initializes that flag false at `44A905` and
timer zero at `44A7EA`. Game-interface-relative offsets are timer `8B4` and flag
`8B0`; authored/reset mode is interface `87C`, complete `93C`.
### Mode setter and restoration ownership — closure
Soldier complete vtable `4C1E64` slot `124` points to generic enemy setter
`4089B0`. At `4089E5..4089FE` it copies **current complete `6C8` into previous
`6CC`**, then stores the requested mode in `6C8`. Requested mode 5 takes jump
table entry `408BA8` directly to the return at `408B8E`; there is no further
mode-5 callback or copy into `93C`. Thus SHRINK selection does **not** snapshot
the dynamic prior mode into the expiry field.
Interface `87C` is registered as the GAM **AIState** property at
`407F67..407F77` (name string `4ECA90`). Shared Yokian construction initializes
both complete `6C8` and `93C` to 2 at `44A7D3/44A7F7/44A7FD`. Generic load/reset
`409480`, at `409503..40951E`, copies interface `608` back to `87C` and passes
it to complete slot `124`; the separate initialization path `409460` copies
`87C` into `608`. The expiry body reads `87C`, not previous dynamic mode `6CC`.
For the three authored VR04 soldiers this restores GAM AIState **2**. A port
which snapshots its dynamic current AI state when shrinking would diverge once
AI begins changing modes; preserve a separate authored/reset AIState field.
Its value is 2 by constructor default, rather than an uninitialized zero.
Named selector `40DD90` forwards the caller's second argument through slot `E4`
at `40DF4C..40DF5E`. Wrapper `40DA30` calls embedded engine sequence selection
at `40DA61`, then explicitly writes the argument byte to complete `AD` at
`40DA64`. Since the embedded animation starts at `90`, this is engine animation
offset `1D`. Engine `find_next_frame` (`OMT2.dll:10021000`) reads `+1D` at
`10021079`: false holds the current endpoint (`100210B4`), true wraps to first
frame (`10021080`). Therefore source `SHRINK(...,0)` **does not loop**; source
`WALK(...,1)` does loop.
The engine sequence-selection boolean also controls restart: `100209F0`,
especially `10020A3A..10020A78`, restarts at first frame when true; when false
and an old frame exists it walks old/new lists to preserve the frame ordinal.
Thus changing WALK→SHRINK need not begin at shrink frame 0. Both have five
samples. Exact within-frame clock preservation remains open; any time-zero
transition in the port is an explicit approximation until closed.
Shared update `44AA00` decrements timer only when it is **strictly positive**
(`44AE5E..44AE6F`), subtracting delta at `44AE75..44AE7F`. It expires only when
the resulting value is **strictly negative** (`44AE85..44AE90`). Exact zero does
not expire in this body and is skipped next tick: preserve/document this source
edge case instead of silently substituting `<= 0`.
Expiry zeros timer (`44AE96`), clears flag (`44AE9C`), clears interface `88C`,
reads authored/reset mode `87C` (`44AEA8`), invokes complete mode slot `124` (`44AEBD`),
and requests **WALK** with argument 1 (`44AEC6`). String `4ECA54` is `WALK`,
not STOP. It restores interface `604` speed 200 (`44AED3`). While shrunk the
inspected branch can move current mode 0 to mode 5, set interface-related value
1500, and speed 400 (`44AE42..44AE54`). Full AI meaning of those transitions is
not closed here.
Calls `43F870(40,15)` while shrunk and `(140,50)` on expiry operate on owned
effect interface `8EC`. They are **effect sizes**, not soldier body radius.
No body-radius setter was found in this bounded shrink/expiry branch; that
negative observation does not prove no other mode/base update changes physics.
## First real targets: VR04 — original level data
`gam/VR04.gam` contains three `3SOL` actors; all set `AIState=2`, `CanMove=1`,
and `HasCollision=1`. Values below come directly from the bounded GAM parser.
| GAM offset | ObjectTag | Position X,Y,Z | PatrolPoint | VisibleRange / FOV |
|---|---|---|---|---|
| `4431` | `yoke1` | `-2463.1035,6327.9810,-7001.6870` | `dyok1` | 1000 / 259 |
| `582C` | `C3DYOKIANSOLDIER` | `1677.5118,6422.5869,-4131.2129` | `eyok1` | 2500 / 259 |
| `67C5` | `yoke2` | `-529.4881,6378.4834,1319.0276` | `fyok1` | 1000 / 359 |
These are authored actors high in the scene, not entrance test dummies. A bounded
interaction test can move the player near one as an explicit test fixture; it
must not relocate original actors or claim their AI has been reconstructed.
## Implementation boundary and unresolved work
At investigation start the runtime's `SceneActorVisuals` supported Carl,
Goddard, and trophy families; it did not render `3SOL`. `MorphAnimation.Sample`
looped all clips. The supported next chunk is to export these real soldier
clips/textures, render authored actors, support a nonlooping last-frame hold,
and apply the recovered SHRINK/timer/WALK transition. Parent owns runtime work;
this report does not assert those changes have shipped or run.
Existing `OriginalScenePhysics` can provide provisional radius-90/factor-1
settling for that bounded interaction. Reusing it is an implementation choice,
not proof of original soldier physics. The following remain explicitly open:
- Full soldier patrol, targeting, attack, damage, death, shadow/effect and sound updates.
- Exact collision/support/root defaults and all dynamic radius changes through base/AI modes.
- Other script/load/reset callers that can modify authored AIState independently of dynamic mode.
- Exact sequence-switch subframe timing and special empty/mismatched sequence cases.
- Non-VR texture-index animation switching and low-detail action availability.
- Original runtime comparison of shrink geometry, 30-second restoration, targeting,
and actor placement; native Windows gameplay verification remains required.
Regression checks validate original identities/dispatch, clip topology and shrink
geometry, authored VR04 actors, and a bounded timer control-flow projection.
They do not execute original code or establish original runtime equivalence.