TeslaRel410/restoration/source410/BT/MISSILE.NOTES.md

MISSILE.CPP / SEEKER.CPP / MISTHRST.CPP / PROJTILE.CPP — the flying rounds

Status: LIVE and DEFAULT (5.3.19) — the full entity lifecycle is verified: spawn → guided flight → proximity detonation → death-row teardown, 20/20/20 over a 110s mutual fight with zero faults. BT_MISSILE_INSTANT=1 keeps the 5.3.18a instant-hit delivery as an A/B dev opt-out.

Interfaces

• SEEKER.HPP + MISTHRST.HPP are AUTHENTIC survivors (CODE/BT/BT/). The Subsystem base chain is the NAME ctor (binary FUN_0041c52c) with the shipped strings "Seeker" @00512e1e and "MissleThruster" @00512e25 (the 1995 misspelling is authentic — keep it).
• MISSILE.HPP / PROJTILE.HPP are STAGED (only MISSILE.TCP / PROJTILE.TCP survive). Binary chain: Entity → Projectile (@004be1bc, 0x340) → Missile (@004bf5b4, vtable @00512f2c, 0x368). Our staged chain matches: Projectile : Mover (make-message path), Missile : Projectile.

What is verified live (BT_MISSILE_FLIGHT=1 fight run)

ONE cluster Missile entity per SRM salvo, spawned through the real Mover make machinery mid-weapon-sim (the Entity ctor self-registers — the engine tolerates mid-roster-walk creation, as the binary did); flight telemetry shows thruster acceleration (150→153 u/s) and closing range; the proximity fuse (rangeToTarget <= 20u staged) delivers damageData (salvo-split amount, burstCount=missileCount) exactly once via TakeDamageMessage with the LAUNCHER as inflictor; lifetime fizzle retires unexploded rounds. Guidance constants are binary-decoded (steer deadband 1e-4, turn gain 4.0, seeker loft 200/50/300/0.1 — .rdata @004bec18/@004bf594).

The teardown crash — SOLVED (5.3.19)

The dtor-chain bisect (logs in ~Missile/~Projectile/~Seeker/~MissileThruster) showed the whole chain COMPLETING, then the fault. The killer was the third strike of the uninitialized-zone-array trap: the staged spawn uses the MECH FAMILY's resourceID, whose DamageZoneStream makes the Entity base ctor allocate the 20-pointer damageZones[] array (entity.cpp:1032, slots UNINITIALIZED) — the Missile never fills it, and ~Entity's teardown loop if (damageZones[i]) delete damageZones[i] called 20 virtual dtors through trash vtables (EIP-in-heap AFTER the subsystem dtors — exactly the bisect signature). FIX: the Projectile ctor NULLs every inherited zone slot. RULE (three crashes now): any entity subclass that does not FILL the allocated zone array must NULL it — the Entity base never initializes the slots, on construction OR destruction. Also fixed en route: the Subsystem NAME ctor left damageZone uninitialized (the resource ctor NULLs it). Ruled out along the way: AlwaysExecute flags, interestZoneID (message base NULLs it), the subsystemArray idiom, Sensor caching, FryDeathRow timing (an app task, one delete per frame, not mid-walk).

Engine truths learned (load-bearing)

• ResourceFile::SearchList(id, type) CRASHES (@0x414938) when id is not in the top-level directory — it derefs its inner FindResourceDescription unconditionally. FindResourceDescription(int) is the NULL-safe probe.
• Resource IDs in MakeMessages must be FAMILY ids: the Mover base ctor runs its own SearchList(resourceID, GameModelResourceType), and member resources resolve only through their family head.
• The streamed explosionModelFile IS a resource FAMILY id after all (5.3.20 decode): SRM6's 17 = 'mslhit' — a 3-member family: VideoModel (id 225, 100 bytes), AudioStreamList (id 227), and an 8-byte GameModel (id 228) = { int 498, Scalar maxTimeOfFlight } — SRM reads 5.0 s (range 800 at ~160 u/s checks out). Resource TYPE numbering (RESOURCE.HPP): 1 ModelList, 9 BoxedSolidStream, 10 VideoModel, 15 GameModel, 17 SubsystemModelStream, 18 GaugeImageStream, 20 DamageZoneStream, 21 SkeletonStream, 30 ExplosionTableStream. A family's raw stream = int count + count member resource ids (what SearchList walks).
• NoCollisionVolumeFlag is LOAD-BEARING on projectile spawns: collision volumes are the Mover DEFAULT (IsCollisionVolume() = the flag NOT set), and the ctor then demands a BoxedSolidStream member — which a projectile family doesn't carry (SearchList NULL → Lock() page fault; the mech family works because bhk1 carries blh_cv.sld). The round's collision is the world query / proximity fuse.
• The original SearchList crash (@0x414938) is the missing-MEMBER case: Check(res) on a member id that doesn't resolve is compiled out in opt and the walk derefs NULL. Probe families manually (FindResourceDescription per member) before handing them to engine paths.
• The spawn keeps the resolved family LOCKED (no Unlock) — the launcher holds its projectile model resident, as the binary does.

Staged / deferred

• Muzzle = mech origin; the authored MuzzleVelocity arc through the MOUNT segment world frame (fire builder @0x4bcc60:8758-64, z NEGATED + mech velocity) is the muzzle wave.
• Lifetime is AUTHORED now (5.0 s from the mslhit GameModel, sanity-banded [0.5, 30] so the owner-family fallback's mech record keeps the default); burn (2s @120 u/s²), launch speed (150 u/s) and fuse radius (20u) remain staged — BT411's model +0x44/+0x48/+0x50 offsets describe a bigger record than the 8-byte 4.10 GameModel, so thrust/detonation-mode live elsewhere (candidates: the VideoModel record's tail, or per-launcher resources).
• Cluster SPLASH + explosion entity (ClassID 0x5C @004be078), world-geometry collision (@0042291c), target-velocity intercept lead, Missile WriteUpdateRecord (tag 0x78) for MP replication.

OPEN DEFECT (found 5.3.121, PRE-EXISTING): lifecycle kill-cycle crash

lifecycle2.conf (KILLTEST.EGG, BT_SPAWN_ENEMY + BT_FORCE_FIRE + BT_FORCE_ZONE=10) now dies ~seconds after the first SRM salvos launch, BEFORE any [death]: Exception 0E ... illegal address 000000FC, faulting instruction mov eax,[eax+0xfc] after mov eax,[ebx+0x128]; mov eax,[eax] with ebx = THE ENEMY MECH (matches the [enemy] spawn address in OUT.TXT). Map resolves the EIP into Missile::MoveAndCollide (0x4b1b54-base) -- the seeker/thruster work is folded in there, but our LeadTarget NULL-guards targetEntity, so the exact deref is not yet identified (mech+0x128 in OUR layout -> a pointer whose first dword is NULL -> +0xfc).

PROVEN PRE-EXISTING by a control run: the identical crash (same 0xFC address, EIP shifted 0xCC by the relink) reproduces on a build with all 5.3.121 changes stashed. The rig last ran green at 5.3.25 -- the break landed somewhere in the gait/renderer/duck arc (5.3.26..5.3.120) and was never noticed because nothing re-ran the kill-cycle conf. Bisect hint: the [msl] LAUNCH lines print, so the launch path is fine; the fault is in the per-frame chase or the mutual-fire path against the enemy mech. Two-agreeing-runs done (both builds crash identically, deterministic).