# Boat staging prop — `boat_prop.fbx`

A single static FBX of the ariki-game expedition canoe, rebuilt exactly as
`ariki-game/src/Viewer/BoatRenderer.cs` assembles it at runtime, for **staging boat-
interaction character animations in iClone 8**. Built by
`tools/export_boat_prop.py` (Blender 5.1.2 headless) from
`ariki-game/assets/models/glbs/Boat__PolynesianCanoe_hull.glb`.

- **Frame:** metres, Z-up, bow = −Y, keel at Z = 0. (Game frame is Y-up, bow = +Z; the
  tool converts via g2b `(x,y,z) → (x,−z,y)`.)
- **Scale:** 8.5 m long (`BoatLength`), exported with FBX unit scale = cm → iClone reads
  it as an **~850 cm** prop with all local scales 1.0.
- **Generate / re-verify:**
  `"$BLENDER" --background --python tools/export_boat_prop.py --`
  (re-runs the export and its built-in self-verify, which must exit 0.)

## Attribution

The hull mesh is the **Polynesian Canoe** by **DITCH.WAV**, licensed **CC BY 4.0**.

- Source: https://sketchfab.com/3d-models/polynesian-canoe-fb4379ba486c43bd846f9b9ef608743a
- Author: DITCH.WAV — https://sketchfab.com/DITCH.WAV
- License: CC BY 4.0 — https://creativecommons.org/licenses/by/4.0/

**Modifications made** (required to be noted under CC BY 4.0):

- The game project already removed the baked crab-claw **sail** from the hull GLB
  (`Boat__PolynesianCanoe_hull.glb` — the `_hull` variant); the carved hull, ama outrigger,
  and iako booms are unchanged.
- Rescaled uniformly ×8.5 to the game's `BoatLength` (8.5 m) and re-oriented so the bow
  runs along the game's +Z (Blender −Y), keel at the waterline.
- **Staging markers and placeholder rigging added** for iClone authoring only — these are
  NOT part of the licensed asset: 5 seat-marker spheres, a mast/boom/sail placeholder, a
  steering-oar placeholder, a waterline outline, and a 1.9 m reference figure. Flat-color
  materials (no textures) on the added parts; the hull retains its original embedded jpg.

Credit is also given in ariki-game's in-game credits screen and root `ATTRIBUTIONS.md`.

## Contents legend

Every named node in the FBX (positions in **game coords** — Y-up, bow +Z — for reference;
in the FBX itself they are in Blender Z-up / bow −Y):

| Node | What it is | Game pos (x, y, z) m |
|---|---|---|
| `Boat_ArikiCanoe` | The hull mesh (carved canoe + baked ama + iako booms), scaled ×8.5, keel at Z=0. The textured part. | keel at y=0, bow at z=±4.25 |
| `Mast` | Mast cylinder, radius 0.055, height 4.2 m, centred on the keel at the sail pivot. | (0, deckTop, 0) |
| `Sail` | Crab-claw sail **placeholder** (silhouette, not accuracy). Foot 2.1 m spreading to **−X** (port), height 3.8 m. | foot at (0, deckTop+0.45, −0.10) |
| `Boom` | Boom spar along X, radius 0.045, length 2.205 m. | centred (−1.05, deckTop+0.45, −0.10) |
| `SteeringOar` | Hoe uli (steering oar) placeholder — tapered shaft + blade, raked aft, at the stern starboard oarlock. | pivot (0.384, 0.75, −3.655) |
| `Seat_Navigator` | Bow seat (4 cm marker). Navigator stands/drives here. | (0, 0.75, +2.55) |
| `Seat_Lookout` | Mast-top lookout post. | (0, 4.00, −0.20) |
| `Seat_Fisher` | Port-side seat beside the **ama** outrigger (−X). | (−1.50, 0.65, 0) |
| `Seat_Rest` | Stern rest seat. | (0, 0.75, −2.975) |
| `Seat_Helm` | Stern helm by the steering oar — where the pilot stands. | (0.072, 0.50, −2.72) |
| `Waterline_Fwd/Aft/Stbd/Port` | Four thin edges forming a **10 × 7 m open rectangle** at the still-water surface (Z = −0.06 m). Not a filled plane. | z = −0.06 |
| `RefFigure_190cm` (+ `_Head`) | 1.9 m capsule reference figure (Ø0.35) standing on `Seat_Helm`, feet at the marker. Scale/height check. | feet at Seat_Helm |

`deckTop` = 0.40 m (computed from the measured hull height as `max(0.12 × height, 0.40)`).
The ama (outrigger) is baked into the hull on the **port** side (−X), where `Seat_Fisher`
sits — verified by the hull's centre-of-mass offset.

## iClone import

1. Drag `boat_prop.fbx` into iClone as a **Prop** (Content Manager → drag, or
   File → Import).
2. In the **Modify** panel, confirm the prop length is **≈ 850 cm** (8.5 m). If iClone
   shows ~8.5 cm or ~85 m, the FBX unit preset on import is wrong — re-import with the
   unit set to **centimeters**.
3. Drop a CC avatar next to the prop and confirm **`RefFigure_190cm` stands head-high**
   beside it (~1.9 m). This is your scale ground-truth.
4. The seat markers (`Seat_*`) are **snap targets** — move/parent hands, feet, hips, and
   props to them when blocking poses.
5. When rendering/previewing, **hide `RefFigure_190cm` and the `Waterline_*`** edges
   (they're staging guides, not part of the scene). The flat-colored placeholder rigging
   (Mast/Sail/Boom/SteeringOar) is a stand-in — hide or replace it once you have the real
   rigging; it exists only so blocking reads correctly.

## Filming / authoring notes (per animation)

Jeremy films everything with **Video Mocap**; these notes flag what's filmable vs. what
needs hand-keying or an ActorCore fallback:

- **Fishing loop** — at `Seat_Fisher` (seated, port side by the ama). Filmable: a stick
  as the fishing-rod prop. Snap the seated pose onto the marker.
- **Row / steer loop** — at `Seat_Helm` (stern). Use a broomstick mimicking the stern
  oar's **±18°** sweep (the game sweeps `4° + effort×14°`, max ±18° under throttle). Film
  the sweep, then snap the hands to Reach targets on `SteeringOar`/`Seat_Helm` in cleanup.
- **Collect-flotsam** — kneel/lean over the gunwale (port side). Keep the hands
  unoccluded in frame (Video Mocap loses occluded joints). Filmable.
- **Climb-aboard** — film over a **~0.65 m box/table proxy** (the gunwale height). Expect
  **heavy Reach-target cleanup**; likely a **hand-key fallback** for the final pull-up.
- **Dive-off** — **airborne motion breaks Video Mocap** (no ground contact, feet leave
  frame). Film only the **takeoff crouch + spring** and the hand-finish; get the airborne
  arc from an **ActorCore dive**, or hand-key it.
- **Sailing sway loops** — gentle stand/brace sway at a seat. **Filmable.** Static bracing
  poses are hand-posed against the mast/boom.

## Per-take iClone export reminder

For every clip you send back through the animation pipeline:

- **Format:** FBX
- **Target Tool Preset:** Blender
- **Frame rate:** 60 fps
- **Range:** All
- **Include Motion:** ON (a 2-frame `*TempMotion` take means motion was NOT exported —
  re-export with this checked)
- **Preserve Bone Names (CC Base):** ON

Then retarget with `tools/cc_retarget.py` as usual.