{"id":67997,"plugin_id":"plugin_asdk_app_6accf4d13858819195c734fdaa2713d3","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-10-28T13:12:03.396Z","digest":"3f0711897f13438e0ac2acef185ae712ac3abae1fa225ca4a71001a42127f372","against":null,"payload":{"description":"Implementation guide for using SpriteCook top-down 15-piece tilesets with a dual-grid autotile renderer. Use when explaining or coding how to map a 4x4 15-piece tileset image into terrain using SpriteCook's dual-grid mask system.","included_files":[],"name":"spritecook-use-dual-grid-tilesets","skill_md_contents":"---\nname: spritecook-use-dual-grid-tilesets\ndescription: \"Implementation guide for using SpriteCook top-down 15-piece tilesets with a dual-grid autotile renderer. Use when explaining or coding how to map a 4x4 15-piece tileset image into terrain using SpriteCook's dual-grid mask system.\"\n---\n\n# SpriteCook Dual-Grid 15-Piece Tilesets\n\nUse this skill when implementing a top-down 15-piece SpriteCook tileset in a game engine or custom renderer.\n\nThis skill is about using a generated tileset. For generation, use `spritecook-generate-tilesets`.\n\n## Concept\n\nA dual-grid tileset stores terrain as logical painted cells, then renders visible tiles between those cells. Each rendered tile is chosen from the four logical cells around it.\n\nFor each rendered tile, sample:\n\n- top-left logical cell\n- top-right logical cell\n- bottom-left logical cell\n- bottom-right logical cell\n\nThat four-cell pattern becomes a 4-bit mask. The mask chooses one frame from the 4x4 15-piece atlas.\n\n## Mask Order\n\nUse SpriteCook's current mask bit order:\n\n```ts\nlet mask = 0\nif (filled(x - 1, y - 1)) mask |= 1 // top-left\nif (filled(x,     y - 1)) mask |= 2 // top-right\nif (filled(x - 1, y    )) mask |= 4 // bottom-left\nif (filled(x,     y    )) mask |= 8 // bottom-right\n```\n\nMask `0` renders nothing. Other masks map into the 4x4 atlas through this lookup:\n\n```ts\nconst frameByMask = [\n  -1,\n  15,\n  8,\n  9,\n  0,\n  11,\n  14,\n  7,\n  13,\n  4,\n  1,\n  10,\n  3,\n  2,\n  5,\n  6,\n]\n```\n\nThe atlas cell is:\n\n```ts\nconst frame = frameByMask[mask]\nif (frame < 0) return null\nconst atlasColumn = frame % 4\nconst atlasRow = Math.floor(frame / 4)\n```\n\n## Renderer Pseudocode\n\n```ts\ntype CellMap = boolean[] // width * height logical terrain cells\n\nfunction cellIndex(x: number, y: number, columns: number) {\n  return y * columns + x\n}\n\nfunction isFilled(cells: CellMap, x: number, y: number, columns: number, rows: number) {\n  return x >= 0 && y >= 0 && x < columns && y < rows && cells[cellIndex(x, y, columns)] === true\n}\n\nfunction dualGridMask(cells: CellMap, x: number, y: number, columns: number, rows: number) {\n  let mask = 0\n  if (isFilled(cells, x - 1, y - 1, columns, rows)) mask |= 1\n  if (isFilled(cells, x,     y - 1, columns, rows)) mask |= 2\n  if (isFilled(cells, x - 1, y,     columns, rows)) mask |= 4\n  if (isFilled(cells, x,     y,     columns, rows)) mask |= 8\n  return mask\n}\n\nfunction atlasCellForMask(mask: number) {\n  const frameByMask = [-1, 15, 8, 9, 0, 11, 14, 7, 13, 4, 1, 10, 3, 2, 5, 6]\n  const frame = frameByMask[Math.max(0, Math.min(15, Math.floor(mask)))]\n  if (frame < 0) return null\n  return { column: frame % 4, row: Math.floor(frame / 4) }\n}\n\nfunction renderDualGrid(ctx, atlasImage, cells: CellMap, columns: number, rows: number, tileSize: number) {\n  for (let y = 0; y <= rows; y += 1) {\n    for (let x = 0; x <= columns; x += 1) {\n      const mask = dualGridMask(cells, x, y, columns, rows)\n      const atlasCell = atlasCellForMask(mask)\n      if (!atlasCell) continue\n\n      ctx.drawImage(\n        atlasImage,\n        atlasCell.column * tileSize,\n        atlasCell.row * tileSize,\n        tileSize,\n        tileSize,\n        x * tileSize,\n        y * tileSize,\n        tileSize,\n        tileSize,\n      )\n    }\n  }\n}\n```\n\n## Two-Surface Tilesets\n\nTilesets generated with `edges=\"two_surfaces\"` (for example grass and water) have a second terrain. The frame lookup never uses atlas frame 12 (column 0, row 3, the bottom-left cell). In a two-surface set that cell holds the full counter-surface tile, such as open water.\n\nDraw the counter surface first, then the masked pieces on top:\n\n```ts\nconst counterSurfaceCell = { column: 0, row: 3 }\n\nfunction renderTwoSurfaceDualGrid(ctx, atlasImage, cells: CellMap, columns: number, rows: number, tileSize: number) {\n  for (let y = 0; y <= rows; y += 1) {\n    for (let x = 0; x <= columns; x += 1) {\n      ctx.drawImage(\n        atlasImage,\n        counterSurfaceCell.column * tileSize,\n        counterSurfaceCell.row * tileSize,\n        tileSize,\n        tileSize,\n        x * tileSize,\n        y * tileSize,\n        tileSize,\n        tileSize,\n      )\n    }\n  }\n  renderDualGrid(ctx, atlasImage, cells, columns, rows, tileSize)\n}\n```\n\nWithout this base layer, mask `0` areas render transparent and the second terrain disappears. For a single-surface (`transparent` edges) set, that cell is empty; skip the base layer.\n\n## Practical Notes\n\n- Render one more tile column and row than the logical map size because rendered tiles sit around painted logical cells.\n- For pixel art, disable smoothing and use nearest-neighbor scaling.\n- Treat mask `15` as the filled interior tile and mask `0` as transparent/no draw. In a two-surface set, mask `0` shows the counter-surface base layer.\n- Paint a test map before shipping a set. If the full tile (mask `15`) doesn't wrap, large filled areas show a visible checkerboard.\n- Use the generated atlas exactly as a 4x4 grid of equal tile-sized cells.\n- Do not reinterpret the sheet as a normal 8-neighbor blob tileset; this mapping is specifically SpriteCook's dual-grid 15-piece layout.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}