perf: find sprites by content key, and draw stand-ins in tests

Every sprite image was a PNG encoded on the main thread as the modules
loaded, in the browser and in every test worker alike, with no way to
hand the game an image built ahead of time.

Each sprite now has a content key: a 53 bit hash of a pixel map's size,
rows, and palette, or of a baked sprite's runs. src/spriteAtlas.ts holds
an atlas, a manifest from key to a box in a prebuilt file, and a
sprite the atlas holds is drawn as a cropped region of that file with no
pixel work. A key it lacks is encoded as before, so nothing changes until
a build provides an atlas, and the browser's images are byte for byte
the same (one hash over every built source before and after).

Tests run in stand-in mode, set in src/vitest-setup.ts: a sprite gets a
data URL named by its key instead of an encoded PNG, and its pixels are
kept so src/testPng.ts reads them back as before. Importing the game in
a fresh test module now takes about 300 ms instead of 395 ms, steady
state over four files, so each worker spends about 90 ms less.

Author: Tanner-Scadden

src/png.ts

@@ -142,6 +142,25 @@ const scanlinesOf = (
   return lines
 }
 
+// NOTE: the RGBA pixels the PNG holds, row after row with no filter bytes,
+// for tests and the atlas generator to read without a PNG decoder.
+export const rasterOf = (
+  width: number,
+  height: number,
+  fills: ReadonlyArray<Fill>,
+): Uint8Array => {
+  const lines = scanlinesOf(width, height, fills)
+  const raster = new Uint8Array(width * height * BYTES_PER_PIXEL)
+  for (let y = 0; y < height; y++) {
+    const start = y * rowLength(width) + 1
+    raster.set(
+      lines.subarray(start, start + width * BYTES_PER_PIXEL),
+      y * width * BYTES_PER_PIXEL,
+    )
+  }
+  return raster
+}
+
 // PNG
 
 const CRC_TABLE: ReadonlyArray<number> = Array.makeBy(256, byte =>

src/sprite.scene.test.ts

@@ -2,7 +2,7 @@ import { Array, Option, Record, pipe } from 'effect'
 import { Canvas } from 'foldkit'
 import type { Html, HtmlBuilder } from 'foldkit/html'
 import { given, scene } from 'foldkit/scene'
-import { describe, expect, test } from 'vitest'
+import { afterEach, describe, expect, test } from 'vitest'
 
 import { playerSprites } from './appearance'
 import { COIN_SPRITE, GLYPH_SPRITES } from './font'
@@ -18,6 +18,7 @@ import {
   spriteDataUrl,
   spriteShapes,
 } from './sprite'
+import { standInKeyOf, useSpriteAtlas, useSpriteMode } from './spriteAtlas'
 import { decodePng, hexOf } from './testPng'
 
 // PIXEL MAPS
@@ -180,6 +181,88 @@ describe('sprite images', () => {
   })
 })
 
+// PREBUILT SPRITES
+
+const keyOf = (shapes: ReadonlyArray<Canvas.Shape>): string =>
+  Option.getOrThrow(standInKeyOf(onlyImage(shapes).src))
+
+const ATLAS_FILE = 'sprites.png'
+
+describe('prebuilt sprites', () => {
+  afterEach(() => {
+    useSpriteAtlas({ sources: [], entries: {} })
+    useSpriteMode('StandIn')
+  })
+
+  test('a stand-in holds the same pixels as the encoded PNG', () => {
+    const standIn = onlyImage(spriteShapes(PIXELS, PALETTE))
+    expect(standInKeyOf(standIn.src)).toEqual(Option.some(keyOf([standIn])))
+    expect(decodePng(standIn.src)).toEqual(
+      Option.flatMap(spriteDataUrl(PIXELS, PALETTE), decodePng),
+    )
+  })
+
+  test('the same pixel map and colors always get the same key', () => {
+    expect(keyOf(spriteShapes([...PIXELS], { ...PALETTE }))).toBe(
+      keyOf(spriteShapes(PIXELS, PALETTE)),
+    )
+    expect(keyOf(spriteShapes(PIXELS, { ...PALETTE, R: '#000000' }))).not.toBe(
+      keyOf(spriteShapes(PIXELS, PALETTE)),
+    )
+  })
+
+  test('a sprite in the atlas is a cropped region of its file, placed by its anchor', () => {
+    const key = keyOf(spriteShapes(PIXELS, PALETTE))
+    useSpriteAtlas({
+      sources: [ATLAS_FILE],
+      entries: { [key]: [0, 7, 9, 5, 6] },
+    })
+    expect(onlyImage(spriteShapes(PIXELS, PALETTE, { x: 2, y: 6 }))).toEqual(
+      Canvas.Image({
+        src: ATLAS_FILE,
+        x: -2,
+        y: -6,
+        width: 5,
+        height: 6,
+        crop: { x: 7, y: 9, width: 5, height: 6 },
+        rendering: 'Pixelated',
+      }),
+    )
+  })
+
+  test('a sprite the atlas marks empty draws nothing', () => {
+    const key = keyOf(spriteShapes(PIXELS, PALETTE))
+    useSpriteAtlas({ sources: [ATLAS_FILE], entries: { [key]: null } })
+    expect(spriteShapes(PIXELS, PALETTE)).toEqual([])
+  })
+
+  test('baked rectangles in the atlas are found by their content, wherever they stand', () => {
+    const rects = (x: number) => [
+      Canvas.Rect({ x, y: 3, width: 3, height: 2, fill: '#000000' }),
+      Canvas.Rect({ x: x + 1, y: 3, width: 1, height: 1, fill: '#ffffff' }),
+    ]
+    const key = keyOf(bakeShapes(rects(2)))
+    expect(keyOf(bakeShapes(rects(40)))).toBe(key)
+    useSpriteAtlas({
+      sources: [ATLAS_FILE],
+      entries: { [key]: [0, 1, 1, 3, 2] },
+    })
+    expect(onlyImage(bakeShapes(rects(40)))).toMatchObject({
+      src: ATLAS_FILE,
+      x: 40,
+      y: 3,
+      crop: { x: 1, y: 1, width: 3, height: 2 },
+    })
+  })
+
+  test('a sprite the atlas lacks is encoded as a PNG outside the tests', () => {
+    useSpriteMode('Encode')
+    expect(onlyImage(spriteShapes(PIXELS, PALETTE)).src).toBe(
+      Option.getOrThrow(spriteDataUrl(PIXELS, PALETTE)),
+    )
+  })
+})
+
 // PAINTER
 
 type DrawCall = ReadonlyArray<unknown>

src/sprite.ts

@@ -3,6 +3,14 @@ import { Canvas } from 'foldkit'
 
 import type { PickupKind, TrapKind, WeaponKind, ZombieKind } from './model'
 import { type Fill, parseColor, pngDataUrl } from './png'
+import {
+  type AtlasHit,
+  atlasLookup,
+  spriteKeyOf,
+  spriteMode,
+  standInKeyOf,
+  standInSource,
+} from './spriteAtlas'
 import type { TrapStage } from './traps'
 
 export type Palette = Readonly<Record<string, string>>
@@ -213,26 +221,114 @@ const imageAt = (
   return Canvas.Image({ src, x, y, width, height, rendering: 'Pixelated' })
 }
 
-// NOTE: a sprite is one image of its pixel map, drawn with a single
-// drawImage, instead of a rectangle for each run of same colored pixels. A
-// palette color that is not a hex or rgb() color keeps the rectangles.
-export const spriteShapes = (
+// NOTE: a prebuilt sprite is a cropped region of one of the atlas's files.
+const atlasImageAt = (hit: AtlasHit, x: number, y: number): Canvas.Image => {
+  builtSpriteSources.add(hit.src)
+  return Canvas.Image({
+    src: hit.src,
+    x,
+    y,
+    width: hit.width,
+    height: hit.height,
+    crop: { x: hit.x, y: hit.y, width: hit.width, height: hit.height },
+    rendering: 'Pixelated',
+  })
+}
+
+// CONTENT
+
+export type SpriteContent = Readonly<{
+  width: number
+  height: number
+  fills: ReadonlyArray<Fill>
+}>
+
+const contentsByKey = new Map<string, SpriteContent>()
+
+// NOTE: every sprite built in stand-in mode, by key, with its pixels as the
+// fills to paint. The atlas generator packs these, and tests read them.
+export const spriteContents = (): ReadonlyMap<string, SpriteContent> =>
+  contentsByKey
+
+export const spriteContentOf = (src: string): Option.Option<SpriteContent> =>
+  Option.flatMap(standInKeyOf(src), key =>
+    Option.fromNullishOr(contentsByKey.get(key)),
+  )
+
+// NOTE: the image for a sprite the atlas does not hold: a stand-in named by
+// its key in stand-in mode, else a PNG data URL encoded here. None when a
+// palette color cannot be read, so the caller keeps rectangles.
+const builtSource = (
+  key: string,
+  width: number,
+  height: number,
+  runs: ReadonlyArray<PixelRun>,
+): Option.Option<string> => {
+  if (spriteMode() === 'Encode') {
+    return runsDataUrl(width, height, runs)
+  }
+  return Option.map(fillsOf(runs), fills => {
+    contentsByKey.set(key, { width, height, fills })
+    return standInSource(key)
+  })
+}
+
+// NOTE: a pixel map's key: its size, its rows, and its palette in symbol
+// order, so the same map and colors always find the same prebuilt image.
+const pixelsKeyOf = (
+  width: number,
   pixels: ReadonlyArray<string>,
   palette: Palette,
-  anchor: Anchor = centerAnchor(pixels),
+): string => {
+  let text = `p${width}x${pixels.length}`
+  for (const row of pixels) {
+    text += `\n${row}`
+  }
+  for (const symbol of Object.keys(palette).sort()) {
+    text += `\n${symbol}=${palette[symbol] ?? ''}`
+  }
+  return spriteKeyOf(text)
+}
+
+const builtSpriteShapes = (
+  key: string,
+  pixels: ReadonlyArray<string>,
+  palette: Palette,
+  anchor: Anchor,
+  width: number,
 ): ReadonlyArray<Canvas.Shape> => {
   const runs = rowRunsOf(pixels, palette)
-  const width = spriteWidth(pixels)
   if (Array.isReadonlyArrayEmpty(runs)) {
     return []
   }
 
-  return Option.match(runsDataUrl(width, pixels.length, runs), {
+  return Option.match(builtSource(key, width, pixels.length, runs), {
     onNone: () => spriteRects(pixels, palette, anchor),
     onSome: src => [imageAt(src, -anchor.x, -anchor.y, width, pixels.length)],
   })
 }
 
+// NOTE: a sprite is one image of its pixel map, drawn with a single
+// drawImage, instead of a rectangle for each run of same colored pixels. A
+// prebuilt one is found by its key with no pixel work at all. A palette color
+// that is not a hex or rgb() color keeps the rectangles.
+export const spriteShapes = (
+  pixels: ReadonlyArray<string>,
+  palette: Palette,
+  anchor: Anchor = centerAnchor(pixels),
+): ReadonlyArray<Canvas.Shape> => {
+  const width = spriteWidth(pixels)
+  const key = pixelsKeyOf(width, pixels, palette)
+  return Option.match(atlasLookup(key), {
+    onNone: () => builtSpriteShapes(key, pixels, palette, anchor, width),
+    onSome: maybeHit =>
+      Option.match(maybeHit, {
+        onNone: () => [],
+        onSome: hit => [atlasImageAt(hit, -anchor.x, -anchor.y)],
+      }),
+  })
+}
+
 type Box = Readonly<{
   left: number
   top: number
@@ -325,9 +421,18 @@ export const bakeShapes = (
     height: run.height,
     color: run.color,
   }))
-  return Option.match(runsDataUrl(width, height, shifted), {
-    onNone: () => shapes,
-    onSome: src => [imageAt(src, box.left, box.top, width, height)],
+  const key = spriteKeyOf(`r${contentKeyOf(width, height, shifted)}`)
+  return Option.match(atlasLookup(key), {
+    onNone: () =>
+      Option.match(builtSource(key, width, height, shifted), {
+        onNone: () => shapes,
+        onSome: src => [imageAt(src, box.left, box.top, width, height)],
+      }),
+    onSome: maybeHit =>
+      Option.match(maybeHit, {
+        onNone: () => [],
+        onSome: hit => [atlasImageAt(hit, box.left, box.top)],
+      }),
   })
 }