security-game/.agents/skills/gig-line-blender-asset-contract/SKILL.md

---
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 required 13 core bones (optional extra bones allowed), five tint slots, 24,000/24,000 character budgets, gear attach space, 256² texture/AO rules, headless flatpak Blender commands, optional MCP guidance, 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.
Blender MCP is optional interactive tooling; the headless flatpak CLI remains
authoritative and CI never needs Blender or MCP. The `blender-skills` pack is
optional, local guidance only, and gitignored. Setup and safety are in
`docs/assets/asset-tooling.md#optional-interactive-blender-mcp`.

## 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/assets/blender-assets.md` — library contract and command reference.
4. `docs/assets/asset-tooling.md` — exact rebuild/bake/capture commands.
5. `docs/assets/npc-model-sourcing.md` and `docs/assets/3d-model-review.md` — accepted limits,
   scorecards and known blockers.
6. `docs/design/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 | The 13 required core bones: `Head`, `HipL/R`, `KneeL/R`, `ShoulderL/R`, `ElbowL/R`, `HandL/R`, `Spine`, `Neck`. Optional extra bones (fingers, face, toes) are allowed; they must not move the core rest positions or break animation proxies. |
| Tint slots | `skin`, `cloth`, `pants`, `accessory`, `hair`. |
| Orientation | Front is Blender −Y / Godot +Z; feet grounded near y = 0; metres. |
| Character budget | **24,000 triangles / 24,000 glTF vertices** per character (`CHAR_MAX_TRIS`/`CHAR_MAX_VERTS`). |
| Frozen fallback | `npc_base` remains the low-poly fallback; it shares the 24,000/24,000 cap but is not required to use it. Do not silently lower the cap. |
| 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`

If MCP is available, use it for interactive part exploration only; mirror the result into a scripted change or local `.blend`, then re-export and run the CLI audit/fit gates. Never make the build, CI, tests or runtime depend on MCP. Setup: `docs/assets/asset-tooling.md#optional-interactive-blender-mcp`.

### 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 24,000/24,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/assets/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.
- `docs/assets/asset-tooling.md#optional-interactive-blender-mcp` — optional MCP installation, connection, safety and
  part-workflow instructions.
- [`references/verification.md`](references/verification.md) — command matrix,
  capture gates, expected results and acceptance criteria.

## Do not

- Make the build, CI, tests or runtime depend on MCP, Blender or API calls.
- 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.