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

name, description, compatibility, metadata

name	description	compatibility	metadata
gig-line-blender-asset-contract	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.	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.	project domain version triggers Gig Line 3d-assets 1.0.0 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

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:

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:

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:

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:

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

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 — 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 — 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.