239 lines
14 KiB
Markdown
239 lines
14 KiB
Markdown
# Blender asset library
|
||
|
||
Architecture context: the asset contracts and fallback path are summarized in
|
||
[`architecture.md`](architecture.md#content-and-asset-pipeline-architecture).
|
||
|
||
Status: built, audited, and integrated (2026-11-01). `NpcAvatar` selects the
|
||
character variants and attaches the gear; `WorldBuilder` loads the prop library
|
||
with colliders and phase-driven emissives. The 0.9.4 neutral baseline and its
|
||
acceptance criteria are in [`npc-visual-review.md`](npc-visual-review.md);
|
||
the committed 8 × 6 contact sheet is
|
||
[`blender_previews/sheet_npc_baseline.jpg`](blender_previews/sheet_npc_baseline.jpg).
|
||
|
||
Generator: [`tools/blender_assets.py`](../tools/blender_assets.py). Manifest (the
|
||
source of truth for integration):
|
||
[`assets/models/blender/manifest.json`](../assets/models/blender/manifest.json).
|
||
|
||
## Art direction
|
||
|
||
The references were the AI mockups in `docs/screens/designs/` and the current
|
||
captures in `docs/screenshots/`.
|
||
|
||
- **People** (`targeting_npc`, `joke_shop_queue`, `studio_arrival`,
|
||
`crowd_panic`, `responder_arrival`): ordinary adults in sweaters, jackets,
|
||
long coats and hoodies; a security guard in a dark uniform with a cap
|
||
and belt; a firefighter in a dark turnout coat with yellow reflective bands,
|
||
a helmet and an SCBA tank. The current skinned `npc_base` is a set of boxes
|
||
and cylinders with a flat face, so silhouette was the main gap.
|
||
- **Props** (`prop_gallery`, `venue_overview`, `late_night_avenue`,
|
||
`joke_shop_queue`): the gallery mockup has an octagonal tapered bollard, a
|
||
slatted bench with thin metal legs, an octagonal green litter bin with a slot
|
||
and recessed panels, a stone planter with a lumpy shrub, a blue news box with
|
||
a window and a slanted top, and a hydrant with caps and nozzles. The venue
|
||
shots add ornate street lamps, palm trees, round stone pots with topiary, a
|
||
chalkboard A-frame sign, a wall lantern, a bulb-lit marquee, glazed double
|
||
doors, stair handrails and a dark sedan. Today's in-game props are primitive
|
||
boxes, and the trees are cones.
|
||
|
||
## Frozen fallback boundary
|
||
|
||
`assets/models/npc/npc_base.blend` is the tracked, frozen plain-primitive
|
||
fallback. Prototype head/face/hand detail from the local part pipeline must not
|
||
be saved into it; a separate contract decision (ADR or owner sign-off) is
|
||
required before any prototype detail is absorbed. Working scenes live under
|
||
`tmp/npc-parts/` (gitignored) and are exported as local GLBs for review, never
|
||
directly over the tracked `.blend`. The same rule already appears in
|
||
[`asset-tooling.md#recommended-part-workflow`](asset-tooling.md#recommended-part-workflow).
|
||
|
||
## Local part pipeline
|
||
|
||
The overhaul uses `tools/npc_parts.py` to build, extract, assemble, inspect and sheet the
|
||
reusable head/face and hand parts before they are rolled into the 12 characters. It reuses the
|
||
`blender_assets.py` builders (no second face/hand implementation) and stays local-only/headless.
|
||
Part sources and preview GLBs live under `tmp/npc-parts/<variant>/`; they are **not shipped
|
||
assets** — only the assembled character GLBs, AO/maps, the manifest and the review sheets are
|
||
committed.
|
||
|
||
```bash
|
||
# Build one part fresh from the current builders (head|face|hand_l|hand_r)
|
||
flatpak run org.blender.Blender --background \
|
||
--python "$PWD/tools/npc_parts.py" -- build --part face --variant npc_casual \
|
||
--out "$PWD/tmp/npc-parts/npc_casual/face.glb"
|
||
# Pull the current shipped head/hands out of the built character GLB (comparison)
|
||
flatpak run org.blender.Blender --background \
|
||
--python "$PWD/tools/npc_parts.py" -- extract --part hand_l --variant npc_casual \
|
||
--out "$PWD/tmp/npc-parts/npc_casual/hand_l.glb"
|
||
# Assemble a variant (currently rebuilds the procedural character)
|
||
flatpak run org.blender.Blender --background \
|
||
--python "$PWD/tools/npc_parts.py" -- assemble --variant npc_casual \
|
||
--out "$PWD/tmp/npc-parts/npc_casual/assembled.glb"
|
||
# Inspect a part or assembled GLB (Blender import view)
|
||
flatpak run org.blender.Blender --background \
|
||
--python "$PWD/tools/npc_parts.py" -- inspect --file "$PWD/tmp/npc-parts/npc_casual/face.glb"
|
||
# Contact sheet / before-after comparison (outside Blender; stdlib + Pillow)
|
||
python3 tools/npc_parts.py sheet --dir tmp/npc-parts/npc_casual \
|
||
--out docs/blender_previews/sheet_parts.jpg
|
||
python3 tools/npc_parts.py compare --before DIR --after DIR --out sheet.jpg
|
||
```
|
||
|
||
`build --part head` produces the bare head shell; `build --part face` is the shell plus
|
||
nose/eyes/mouth/ears; `build --part hand_l|hand_r` are the left/right hand geometry. `extract`
|
||
pulls the current shipped geometry out of the built character GLB by vertex group (`Head` for
|
||
`head`/`face`, `HandL`/`HandR` for the hands), so it shows what is actually shipped rather than
|
||
what the builders would emit fresh. The assembled GLB must still pass
|
||
`blender_assets.py inspect`/`audit`/`fit` before any part is accepted.
|
||
|
||
## Optional MCP
|
||
|
||
Blender MCP can be used for interactive head/face/hand part exploration, but it
|
||
is not required. The headless commands below remain the build and audit path;
|
||
see [`asset-tooling.md#optional-interactive-blender-mcp`](asset-tooling.md#optional-interactive-blender-mcp) for installation, connection and safety.
|
||
|
||
## Running it
|
||
|
||
```bash
|
||
# Build every asset (or --only a,b,c). Writes GLBs, .blend sources, manifest.
|
||
flatpak run org.blender.Blender --background \
|
||
--python "$PWD/tools/blender_assets.py" -- build
|
||
# Cycles previews (CPU, ~3 s each) -> docs/blender_previews/<name>.png (gitignored)
|
||
flatpak run org.blender.Blender --background \
|
||
--python "$PWD/tools/blender_assets.py" -- render
|
||
python3 tools/blender_assets.py sheet # -> docs/blender_previews/sheet_<category>.jpg
|
||
python3 tools/blender_assets.py audit # stdlib only; exit 1 on any issue
|
||
python3 tools/blender_assets.py fit # head/clothing fit + bag-body clearance, per character
|
||
python3 tools/blender_assets.py texels # 256² slot-map density (authored + 4× fabric), per character
|
||
python3 tools/blender_assets.py list
|
||
# import a GLB, apply node transforms, report geometry/bones/UVs/skinning + contract failures
|
||
flatpak run org.blender.Blender --background \
|
||
--python "$PWD/tools/blender_assets.py" -- inspect --file "$PWD/tmp/downloads/x.glb"
|
||
godot --headless --path . --import # after any rebuild
|
||
```
|
||
|
||
The flatpak cannot read `/tmp` and its cwd is `/app/blender`, so the script
|
||
derives every path from its own location. A full build takes about 5 s; a full
|
||
render about 2.5 min.
|
||
|
||
## Layout
|
||
|
||
| Kind | Path | Count |
|
||
| --- | --- | --- |
|
||
| Characters (skinned) | `assets/models/blender/npc/<name>.glb` | 8 |
|
||
| Gear (static) | `assets/models/blender/npc_gear/<name>.glb` | 18 |
|
||
| Props (static) | `assets/models/blender/props/<name>.glb` | 20 |
|
||
| Editable sources | `assets/models/blender_src/<name>.blend` (`.gdignore`d) | 46 |
|
||
| Review sheets | `docs/blender_previews/sheet_{npc,npc_gear,props}.jpg` | 3 |
|
||
|
||
## Conventions
|
||
|
||
- Blender is Z-up. The glTF exporter converts to Godot Y-up.
|
||
- **Front = Blender −Y = Godot +Z**, the face direction that
|
||
`NpcAvatar.yaw_towards()` assumes.
|
||
- **Foliage** (`street_tree`, `planter_box`, `round_planter`) is a cluster of many small
|
||
flat-shaded clumps plus outer clumps that break the silhouette, not one smooth blob. That is
|
||
how the realism pass made the street greenery read as leaves; the three assets carry fresh AO
|
||
maps (`street_tree` is 2,592 triangles).
|
||
- Grounded assets have their origin on the floor (`min y ≈ 0`). The two
|
||
exceptions are `wall_lantern` (origin on the wall plate, at mount height) and
|
||
`marquee` (origin at the wall where the canopy meets it, at canopy height).
|
||
- Units are metres, at the same scale as the current world (1.82 m characters).
|
||
|
||
## Characters
|
||
|
||
All library variants share the [character and gear asset contract](architecture.md#character-and-gear-asset-contract):
|
||
`npc_base` mesh node, required 13 core bones (optional extras allowed), five
|
||
tint slots, +Z visual front, 24,000/24,000 character budget and the same 256²
|
||
slot-map/AO rules. Role selection and look notes:
|
||
|
||
| Character | `layer_for()` / look | Suggested roles | Preview gear |
|
||
| --- | --- | --- | --- |
|
||
| `npc_casual` | `none`: sweater/tee, short sleeves | tourist, confused visitor, intoxicated, guest | backpack, camera |
|
||
| `npc_jacket` | `jacket`: collar + placket | authorized staff, protester, guest | lanyard, clipboard |
|
||
| `npc_coat` | `coat`: knee-length coat, long hair | influencer, trespasser, violent threat | sunglasses, shoulder bag, phone |
|
||
| `npc_vest` | `vest`: hi-vis vest, reflective bands | delivery | cap, clipboard |
|
||
| `npc_dress` | `dress`: slim build, bun, tights | performer | shoulder bag |
|
||
| `npc_hoodie` | `hood` accessory: hood up, beard, pocket | trespasser, mental crisis, violent threat | cup |
|
||
| `npc_firefighter` | responder: broad build, banded turnout coat, boots | responder | helmet, SCBA tank, flashlight |
|
||
| `npc_guard` | uniform: belt, buckle, badge, shoulder patches, radio | player guard / venue security | cap, wand |
|
||
|
||
**Fixed-colour materials.** Detail materials outside the five slots (`hivis`,
|
||
`reflective`, `leather`, `steel`, `patch`, `plastic_black`, `rubber`) carry a 4×4
|
||
colour texture. The current `_apply_outfit_materials()` sets
|
||
`albedo_color = WHITE` on any slot it does not recognise, and these keep their
|
||
colour through that. When integrating, tint only the five contract slots.
|
||
|
||
**Runtime tint notes (implemented).** Only the five contract slots are tinted;
|
||
fixed detail materials keep their authored colour. On `npc_vest` the vest is the
|
||
fixed `hivis` material and `cloth` is the undershirt, so the yellow override is
|
||
skipped. `npc_firefighter`/`npc_guard` use dark turnout/uniform tints instead of
|
||
the role's `TYPE_COLORS`.
|
||
|
||
## Gear attach points
|
||
|
||
Gear is authored in attach-point space; the exact contract and runtime fit offsets are in
|
||
[`architecture.md#character-and-gear-asset-contract`](architecture.md#character-and-gear-asset-contract).
|
||
|
||
## Props
|
||
|
||
| Prop | Replaces / role | Notes |
|
||
| --- | --- | --- |
|
||
| `bollard`, `bench`, `trash_bin`, `planter_box`, `newspaper_box`, `fire_hydrant` | `assets/models/generated/<name>.glb` | same footprint and height as the generated set, so colliders and `PROP_PLACEMENTS` still fit |
|
||
| `street_lamp` | the box lamps in `_build_street_furniture()` | 5 m; the arm points to −X with the bulb at (−0.85, 4.8, 0). Rotate 180° for the other side of the street. Emissive `bulb` |
|
||
| `street_tree` | the cone trees | 3.6 m, with a tree grate |
|
||
| `traffic_cone` | the `cone` prop accessory | 0.69 m |
|
||
| `palm_tree` | new (boulevard) | 7 m, 14 fronds |
|
||
| `round_planter` | new (mockup pots) | stone pot with topiary |
|
||
| `a_frame_sign` | new (comedy club queue) | chalkboard |
|
||
| `wall_lantern` | new (club door) | wall-mounted; emissive `bulb` |
|
||
| `crowd_barrier`, `stanchion` | new (queue / crowd control) | 2.2 m bike-rack barricade; chrome post with velvet rope |
|
||
| `handrail` | new (steps) | 2 m run that climbs 0.8 m along +X |
|
||
| `security_podium` | new (door check-in) | tablet screen is mildly emissive |
|
||
| `double_door` | the procedural entrance door | 2.0 × 2.7 m; emissive `lock_led` on the card reader |
|
||
| `marquee` | the procedural marquee | 6 m canopy and sign box; emissive `bulb` + `sign_face`. Overlay the text with the existing `Label3D` |
|
||
| `sedan` | new (studio arrival) | 4.6 m; emissive `headlight`, red tail lamps |
|
||
|
||
Props use plain PBR factors (base colour, roughness, metallic, emission) plus
|
||
the committed 256² baked AO maps (`<name>_ao.png`) wired by `WorldBuilder`;
|
||
emissive materials are tied to `WorldBuilder.set_night_mode()`. Characters
|
||
carry baked AO and the shared neutral material maps described above.
|
||
|
||
## Checks
|
||
|
||
- `python3 tools/blender_assets.py audit`: container, `POSITION`/`NORMAL`/
|
||
`TEXCOORD_0`, UVs in [0, 1], no zero-area triangles (Godot warns about them
|
||
during LOD generation), budgets (characters 24000/24000, gear 1500, props 4000
|
||
triangles), grounding, and an editable `.blend`. For characters it also
|
||
checks skinning, bones, slots, the `npc_base` mesh node and the height.
|
||
- `tools/tests/test_blender_assets.py`: catalogue and contract consistency with
|
||
`npc_pipeline.py`, plus a clean audit, a texel-density gate (all five slots,
|
||
40–400 px/m authored, 250 px/m fabric floor) and full manifest coverage when
|
||
the library is built.
|
||
- `src/test/tests/test_blender_assets.gd`: every asset imports as a scene
|
||
with geometry, characters keep their bones and slots, joints match
|
||
`npc_base`, the bones accept `NpcAvatar`'s pose composition, and props are
|
||
grounded.
|
||
- `tools/test_model_review.py`: every `CHARACTERS`/`GEAR`/`PROPS` entry has a
|
||
scorecard row and verdict in `docs/3d-model-review.md` (coverage gate).
|
||
- `src/test/tests/test_world.gd`: every library prop that blocks walking has a
|
||
`StaticBody3D` + `NavigationObstacle3D`, checked against the catalogue
|
||
(collider/proxy gate).
|
||
|
||
## Known limitations
|
||
|
||
- Characters carry a baked `<name>_ao.png` (red channel, wired by
|
||
`_apply_outfit_materials()`), but no ORM texture of their own. They reuse the
|
||
tiling slot maps, so the runtime `SurfaceMaterials` recipes still supply
|
||
roughness.
|
||
- There is a single body topology per build (average, slim, broad) and no
|
||
shape keys. Height variety still comes from `outfit_for()["height_scale"]`.
|
||
- Skirts and coats follow the hip and knee bones, so a full stride can clip
|
||
the legs through the hem.
|
||
- Preview colours (`PREVIEW_TINTS`) only stand in for `outfit_for()`. The GLBs
|
||
stay neutral.
|
||
- The 0.9.4 baseline found three P1 portrait issues. The tourist's photo prop
|
||
now only appears in photo/film poses and the backpack straps were refit as
|
||
flattened chest bands. The face carries the 0.9.4 sculpt (socketed sclera,
|
||
chin/cheekbone, nose, lips) but its `seg=18/rings=12` head still reads
|
||
somewhat faceted at portrait range; a subdivision/deeper-sculpt prototype is
|
||
gated on the owner scorecard review. The full ranked list and measurements are
|
||
in [`npc-visual-review.md`](npc-visual-review.md).
|