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.

SOLVED (5.3.126): the lifecycle kill-cycle crash was a MISSING MAPPER

Symptom: lifecycle2.conf died seconds after the SRM salvos with Exception 0E ... illegal address 000000FC, EBX = the spawned enemy mech. The map put the EIP inside Missile::MoveAndCollide -- a red herring: the map resolves the nearest PRECEDING symbol, and the real faulting code was a mech-side inline.

The instruction settled it: mov eax,[ebx+0x128]; mov eax,[eax]; mov eax,[eax+0xFC] = mech->subsystemArray[0]->member with subsystemArray[0] NULL. Roster slot 0 is the controls mapper, and the BT_SPAWN_ENEMY dev enemy never got one -- SetMappingSubsystem is called only from BTL4APP's viewpoint-entity path, i.e. for the PLAYER's mech. The binary never NULL-checks slot 0 (mech2's advancers, the master perf's duck evaluation and the census all deref it bare, correctly: a real mech always has its mapper), so the first frame the enemy reached one of those reads, it faulted.

CONFIRMING EVIDENCE (the fault-address rule, used properly this time): the faulting member offset MOVED 0xFC -> 0x100 across the 5.3.125 build, which added ejectLatch to MechControlsMapper -- a 4-byte layout shift in exactly the class being dereferenced. That named the object beyond doubt.

Why it lay hidden since ~5.3.26: before the gait arc nothing dereferenced a non-player mech's mapper. Missile::MoveAndCollide was never involved; the missile flight path is exonerated.

FIX: the dev enemy spawn now installs a plain MechControlsMapper (inert without device input) in slot 0, preserving the binary's contract. VERIFIED: full lifecycle green -- kill -> respawn -> second kill -> OUT OF LIVES -> mission end -> clean DOS exit, zero exceptions.