---
name: gig-line-blender-asset-contract
description: Use when adding, rebuilding, auditing or fixing any Gig Line Blender-authored character, NPC base, gear, prop or venue geometry. Covers the 13-bone npc_base contract, five tint slots, triangle/vertex budgets, gear attach space, 256² texture/AO rules, headless flatpak Blender commands, and the inspect/audit/fit/proportion/capture gates. Do not use for pure GDScript/UI work or release publishing.
compatibility: Gig Line repository checkout. Godot 4.7.2 on PATH; Blender 5.2 LTS via the org.blender.Blender flatpak for build/bake/render. Audit, fit, inspect and proportion checks are stdlib-only.
metadata:
  project: Gig Line
  domain: 3d-assets
  version: "1.0.0"
  triggers: Blender, NPC, character, gear, prop, npc_base, GLB, AO, texel, asset rebuild, fit, audit
---

# Gig Line Blender Asset Contract

Use this skill for any change that touches:

- `assets/models/blender/**`
- `assets/models/generated/npc_base.glb`
- `assets/textures/npc/**`
- `tools/blender_assets.py`, `tools/npc_pipeline.py`, `tools/bake_ao.py`,
  `tools/npc_proportions.py` or `tools/npc_baseline.py`
- Blender-authored venue/prop geometry

The project contract and measured gates override any generic Blender advice.
There is **no Blender MCP** in this project. Blender runs headless through the
flatpak CLI; the `blender-skills` pack is optional, local guidance only, and
gitignored.

## Read first

From the repository root, read the relevant sources rather than relying on this
skill alone:

1. `AGENTS.md` — required workflow and verification.
2. `TODO.md` and `MEMORY.md` — current track, claimed tasks, known gotchas.
3. `docs/blender-assets.md` — library contract and command reference.
4. `docs/asset-tooling.md` — exact rebuild/bake/capture commands.
5. `docs/npc-visual-review.md` and `docs/3d-model-review.md` — accepted limits,
   scorecards and known blockers.
6. `docs/known-limitations.md` — limits that must not be silently “fixed” into
   contract changes.

The contract lives in code and docs, not in this skill. If they disagree, stop
and resolve the source of truth before editing assets.

## Non-negotiable contract

| Area | Rule |
| --- | --- |
| Mesh root | `npc_base` mesh node, skinned under `Rig`; preserve the limb node names. |
| Bones | 13 contract bones: `Head`, `HipL/R`, `KneeL/R`, `ShoulderL/R`, `ElbowL/R`, `HandL/R`, `Spine`, `Neck` (parent/helper bones must not change the contract). |
| Tint slots | `skin`, `cloth`, `pants`, `accessory`, `hair`. |
| Orientation | Front is Blender −Y / Godot +Z; feet grounded near y = 0; metres. |
| Library budget | **8,000 triangles / 8,000 glTF vertices** per character (`CHAR_MAX_TRIS`/`CHAR_MAX_VERTS`). |
| Frozen fallback | `npc_base` keeps **6,000 tris / 4,000 verts**. Do not silently raise or lower it. |
| Gear budget | **1,500 triangles** per gear piece; authored in attach-point space. |
| Prop budget | **4,000 triangles** per prop. |
| Gear attach | Use the catalogued attach points; verify with `fit`. Runtime `GEAR_OFFSETS` (lanyard forward, firefighter helmet up) and `HAND_ITEM_FORWARD` are intentional, not asset-contract changes. |
| Textures | 256² albedo/normal/ORM maps. Cloth and pants use `NPC_FABRIC_UV_SCALE = (4,4,1)` and **skip** baked per-character AO; skin/hair/gear keep baked AO. |
| CI | Offline and skill-free. Committed GLBs/AO/maps must make CI pass without Blender or MCP. |
| Licensing | No new asset source without ADR-0015: CC0, or CC-BY with attribution in `CREDITS.md`; record provenance. |

Do not change the renderer, engine baseline, runtime dependency graph or the
`npc_base` contract as part of an asset pass.

## Workflow

### 1. Preflight and claim

```bash
git status --short
git log --oneline -5
godot --version
flatpak run org.blender.Blender --version | head -3
```

Inspect the current asset and the relevant docs. Claim the TODO item with `[-]`
before starting. Work on one asset family per commit.

### 2. Establish a baseline

Run the checks that do not need Blender first:

```bash
python3 tools/blender_assets.py audit
python3 tools/blender_assets.py fit
python3 tools/blender_assets.py texels
python3 tools/npc_proportions.py report
python3 tools/npc_pipeline.py audit
```

For a specific incoming or existing GLB:

```bash
flatpak run org.blender.Blender --background \
  --python "$PWD/tools/blender_assets.py" -- \
  inspect --file "$PWD/path/to/asset.glb" --category npc_gear --json
```

Record the before measurements (tris/verts, head/shoulder/hip/leg/arm/foot,
fabric texel density, gear clearance). Do not “improve” an asset without a
measurable target.

### 3. Optional Blender-skill routing

If the local `blender-skills` pack is installed, load `blender-director`, then
only the specialists the task needs:

- character mesh/face/hands: `character-artist`, `retopology`
- rig/weights/pose: `rigging`
- UVs/texel density: `uv-workflow`
- maps/materials: `texture-workflow`, `materials`, `lookdev`
- gear/props: `prop-artist`, `hard-surface`
- budget/LOD/collision: `asset-optimization`, `lod-pipeline`, `collision-proxy`
- final review: `qa-review`

Translate any MCP instruction into a change to `tools/*.py` or a headless CLI
run. Never add an MCP dependency to the build, CI or runtime.

### 4. Build or bake

Characters, gear and library props:

```bash
flatpak run org.blender.Blender --background \
  --python "$PWD/tools/blender_assets.py" -- build --only <name>

flatpak run org.blender.Blender --background \
  --python "$PWD/tools/bake_ao.py" -- --only <name>
```

NPC base and its material maps:

```bash
python3 tools/npc_pipeline.py prepare      # only when fabric tiles change
flatpak run org.blender.Blender --background \
  --python "$PWD/tools/npc_pipeline.py" -- build
python3 tools/npc_pipeline.py audit
```

Do not overwrite a review image or a promoted texture pick. Use a new `-vN`
path and document the promotion.

### 5. Import and capture

```bash
godot --headless --path . --import
godot --headless --path . --script res://src/test/test_runner.gd

# neutral baseline: 8 variants x 6 views, raw frames stay in tmp/
godot --path . --script res://src/test/capture_npc_baseline.gd \
  -- --out=res://tmp/npc-baseline

# final-context: 96 frames across both venues and day/night
godot --path . --script res://src/test/capture_npc_review.gd \
  -- --out=res://tmp/npc-review
```

Compare before/after with `tools/npc_baseline.py compare`; do not replace the
committed baseline sheet until a fix actually lands. See
`references/verification.md` for the full gate matrix.

### 6. Verify and hand off

At minimum:

- `blender_assets.py audit` and `fit` exit 0.
- `npc_proportions.py` passes the stylized guide.
- `npc_pipeline.py audit` passes if the base/textures changed.
- texel density is inside the authored/fabric bands.
- No character exceeds 8,000/8,000; gear/prop caps hold.
- 24-NPC budget and Web/Compatibility path remain green.
- Contract tests, headless suite, capture gates and docs check pass.
- The diff contains only the intended assets, tools, tests and docs.

State in the handoff: files changed, measurements before/after, skills used,
gates run, and any accepted limit.

## Failure playbook

- **`Class "..." hides a global script class`** — a stray `.gd` backup is in the
  project. Delete `tmp/*.gd` backups, `rm -rf .godot`, re-import; never keep
  `class_name` copies in `tmp/`.
- **Blender cannot see the path** — the flatpak cwd is `/app/blender`; use
  absolute paths (`"$PWD/..."`).
- **Empty or stale captures** — close modals/pause, check the capture script's
  settle frames, and remove stale output directories before re-running.
- **Pose harness mismatch** — the current `capture_npc_pose.gd` is blocked per
  `docs/3d-model-review.md`; do not use its frames as pose evidence until the
  recipe is fixed.
- **Asset test fails after import** — re-run audit/fit first, then import; if the
  manifest or AO path changed, rebuild the affected asset rather than editing
  the manifest by hand.
- **Uncertain about a visual change** — produce a labelled before/after sheet and
  ask for review; do not hide a regression behind a budget claim.

## Bundled references

- [`references/asset-contract.md`](references/asset-contract.md) — full contract,
  inventory, file locations and provenance rules.
- [`references/verification.md`](references/verification.md) — command matrix,
  capture gates, expected results and acceptance criteria.

## Do not

- Add an MCP server, Blender dependency or API call to the build/runtime.
- Change the bone/tint/contract to make a generic asset fit.
- Rewrite committed baselines or overwrite existing images.
- Commit `.blend` sources, raw captures or generated AI inputs.
- Treat an asset audit as a substitute for visual review at portrait and crowd
  distance.