game-assets

name	game-assets
description	Budget-aware asset planning, image/3D/animation generation, background removal. Load when generating or managing game assets.

Game Assets — Planning, Generation & Processing

Overview

Three-phase asset workflow:

1. Plan — analyze game, identify assets, budget allocation
2. Generate — create images, 3D models, animated sprites
3. Process — background removal, frame extraction, loop trimming

---

Phase 1: Asset Planning

Input

• budget_cents — total budget (or remaining for iterations)
• Game plan spec (in .specs/) — game description, risk tasks, main build with asset needs
• Architecture notes (draft in .ai.tmp/) — architecture with Asset Hints section
• reference.png — visual composition target
• Art direction notes (draft in .ai.tmp/) — art direction from visual target phase

Workflow

1. Read reference.png — understand visual composition, proportions, environment layers.
2. Read architecture Asset Hints + game plan Assets needed — reconcile both lists (they may overlap or complement each other).
3. Categorize assets:
   • 3D models — characters, vehicles, key props, buildings (need geometry)
   • Textures — ground, walls, UI backgrounds (flat, tileable)
   • Backgrounds — sky panoramas, parallax layers, title screens (large scenic)
   • Animated sprites — characters/objects with multiple actions (plan motion graph first)
4. Budget allocation (see cost table below).
5. Identify anchors vs derivatives — anchors generated first, derivatives use anchor as --image input.
6. Generate, review, convert — images in parallel, review PNGs, retry bad ones (max 1), convert approved 3D refs to GLBs.

Cost Table

Asset Type	Backend	Cost	Notes
Texture / simple sprite	Grok	2c	Fast, simple images
Character / reference	Gemini 1K	7c	Precise prompt following
Background (simple)	Grok	2c	Sky, clouds, abstract
Background (precise)	Gemini 2K	10c	Specific layout/composition
3D model (full)	Gemini 1K + GLB	47c	7c image + 40c GLB high quality
Animation reference	Gemini 1K	7c	Once per character
Animation action (root)	Gemini pose + video	7c + 5c x duration	From reference
Animation action (chained)	Video only	5c x duration	From predecessor's last frame

Reserve ~10% of budget for retries. Prioritize by visual impact — cut low-impact assets first.

Backend Selection

• Gemini (--model gemini) — reference images, character design, 3D model references, animated sprite refs/poses, backgrounds with precise layout. Costs more but reliably matches prompt.
• Grok (--model grok, default) — textures, simple objects, item kits, props, simple scenic backgrounds. High-quality but imprecise — great when exact prompt adherence doesn't matter.

Art Direction Usage

Read the Art direction from your draft but do NOT mechanically prepend it. Different asset types need different treatment:

• Textures — often need no style language at all
• 3D model references — need clean studio lighting; style cues can hurt mesh quality
• Backgrounds — benefit most from art direction language
• Sprites — some style cues, adapted to the subject

Image References for Consistency

Feed a generated image as --image input when subsequent assets need to match it:

• Style family — one hero asset as input for the rest of the set
• Multiple views — front view as input for side, back, 3/4 angle
• Variants — base object as input for recolors, damaged versions, sizes
• Scene coherence — background as input for foreground props

Generate anchors first, review, then fan out derivatives in parallel.

---

Phase 2: Generation CLI

All tools are TypeScript-based. Run from project root.

Generate Image

godot-asset-gen image --prompt "the full prompt" -o assets/img/car.png

Options:

• --model (default grok): grok (2c), gemini (5-15c by size)
• --size (default 1K): Grok: 1K, 2K. Gemini: 512, 1K, 2K, 4K
• --aspect-ratio (default 1:1): 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3
• --image — reference image for image-to-image editing

Typical combos:

• --model gemini --size 1K — refs, characters, 3D refs (7c)
• --model gemini --size 2K --aspect-ratio 16:9 — backgrounds (10c)
• --model grok — textures, simple objects (2c)

Generate GLB (3D Model)

godot-asset-gen glb --image assets/img/car.png -o assets/glb/car.glb

Options:

• --quality: default (50c) or high (40c, HD textures)

Do NOT remove background before GLB conversion — Tripo3D needs the solid white bg.

Generate Video (Animated Sprites)

godot-asset-gen video --prompt "walking right, smooth cycle" --image assets/img/pose.png --duration 2 -o assets/video/walk.mp4

Options:

• --duration (1-15 seconds)
• --resolution (default 720p): 720p, 480p — always use 720p

Set Budget

godot-asset-gen set_budget 500

Sets budget to 500 cents. Call once at start. All generations check remaining budget.

Output Format

JSON to stdout: {"ok": true, "path": "...", "cost_cents": 7} On failure: {"ok": false, "error": "...", "cost_cents": 0}

---

Prompt Templates

Background / Scenic Image

{description in the art style}. {composition instructions}.

godot-asset-gen image --prompt "..." --size 2K --aspect-ratio 16:9 -o path.png

Texture (Tileable)

{name}, {description}. Top-down view, uniform lighting, no shadows, seamless tileable texture, suitable for game engine tiling, clean edges.

godot-asset-gen image --prompt "..." -o path.png

Single Object / Sprite

Simple (Grok):

{name}, {description}. Centered on a solid {bg_color} background.

Character (Gemini):

{name}, {description}. Centered on a solid {bg_color} background.

godot-asset-gen image --model gemini --prompt "..." -o path.png

Item Kit (Multiple Objects)

{item1}, {item2}, {item3}, {item4}. 2x2 grid layout, each item centered in its cell, solid {bg_color} background. {art style}.

Slice into individual PNGs:

godot-grid-slice path_grid.png -o assets/img/items/ --grid 2x2 --names "sword,shield,potion,helm"

3D Model Reference

3D model reference of {name}. {description}. 3/4 front elevated camera angle, solid white background, soft diffused studio lighting, matte material finish, single centered subject, no shadows on background. Any windows or glass should be solid tinted (opaque).

godot-asset-gen image --model gemini --prompt "..." -o path.png

Key: 3/4 front elevated angle, solid white/gray bg, matte finish, opaque glass, single subject.

Animated Sprite

Reference (Gemini 1K):

{name}, {description}. Neutral standing pose, facing right, centered on a solid {bg_color} background. Clean silhouette.

Pose (per action):

{action pose description}, side view, solid {bg_color} background.

Video (per action):

{action}, smooth animation. Solid {bg_color} background.

---

Phase 3: Processing

Background Removal

Applies to: characters, props, icons, UI elements, animated sprite frames. Does NOT apply to: textures, backgrounds, 3D model references.

CRITICAL: Never prompt for "transparent background" — the generator draws a checkerboard. Always use a solid color background, then remove it.

BG Color Strategy

Pick a color that is (1) distinct from the subject for clean mask separation, and (2) close to the expected in-game environment so residual fringe blends naturally.

Examples: forest → dark-green; sky/water → steel-blue; dungeon → dark-gray; generic → medium-gray.

Avoid pure chromakey (#00FF00) — creates unnatural fringing.

CLI

Single image:

godot-rembg assets/img/car.png -o assets/img/car_nobg.png --preview

Batch (video frames):

godot-rembg --batch frames_dir/ -o clean_dir/

Modes

-m auto (default) selects based on mask coverage:

Mode	When	Behavior
trust	5-70% mask fg	Keep all mask-fg pixels, aggressively remove bg
adapt	>70% mask fg	Adaptive threshold — fg pixels CAN be removed if bg-colored
color	<5% mask fg	Color matting only, no mask — rough fallback

QA Verification

Always pass --preview — generates a _qa.png composited on contrasting solid color. Read the QA image to check for remnants, fringing, or missing foreground. Delete after inspection.

Fixing Results

• Background remnants → --bg-thresh 0.03 (lower = more aggressive)
• Missing foreground → -m trust or --fg-thresh 0.30 (higher = more protective)
• Fringing → -m adapt --fg-thresh 0.10 + --bg-thresh 0.03. If persists, bg color too close to subject.
• Mask failed → result rough, regenerate source image

Tune --bg-thresh and --fg-thresh together. For batch: tune on one frame first.

Frame Extraction

mkdir -p assets/video/knight_walk_frames
ffmpeg -i assets/video/knight_walk.mp4 -vsync 0 assets/video/knight_walk_frames/%04d.png

Loop Detection (Looping Animations Only)

godot-loop-detect assets/video/knight_walk_frames/

Output: {"loop_frame": 54, "similarity": 0.9983, "window": 7, "total_frames": 73}

window: 0 means no good loop point — use whole clip. Delete frames after loop point. Skip for one-shot animations (attack, death, jump).

Grid Slicing (Item Kits)

godot-grid-slice path_grid.png -o assets/img/items/ --grid 2x2 --names "sword,shield,potion,helm"

---

Asset Manifest Format

Track all assets in a draft (via draft-create). Every asset row must include a Size column — the intended in-game dimensions:

• 3D models: target size in meters (e.g., 4m long)
• Textures: tile size in meters (e.g., 2m tile)
• Backgrounds: pixel dimensions (e.g., 1920x1080)
• Sprites: display size in pixels (e.g., 128x128 px)

# Assets

**Art direction:** <the art direction string>

## 3D Models

| Name | Description | Size | Image | GLB |
|------|-------------|------|-------|-----|
| car | sedan with spoiler | 4m long | assets/img/car.png | assets/glb/car.glb |

## Textures

| Name | Description | Size | Image |
|------|-------------|------|-------|
| grass | green meadow | 2m tile | assets/img/grass.png |

## Backgrounds

| Name | Description | Size | Image |
|------|-------------|------|-------|
| forest_bg | dense forest | 1920x1080, fullscreen | assets/img/forest_bg.png |

## Sprites

| Name | Description | Size | Image |
|------|-------------|------|-------|
| coin | spinning gold coin | 64x64 px | assets/img/coin.png |

## Animated Sprites

### knight

**Reference:** `assets/img/knight_ref.png`
**Transitions:** idle <-> walk, walk -> attack -> idle

| Action | Type | Size | Duration | Start From | Frames Dir |
|--------|------|------|----------|------------|------------|
| idle | loop | 128x128 px | 2s | ref | assets/img/knight_idle/ |
| walk | loop | 128x128 px | 3s | ref | assets/img/knight_walk/ |
| attack | one-shot | 128x128 px | 2s | walk | assets/img/knight_attack/ |

Start From: ref = generate pose from reference. Action name = use that action's last extracted frame as video input.

Generation order: roots first (parallel) -> extract + loop trim -> chains (parallel) -> extract -> batch rembg all.

---

Visual Pitfalls

Direction and Orientation

Generators cannot reliably distinguish left vs right facing. Generate one direction only, flip in-game (sprite.flip_h = true). Verify with visual-qa.

Video Size Consistency

Image assets (1024px) vs video frames (~720px): resize everything to the smallest source size before background removal. Downscale images to match video resolution.

Animation Playback

Video frames are typically 24fps — set frame duration to 1.0/24 = 0.042s. Don't reset frame counter between movement tiles.

Common Mistakes

• Detailed image shrunk to a tile — 1024px downscaled to 64px looks muddy. Use 128px+ display, kit images, or prompt for bold simple forms.
• Tiling texture for unique background — use --size 2K scenic instead.
• Image where code works — pure geometry (solid rectangles, circles) should be drawn in code. Anything with texture/detail/artistic style should use generated assets.
• Stretching texture — small texture on large surface looks blurry. Use tileable or higher resolution.

Image-to-Image Prompting

When --image is provided, the model sees the reference. Do NOT re-describe the character — focus on what's different (action, angle, change). Re-describing competes with the visual reference.