spritecook-generate-tilesets

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.