spritecook-generate-tilesets — Claude Code skill: tilesets via

---
name: spritecook-generate-tilesets
description: "Tileset generation guide for SpriteCook. Use with spritecook-workflow-essentials when generating autotile tilesets through SpriteCook MCP tools, choosing tile sizes, using reference/edit/style asset IDs, and saving generated tileset asset IDs."
---

# SpriteCook Generate Tilesets

Use this skill for SpriteCook tileset generation. Pair it with `spritecook-workflow-essentials` for credits, manifests, safe downloads, and asset tracking.

**Requires:** A connected SpriteCook MCP server. If disconnected, explain that connection is needed and use the host's native connection flow when authorized. Do not install software or change authentication settings as part of an art task.

## Tools

### `list_tileset_options`

Call this when you need current supported perspectives, piece sets, tile sizes, elevations, edge modes, output dimensions, or defaults.

### `generate_tileset`

Generate a game-ready tileset. The tool returns a job immediately by default; follow the returned `poll.tool` and `poll.arguments` until canonical `assets` entries are ready.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `prompt` | string | required | Terrain/material request, e.g. `mossy dungeon floor` |
| `style_mode` | string | `pixel` | `pixel` or `detailed` |
| `perspective` | string | `topdown` | `topdown`, `platformer`, or `isometric` |
| `piece_set` | string | registry default | `15-piece`, `17-piece-base`, `autotile-16-set`, `isometric-3x5-32`, or `isometric-2x4-64` |
| `tile_size` | int | registry default | Final tile size in pixels |
| `elevation` | string | registry default | `no-elevation` or `minimal` where supported |
| `edges` | string | `transparent` | `transparent` or `two_surfaces`; `two_surfaces` only works for 15-piece top-down |
| `variations` | int | `1` | Number of variations, 1-4 |
| `model` | string | null | Optional model override. Omit to use SpriteCook's tileset default |
| `colors` | string[] | null | Optional hex color guidance, max 64 |
| `force_enabled` | bool | `false` | Force the output toward `force_colors` |
| `force_colors` | string[] | null | Optional forced hex palette, max 64 |
| `project_id` | string | null | Owned project to place the tileset in |
| `reference_asset_id` | string | null | Existing tileset asset to use as source/reference; tileset settings are inherited |
| `edit_asset_id` | string | null | Existing tileset asset to edit; tileset settings are inherited |
| `style_asset_id` | string | null | Existing asset to use as visual style guide only |
| `wait_seconds` | int | 0 | Optional bounded wait from 0-90 seconds before returning the polling contract |

`reference_asset_id` and `edit_asset_id` are mutually exclusive. The referenced asset must belong to the SpriteCook account.

## Recommended Defaults

- For top-down pixel autotiles, start with `style_mode="pixel"`, `perspective="topdown"`, `piece_set="15-piece"`, `tile_size=32`, `edges="transparent"`.
- For top-down inner-corner base tiles, use `piece_set="17-piece-base"` and keep `edges="transparent"`.
- For side-view platformers, use `perspective="platformer"`, `piece_set="autotile-16-set"`, `edges="transparent"`.
- For detailed top-down tilesets, use `style_mode="detailed"` and call `list_tileset_options` before choosing size/elevation.
- Use `model` only when the user explicitly wants to compare models.

## Reference Workflow

- When the user asks to use a saved tileset preset, use `list_presets(mode="tileset", query=...)` and `get_preset_settings` first, then map the returned tileset settings into `generate_tileset`.
- If the user has a local image file path, use `spritecook-upload-assets` first, then pass the returned asset ID as `reference_asset_id`, `edit_asset_id`, or `style_asset_id`.
- If the user supplies a small data URL or raw base64 value, call `import_asset` first, then pass the returned asset ID as `reference_asset_id`, `edit_asset_id`, or `style_asset_id`.
- Use `reference_asset_id` when the existing tileset should guide a new generation while preserving its tile size/layout.
- Use `edit_asset_id` when the user wants a direct change to an existing tileset.
- Use `style_asset_id` as a style guide image when the image should affect only visual style, palette, proportions, and rendering, not tileset layout. The prompt does not need to repeat that the image is a style guide unless the user asks to emphasize a specific detail.
- When referencing or editing a tileset, do not change `style_mode`, `perspective`, `piece_set`, `tile_size`, or `elevation`; SpriteCook inherits and locks those settings.
- `edges` is not inherited. When the source is a `two_surfaces` set, pass `edges="two_surfaces"` again on every edit or reference generation; otherwise the request falls back to `transparent`.
- Edits and reference generations skip the layout guide grid that fresh generations use, so they fail or produce pieces that don't tile more often. An edit can fail with `tileset_unusable`; the credits are refunded. When an edit fails twice, generate from the set as `reference_asset_id` or start fresh with a clearer prompt instead of retrying the same edit.

## Prompting

- Keep prompts short and material-focused: `snowy stone path`, `muddy swamp grass`, `volcanic rock`, `clean wooden floor`.
- For single-surface tilesets, name one main material.
- For `two_surfaces`, name both surfaces clearly: `grass and water`, `volcanic rock and lava`.
- Avoid asking for labels, UI, characters, props, or scene composition inside the tileset.

## Output Handling

- Pass `wait_seconds=90` on `generate_tileset`; most tilesets finish inside it, so polling is rarely needed. Otherwise follow the returned polling contract with `check_job_status` until the job reaches a terminal state.
- Check every variation before using it. About one in three can have a full interior tile that doesn't wrap (opposite edges differ in brightness) or pieces that don't meet cleanly, and the response doesn't flag it. Compare the full tile's left and right edges and its top and bottom edges, and paint a small test map with `spritecook-use-dual-grid-tilesets` for 15-piece sets. A full tile that doesn't wrap shows as a checkerboard over large areas. Pick a clean variation or regenerate.
- 15-piece sets keep the grid's stepped silhouette on diagonals. Shorelines get a soft edge, but a diagonal coast still reads as steps.
- Save each returned `asset_id` in the project manifest or task notes.
- Use `sprite_url` as the canonical downloadable tileset image.
- Treat `url`, `pixel_url`, and `raw_url` as compatibility aliases.
- If a successful response contains `warning.code="asset_output_unavailable"`, execute the supplied `warning.recovery` tool call.