rehan-remade / fal-assets

Game assets with fal

fal runs hundreds of generative models behind one API key. Use it whenever the mod needs something that
doesn't exist yet: a weapon sprite, a boss, a unit rendered from 16 angles, a tileable floor, a laser sound,
boss music, a voiced line.

Setup (check once per session)

• Key. FAL_KEY must be set (create one at https://fal.ai/dashboard/keys). um fal also reads it from
  a .env file (FAL_KEY=...) in the working folder. Never write the key into mod files; um publish check
  flags leaked keys.

• MCP. fal's hosted MCP server is https://mcp.fal.ai/mcp with header Authorization: Bearer $FAL_KEY.
  The repo pre-configures it for each agent:

  • Claude Code: .mcp.json
  • Codex: .codex/config.toml
  • Cursor: .cursor/mcp.json
  • VS Code/Copilot: .vscode/mcp.json
  • Gemini CLI: gemini-extension.json

  To add it by hand:

  • Claude Code: claude mcp add --transport http fal https://mcp.fal.ai/mcp --header "Authorization: Bearer $FAL_KEY"

  • Codex (~/.codex/config.toml): [mcp_servers.fal] with url = "https://mcp.fal.ai/mcp" and
    bearer_token_env_var = "FAL_KEY"

  • anything else: point its MCP config at the URL and header above.

  MCP tools: search_models, recommend_model, get_model_schema, get_pricing, run_model,
  submit_job/check_job/get_job_result, upload_file, search_docs.

• No fal key? For images, um comfy uses a local ComfyUI server instead (um comfy status, then
  um comfy image "..." --sprite). It has no audio, 3D or video recipes.

• CLI alternatives: pip install fal gives fal api <endpoint> key=value key:=json; the genmedia CLI
  (genmedia run ... --json --download) is agent-friendly too.

Which interface

• Discovery (what's the best model for X right now, its inputs, its price): fal MCP
  recommend_model / search_models / get_model_schema / get_pricing, or um fal search,
  um fal schema <endpoint>, um fal price <endpoint>. The catalog changes weekly. The defaults below were
  current in September 2026; check before a big batch.

• Anything that must land on disk (every game asset): um fal <recipe>. It uploads local inputs,
  queues, polls, downloads every output file, and appends the endpoint, inputs, seed and request id to
  <out>/fal_manifest.jsonl, so every asset can be traced and regenerated.

• Quick look or one-off where a URL is enough: MCP run_model.

Recipes (um fal <recipe> --help for options; --model overrides the endpoint; --set k=v passes extra inputs)

Other useful endpoints:

• 3D: tripo3d/tripo/remesh and fal-ai/meshy/v5/remesh (low-poly, game-ready), fal-ai/trellis-2/retexture.
• Motion: fal-ai/hunyuan-motion (text → motion).
• Icons: fal-ai/recraft/v4.1/text-to-vector (SVG icons).
• Video cutouts: pixelcut/video-background-removal.
• Music: google/lyria-3.5.
• Voice: fal-ai/minimax/speech-2.8-hd.

Prompting game art that fits the game

• Look at the game's own assets first: pixel size, outline, palette, perspective, facing, how busy they
  are. Put that into a reusable style suffix. For Terraria: *"16-bit pixel art game sprite in the style of
  Terraria, crisp dark outline, limited palette, centered, plain flat white background, no shadow, no
  text"*.

• Describe the view and orientation explicitly: "perfectly horizontal side view with the muzzle pointing
  right" for held weapons, "seen from the side facing left" for enemies, "pointing straight down" for a
  falling bomb. Engines have conventions (Terraria items point right, NPCs face left) and fixing
  orientation afterwards costs quality.

• Backgrounds: transparent (gpt-image-2) or a flat colour that um sprite cutout can flood-fill.
  Avoid gradients, scenery and ground shadows. If a soft shadow sneaks in, use --grey / --keep-top
  in cutout.

• Player / team colour: ask for "bright saturated blue accents" on the parts that should take the
  player's colour, then um sprite team-mask --hue blue turns them into a mask.

• Consistency across a set: generate one hero image, then derive the rest with the edit endpoint and the
  hero as --ref ("same robot, now firing, muzzle flash"). Don't ask one prompt for a whole sprite sheet;
  grids come out uneven.

• Many angles or frames of the same object: go 3D. Take the concept, run um fal model3d, then
  um render3d from the game's camera (asset-pipeline skill). That's how the AoE2 robotaxi got 16
  consistent headings × 5 animations.

• No text or logos in art unless wanted: models love to add them.

Audio for engines

• The SFX and music endpoints return MP3. Convert to what the engine wants:

  • ffmpeg -i x.mp3 -ar 44100 x.wav (XNA/tModLoader, most engines);
  • ffmpeg -i x.mp3 -c:a libvorbis -q:a 5 x.ogg (Minecraft, Godot, Unity);
  • trim silence first: -af silenceremove=start_periods=1:start_threshold=-50dB.
• Loops: um fal sfx ... --loop, or ask the music model for a loopable track and crossfade the ends.

• Keep SFX short (0.2-2 s) and normalize loudness (-af loudnorm=I=-16) so they sit with the game's own
  sounds.

Cost and etiquette

• Price the expensive stuff: before batching 3D, video or long music, check the price
  (um fal price <endpoint> / MCP get_pricing). For more than about 20 generations or anything
  video-sized, tell the user the rough cost first.

• Iterate cheap: use low quality or resolution while exploring (--quality low, --res 0.5K), then
  re-run the winners at full quality with the same prompt (and seed where supported).

• Reproducibility: keep fal_manifest.jsonl with the assets; it records prompts, seeds and request ids.

• Credits: in the mod's README, credit that assets were generated with fal and name the models. Check a
  model's license page for commercial use.