# v2: characters, bodies and animation

One body system for players, peds and police: skeleton, body, face, clothing, the bake, the
ragdoll, animation, data, safety and the asset and licence rules. Index:
`agents/world-format-v2.md`. Schema: `agents/v2-formats.md` section 12 (wear, body, outfit,
look, approvals). Brief: `agents/v2-i-characters.md`. Built: characters milestone (goal 10) in
`v2/build/characters/` and `v2/sim/characters/`.

Replaces v1's 22-box, 11-bone `person.js` and its separate 14-joint verlet `ragdoll.js`. The
target is gmod/Euphoria-level bodies, not canned stiff animation.

## Animation
- **Kinematic base from motion matching:** pick the best frame from a mocap database each tick
  instead of hand-built state machines.
- **Physics on top (active ragdoll):** the character is a physics body following the animation
  with balance. Getting shot, clipped by a car or hitting a kerb pushes it; it stumbles,
  recovers or falls, and ragdolls when it can't. First step: PD joint controllers on Rapier
  joint motors with hand-tuned balance (as ashleve/ActiveRagdoll does; no ML needed).
- **ML controllers** (DeepMimic / AMP family, trained offline, small networks in the browser)
  are a stretch goal. No one has published browser inference numbers for AMP/ASE policies;
  PFNN (a few MB, milliseconds) is the only hard data point.
- **Balance on moving platforms:** the ragdoll reads its support's acceleration, so standing
  in a van, a Metro or a boat makes the body lean, brace, step and grab; hard braking throws
  you forward; a sharp corner can put you on the floor.
- Hit reactions are per-bone (Source hitboxes): a leg shot changes how you move.
- NPC animation tiers and the per-client ragdoll cap: `npcs.md`.

## Skeleton, body, face
- **One skeleton:** VRM 1.0 humanoid bone names (open spec; three-vrm is MIT) on MPFB2's
  `game_engine` rig topology. Retarget maps (Mixamo, Rocketbox, CMU) are data tables. Fingers
  are optional bones that LOD drops. One transform format everywhere (position + unit
  quaternion, float32), shared with the snapshot.
- **Body:** MakeHuman/MPFB2 base mesh and targets (assets CC0; the GPLv3 code is never shipped),
  glTF with a few morphs (masc/fem, weight, muscle, proportions); height by bone scale. Base
  layer (underwear, vest) baked into the skin material, not removable, enforced in the shader.
  **Adult bodies only (decided 2026-09-27).**
- **Face:** separate head mesh; ARKit 52 as the master expression set; Oculus 15 visemes and
  VRM's 5 vowels derived by mapping tables; face presets plus a few sliders.
- **Face in motion:** Rhubarb Lip Sync (MIT) in **phonetic** mode for recorded lines (Geordie
  vowels won't match an American dictionary), viseme tracks stored on the voice-line entry;
  wawa-lipsync or TalkingHead HeadAudio (MIT) for live audio; look-at via eye bones and
  head/neck IK toward targets fired as events (`OnLoudNoise`, nearest player, threat).

## Clothing
- **Slots:** hair, hat, face, top_inner, top_outer, hands, legs, feet, back, accessory[n]. Each
  item is a skinned glTF on the canonical skeleton carrying the body's shape morphs
  (transferred offline: Roblox's cage idea done at build time).
- **No clipping, three ways:** (1) hide masks: the body is split into ~16 regions and items
  declare `hides: [...]`, discarded in the shader; (2) layer index 0-5 with build-time push-out
  outside the layer beneath, tested at shape extremes and a pose set; (3) outer items declare
  `occludes: [...]` to cull inner garments.
- **Variety without meshes:** three tint channels into a shared palette, one pattern slot from
  an approved library, wear/dirt parameters from systems (`wet`, `dirt`, `burnt`).
- **Data (principle 7):** `wear/...` entries carry slot, layer, hides, occludes, LODs, morphs,
  tints, pattern, and `mass, insulation, waterproof, flammability`, optional `armour`,
  `hi_vis`. Systems read the numbers without knowing clothing exists: a T-shirt on the Quayside
  in January makes you shiver; police AI reads `hi_vis` and masks. Moderation state lives
  outside the item, in the hub's approvals list (formats v1.2).
- **The `look` record:** `body` and `outfit` components form a hashed `look` (~90 bytes
  typical, 160 max); only that is networked; packages fetched content-addressed; unknown ids
  fall back to slot defaults; the server checks ids against the lockfile and moderation state.
  Orchestrator decision (delegated; taken in the characters build, logged in the formats; challenge
  if wrong): the look record hashes wire-rounded values.
- **Mods** add `modid:wear/...` packages, validated automatically: skeleton match, <= 4
  influences per vertex, per-slot budgets, a clipping render test, the moderation gate.

## Bake, tiers and ragdoll
- **Per-character bake:** on outfit change a worker applies morphs, joins all items into one
  skinned mesh, drops culled triangles and packs a texture array: ~2 draw calls a person
  (built: one material, 1 draw per LOD). Proposed LODs ~15k / 5k / 1.5k triangles, to be set
  by the harness.
- **By tier:** near = full mesh, face morphs, active ragdoll; mid = GPU-skinned (three r186 TSL
  skinning), kinematic, promoted on contact; far = skinned instancing (three.ez
  instanced-mesh) or VAT from 8-16 outfit variants per district.
- **Same body drives the ragdoll:** ~15 capsules/boxes fitted per bone to the baked body (a
  heavier body gets fatter capsules), mass from volume x density, joint limits from the
  skeleton, motion-matching output as PD targets, hitbox groups for per-bone damage; clothing
  adds colliders only with an `armour` component.
- **Limb detach is a world rule** (decided 2026-09-27): on in the 18-rated canonical world, off
  in 12-rated worlds (`platform-and-community.md`).
- **Measured (goal 10, 2026-09-27):** MPFB2 CC0 assets only (own reader, no MPFB2 code),
  young-adult targets only, 53-bone VRM 1.0 skeleton. Example ped (1.78 m, tee, jeans,
  trainers): LOD0 27,406 triangles (10,656 body triangles hidden), LOD1 4,999; bake 1.5-2.5 s
  headless. Ragdoll 16 segments / 15 joints, 68.8 kg from body volume; dropped and pushed it
  settles in ~2.3 s with 8 solver iterations (not at 4). Every morph-cube corner is 6.85-7.55
  heads tall. **Placeholders:** skin-tight garment shells (no drape), bald, no face morphs, LOD0
  at 27k against the proposed 15k, no PD motors yet. Turntable
  `v2/build/characters/ref/turntable.png`.

## Asset generation
Whole-character generators are out (fused triangle soup, no layers). Garments: GarmentCode
(MIT) sewing patterns, draped on the base body (stock Warp, not NVIDIA's non-commercial fork),
remeshed, Robust Skin Weights Transfer (MIT), morph transfer, validator. StdGEN (Apache-2.0)
for concept-to-layers; FLUX.1 schnell (Apache-2.0; dev is non-commercial) or MV-Adapter for
fabric patterns; UniRig / MagicArticulate for non-humanoid rigs.

## Safety
Shared and canonical worlds show only approved items; patterns and decals from curated
libraries; clothing text in our font through a word filter. Uploaded textures stay
personal/private until an NSFW classifier passes both the texture and a turntable render of the
dressed body, plus OCR for slurs, logos and extremist symbols, then the proposed-layer queue.
Under-18 viewers, and everyone in canonical, see unapproved items on others as slot defaults.
No photo-to-face for anyone.

## Motion data and licences
- **Use:** 100STYLE (CC BY 4.0); CMU mocap (commercial use OK, never resold, even converted: a
  free mod SDK is probably fine; legal read is an owner task); orangeduck/Motion-Matching (MIT)
  as the algorithm reference with its LAFAN1 data swapped out; DeepMimic, MimicKit,
  ProtoMotions for balance and recovery training.
- **Never use:** LAFAN1 and ZEGGS (CC BY-NC-ND), Bandai Namco motion (NC), AMASS / HumanML3D /
  Motion-X / BEDLAM and anything **SMPL/SMPL-X** (non-commercial; rules out WHAM, 4D-Humans,
  GVHMR output), ASE/AMP checkpoints (NVIDIA NC), MB-Lab (AGPL taints exports), Wav2Lip,
  RigAnything, Hunyuan3D, nvdiffrast, VRoid meshes in a character maker, Ready Player Me
  (reportedly shut down Jan 2026).
- **Quaternius: use it (decided 2026-09-27).** The Quaternius Asset License v1.0 (28 Aug 2026,
  checked at quaternius.com) allows free use in personal, educational and commercial games, no
  credit required, but **forbids redistributing the assets themselves as assets** (its FAQ
  still says CC0; the QAL governs). So Quaternius models ship only inside the official `ncl`
  content, never in a separately downloadable mod-hub pack and never exportable from the forge
  as raw files. Stylised low-poly: placeholders until the catalogue replaces them, tagged in
  `prov`.