# Kermit Hoverboard: native animated vehicle import

## Delivered item

- Inventory type/id: `9/84`
- Spawn command: `/itemN 9 84 1`
- Name: `Kermit Hoverboard`
- Description: `Someday we'll find it...`
- Vehicle mesh row: `81`
- Icon row: `82` (`m_iIconType=12`, `m_iIconNumber=2083`, loaded as `FFRGui/Icons/Vehicle/vehicle_2083.png`)
- Asset lookup: `vehicle_kermithoverboard`
- Template preserved: FFR Hoverboard `9/77`

The item clones FFR Hoverboard's complete Unity 2 prefab rather than replacing it. That preserves its legacy `Animation` component, hoverboard stance contract, material/toon shader, vehicle sounds, and `tag01`/`tag02` effect anchors. Item effects `1/1` are retained; these are the standard red/orange hover trails.

## Source and rollback

- Source handoff: `D:\Downloadz\Codex_Vehicle_Handoff_Kermit_Flintstones_WhiteSeat_2026-08-10.zip`
- Blender scene: `work\kermit-hoverboard-r42\handoff\Codex_Vehicle_Handoff_Final_WhiteSeat_2026-08-10\Kermit_Hoverboard\Frog_Hoverboard_Concept_Upgrade.blend`
- Work checkpoint: `work\kermit-hoverboard-r42`
- Pre-install rollback: `archive\pre-kermit-hoverboard-r42-20260810-0015`

Restore FFRShared, FFRGui, TableData, manifest, and both server XDT copies together. A partial rollback produces blank inventory entries or invisible vehicles.

## Why the native clone is required

The 2009 client is Unity 2.6-era Mono. It must not depend on Animator, modern particle APIs, runtime FBX/OBJ parsing, or a new managed animation loop. The FFR Hoverboard already contains a working `AnimationClip`, a skinned mesh, an armature, and trail anchors. The importer therefore clones that serialized object graph and replaces only cloned geometry/texture data.

The Kermit source has four independent Blender rotor controls. The prepared OBJ marks five groups: body plus left/right front/rear rotors. The injector expands the native three-bone skin to five bones, derives each pivot from its serialized wheel-group centroid, writes a matching transform/bind-pose pair, and retargets the duplicated legacy position curves. No runtime script is required and vertices remain in authored rest space.

The cloned mesh type stores normals/tangents in `m_TangentSpace`, not `m_Normals`. Always generate one tangent-space row per imported vertex. Because the Blender exporter swaps X/Y and the importer mirrors X, do not reverse triangle order a third time. Preserve the template `tag01`/`tag02` transforms unless a gameplay test demonstrates a vehicle-specific need.

The Kermit atlas reserves its lower 1/8 for flat-material swatches and its upper 7/8 for the original painted texture. Transform painted Blender UVs with `0.125 + v * 0.875`; sample flat swatches at `v = 0.0625`. Do not use `v * 0.875` for painted faces or `v = 0.9375` for swatches.

The final r46 color-match pass also records the UV triangles for
`Hoverboard_Body_Part.002` and `.003` (the two eye meshes). Their UV coverage
has only 0.03 percent overlap with the remaining body, allowing localized pupil
and eye-bulb correction in `build_kermit_atlas.py`. Keep the pod palette in that
script's preparation data: one Unity 2 material replaces Blender's six pod
materials, so the render look must be baked into the lower atlas swatches.

## Rebuild prerequisites

```powershell
$root = 'E:\twitterclonewithcomments\FFRebornTest'
$python = 'C:\Users\Rain\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe'
$blender = 'C:\Program Files\Blender Foundation\Blender 5.2\blender.exe'
$unitypack = 'E:\twitterclonewithcomments\MASTER_WORKSPACE_2026-05-18\fusionfall-academy\tools\unitypackff-lib\UnityPackFF-master'
$env:PYTHONPATH = "$root\work\lich-hat-v0.1\python-deps;$unitypack"
```

UnityPackFF must receive the extracted inner `CustomAssetBundle-*`, never the outer `.resourceFile` wrapper.

## Step-by-step rebuild

1. Extract `FFRShared.resourceFile`, `FFRGui.resourceFile`, and `TableData.resourceFile` with `tools\disunityff\disunity.bat bundle-extract`.
2. Inspect the FFR Hoverboard record (`m_pVehicleItemTable` item 77), prefab container `vehicle_ffrhoverboard`, native mesh, skin, clip, and `tag01/tag02`. Do not modify item 77.
3. Prepare the Blender model:

```powershell
$env:KERMIT_BLEND = '<handoff>\Frog_Hoverboard_Concept_Upgrade.blend'
$env:KERMIT_OUT = "$root\work\kermit-hoverboard-r42\prepared"
& $blender -b --python "$root\tools\kermit-hoverboard\prepare_kermit_hoverboard_blender.py"
& $python "$root\tools\kermit-hoverboard\build_kermit_atlas.py" `
  --report "$env:KERMIT_OUT\prepare-report.json" `
  --source "$env:KERMIT_OUT\kermit-source.png" `
  --output "$env:KERMIT_OUT\vehicle_kermithoverboard.png"
```

The preparation script excludes authoring-only inverse hull duplicates, maps Blender long-X/lateral-Y/up-Z to FusionFall Y/X/Z, applies one uniform scale against FFR Hoverboard's native length, preserves UVs, builds flat-material atlas swatches, and emits named rotor groups. The current result is 29,928 serialized vertices and 57,159 triangles, below the legacy 16-bit vertex limit.

4. Inject the cloned animated prefab:

```powershell
& $python "$root\tools\kermit-hoverboard\inject_kermit_hoverboard_bundle.py" `
  --input-bundle <extracted-FFRShared-inner> `
  --output-bundle "$root\work\kermit-hoverboard-r42\FFRShared-kermit-inner" `
  --mesh "$env:KERMIT_OUT\vehicle_kermithoverboard.obj" `
  --texture "$env:KERMIT_OUT\vehicle_kermithoverboard.png"
```

5. Render the icon at 512, crop/downsample to 64, and inject it into the vehicle-icon bundle as DXT5:

```powershell
$env:KERMIT_ICON_512 = "$env:KERMIT_OUT\kermit-hoverboard-icon-512.png"
& $blender -b --python "$root\tools\kermit-hoverboard\render_kermit_hoverboard_icon_blender.py"
& $python "$root\tools\kermit-hoverboard\make_icon_64.py" `
  $env:KERMIT_ICON_512 "$env:KERMIT_OUT\kermit-hoverboard-icon-64.png"
& $python "$root\tools\kermit-hoverboard\inject_kermit_hoverboard_icon.py" `
  --input-bundle <extracted-FFRGui-inner> --output-bundle <patched-FFRGui-inner> `
  --icon "$env:KERMIT_OUT\kermit-hoverboard-icon-64.png"
```

6. Patch both server XDT copies, then embed the exact runtime XDT in FFRShared:

```powershell
& $python "$root\tools\kermit-hoverboard\patch_kermit_hoverboard_xdt.py" `
  "$root\server\openfusion-reborn\tdata\xdt.json" `
  "$root\runtime\server\tdata\xdt.json"
& $python "$root\tools\kermit-hoverboard\replace_ffrshared_xdt.py" `
  --input-bundle <Kermit-FFRShared-inner> --output-bundle <Kermit-XDT-FFRShared-inner> `
  --xdt "$root\runtime\server\tdata\xdt.json"
```

7. Merge standard tables into native TableData:

```powershell
& $python "$root\tools\Patch-RedemptionClientTables.py" `
  <extracted-TableData-inner> "$root\runtime\server\tdata\xdt.json" <patched-TableData-inner>
```

8. Replace the three extracted inner files, run `bundle-inject` on their outer resource files, and update manifest byte sizes with `tools\kermit-hoverboard\update_manifest.py`.
9. Extract the rebuilt wrappers again and run:

```powershell
& $python "$root\tools\kermit-hoverboard\verify_kermit_hoverboard.py" `
  --ffrshared <final-FFRShared-inner> --ffrgui <final-FFRGui-inner> `
  --tabledata <final-TableData-inner> --server-xdt "$root\runtime\server\tdata\xdt.json"
```

The verifier fails closed on item resolution, icon format, vertex/skin counts, five bind poses, four rotor curve paths, effect values, and embedded/server XDT equality.

## Acceptance boundary

Structural extraction/reload is proven. Fresh-cache gameplay remains the visual acceptance test for player stance, scale, all four wheel pivots, and trails. Use `/itemN 9 84 1`, activate the vehicle, check both player body types, rotate the camera, move/stop/jump, and confirm item 77 still behaves unchanged.

## Reusing this workflow

Clone a vehicle whose stance and effect contract match the new model; preserve the original; export named movable groups; keep the combined mesh under 65,535 vertices; reuse legacy Animation curves/bones rather than managed animation; append item/string/mesh/icon records; synchronize FFRShared/native TableData/server XDT; repack wrappers; update manifest sizes; re-extract and verify before gameplay QA.