jeremy
4d6a4f6006
tools/export_boat_prop.py (GLM-implemented, 2 rounds): hull at game scale (8.5 m, keel 0, no recenter) + placeholder mast/sail/steering oar + 5 seat markers + waterline + 1.9 m ref figure; self-verify incl. right-side-up gates added after round 1 shipped an upside-down hull with all checks green. Registry: boat actions table (6 slots, direct names). README carries CC BY 4.0 attribution + iClone import/filming notes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
112 lines
6.4 KiB
Markdown
112 lines
6.4 KiB
Markdown
# 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.
|