# Pocket humanoid v1 / humanoid-1

The actual reference model is `assets/explorer.glb`. Rebuild the body, all eight cosmetics and eight clips with `npm run assets`. Editable procedural source is `scripts/assets.ts`; no proprietary authoring tool or downloaded geometry is required. `assets/rig-profile.json` is the machine-readable reference. `assets/LICENSE.md` covers all sample geometry, animations and source under CC0-1.0. Signal Studio is a fictional contributor recorded separately in `contributions/signal-studio/manifest.json`.

## Coordinates, hierarchy and bind pose

Units are metres, +Y up, +Z avatar forward, +X the avatar's left when viewed face-on. The gameplay/presentation root has identity scale and is separate from the animated bones. Every joint has identity quaternion and unit scale in the rest pose. Bone positions below are relative to the parent. Exported inverse bind matrices are the inverses of their accumulated rest-pose world matrices.

| Joint    | Parent    | Local translation | Humanoid semantic |
| -------- | --------- | ----------------- | ----------------- |
| Hips     | Mesh root | 0, 0.90, 0        | hips              |
| Spine    | Hips      | 0, 0.45, 0        | spine             |
| Head     | Spine     | 0, 0.45, 0        | head              |
| LeftArm  | Spine     | -0.45, 0.21, 0    | leftUpperArm      |
| RightArm | Spine     | 0.45, 0.21, 0     | rightUpperArm     |
| LeftLeg  | Hips      | -0.18, -0.05, 0   | leftUpperLeg      |
| RightLeg | Hips      | 0.18, -0.05, 0    | rightUpperLeg     |

This seven-joint stylized rig has no elbows, knees, fingers, expressions or eye bones. The semantics provide an explicit future mapping; this asset is not claimed to be a complete VRM model or a general retargeting system. The semantic left/right labels preserve the original v0.1 joint names and coordinates. A future VRM conversion must explicitly resolve handed anatomical naming rather than silently reinterpret this version. [VRM Animation](https://vrm.dev/en/vrma/) describes broader humanoid, expression and gaze channels deferred here.

Rigid cosmetics are modelled in local `Head` or `Spine` socket coordinates. Composition applies the socket's rest matrix and assigns its joint weight. Four mutually exclusive slots are supported: head, face, back and upper-body. Trail jacket is a genuine skinned mesh using Spine, LeftArm and RightArm; its shoulder vertices blend arm/spine weights. Its joint names and inverse bind matrices must match the reference within 0.001. No animation can move the gameplay root.

## Coverage, materials and budgets

The body exports `_BODYREGION` (loaded as `_bodyregion`), with 1 marking the torso and 0 all other regions. An upper-body garment declaring `coverage: ["torso"]` removes the 48 torso triangles whose three vertices have region 1. The mask is removed before geometry assembly. Garment cuffs cover the reference sleeves; hands, hips, legs and head remain visible. Only this torso hide policy is supported; arbitrary layering and body shapes are deferred. Removing the garment restores the original body source. Shared source geometry is never edited.

The current composition profile supports one opaque, rough, vertex-colour material without textures, morph targets or shader extensions. This intentionally rejects unsupported material features; it does not discard an imported texture and then claim a small texture budget. The creator validator must report decoded texture dimensions/mipmapped memory before incompatibility rejection. The full outfit limits remain 10,000 triangles, 2 measured colour-pass calls, 2 rendered materials, 1024-pixel textures, 8 MiB texture runtime storage including mipmaps, 64 joints and 4 influences per vertex.

Composition merges the body and equipped parts into one SkinnedMesh and one material. `measureAvatar` renders that actual mesh into a 64×64 target with no scenery, shadow pass or postprocessing; it reads Three.js render calls/triangles after drawing. The budget says unmeasured until this render occurs. This verifies the primary pass, not a frame-rate guarantee or total shadow-pass cost. The largest legal sample combination and all clips are exercised in `tests/avatar.test.ts`; browser wardrobe tests check actual submitted calls and coverage. The isolated draw is distinct from the later 16-visible-avatar graphics workload.

## Animation and lifetime

The rendering report also includes the generated skinning palette texture: the seven-joint sample currently uses 1,024 bytes of RGBA32F data without mipmaps. Authored image texture storage is zero for this profile. These format/array storage calculations are separate from Three.js geometry/texture object counters and do not claim exact driver allocation sizes.

Stable IDs: idle (3s loop), walk (1s loop), run (0.65s loop), jump (0.6s pose sequence), fall (0.6s held pose), land (0.2s recovery), wave (2.4s one-shot), dance (4s one-shot). All clips contain only approved bone quaternion tracks. Translation/scale tracks, including Hips root motion, are rejected. Server locomotion selects the local pose; server emote start/end times allow remote playback to start at the correct age. Locomotion blends for 0.16s. Dance stops on locomotion; wave can accompany movement. There are at most three running actions: current locomotion, one fading locomotion, one emote. Previous fading actions are stopped before another transition starts.

SkeletonUtils clones bones and skeletons for every instance. Composed geometry, chosen colours, material and mixer are private to that instance. The source-asset cache deduplicates loads and retains at most 16 templates with inactive LRU eviction. Cache templates never acquire per-avatar colours or playback state. Disposal releases each instance's geometry, material, skeleton/bone texture, mixer and label. Removing an Object3D alone is insufficient; see [Three.js disposal](https://threejs.org/manual/en/how-to-dispose-of-objects.html).

Request generations prevent a delayed outfit load from replacing a newer selection, both in world presentation and the preview. Failures use the player's colour and identity label, with explicit error/fallback state; they do not assert an ownership loss. Avatars beyond 24 metres use the same cheap capsule representation. Canonical revisions and try-on states are separate: previews load approved public assets but never write ownership or send room appearance packets.