FTL Mod Generator
Generate complete, playable FTL: Faster Than Light mods from a simple text prompt. This skill orchestrates LLM-powered content generation, sprite creation, XML validation, and Slipstream mod patching.
What This Skill Does
Transforms a theme like "rogue scientists with unstable laser weapons" into a complete FTL mod containing:
Themed weapons with 12-frame spritesDrones with 4-frame spritesAugments and crew racesEvents with choices and outcomesValidated XML integrated via SlipstreamPrerequisites
Before generating mods, ensure:
1. FTL: Faster Than Light is installed
2. Slipstream mod manager is set up
3. API keys configured in `.env`:
- Claude or OpenAI for content generation
- Google Gemini for sprite generation
4. Python environment with `ftl-gen` installed (`pip install -e ".[dev]"`)
Generation Process
1. Gather Requirements
Ask the user:
**Theme**: What's the mod concept? (e.g., "cyberpunk hackers", "ancient aliens")**Content counts**: How many of each item type? - Weapons (-w)
- Events (-e)
- Drones (-d)
- Augments (-a)
- Crew (-c)
**Options**: Validate? Patch? Run game? Cache images?2. Build Command
**CRITICAL**: Always specify all content flags explicitly. Never run `ftl-gen mod` without `-w`, `-e`, `-d`, `-a`, `-c` flags as it triggers interactive prompts.
```bash
ftl-gen mod "theme" -w5 -e3 -d2 -a1 -c0 --validate --patch --run
```
Flags:
`--validate`: Run Slipstream validation`--patch`: Apply mod to FTL installation`--run`: Launch game after patching`--cache-images`: Reuse previously generated sprites3. Execute Generation
Run the command via Bash tool. The generator:
Creates LLM prompts constrained to valid FTL mechanicsGenerates JSON for each item typeValidates descriptions (catches impossible mechanics)Converts to XML using Pydantic schemasGenerates sprites via Gemini (green screen backgrounds removed)Builds sprite sheets (weapons: 16x60x12, drones: 50x20x4)Packages into `.ftl` mod fileValidates with SlipstreamOptionally patches and runs4. Handle Errors
Common issues:
**Validation failures**: XML doesn't match FTL schema - check `src/xml/validators.py`**Description mismatches**: LLM described impossible mechanics - regenerate that item**Sprite generation fails**: Gemini API issue - retry or use `--cache-images`**Slipstream errors**: Java/path issues - verify Slipstream setup in config5. Verify Results
Check:
Mod appears in `output/mods/{theme}/` directoryItems show up in FTL stores when game runsNo crashes or graphical glitchesBalance feels reasonable (not too OP/useless)Known Limitations
Inform users of current constraints:
**Events defined but don't trigger** - not hooked into sector pools yet**Ships need manual layouts** - only blueprints generated, no room files**Crew won't spawn naturally** - not integrated into enemy/hire pools**No Hyperspace support** - advanced features (lua scripting, custom systems) unavailable**Limited sprites** - weapons/drones only, no crew animations or ship hullsExample Usage
```bash
Generate pirate-themed mod with weapons and events
ftl-gen mod "space pirates with ramshackle weaponry" -w5 -e3 -d2 -a1 -c0 --validate --patch
Quick test with minimal content
ftl-gen mod "test faction" -w1 -e0 -d0 -a0 -c0 --validate
Full generation with all options
ftl-gen mod "ancient precursors" -w8 -e5 -d4 -a3 -c2 --cache-images --validate --patch --run
```
Project Structure Reference
Key files when debugging or extending:
`src/ftl_gen/cli.py` - Command interface`src/ftl_gen/core/generator.py` - Main orchestration logic`src/ftl_gen/llm/prompts.py` - Content generation prompts (constrain these to fix invalid output)`src/ftl_gen/images/sprites.py` - Sprite sheet assembly`src/ftl_gen/xml/validators.py` - XML validation rulesImportant Notes
**Never omit content flags** - always specify `-w`, `-e`, `-d`, `-a`, `-c` counts**Image generation costs money** - Gemini API charges per sprite, use `--cache-images` when iterating**Validation is essential** - always use `--validate` to catch XML errors before patching**Backup FTL installation** - Slipstream patching modifies game files**Check game version** - Some features require specific FTL versions