Rijad Zuzo
117 lines
6.1 KiB
Markdown
117 lines
6.1 KiB
Markdown
# 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.
|