Assets

Asset acquisition for Rogue Gauntlet

Find, fetch, and register third-party (or self-authored) assets while staying license-clean and visually cohesive. assets/AGENTS.md is the policy + manifest source of truth (the open-source free-download rule, the KayKit cohesion rule, the licensing rules, and the ATTRIBUTIONS.json schema). This skill is the mechanics: which script, what command, and how the pieces fit. Read assets/AGENTS.md before adding anything.

Secrets

Keys live in the repo .env (gitignored): POLYPIZZA_KEY, HF_TOKEN. Load them per shell:

set -a; . /Users/andrerabold/Projects/Personal/rogue-gauntlet/.env; set +a

Never print key values or pass them on a command line that gets logged.

The two automation channels

1. KayKit -> GitHub (no key) — cohesive whole packs

Our primary 3D style. Public repos under github.com/KayKit-Game-Assets, all CC0.

python3 scripts/fetch_kaykit.py KayKit-Game-Assets/KayKit-Halloween-Bits-1.0 assets/kaykit-halloween-bits --dry-run
python3 scripts/fetch_kaykit.py KayKit-Game-Assets/KayKit-Halloween-Bits-1.0 assets/kaykit-halloween-bits

Pulls the gltf set (.gltf+.bin+shared texture) + LICENSE, flattened to match existing assets/kaykit-* dirs. Stdlib only. (GH_TOKEN optional, only to lift the unauth rate limit.)

2. Poly Pizza -> API (POLYPIZZA_KEY) — discovery + single models

Indexes Quaternius, Kenney, and many others. Mixed CC0 / CC-BY.

# discover: see tris (low-poly?), licence, and Animated before committing
python3 scripts/fetch_polypizza.py search goblin --limit 25 --cc0 --max-tris 3000
# download one + get a ready-to-paste manifest entry (CC-BY attribution captured)
python3 scripts/fetch_polypizza.py get <ID> assets/<id>

Prefer --cc0 to avoid attribution debt; if you take a CC-BY model, the printed attribution_text MUST go in the manifest and the shipped credits.

Add-an-asset workflow

1. Discover / fetch with the right channel above.
2. Register in assets/ATTRIBUTIONS.json — the Poly Pizza get prints a near-complete entry; for KayKit, copy an existing kaykit-* entry and adjust. Set the right compatibility_group (kaykit for KayKit; for Poly Pizza models triage out of polypizza-unsorted once you've judged style fit).
3. Import into Godot (generates import caches + .uid sidecars), from the repo root:

   .agents/skills/godot-mcp/scripts/godot.sh --headless --path "$PWD" --import
   

4. Verify: /usr/local/share/dotnet/dotnet build "Rogue Gauntlet.sln", and validate a sample model loads (.agents/skills/godot-mcp/scripts/inspect_resource.gd).
5. New creator/style only: do the in-engine visual side-by-side (see assets/AGENTS.md).

Turning a downloaded character into an enemy (recipe)

Validated on the Quaternius monsters. Enemies instance scenes/enemies/enemy_base.tscn and override the model + an AnimationTree state machine + tuning resources (see the skeleton variants in scenes/enemies/skeleton/ as the reference). Steps:

0. Pick a coherent set, not just same-creator. One creator's "monster pack" often spans several visual sub-series — e.g. Quaternius has a textured-atlas EnemyArmature series (goblin, zombie) AND a vertex-colored series (orc, demon, ghost, yeti, slime, bat, spider) that do not match. Probe candidates and group by look (textured vs vertex-color via the material check) before committing; mixing sub-series reads as broken even though it's "all Quaternius". Within one coherent set, rigs still differ per body type (CharacterArmature/MonsterArmature/BatArmature/ SpiderArmature) — that's fine, just map clips per model.
1. Probe the model's animations. Load the GLB and list its AnimationPlayer clips — names vary per model and rig: humanoids use Idle/Walk + Punch|Bite_Front + HitReact|HitRecieve + Death; the bat flies (Bat_Flying for idle+move, Bat_Hit); the spider has no hit clip (reuse Spider_Idle for the Hit state). The state machine must reference the exact strings. Flyers (bat/ghost) get a model transform Y-offset to hover; true flight needs a movement/behavior change.
2. Fix looping in the .glb.import. Fresh imports have _subresources={}, so Idle/Walk/Run play once and freeze. Add "animations": { "<clip>": { "settings/loop_mode": 1 } } for the looping clips (leave Attack/Hit/Death at 0 so their at-end transitions fire), then reimport.
3. Normalize scale — by eye, not by measurement. Downloaded characters arrive at arbitrary sizes. Set a uniform transform scale on the model node under Pivot, scaling about the origin so the feet stay on the ground and the pivot is intact. Confirm the size visually in the editor against an existing actor — headless height measurement of GPU-skinned GLBs is unreliable (bind-pose AABBs and bone spans both mislead and disagree with each other), so the editor eyeball is authoritative. As a starting point, Quaternius monsters sit at ≈ 0.75 to read right next to the KayKit skeleton; expect to nudge per model.
4. Match the collision shapes to the reference enemy. Use the same capsule sizing the skeleton variants use — radius 0.75, height 2.0, body CollisionShape3D at y = 1.2, plus the hurtbox CollisionShape3D. Don't shrink them to a mis-scaled model; size the model to them.
5. Author the scene (scenes/enemies/<creature>/<name>.tscn, one folder per creature family like skeleton/ — not per author): instance enemy_base.tscn; add the model under Pivot; add an AnimationTree under EnemyBehaviorComponent with root_node → the model, anim_player → the model's AnimationPlayer, advance_expression_base_node → .., and a tree_root state machine (Idle/Walking/Attack/Hit/Dying/Dead) whose transitions key off the behavior flags IsMoving/IsAttacking/IsHit/IsDead. Add the two CollisionShape3Ds (hurtbox child + body). Set HealthComponent, DeathComponent.Xp, HurtBoxComponent.Evasion, LootTableComponent.Table, and EnemyBehaviorComponent.Profile.
6. Author a profile co-located in the creature folder (scenes/enemies/<creature>/<name>_behavior.tres, script EnemyBehaviorProfile) — each creature folder is self-contained (scene + profile). If the model has no spawn clip, set InitialAction = 0 (Idle), not Spawning.
7. Register the scene path in scenes/levels/dungeon/dungeon_mob_factory.tres.
8. Verify: reimport, dotnet build, then a headless probe that instantiates the scene and asserts the AnimationTree resolves and every state maps to a clip the player has; finally boot res://scenes/main/main.tscn and confirm the monster spawns. The cohesion/look call is the maintainer's — eyeball it next to existing actors.

Visual catalog (model screenshots)

scripts/render_catalog.gd renders a transparent-background PNG of every .glb/.gltf in a directory (posed in Idle, 3/4 camera) — used to build docs/monster-catalog/.

.agents/skills/godot-mcp/scripts/godot.sh --path "$PWD" \
  --script .agents/skills/assets/scripts/render_catalog.gd -- docs/monster-catalog res://assets/quaternius-monsters

scripts/render_item_catalog.gd does the equivalent for items: loads each item .tres, instances its Scene, auto-centers/auto-rotates it (mirroring Preview.cs's in-game inventory preview framing) and screenshots it alone against a transparent background — used to build docs/item-catalog/.

.agents/skills/godot-mcp/scripts/godot.sh --path "$PWD" \
  --script .agents/skills/assets/scripts/render_item_catalog.gd -- docs/item-catalog res://scenes/items/weapons/axe_common.tres [more...]

• Run WINDOWED — not --headless. Headless uses the dummy renderer: viewport captures come back blank and the script hangs. A real window opens briefly and renders on the GPU. (timeout isn't on macOS — rely on the runner's own time cap if you need a guard.)
• Pass the dir to render_catalog.gd and let it scan (DirAccess); don't word-split a file list on the shell — zsh doesn't split unquoted $VARS like bash, so only one path reaches the script. render_item_catalog.gd takes explicit item paths instead (items live scattered across scenes/items/<category>/, not one flat asset folder).
• After regenerating, update the table in docs/monster-catalog/README.md or docs/item-catalog/README.md.

In-hand weapon/shield verification (does NOT catch everything the catalog does)

The floating catalog render above is not sufficient to validate a new weapon or shield. It auto-frames and auto-rotates for a nice thumbnail, which can hide exactly the two defects that only show up once a model is actually bone-attached to the player:

1. Wrong local-axis convention. BoneAttachmentManager parents the item's Scene directly under a BoneAttachment3D with zero corrective transform, so the model's own local axes must already match what that bone's rest pose expects. Different weapon-hand bones expect different conventions (a melee bone expects "extends away from grip" along local +Y; a raw bow/crossbow-style asset instead puts its aim along local Z with limbs along X) — get it wrong and the model can end up thin-edge-on to every normal camera angle, reading as fully invisible, not just "rotated a bit wrong."
2. Cross-tier scale inconsistency. A raw downloaded model isn't guaranteed to be scaled consistently with an existing baked-mesh sibling in the same item ladder (e.g. a new tier-2 .glb coming in at half the height of the tier-1 item it's supposed to visually escalate from).

scripts/render_held_items.gd equips a sequence of items on a standalone player (no GameSession/class active — the authored Barbarian rig) and screenshots the character from three angles per item (front, weapon-hand 3/4, shield-hand 3/4), so whichever hand an item lands in is covered without needing to guess the right camera angle up front:

.agents/skills/godot-mcp/scripts/godot.sh --path "$PWD" \
  --script .agents/skills/assets/scripts/render_held_items.gd -- /tmp/held_test \
  res://scenes/items/weapons/axe_rare.tres res://scenes/items/armor/shield_rare.tres [more...]

• Windowed only, same reason as above.
• Requires a floor: the player is a physics-driven CharacterBody3D and free-falls under gravity in an otherwise-empty scene (for however many physics ticks elapse before the first idle frame — decoupled from frame count and inflated by first-load shader/asset stalls), landing at an unpredictable height by the time you'd screenshot. The script adds a StaticBody3D floor and waits SETTLE_FRAMES before measuring/framing; don't drop this if you fork the script.
• If an item is invisible in ALL three angles (not just badly positioned in one), suspect the local-axis convention, not scale/position. Diagnose by rendering the raw .glb alone at identity transform with RGB axis gizmos (R=+X, G=+Y, B=-Z), then compare against a sibling weapon on the same bone that's known to render correctly rendered the same way — the direction its long axis points tells you which local axis needs to land on which. Fix with a thin corrective wrapper .tscn (rotation_degrees on the instanced child); see the godot-mcp skill's tres-authoring.md for the pattern.
• IsTwoHanded on a Weapon changes which BoneAttachment3D it resolves to (see docs/character-classes.md), so re-verify in-hand appearance after changing it — a weapon that looked right on one bone isn't guaranteed to look right on another.

Authoring our own (image-to-3D) — experimental

scripts/hf_image_to_3d.py runs image-to-3D on HF hardware (TripoSR Space) via gradio_client. Honest scope before you invest:

• Output is high-poly PBR + unrigged — needs a manual Blender low-poly/palette pass and skinning to the KayKit rig. HF solves compute, not the style/rig gap.
• The GPU step needs ZeroGPU quota; a free token usually hits the wall (validated). Reliable routes: HF Pro, or duplicate the Space to a dedicated GPU.
• Needs gradio_client: python3 -m venv .venv && .venv/bin/pip install gradio_client.

.venv/bin/python scripts/hf_image_to_3d.py concept.png monster.glb 256

Gotchas

• Binary repo files may be Git-LFS — fetch via raw.githubusercontent.com (the scripts do); it resolves LFS transparently. ?download=true resolves HF LFS similarly.
• Triangle count is the quick low-poly filter on Poly Pizza; KayKit-grade props are roughly hundreds-to-low-thousands of tris. A 70k-tri "skeleton" will not match.
• CC-BY is not free of obligations — attribution is legally required in shipped builds. Prefer CC0; record attribution when you don't.
• Tiny palette-atlas textures need lossless + no mipmaps. Many low-poly models (Quaternius is 32×32) color faces by sampling flat cells from a minuscule atlas. Godot's default 3D texture import (compress/mode=2 VRAM/BC + mipmaps) wrecks these — BC's 4×4 blocks straddle palette cells and mipmaps blend neighbours, so the "skin" comes out muddy/wrong. Set compress/mode=0 and mipmaps/generate=false on the atlas .import and reimport. (Large UV textures like KayKit's 1024² are fine with the default.)
• Don't commit the scratch venv or downloaded archives. Keep .venv/ and any zips out of git.
• For Godot import/scene/resource specifics, defer to the godot-mcp skill.