lords-of-ash/.claude/skills/asset-gen/SKILL.md

---
name: asset-gen
description: >
  Generate themed visual assets for the Lords of Ash CK3 total conversion mod
  using the generate_image MCP tool (Nano Banana / Gemini 2.5 Flash Image).
  Use when generating any mod art: trait icons, modifier icons, decision
  illustrations, event backgrounds, loading screens, bookmark art, coat of arms
  emblems, religion icons, building icons, MaA icons, lifestyle assets, scheme
  icons, focus icons, activity assets, workshop thumbnail, or frontend art.
  Also use when the user asks about visual identity, art direction, asset
  pipeline, or DDS conversion. Triggers on: "generate icons", "make trait art",
  "create loading screen", "asset pipeline", "convert to DDS", "art style",
  "generate assets", "batch generate".
---

# Asset Generation — Lords of Ash

Generate visually consistent, CK3-native art assets using the `generate_image`
MCP tool.

Asset descriptions, filenames, resolutions, and directory paths are documented
in `docs/REQUIRED_ASSETS.md`. This skill provides the visual identity, prompt
system, and workflow.

## Prompt Assembly

Every `generate_image` call uses three parts:

```
[STYLE PREFIX] + [CATEGORY TEMPLATE] + [ASSET DESCRIPTION from docs/REQUIRED_ASSETS.md]
```

Never call `generate_image` with just the asset description. Always prepend the
style prefix and matching category template.

- **Style prefix and color palette**: Read `references/style-guide.md`
- **Category templates**: Read `references/category-templates.md` and match by
  asset type (trait icon, modifier icon, decision illustration, etc.)
- **Asset description**: Look up the specific asset in `docs/REQUIRED_ASSETS.md`

## Aspect Ratio Mapping

| Asset Type | Pixel Size | `aspect_ratio` |
|------------|-----------|----------------|
| All square icons | various | `1:1` |
| Decision illustrations | 1100x440 | `5:2` (fallback: `16:9` + crop) |
| Event backgrounds | 1592x848 | `16:9` |
| Loading screens | 3840x2160 | `16:9` |
| Bookmark art | 1920x1080 | `16:9` |
| Frontend art | 3840x2160 | `16:9` |
| Activity headers | 1100x440 | `5:2` (fallback: `16:9` + crop) |
| Lifestyle strips | 480x160 | `3:1` (fallback: `16:9` + crop) |
| Perk tree backgrounds | 348x812 | `9:16` + crop |
| Lifestyle sidebars | 608x1552 | `9:16` + crop |

If the tool doesn't support an exact ratio, generate at the nearest standard
ratio and resize/crop with ImageMagick.

## Single Asset Workflow

1. Find the asset in `docs/REQUIRED_ASSETS.md` — note filename, resolution,
   directory, DDS format, and description.
2. Read `references/style-guide.md` for the style prefix.
3. Read `references/category-templates.md` for the matching template.
4. Assemble the full prompt and call `generate_image` with correct `aspect_ratio`.
5. Save the PNG to `lords_of_ash/` at the correct `gfx/` path.
6. Report what was generated.

## Batch Workflow

When generating multiple assets of the same type:

1. Read the style prefix and category template once.
2. Iterate through assets in `docs/REQUIRED_ASSETS.md` for that category.
3. Use the same style prefix and template for every asset.
4. Call `generate_image` in batches of **no more than 3 parallel calls** at a
   time. Wait for each batch to complete before starting the next. This avoids
   overwhelming the image generation API.
5. Save PNGs to correct paths after each batch.
6. Report summary: count generated, failures, paths written.

## Modifier Coin Base

All modifier icons use a shared hammered-metal coin base for visual cohesion.
Pass it as `inputImagePath` when generating modifier icons:

```
~/Pictures/mcp-images/icons/modifiers/modifier_base_coin.png
```

Use the stronger prompt pattern to keep the model on the coin base:

> On a weathered dark steel-silver coin with rough beveled edges and warm
> gold-amber rim glow, against a dark navy-charcoal swirled background.
> CK3 game modifier icon, painterly style. Embossed relief on the coin
> surface of [MOTIF]. The motif is engraved into the smooth grey coin face
> as a bas-relief.

If the model drifts (different edge style, wrong background), regenerate — the
coin base consistency is critical for the set to look cohesive at 60x60.

## PNG Output Directory Structure

Generated PNGs are saved under `~/Pictures/mcp-images/`. Mirror the mod's
`gfx/` directory structure so source PNGs are organized the same way as the
final DDS files:

```
~/Pictures/mcp-images/
  icons/modifiers/          → modifier icons (60x60)
  icons/traits/             → trait icons (120x120)
  icons/faith/              → faith icons (100x100)
  icons/buildings/          → building icons (60x60)
  icons/maa/                → MaA regiment icons (60x60)
  icons/focuses/            → focus icons (140x140)
  icons/schemes/            → scheme icons (120x120)
  icons/casus_belli/        → casus belli icons (60x60)
  illustrations/decisions/  → decision illustrations (1100x440)
  event_backgrounds/        → event scene backgrounds (1592x848)
  loading_screens/          → loading screens (3840x2160)
  bookmarks/                → bookmark art (1920x1080)
  frontend/                 → frontend/menu art (3840x2160)
  coat_of_arms/             → CoA emblems (128x128)
  lifestyles/               → lifestyle strips, sidebars, perk trees
```

Use the `fileName` parameter with the subdirectory path (e.g.,
`icons/modifiers/modifier_foo.png`) to save directly into the right location.
Do not save PNGs loose in the root `mcp-images/` directory.

When regenerating an asset, overwrite the existing file — do not create
versioned copies (`_v2`, `_v3`, etc.).

## DDS Conversion

CK3 requires DDS format. After generating PNGs, convert using the format
mapping and commands in `references/dds-conversion.md`.

All output paths are under `lords_of_ash/gfx/`. The full directory structure is
documented at the end of `docs/REQUIRED_ASSETS.md`.

## Critical Rules

- Always prepend the style prefix — without it, images drift in style.
- Icons need dark/near-black backgrounds — light backgrounds break CK3 UI.
- Trait icons are 120x120, NOT 60x60. Modifier icons are 60x60.
- Trait icons MUST be uncompressed ARGB in DDS, not DXT5.
- CoA emblems MUST be uncompressed ARGB for the color mask system.
- Modifier icons need mipmaps; trait icons do not.
- Decision illustrations: weight composition right (left side has UI overlay).
- Filenames are case-sensitive on Linux — match mod code exactly.
- Append "absolutely no text, no letters, no words, no labels, no titles, no
  captions, no watermarks" to icon prompts — the model tends to add text despite
  weaker phrasing.
- Never use circular medallion/coin framing for icons — the model defaults to
  round compositions which leave white/light corners on a square canvas. Enforce
  "flat square, dark background edge-to-edge" in the prompt.
- Icons must be symbolic motifs only, not scenes or landscapes. If the model
  generates an environment instead of an icon, the prompt needs stronger
  "this is an icon, not a scene" language.
- Enforce painterly style explicitly — the model sometimes drifts to vector/flat
  graphic/mobile game art. Add "painterly style only — NOT vector art, NOT flat
  graphic design, NOT mobile game art" when this happens.
- For trait families that form a progression (e.g. weak/strong/savant), describe
  the same base motif in each prompt and only vary the intensity/effects. Specify
  orientation ("horizontal", "not tilted") to keep compositions consistent.
- Allomantic energy uses cyan-blue, never green or purple.

## Quality Checklist

After generating, verify:
- Colors match the palette (no oversaturated neons, no pastels)
- Composition matches the category template
- No unwanted text, labels, or signatures
- Dark/near-black background for icons
- Resolution correct (or needs crop/resize)
- Visually distinguishable from similar assets in same category
- Ash, mist, or metallic elements present where appropriate