feat(characters): add modular woodland traveler kit
This commit is contained in:
Rijad Zuzo
@@ -0,0 +1,116 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user