# Woodland character kit

Original Blender geometry inspired by the supplied cat-traveler reference:
broad cheeks, relaxed almond eyes, whiskers, layered clothing, rolled cuffs,
boots, a scarf, and a travel pack with a bedroll. The reference image is not
embedded in the assets. Player and NPC visuals use this kit in the main game.

## Try and configure

Run `tools/CharacterWorkshop.tscn` in Godot 4.7 (F6), or:

```bash
/Applications/Godot.app/Contents/MacOS/Godot --path "$PWD" tools/CharacterWorkshop.tscn
```

Choose one of six presets, change the parts and proportions, drag the model to
turn it, scroll over the model to zoom, and enable the walking preview. **Save
profile** writes a `CharacterAppearanceProfile` `.tres` to the chosen file.
Assign that resource to `PlayerVisual.appearance` or `NpcVisual.appearance` in
the Inspector. The player defaults to `profiles/reference_cat.tres`. NPCs with
no authored override derive their appearance from their stable simulation ID.
The workshop is a separate authoring scene; it does not modify a game save.

| Control | Available values |
| --- | --- |
| Head and tail | Cat, fox, rabbit, badger, otter |
| Ears | Species default, or any of six ear pairs including lop ears |
| Height | 0.80–1.15 times the base height |
| Body fullness | 0–1 Blender `Stout` shape key |
| Head size / leg length / ear length | 0.88–1.12 / 0.85–1.15 / 0.65–1.20 |
| Clothing | Open vest, long coat, work tunic with apron |
| Arms | Relaxed or holding pack straps |
| Accessories | Scarf, spectacles, beret, brimmed hat, satchel, travel pack |
| Palette | Fur, muzzle, outfit, shirt, scarf, trousers, leather |

The workshop exposes the four main palette colors. All seven channels are
editable on the profile resource. Profession tint remains a separate, subtle
overlay driven by the actual NPC profession.

## Blender source and rebuilding

Open `art/characters/woodland_character_kit.blend`. The visible collection is an
assembled traveler; the hidden library meshes contain the editable building
blocks. Unhide a library object to edit it. Torso and wearable meshes have
`Basis` and `Stout` shape keys. Preview objects are copies of library objects.

```bash
/Applications/Blender.app/Contents/MacOS/Blender --background \
  --python tools/art/build_character_kit.py
/Applications/Godot.app/Contents/MacOS/Godot --headless --editor --path "$PWD" --import
```

The reproducible Blender 5.1 generator rebuilds the source, GLB, and triangle
manifest. Regenerating replaces manual edits to those generated files. Commit
changes to the generator when they should survive a rebuild. Godot only imports
the portable GLB; `.gdignore` excludes the Blender authoring directory.

## Mesh and animation contract

`woodland_parts.glb` contains 31 named parts, each with one opaque surface. The
reference cat uses 10 surfaces and 20,070 base triangles before Godot's generated
LODs. The GLB is approximately 4.6 MiB. `mesh_budget.json` records each part's
triangle count, origin and shape-key support. Accessories are optional; only
selected meshes enter the live scene.

- `AnimalAppearance` caches the imported mesh library once. Characters share
  `ArrayMesh` resources and have their own shader material and blend-shape
  weights. No per-frame mesh rebuilding or CPU deformation is performed.
- Godot Y is up, +Z is forward. The existing body, head, arm, leg and tail node
  paths remain animation sockets. Ear/glasses attachments follow the head;
  scarf and bag attachments follow the torso. `Hair` is the optional hat socket.
- Fullness deforms the torso and worn gear together. Shoulder/hip spacing follows
  it. Leg length raises the upper body while keeping the soles on the ground.
  Gait uses configured rest heights; the hiker pose has restrained arm swing.
- Animation remains the existing rigid-part procedural gait. The kit does not
  add a skeletal animation library, facial rig, cloth simulation, or physics
  bodies. Changes to these appearance controls are cosmetic: collision,
  navigation, interaction reach, authoritative positions, and saves retain
  their existing contracts. Very unusual mixed parts may need art adjustment.
- `UV2.x` stores a discrete palette role (0 fixed vertex paint, 1 fur, 2 muzzle,
  3 outfit, 4 linen, 5 scarf, 6 trousers, 7 leather, 8 fur markings, 9 outfit seams).
  Preserve both UV layers and vertex colors on export. Do not regenerate UV2
  lightmap coordinates. `character_cel.gdshader` supplies soft cel bands with
  no texture sampling, transparency, outline pass, or screen-space effect.

## Verification and review

`tests/character_appearance_test.gd` checks the real imported geometry, palette
roles, independent morph weights, shared meshes, attachment reuse, all six
presets, extreme proportions, stable IDs/RNG isolation, gait rest heights, and
NPC cue clearance. Existing lifecycle scenarios cover profession, inventory,
death, and save/load behavior. Run the full repository quality gate before a
commit.

```bash
./tools/quality.sh
/Applications/Godot.app/Contents/MacOS/Godot --path "$PWD" \
  --rendering-driver metal --script tools/capture_character_kit.gd
/Applications/Godot.app/Contents/MacOS/Godot --path "$PWD" \
  --rendering-method gl_compatibility --script tools/capture_character_kit.gd
/Applications/Godot.app/Contents/MacOS/Godot --path "$PWD" \
  --rendering-driver metal --script tools/capture_character_kit.gd -- --world
```

The `docs/baselines/character_*.png` images are actual Godot renders. They show
the traveler, rear pack detail, preset lineup, workshop and main-world placement.
These local Apple M1 Max checks do not establish a frame-time budget for a
large crowd or a weaker GPU.

The workshop uses filmic tonemapping with a separately calibrated Compatibility
exposure to preserve cream-fabric highlights. This only stages the authoring
preview; the main world retains its existing day/night environment. Metal and
Compatibility images are separate visual reviews, not a pixel-parity claim.
The full Godot 4.7 gate passes 61 scenario runs (including 111 character checks)
and 182 GUT tests / 2,279 assertions. The native workshop controls and profile
export were also exercised directly.