Vessel construction unification — Dolphin rig swap, measured audits, vestige retirement [flight 15: the boosters' roll floor removed]

[gradies]

The fleet is built two incompatible ways — a skinned family (one armature, one skinned hull, element shapes) and a part-per-mesh family (a static mesh per part, no armature, therefore no morph and no puppetry). This branch moves the Dolphin from the second to the first, which is the only time a vessel has ever changed families, and fixes the instruments that were reporting on it.

The governing rule was that nothing is deleted until what it carries has been measured and, if valuable, extracted. Phases 0 and 1 exist to honour that, and two "vestiges" turned out to be load-bearing.

DRAFT — the ship flies right; flight 13 found the depth-cue inversion that drove the whole booster-seat loop, and flights 14–15 pinned the boosters to the body. Fifteen flights, each finding something the previous one masked, until a rebuild in which every number is a measurement and a four-lens adversarial panel signed the diff. Flight 10 is the one worth reading: it caught a process defect rather than a code one, and it now has a build gate. The verification history below is the honest record and is the most useful thing on this PR.

What landed

Phase 0 — re-survey before touching anything. Two rows of VESSEL_CONSTRUCTION.md §4 were wrong about liveness. urchan_shapekey_with_animations.fbx (7 clips → 9 vessels) and SparrowModel4.fbx (the Missile Launch states) have zero prefab references and are load-bearing — an AnimatorController references clips by the model's guid, so a sweep measured against prefabs and scenes cannot see them. Both were on the deletion list.

Phase 1 — salvage inventory. Every candidate checked for shapes, bones, takes, referrers, and geometry not present elsewhere, written down before anything moved. RhinoModel.fbx is held: it is the only copy of the Rhino's pre-subdivision wings.

Phase 2 — the Dolphin rig swap. dolphin_shapekey_with_animations.fbx carries a real four-element morph, the 28-bone armature RiptideAnimation names, and six exhaust nozzles the shipped hull scaled to 0.00095 units and never drew. The rig is the shipped hull, in the same place, so each gameplay volume is re-homed onto its bone with the world pose preserved and no collider is re-fitted.

Phase 3 — Rhino and Urchin, decided explicitly. Their rigs' element shapes are labelled but inert — one vertex, moved 0.0000 units. Challenged ("are we sure there are no rhino blend shapes on any model?") and re-verified across all 93 distinct FBX blobs in project history, after discovering this clone was shallow with 2 of 363 branches fetched. One blob ever, always empty. Decision: swap for the puppetry, leave the morph honestly absent.

Phase 4 — audits measure the thing, not its label. The morph audit compared shape names and would have reported the Rhino green after its swap. It now measures travel relative to the mesh's own diagonal and reports LABELLED BUT INERT.

Phase 5 — retire the cleared vestiges. 11.7 MB, zero dangling references.

Verification history — the part worth reading

Flight 1 — every asset check passed; the ship flew broken. The rig's .meta had externalObjects: {}, so it imported its own DCC materials — and accent.001, the material that should carry the DOMAIN colour, is EmissiveColor (1.0, 0.395, 0.0) at EmissiveFactor 10. Worse, submesh order is not a convention (Sparrow puts Domain at 1, the Manta family at 2, this rig's body at 1), so the default _domainMaterialSlot: 1 painted the team colour over the whole body — what that field's own tooltip forbids. Fixed by remapping the three roles and moving to the order-independent _domainReplacesMaterials.

Flight 2 — colours fixed, puppetry wrong. "Roll and pitch are mixed, pitch is inverted, the wings fold up when drifting", with the hypothesis that the models had different coordinate systems. Correct. Quaternion.Euler(...) on localRotation turns about the parent's axes — the ship's on root-parented art, a bone's on a rig. Measured, for a commanded pitch: jetT.l turned about (−0.541, 0.840, −0.043) (mostly yaw), winghold.l about (−1.000, 0, 0) — the ship's pitch axis exactly negated, which is the inverted pitch, because that bone rests at (77.08, 0, −180). Separately, parts re-parented onto the drift handle replayed a bone-captured rest under a foreign parent: 164.50° (wings) and 152.38° (engines) off, on drift entry, with no input. That is the fold.

Flight 3 — roll still wrong, engines never moved, drift re-aimed. The engines' "backward" and "default" offsets were the same vector, so half the drift clearance had never existed — and translating the constants faithfully preserved the omission. A degenerate constant pair is not a design.

Flight 4 — the drift was backwards, and that one was mine. A drift splits the ship: the fuselage and jaws aim, while the wings and engines hold Course so the hull reads as slewing across its own path. I had read the clearance statement as the whole intent and deleted the Course re-parenting as dead machinery. It wasn't dead — it looked inert only because the frames were still wrong. Restored as a frame rather than a re-parent, which is strictly better on a rig.

Flight 5 — roll is the HULL, not the wings. Reported inverted, negated, reported still swapped. A pure sign flip is one of the few edits whose effect is certain, so a symptom surviving one is evidence about where the defect is. It is VesselTransformer.Roll() — byte-identical to bleeding-edge, shared by six vessels, and untouched by this branch. My negation was reverted. Separately the wings bank against the hull in a way the math says is impossible (their delta is provably identical to the chassis's), so that is now an authored parameter rather than a fourth guess.

Flight 6 — "the best yet" on base puppetry; the drift asked to be redesigned, not restored. Three asks: jets further back at rest, appendages holding Course orientation during a drift (not frozen at entry), wings forward / jets back. The frozen-at-entry frame became a stateless one — the hull re-aimed onto Course by the shortest arc, rebuilt every frame (§4.6.2: a frame that must hold still cannot be a Transform parented under the thing that moves; the parented handle accumulated 24.6° of twist). The wings' own pitch is Brake(throttle) — zero unless braking — so their whole pitch response was the chassis term the old hierarchy delivered free; it is composed in explicitly, bit-identical to the legacy hierarchy at one ULP (§4.6.1).

Flight 7 — the offsets did not read, then read 100× too big. The positional layer ran only on the puppetry path (Idle() writes rotations only — §4.6.3), and the offsets were absolute units whose scale neither model states. Rebasing them on the occlusion corridor's hull measure imported the very ambiguity it fled — that helper measures through the root bone, exactly where the disputed armature factor lives — and threw the parts off the ship (§4.6.4).

Flight 8 — PASSED: the measured rebuild. "This is close to perfect. with only 2 minor adjustments." Instead of an eighth guess, a four-agent hunt measured the ground truth (§4.6.5). The import model is now PINNED — fitted against the colliders the swap itself preserved (residual 3e-5): Unity's import is a 0.01·mirror-X conjugation; the bones keep lossyScale 100 while their world poses land exactly on the hull. Both prior readings were half-right, and everything re-derives from it:

• Every number is a measurement. driftWingForward 2.2 = the proven bleeding-edge lunge (its own constants, mapped through the rig's rest — the reach-fraction scheme's |f|≤1 clamp on a 1.96 basis could not express it at any authoring). jetRestBackward 0 — the "jets pushed forward" report inverted on measurement: the old runtime dragged its engine pivots from authored z −2.047 to −1.7 every frame; the rig, which retires that drag, already rests its drawn nozzles 0.40 behind the old screen. driftJetBackward 0.5 is the one ask rather than parity (bleeding-edge's "backward" and "default" engine constants were the same vector — its engines never moved).
• The cage holds ONE frame — Course — for positions and orientations (the legacy DriftHandle re-parent did both; holding only orientation swept the cage sideways with the aiming hull), and the pose is written exactly in cage coordinates with the entry pose adopted and blended to station: a lerp toward a hull-independent target trails a 110°/s aim by ~53°/1.7 wu of visible drag — the standing "the wings and jets still appear to move as I am drifting and aiming".
• Guards the adversarial panel demanded: the cage is slew-limited to 360°/s (FromToRotation's antipode churn is 68°/frame at 3° off a reverse aim, and the exact write removed the lerp that used to hide it); the rest anchor is a capture-time constant (a live read applies the chassis term twice on legacy art — 27.8°); updateWhenOffscreen on the skinned renderer (rest-pose culling bounds vs a 2.2 wu lunge); the entry blend is exponential (legacy feel); and the three clearance fields are serialized into the prefab deliberately.

Flight 9 — PASSED ("everything is perfect. just move the flying position of the boosters back further.") — the two flight-8 feel asks (050b7eee2): the wings' and all six boosters' ROLL response is mirrored (roll negated everywhere it reaches those parts — own term and composed chassis term; the chassis keeps the true roll, the aileron cross-coupling and the drift cage's roll-follow are untouched), and the boosters' rest seat moves to exactly halfway to the drift station (0.25 + 0.25) with the station itself — called perfect — byte-identical at 0.50 and pinned by the verifier as a balanced pair — that pin turned out to be the mistake flight 10 uncovered; it is retired below. Deliberate deltas from bleeding-edge on record in §4.6.5: the deeper engine rest, engines moving on a drift at all, and the mirrored appendage roll. (Flight 15 revisits the boosters' half of that mirror — direction preserved, see below.)

Flight 10 — "oddly this seemed to do nothing", and it was exactly right (f38a4e777). The code was never at fault: a tuning step below the threshold of visibility is indistinguishable from a change that never applied. Flights 9 and 10 each moved the booster seat 0.125 wu — 3.6% of the 3.45 hull, a handful of pixels at chase distance — so two playtests bought no information. The cause was a constraint this branch imposed on itself: an earlier pass PINNED the drift station at 0.50 off one flight's sign-off, so every later "further back" had to be paid out of the shrinking gap to that ceiling and halved its own step.

Fixed by measuring the ship instead of guessing. From the rig's own skin clusters (vessel frame): nozzles sculpt at z −2.290…−1.887, fuselage tail at −2.471 — so at any seat under 0.584 the boosters sit tucked alongside the tail, which is precisely the report. Shipped jetRestBackward 0.375 → 0.6 (clears the tail; the cluster reads as engines behind the body), driftJetBackward 0.125 → 0.25 (the drift SLIDE restored to a visible 7.3%), station free to follow at 0.85. Pin the motion, not the absolute station. The verifier's station pin is retired for a 5%-of-hull visibility floor — on the seat, on the slide, and on any step away from a value a playtest could not see — so a sub-threshold tune fails the build rather than costing a flight.

Flight 11 — "the wings don't travel far enough forward to get clearance while drifting, and the boosters still return to a position far to forward" (55afcd933). Both answered geometrically. The wing lunge stops being old-game parity and becomes a clearance: the aiming hull's jaw tip sweeps a 2.835-radius sphere about the vessel origin (max |r| over the jaw skin verts), and at 2.2 the wings' nearest vertex sat at |r| 1.76 — inside it, exactly as reported (the old game interpenetrated too; parity preserved the defect). Shipped driftWingForward 2.2 → 3.5, rounding up the bisected L* = 3.492 — the smallest lunge putting every wing vertex outside that sweep ×1.05 gape margin, so the jaws cannot reach the wings at any drift aim angle (within the ±4 clamp; binding vert the wing root at (−0.760, 0, −0.614)). The booster seat goes bold after three escalating asks: jetRestBackward 0.6 → 1.0 — 0.6 cleared the tail by a sub-visible 0.017; 1.0 lands the nozzles' leading edge 0.42 wu behind the tail (29% of hull, a 0.4 step, both far above the floor). driftJetBackward stays 0.25. The verifier gains a geometric clearance assertion in check 8 (binding vert vs jaw sweep), so an under-clearing retune fails the build.

Flight 12 — "everything is perfect now (even the wings and the drifting position of the boosters) except the home position of the boosters ... they continue to rest near the origin of the fuselage" (50d568fab). Drift is now locked in as correct. The rest seat had been called too far forward across three flights (10, 11's ask, 12) against three successively deeper, individually-measured seats (0.6, then 1.0) — each one clear of the 5%-of-hull visibility floor (flight 10's actual defect) but still not enough, which is a different failure than flight 10's. Two changes: decouple — BackwardThrusterOffset used to read jetRestBackward + driftJetBackward, so every rest-seat bump silently moved the drift clearance too; flight 11's 0.6 → 1.0 bump happened to land the drift total at 1.25, and flight 12 confirms that reads as perfect, so a further rest bump risked dragging a value nobody had asked to move. driftJetBackwardTotal is now its own field, locked at 1.25, with no path back to jetRestBackward. The seat was then pushed to 1.8 on the theory that three above-floor increases surviving the same verdict meant "not enough" — flight 13 reversed that; the decoupling stands and is what made the reversal a one-field change.

Flight 13 — "I had to look at the scene view to realize the boosters were far more back than I realized. it is just getting puppeteer[ed] in a way that made me perceive them as much closer" (62677def8). The seat was applying all along, and no seat could ever have fixed the report: the Dolphin's chase camera is on-axis and level (followOffset (0, 0, −20)), so a part's station along the hull projects to almost nothing on screen — the surviving depth cues are SIZE and OCCLUSION, and both invert the intent. A booster seated 1.8 aft sits 3.7 wu nearer the lens than the wings, renders ~24% larger, and draws over the hull wherever silhouettes overlap — occlusion, the strongest monocular cue, says "in front of the wings". Every seat increase made the in-game read worse-or-same while the true geometry marched backwards, which is the loop flights 10→12 lived in. On top of that, the puppetry flailed each case up to 100° at full stick (chassis 25° composed with the shared exaggerated 75°), sweeping six enlarged, hull-occluding silhouettes across the wing region. The fix tunes the read, not the depth: jetRestBackward 1.8 → 1.0 (the true-geometry value — nozzle leading edge 0.42 wu behind the tail, judged in the scene view where depth is honest) and a new thrusterAnimationScaler = 25 for the boosters' own puppetry term (full-stick deflection halves to 50°; the wings keep their signed-off terms). The verifier gains a swing-envelope assertion: the most-forward z any of the 7,500 jet-cluster skin verts reaches over the full input cube, rotated about the six measured bone pivots, must stay behind the fuselage tail plane at the shipped seat + amplitude (margin 0.244 wu; the retired 75° term at the 0.6 seat crossed by 0.39). General rule: on an on-axis chase camera, moving a part aft moves it toward the lens — answer a "too far forward" report by tuning silhouette separation and motion amplitude, never by more depth.

Flight 14 — "less separation between boosters and fuselage … when turning the boosters should stay more pinned to the fuselage puppeteering. it should still separate, just closer to pinned than now" (4b7cdbac5). Read off the code rather than assumed: Chassis resolves to the fuse bone — the fuselage itself — and turns Euler(p·25, y·25, r·25), while the boosters compose appendageChassisTurn = Euler(p·25, y·25, −r·25) before their own term. So on pitch and yaw the boosters' chassis component tracks the fuselage exactly and thrusterAnimationScaler is the whole of what separates them from it — one number, with 0 meaning literally pinned. Shipped 25 → 12: measured peak swing of a booster off a perfectly-pinned one (over the input cube, at the farthest jet vertex, 0.444 wu from its pivot) 75 → 0.847 wu, 25 → 0.345, 12 → 0.165, 0 → 0, and relative-to-fuselage angle on pitch/yaw 35.2° → 17.0° — half the swing, still legibly separating. The flight-13 envelope invariant strengthens with it (margin 0.24 → 0.38 wu behind the tail plane). On ROLL a 50° floor survives own = 0 and this dial cannot reach it: the appendage chassis term mirrors roll (the signed-off legacy-parity ask) while the fuselage keeps true roll, so roll separation only falls 86.6° → 65.3° — recorded as a named constant in the verifier so a future "still too loose when I roll" goes to the mirror, not to another amplitude cut that cannot reach it. Check 8 gains a separation assertion (shipped swing strictly smaller than what it replaced and strictly non-zero — "still separates" is the ask). General rule: when one term is shared with the body a part is measured against, it is not separation — separation is only what the part adds on top, so identify which terms cancel before tuning any of them.

Flight 15 — "the boosters need to remain much closer to the back of the fuselage" (903017d0a). Third ask in the same direction, and flight 14's own measurement said the dial could not deliver it: at thrusterAnimationScaler = 0 a pure roll still separated a booster from the body by 50°, because the boosters took appendageChassisTurn — whose roll is mirrored — while the fuselage keeps true roll, so on that axis the two added where on pitch and yaw they cancel. The boosters now compose a chassis term carrying the body's true roll (thrusterChassisTurn) and keep the mirror in their own term only, so the chassis component cancels on all three axes and the dial bounds the whole separation; thrusterAnimationScaler 12 → 5 on top of that. Measured over the input cube: worst-case relative-to-fuselage angle 65.3° → 8.8° (7.4×), peak swing off a perfectly-pinned booster 0.165 → 0.068 wu, flight-13 envelope margin 0.375 → 0.409 wu. The signed-off flight-9 mirror is preserved, and by sign rather than by argument: relative roll is −5.00°/+5.00° at full stick where it was −62.00°/+62.00° — same direction, smaller magnitude — and the verifier now asserts that sign, so a construction that cancelled the own term's mirror too would fail rather than quietly lose the ask. The wings are untouched (nobody has reported them; flight 12 called them perfect). General rule: a term shared with the body cancels on the axes where it matches it and DOUBLES on any axis where it is negated — mirror what a part CONTRIBUTES, never what it INHERITS.

Verification status

• Editor-verified: Audit Vessel Elemental Morphs reports the Dolphin at all four elements — Mass 12.056%, Charge 4.314%, Space 3.140%, Time 13.538% of the hull diagonal. Fleet line: 9/12 vessels ship element shapes that move the hull (shape keys; the merged auditor now counts procedural morphs alongside them — see the merge note).
• Asset-verified against the prefab YAML, differentially: six sub-pixel Engine GameObjects removed and nothing else · MeshRenderer 18→1, MeshFilter 19→2 · 11 Box + 1 Sphere colliders unchanged · 0 dangling fileIDs introduced · §3 reachability clean · Dolphin absent from the §3.4 duplicate-hull list, proving the old renderers were removed rather than merely disabled.
• Compile-verified: Roslyn, stubs transcribed from real declarations and proven by negative controls that fail correctly. It caught an invented type name (SwapSpec; it is RigSwap). Note unity-ci.yml's unity job is gated on an unset UNITY_RUNNER_LABEL, so nothing in CI compiles C# on any PR here.
• Math-verified: Tools/Build/verify_vessel_rig_puppetry_frames.py — now 13 checks against the rig's measured bones: the two original invariants (ship-aligned part bit-identical, 0.000000000°; zero-input drift entry moves nothing, 0.00°), plus the world-unit round trip exact at chain scale 1 and 100, the cage bit-still under single-axis aim with the vessel-frame control reproducing the 2.5 wu sweep defect, the 30° roll-following orbit at radius drift 2e-16, legacy-art single chassis application (1.1e-16 vs the 27.8° live-anchor control), the antipode guard + slew limit (raw 20°/step vs shipped 6.00), the lag control (a lerped cage trails a full-rate aim by 53°; the exact write, 0), and the visibility floor — 5% of hull on the booster seat, on the drift slide, and on any step away from a value a playtest could not see, plus the measured tail-clearance anchor — the wing clearance assertion (the binding wing vert at the shipped lunge must sit outside the jaw-tip sweep ×1.05) — the swing envelope, the separation assertion, and flight 15's floor-removed + mirror-direction assertions — and, since flight 12 decoupled them, an independent tail-clearance + visibility-floor check on the drift total and the rest seat.
• Measurement-verified: the import model was fitted against the twelve colliders the swap preserved (full-matrix residual 3.4e-5–5.8e-5; five independent negative controls, including the old prefab's −2.047034 reproduced to six decimals and the rig's jaw centroids equal to the old nose geometry to four). The old game's on-screen part positions were reconstructed from bleeding-edge's own constants — the drift numbers are that record, not feel values.
• Panel-verified: a four-lens adversarial review (frame math / lifecycle / assets / simulated playtest) ran over the final diff; its one blocker (the antipode churn band, exact-written) and every risk it raised are fixed in 2db1a87ed.
• Flight-verified: flights 8 through 15 ("close to perfect" → "everything is perfect" → "even the wings and the drifting position of the boosters" now perfect) — base puppetry, the mirrored roll, the wing lunge, and the drift cage all read on screen and are signed off. The one open item is the read tune — flight 13's true-geometry seat, the booster flail cut twice more, and flight 15's removal of the 50° roll floor (903017d0a) — awaiting its flight. All four dials are live inspector fields on Dolphin.prefab (RiptideAnimation.driftWingForward / jetRestBackward / driftJetBackwardTotal / thrusterAnimationScaler), draggable in play mode.

⚠️ This branch is no longer editor-only. The playtest fixes added runtime changes under Assets/_Scripts/Controller/Animation/, so it now ships code.

What a reviewer should know

A rig swap is three jobs — geometry, materials, animation — and passing the first says nothing about the other two, because both of those only fail on screen (VESSEL_CONSTRUCTION.md §4.6). VesselRigSwapper now refuses a rig whose hull wears none of the fleet's materials; the Rhino and Urchin rigs have the same empty externalObjects and would have reproduced flight 1 exactly.

Guid ownership. An FBX's .meta can carry a material remap into another FBX, so grep -rl | head -1 returns a plausible false positive — it had put two passes of Rhino jets on a placeholder hull, and CLAUDE.md itself repeated the wrong answer. Resolve with grep -c "^guid: $g" per candidate.

A magnitude is only comparable to numbers from the same tool. The in-editor audit and the offline mirror report the same four shapes 1.283× apart, identical to four digits — the denominator, not a discrepancy: mesh.bounds on a skinned mesh is the culling volume in root-bone space. Do not reconcile them (§4.5).

Also fixed: measure_vessel_prefabs.py read the model only from m_Mesh, which a stripped renderer does not carry — it reported the swapped Dolphin as UNRESOLVED and had been blind to Scarab, Serpent, Sparrow and Squirrel all along.

Merge note

Conflicted with #801 (skyburst missile tail) on two adjacent CLAUDE.md index rows. Each side changed exactly one row and left the other at the merge base, so the resolution is disjoint and lossless: ours for VESSEL_CONSTRUCTION.md, theirs for VESSEL_TAIL_AND_JETS.md. Both verified byte-identical to the side they came from.

Second merge (a2f492665), and this one was substantive. bleeding-edge absorbed the Scarab pass (#821), which improved the same auditor for the same reason from a different direction — so the resolution is a union, not a pick:

• ours measures magnitude — a labelled shape travelling less than the measured threshold (real shapes move 2.46%–17.94% of their mesh diagonal, fake ones 0.0000%) is reported INERT rather than counted;
• theirs handles procedural sources (IProceduralElementMorphSource — the Scarab re-blends baked geometry deltas) and shapes under a hidden legacy model root, which draw nothing.

A shape now counts only if it moves the hull AND is actually drawn; the two inert reasons are disjoint and both apply, and procedural coverage contributes elements on top. Reporting keeps ours' per-shape travel verdict and theirs' distinct "hidden legacy model — never drawn" line, so the two failure modes stay tellable apart. Docs resolved the same way: CLAUDE.md keeps our Dolphin fleet line (theirs predates the swap and still calls the Dolphin shape-less) and gains their Scarab paragraph; the verification checklist keeps both new entries; VESSEL_CONSTRUCTION.md takes their Scarab row and keeps ours' Serpent row, whose dagger anchors a footnote below it.

The merged auditor was compiled against transcribed stubs with two negative controls — a typo in the merged path, and a wrong member name on the procedural interface (8 and 4 errors, restore clean) — since a merge resolution of a C# file that nothing in CI compiles is exactly where a silent syntax error would land.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HVDmUarLeSWQa8kRBnubqw