fal-gamedev

What this skill does

# 2D Game Assets

> Requires the [genmedia CLI](https://github.com/fal-ai-community/genmedia-cli) (run `genmedia init` once).

Full pipeline for 2D pixel art game assets: character → sprite sheets → background removal → game background. Each recipe is independently invokable, run just the part you need.

Always use `--json` so output is machine-readable. Use `--download` to save files locally. Do **not** curl URLs manually, use the `--download` flag.

---

## Execution rules, follow these strictly

1. **Each genmedia command = one Bash tool call**: issue each `genmedia run` and `genmedia status` as its own bare tool call. No variable assignments, no pipes, no shell redirects. This keeps every call matching the `genmedia *` allowlist so it runs without permission prompts.

2. **Parallel jobs → async**: issue each `genmedia run --async` as its own separate Bash tool call (not combined into one shell block). All jobs queue and run in parallel on fal's side; total time ≈ slowest single job. After all are fired, poll each with `genmedia status` sequentially (not in parallel, one failure must not cancel others).
 ```bash
 # Step 1, fire async (each line = its own Bash tool call, returns request_id immediately)
 genmedia run fal-ai/nano-banana-pro/edit --prompt "$WALK_PROMPT" --image_urls "[\"$CHARACTER_URL\"]" --aspect_ratio "1:1" --resolution "1K" --async --json
 genmedia run fal-ai/nano-banana-pro/edit --prompt "$IDLE_PROMPT" --image_urls "[\"$CHARACTER_URL\"]" --aspect_ratio "1:1" --resolution "1K" --async --json

 # Step 2, poll sequentially (each line = its own Bash tool call)
 genmedia status fal-ai/nano-banana-pro/edit <walk_request_id> --result --download ./walk.png --json
 genmedia status fal-ai/nano-banana-pro/edit <idle_request_id> --result --download ./idle.png --json
 ```

3. **URL source**: always read `downloaded_files[0].url` from the tool result JSON. This is the correct path for all models (nano, gpt, Bria).

4. **Bria sync**: Bria (`fal-ai/bria/background/remove`) has no queue endpoint and does not support `--async`. Run it sync. It completes in seconds.

5. **Folder structure**: always save into this layout, deriving the character slug from the character description (kebab-case, e.g. `pirate-carrot`):
 ```
 ./game-assets/
 <character-slug>/
 character.png
 sprites/
 walk.png
 idle.png
 attack.png
 jump.png
 backgrounds/
 layer1-sky.png
 layer2-midground.png
 layer3-foreground.png
 ```
 Create the folders before downloading (`mkdir -p`). Use this structure even for partial runs (e.g. just one sprite sheet still goes in `sprites/`).

6. **End summary**: after all downloads complete, print a summary listing every file path and its CDN URL. Format:
 ```
 === Game Assets: pirate-carrot ===
 character game-assets/pirate-carrot/character.png
 https://...
 walk game-assets/pirate-carrot/sprites/walk.png
 https://...
 ```

7. **400 on status poll**: `genmedia status --result` fetches the result once; it does not poll automatically. A 400 with `"Request is still in progress"` means the job is still running, wait 10 seconds and retry the exact same `genmedia status` call with the same request_id. Do **not** re-fire the original `genmedia run --async` (the job is already running on fal's side). Keep retrying every 10–15 seconds until you get a successful result.

---

## When to use
- Generating a pixel art character from a text description or reference image
- Creating sprite sheet animations (walk, jump, attack, idle) for a side-scroller
- Creating isometric RPG sprite sheets (walk, attack, idle across directions)
- Removing backgrounds from sprite sheets to get transparent PNGs
- Generating parallax backgrounds (3-layer) for side-scrollers
- Generating top-down isometric game maps for RPGs

## Models in the stack
- **Nano Banana Pro**: `fal-ai/nano-banana-pro`, character + background generation; better quality and faster, recommended default
- **Nano Banana Pro Edit**: `fal-ai/nano-banana-pro/edit`, sprite sheet generation from character image
- **GPT-Image-2**: `openai/gpt-image-2`, character + background generation; slower than nano, use when user prefers it or wants cheaper output (`quality=low`)
- **GPT-Image-2 Edit**: `openai/gpt-image-2/edit`, sprite sheet generation; slower than nano, requires model-specific walk prompt; use `quality=low` for cheaper runs
- **Bria RMBG 2.0**: `fal-ai/bria/background/remove`, background removal on all sprite sheets

---

## Recipe 1. Generate character

Ask the user: character description (text) or an existing image to convert. Ask model preference: `nano` (default, better quality + faster) or `gpt` (slower; use `quality=low` if user wants cheaper output).

```bash
CHARACTER_STYLE_PROMPT="Generate a single character only, centered in the frame on a plain white background. The character should be rendered in detailed 32-bit pixel art style (like PlayStation 1 / SNES era games). Include proper shading, highlights, and anti-aliased edges for a polished look. The character should have well-defined features, expressive details, and rich colors. Show in a front-facing or 3/4 view pose, standing idle, suitable for sprite sheet animation."

IMAGE_TO_PIXEL_PROMPT="Transform this character into detailed 32-bit pixel art style (like PlayStation 1 / SNES era games). IMPORTANT: Must be a FULL BODY shot showing the entire character from head to feet. Keep the character centered in the frame on a plain white background. Include proper shading, highlights, and anti-aliased edges for a polished look. The character should have well-defined features, expressive details, and rich colors. Show in a front-facing or 3/4 view pose, standing idle, suitable for sprite sheet animation. Maintain the character's key features, colors, and identity while converting to pixel art."

# Text → pixel art character (nano)
genmedia run fal-ai/nano-banana-pro \
 --prompt "$CHARACTER_STYLE_PROMPT Character: <character_desc>" \
 --aspect_ratio "1:1" --resolution "1K" \
 --download ./game-assets/<slug>/character.png --json

# Text → pixel art character (gpt)
genmedia run openai/gpt-image-2 \
 --prompt "$CHARACTER_STYLE_PROMPT Character: <character_desc>" \
 --image_size "square_hd" --quality "high" \
 --download ./game-assets/<slug>/character.png --json

# Existing image → pixel art (nano), upload source image first, then run edit
genmedia upload /path/to/image.png --json
genmedia run fal-ai/nano-banana-pro/edit \
 --prompt "$IMAGE_TO_PIXEL_PROMPT" \
 --image_urls "[\"<uploaded_url_from_above>\"]" \
 --aspect_ratio "1:1" --resolution "1K" \
 --download ./game-assets/<slug>/character.png --json
```

Read `downloaded_files[0].url` from the tool result, this is `CHARACTER_URL`, needed for all sprite sheet recipes.

---

## Recipe 2. Generate sprite sheets

Pass `CHARACTER_URL` from Recipe 1. Choose `--style side` (side-scroller) or `--style iso` (isometric RPG). Choose model: `nano` or `gpt`.

**Side-scroller sheets**: 4-frame 2×2 grid animations. Covered types: `walk`, `jump`, `attack`, `idle`. Do not generate additional animation types (hurt, death, run, etc.) unless the user explicitly requests them.

Fire all sheets async (each is its own Bash tool call), then poll sequentially:

```bash
WALK_PROMPT="Create a 4-frame pixel art walk cycle sprite sheet of this character. Arrange the 4 frames in a 2x2 grid on white background. The character is walking to the right. Top row (frames 1-2): Frame 1 (top-left): Right leg forward, left leg back - stride position. Frame 2 (top-right): Legs close together, passing/crossing - transition. Bottom row (frames 3-4): Frame 3 (bottom-left): Left leg forward, right leg back - opposite stride. Frame 4 (bottom-right): Legs close together, passing/crossing - transition back. Each frame shows a different phase of the walking motion. This creates a smooth looping walk cycle. Use detailed 32-bit pixel art style with proper shading and highlights. Same character design in all frames. Character facing right."

WALK_PROM