high-end-character-and-horse

High-End Character & Horse Systems

Characters are where browser 3D games most often fall apart: the mesh looks fine in isolation, then draw calls triple, materials clone per NPC, mount alignment drifts, and the selection scene leaks memory into gameplay. This skill is the order of operations that avoids that. Engine discipline (headless simulation, fixed-step loop, no gameplay value in React state) comes from build-3d-game and is not repeated.

Non-negotiables

Ranked by how often violating them wrecks a build.

1. Freeze the rig contract before anything else. One skeleton per species, frozen bone and socket names, deformation bones only in the export. Every archetype, body type, and outfit shares it: that is what lets one animation library serve all of them. Changing it later is a migration, not an edit.
2. Variation is uniforms, masks, and atlas indices, not texture sets. One texture set per variant ends the project on memory.
3. Four materials per character, three per horse. Merge at author time anything not independently swapped.
4. In-place clips, code-driven translation. Every locomotion clip carries an authored groundSpeed; playback rate = actual / authored, clamped to ±25%; outside the clamp the state changes rather than the clip stretching. Paired mount/dismount clips are the only root-motion exception.
5. Footfall correctness is not negotiable for quadrupeds. Correct beat patterns per gait, phase-gated transitions. Details in references/animation-and-ik.md.
6. Hoof and foot IK reads a heightfield, not the scene graph. Analytic two-bone solvers with hard limits, distance-banded update rate, off at LOD2+. Details in references/animation-and-ik.md.
7. Sockets carry alignment; runtime carries none. If a prop or rider sits wrong, the authored origin is wrong. Never accumulate per-outfit runtime offsets.
8. The client never decides appearance validity. Client-side validation is UX only. The server re-validates presets, enabled state, archetype compatibility, counts, review gates, and name policy, and takes ownership from the auth context, never from request data.
9. Ref-count parts by asset hash; hand over, don't free-and-refetch. Release at zero references, not on component unmount. Selected bundles transfer into gameplay with counts intact.
10. Precompile every visible material variant before the loading screen closes. A stall after loading is a bug.
11. Culturally specific content is review-gated in the build, not in a reminder. A requires_review asset with no cleared log entry fails the build.
12. Screenshot the review scene or it does not work. Art is not accepted until it passes its scene.

Memoization gate

useMemo / useCallback / memo are disallowed in character code by default. Before proposing one, state which state changes, which computation or identity that invalidates, and which invariant makes the invalidation structurally required. Vague answers mean the state graph is wrong, not the caching. Selection UI is the one place React legitimately owns state, and even there the preview scene is imperative.

Order of operations

1. Archetypes and framing first. About five distinct silhouettes with narrative reasons to exist. Decide cultural framing before any art is briefed: retrofitting a review gate is worse than designing around it.
2. Freeze both rig contracts (human, quadruped) with sockets and LOD bone subsets. Engineering sign-off. Everything else depends on this.
3. Part split and material plan. Split only what is independently swapped. Write the draw-call and material budget down before modeling.
4. LOD ladder with bone step-down, distance-banded with hysteresis.
5. Build systems against CC0 stand-ins so authored assets drop into a working pipeline instead of blocking every workstream.
6. Animation state machines with layers, explicit transition times, interrupt precedence, and event markers driving gameplay effects. Never bind an effect to clip completion: a blend-out silently skips it.
7. Locomotion model before controls. Intent to speed to gait to clip; turn radius is an output.
8. Rider sync: parent at a saddle socket, IK hands and feet to rein and stirrup sockets, alignment baked into paired clips.
9. Persistence relational, not a blob. Identity is queried, validated, version-migrated; volatile checkpoint data stays in the save JSON. Every mutating call idempotent.
10. Selection UX last in build order, first in perceived quality. Preload, draft recovery, keyboard path, reduced motion, clean handover.
11. Measure, then optimize. Report 1% lows. Teardown growth across three cycles is a leak and fails outright.

Original-IP and honesty rules

Inspiration from silhouette language and camera work of major games is fine; copying characters, outfits, tack, coats, animations, UI, or names is not. Textile motifs are geometric and original, never derived from a cultural pattern. Mark targets as targets: a budget from a calculation is not a measurement. Never report a number without device and date, never report a check as run unless it ran, and say plainly when no acceptable open asset exists rather than shipping a stand-in as final.

Good vs bad

Bad: add a second texture set for the black coat variant, ship it, then add four more coats the same way. Texture memory quadruples and mobile dies.

Good: one coat texture with mask channels; coat color, markings, and wear are uniform writes and atlas indices. Five coats cost near zero extra memory.

Verification

Run the review scene for each asset: slope IK on a test ramp, slow-motion footfall pass, mount/dismount cycle, LOD ladder walk-back, material count overlay, then three selection-to-gameplay teardown cycles. Expect correct beat order per gait, zero rider drift, material counts at or under budget, and flat memory across the three cycles. If memory grows, the disposal registry or ref-counting is broken: fix before accepting any more art.

Completion checklist

• [ ] Both rig contracts frozen with named sockets and LOD bone subsets
• [ ] Material and draw-call budget written down and met per LOD
• [ ] No per-variant texture sets; variation via masks, uniforms, atlas indices
• [ ] Clips in-place with authored groundSpeed; rate clamp respected
• [ ] Footfall order verified frame by frame; hoof IK limited, banded, off at LOD2+
• [ ] Rider never floats, slides, or detaches across every gait, jump, and stop
• [ ] Effects bound to event markers, not clip completion
• [ ] Server re-validates every preset, count, and review gate; ownership from auth context
• [ ] Every mutating persistence call idempotent
• [ ] Parts ref-counted; handover keeps counts intact; precompile leaves zero stalls
• [ ] Three selection/gameplay cycles show flat memory
• [ ] Keyboard path complete; reduced motion honored
• [ ] No requires_review asset without a cleared consultation entry
• [ ] Review-scene screenshots captured; console clean

Any box unchecked: not done. Fix or say so.

Footguns

• Editing the rig after content exists. Every clip and outfit breaks at once. Fix: freeze the contract with sign-off, treat any change as a versioned migration.
• Effects bound to clip completion. Interrupted blends skip the effect silently. Fix: event markers on the timeline.
• Freeing parts on component unmount. Selection-to-gameplay handover refetches everything. Fix: ref-count by asset hash, release at zero.
• Trusting client appearance payloads. A modified request equips review-gated or disabled content. Fix: server re-validates everything, ownership from auth context.

Red flags

Stop if you catch yourself saying:

• "We can adjust the skeleton later"
• "One extra material won't matter"
• "The rider looks attached enough"
• "Client validation already covers it"
• "Memory probably settles after a while"

Each of these is how character systems die by a thousand cuts. The budgets and contracts are hard limits, not opening bids.