// Stills ("animations": {}): the flipbook they keep for viewing is never offered as an animation. Patches, the render // check, inspect, validate --fps, pixel_render's animation and saveAs, and every exported atlas say so. import test from 'node:test'; import assert from 'node:assert/strict'; import { spawnSync } from 'node:child_process'; import { mkdtemp, rm, writeFile, readFile } from 'node:fs/promises'; import { PassThrough } from 'node:stream'; import os from 'node:os'; import path from 'node:path'; import { fileURLToPath } from 'node:url'; import { renderProject, inspectProject, analyzeProject, briefDiagnostics, compareProjects, briefComparison, buildAtlas, exportAtlas, PixelError } from '../src/core.js'; import { patchRecipe } from '../src/patch.js'; import { checkDelivery } from '../src/check.js'; import { frameGrid } from '../src/sequence.js'; import { createBundle } from '../src/export.js'; import { inspectMotion } from '../src/motion.js'; import { compilePoses, compileAutotile } from '../src/authoring.js'; import { startMCP } from '../src/mcp.js'; import { loadEngine } from '../playground/render.js'; import { handleRequest } from '../playground/worker.js'; import { stampRig } from '../scripts/pose-fixtures.mjs'; const root = fileURLToPath(new URL('../', import.meta.url)); // A health bar's four states: one, two and three pixels, then full. const bar = { version: 1, name: 'hp', width: 8, height: 1, palette: { g: '#00ff00' }, frames: [1, 2, 3, 8].map((n, i) => ({ name: `s${i + 1}`, ops: [{ op: 'rect', x: 0, y: 0, w: n, h: 1, color: 'g' }] })), animations: {} }; const stillsText = /^the frames are stills \("animations": \{\} in the recipe\), so there is no animation to choose: list the frames to play under "animations".*remove the field to play every frame in order$/; const temp = async t => { const base = path.resolve(os.tmpdir()), dir = await mkdtemp(path.join(base, 'pixelbolt-stills-')); t.after(async () => { assert.ok(dir.startsWith(base + path.sep)); await rm(dir, { recursive: true, force: true }); }); return dir; }; const cli = (...args) => spawnSync(process.execPath, ['bin/pixelbolt.js', ...args], { cwd: root, encoding: 'utf8' }); test('a patch that removes the last animation says once that the frames are now stills, with no phantom "default"', async t => { const walk = { ...bar, animations: { walk: { frames: ['s1', 's2'] } } }; const reply = recipe => { const { image, ...report } = compareProjects(renderProject(walk), renderProject(recipe)); return briefComparison(report); }; const removed = patchRecipe(walk, [{ remove: 'animations.walk' }]).recipe; assert.deepEqual(removed.animations, {}); const brief = reply(removed); assert.deepEqual(brief.animations, { removed: ['walk'] }); assert.match(brief.stills, /^the frames are now stills \("animations": \{\}\): .*remove the animations field to play every frame in order again/); // Back from stills: the named animation is added, and nothing called "default" was removed. const { image, ...back } = compareProjects(renderProject(bar), renderProject(walk)); assert.deepEqual([back.animations, back.stills], [{ added: ['walk'] }, undefined]); // Stills to stills say nothing of animations. The flipbook of a recipe that left the field out was played, as // "default", so turning it into stills removes it. const same = briefComparison(compareProjects(renderProject(bar), renderProject(bar))); assert.deepEqual([same.animations, same.stills], [undefined, undefined]); const flipbook = briefComparison(compareProjects(renderProject({ ...bar, animations: undefined }), renderProject(bar))); assert.deepEqual(flipbook.animations, { removed: ['default'] }); assert.match(flipbook.stills, /now stills/); // The CLI's patch reply is shaped the same way. const dir = await temp(t), file = path.join(dir, 'walk.json'), changes = path.join(dir, 'changes.json'); await writeFile(file, JSON.stringify(walk)); await writeFile(changes, JSON.stringify([{ remove: 'animations.walk' }])); const run = cli('patch', file, '--changes', changes, '--out', path.join(dir, 'walk2.json')); assert.equal(run.status, 0, run.stderr); const printed = JSON.parse(run.stdout); assert.deepEqual(printed.animations, { removed: ['walk'] }); assert.equal(printed.stills, brief.stills); assert.equal(run.stdout.split('now stills').length, 2); }); test('stills offer no animation to choose: the check, inspect, render and pixel_render refuse one with the stills text', async t => { const project = renderProject(bar); for (const animation of ['walk', 'default']) { assert.throws(() => checkDelivery(project, { recipe: bar, animation }), error => error instanceof PixelError && error.path === 'animation' && stillsText.test(error.message.slice('animation: '.length))); assert.throws(() => inspectProject(project, { animation }), error => error.path === 'inspect.animation' && stillsText.test(error.message.slice('inspect.animation: '.length))); } const dir = await temp(t), file = path.join(dir, 'hp.json'); await writeFile(file, JSON.stringify(bar)); const rendered = cli('render', file, '--out', path.join(dir, 'out'), '--animation', 'default'); assert.equal(rendered.status, 1); assert.doesNotMatch(rendered.stderr, /choose one of|animations\/default/); assert.match(JSON.parse(rendered.stderr).error, /^animation: the frames are stills/); const inspected = cli('inspect', file, '--animation', 'default'); assert.equal(inspected.status, 1); assert.match(JSON.parse(inspected.stderr).error, /^inspect\.animation: the frames are stills/); }); test('the motion review refuses any animation on stills with the stills text: inspectMotion, inspect --motion and pixel_inspect', async t => { // A pose source whose poses are stills: its metadata is a pose's, but there is still no animation to review. const { recipe, metadata } = compilePoses({ ...stampRig(16, 2, 3), animations: {} }), poses = renderProject(recipe); const review = /^motion\.animation: the frames are stills \("animations": \{\} in the recipe\), so there is no animation to review: /; for (const [project, options] of [[renderProject(bar), { animation: 'default' }], [renderProject(bar), {}], [poses, { animation: 'default', metadata }], [poses, { animation: 'walk', metadata }]]) { assert.throws(() => inspectMotion(project, options), error => error instanceof PixelError && error.path === 'motion.animation' && review.test(error.message), JSON.stringify(options.animation)); } const dir = await temp(t), file = path.join(dir, 'stamp.poses.json'); await writeFile(file, JSON.stringify({ ...stampRig(16, 2, 3), animations: {} })); const inspected = cli('inspect', file, '--motion', 'default'); assert.equal(inspected.status, 1); assert.match(JSON.parse(inspected.stderr).error, review); const call = await session(t, dir, 'pixel_inspect'); for (const args of [{ project: bar, view: 'motion', animation: 'default' }, { project: bar, view: 'motion' }]) { const { isError, info } = await call(args); assert.equal(isError, true); assert.match(info.error, review); } }); test('the check on stills offers no loop, and expect.gifScale is a problem with the stills text', () => { const plain = checkDelivery(renderProject(bar), { recipe: bar }); assert.equal(plain.hint, 'Pass expect with what the user asked for (width, height, frames, colors, transparent, sheet) to check every file against it.'); const asked = checkDelivery(renderProject(bar), { recipe: bar, expect: { gifScale: 2 } }); assert.equal(asked.ok, false); assert.deepEqual(asked.problems.map(problem => [problem.file, problem.asked, problem.got]), [['gifs/', { gifScale: 2 }, 'stills']]); assert.match(asked.problems[0].fix, /^the frames are stills \("animations": \{\} in the recipe\), so there is no animation to make a GIF of: /); }); test('validate --fps and inspect --diagnostics measure the frames of stills, not their flipbook', async t => { const project = renderProject({ ...bar, frames: bar.frames.map(frame => ({ ...frame, duration: 50 })) }); const grid = frameGrid(project, 30); assert.equal(grid.animations, undefined); assert.equal(grid.offGrid.length, 4); assert.deepEqual(grid.notes, ['4 of 4 frame durations are not whole video frames of 33.333 ms; at integer milliseconds, whole frames at 30 fps are multiples of 100 ms.']); // The full bar back to one pixel would be a loop jump, if the states played as a loop. const flipbook = analyzeProject(renderProject({ ...bar, animations: undefined })); assert.ok(flipbook.findings.some(finding => finding.code === 'loop-jump')); const diagnostics = analyzeProject(renderProject(bar)); assert.equal(diagnostics.animations, undefined); assert.equal(diagnostics.findings.some(finding => finding.code === 'loop-jump'), false); assert.equal(briefDiagnostics(diagnostics).animations, undefined); assert.deepEqual(briefDiagnostics(diagnostics).frames.map(row => row.frame), ['s1', 's2', 's3', 's4']); const dir = await temp(t), file = path.join(dir, 'hp.json'); await writeFile(file, JSON.stringify(bar)); const validated = cli('validate', file, '--fps', '30'); assert.equal(validated.status, 0, validated.stderr); const reply = JSON.parse(validated.stdout); assert.deepEqual([reply.ok, reply.frames, reply.animations, reply.frameGrid.animations], [true, 4, undefined, undefined]); const inspected = cli('inspect', file, '--diagnostics'); assert.equal(inspected.status, 0, inspected.stderr); assert.doesNotMatch(inspected.stdout, /"default"|loop-jump/); }); test('a pose source with "animations": {} compiles to a stills recipe, and validate accepts it', async t => { const { recipe } = compilePoses({ ...stampRig(16, 2, 3), animations: {} }); assert.deepEqual([recipe.animations, recipe.frames.length, renderProject(recipe).stills], [{}, 3, true]); const dir = await temp(t), file = path.join(dir, 'stamp.json'); await writeFile(file, JSON.stringify(recipe)); const validated = cli('validate', file); assert.equal(validated.status, 0, validated.stderr); assert.deepEqual([JSON.parse(validated.stdout).frames, JSON.parse(validated.stdout).animations], [3, undefined]); }); // A 2x2 tile set: two plain tiles with tile fields, on an opaque fill. const tiles = { version: 1, name: 'floor', width: 2, height: 2, palette: { a: '#336633', b: '#663333' }, sheet: { padding: 0 }, frames: [{ name: 'grass', tile: { weight: 1 }, ops: [{ op: 'rect', x: 0, y: 0, w: 2, h: 2, color: 'a' }] }, { name: 'dirt', tile: { weight: 2 }, ops: [{ op: 'rect', x: 0, y: 0, w: 2, h: 2, color: 'b' }] }] }; const meadow = compileAutotile(JSON.parse(await readFile(path.join(root, 'examples', 'meadow.autotile.json'), 'utf8'))).recipe; test('an autotile set with "animations": {} delivers tiles, and the README of a tile set says opaque or transparent as its sheet is', async () => { for (const recipe of [meadow, { ...meadow, animations: {} }]) { const delivered = checkDelivery(renderProject(recipe), { recipe }).delivered; assert.deepEqual([delivered.tiles, delivered.stills, delivered.animations], [meadow.frames.length, undefined, undefined]); } const readme = async recipe => (await createBundle(recipe)).files.get('README.txt').toString(); assert.match(await readme(tiles), /^floor\.png: opaque RGBA tile sheet$/m); assert.match(await readme({ ...tiles, animations: {} }), /^floor\.png: opaque RGBA tile sheet$/m); assert.match(await readme({ ...tiles, sheet: { padding: 1 } }), /^floor\.png: transparent RGBA tile sheet$/m); }); test('a still tile set of tile fields delivers tiles whether animations is left out or {}, as the export decides, and a loop asked of it is a problem', () => { for (const [recipe, got] of [[tiles, 'tiles'], [{ ...tiles, animations: {} }, 'stills']]) { const project = renderProject(recipe), check = checkDelivery(project, { recipe }); assert.deepEqual([check.delivered.tiles, check.delivered.stills, check.delivered.animations], [2, undefined, undefined], got); assert.equal(check.hint, 'Pass expect with what the user asked for (width, height, frames, colors, transparent, sheet) to check every file against it.'); for (const loop of [true, false]) { const asked = checkDelivery(project, { recipe, expect: { loop } }); assert.equal(asked.ok, false); assert.deepEqual(asked.problems.map(problem => [problem.file, problem.asked, problem.got]), [['animations/', loop ? 'a loop' : 'one play', got]]); assert.match(asked.problems[0].fix, got === 'tiles' ? /^the frames are tiles \(a tile set whose recipe names no animations\), so there is no animation to (loop|play): list the frames to play under "animations"/ : /^the frames are stills \("animations": \{\} in the recipe\), so there is no animation to (loop|play): /); } // Tiles are counted as frames. assert.equal(checkDelivery(project, { recipe, expect: { frames: 2 } }).ok, true); assert.deepEqual(checkDelivery(project, { recipe, expect: { frames: { default: 2 } } }).problems.map(problem => problem.got), [`2 ${got}`]); } // A tile set that names an animation plays it, and a loop asked of it is checked. const named = { ...tiles, animations: { sway: { frames: ['grass', 'dirt'] } } }, project = renderProject(named); assert.deepEqual(Object.keys(checkDelivery(project, { recipe: named }).delivered.animations), ['sway']); assert.equal(checkDelivery(project, { recipe: named, expect: { loop: true } }).ok, true); }); test('pixel_render lists no animations for a bundle that exports still', async t => { const dir = await temp(t), render = await session(t, dir); for (const [recipe, still] of [[bar, true], [tiles, true], [{ ...tiles, animations: {} }, true], [{ ...bar, animations: undefined }, false]]) { assert.equal((await createBundle(recipe)).still, still); const { isError, info } = await render({ project: recipe }); assert.equal(isError, false, JSON.stringify(info)); assert.equal(info.files.some(file => file.startsWith('animations/')), !still, JSON.stringify(info.files)); assert.ok(info.files.includes('frames/.png')); } }); test('every exported atlas of stills or a still tile set lists frames alone: createBundle, exportAtlas and the playground', async () => { const strip = metadata => Object.keys(metadata).concat(metadata.meta.frameTags ? ['frameTags'] : []); for (const recipe of [bar, tiles, { ...tiles, animations: {} }]) { const project = renderProject(recipe), metadata = exportAtlas(recipe, project, buildAtlas(project).metadata); assert.deepEqual(strip(metadata), ['frames', 'meta']); assert.deepEqual(JSON.parse((await createBundle(recipe)).files.get(`${recipe.name}.atlas.json`)), JSON.parse(JSON.stringify(metadata))); } // A recipe that plays something keeps its animations and tags. const playing = { ...bar, animations: undefined }, project = renderProject(playing); assert.deepEqual(strip(exportAtlas(playing, project, buildAtlas(project).metadata)), ['frames', 'animations', 'meta', 'frameTags']); const engineURL = new URL('../src/', import.meta.url), request = { version: '0.17.0', override: engineURL.href, text: JSON.stringify(bar) }; const preview = await handleRequest({ ...request, type: 'render' }); assert.deepEqual([preview.stills, preview.project, preview.recipe], [true, undefined, undefined]); const atlas = await handleRequest({ ...request, type: 'export', export: 'atlas', scale: 1, frame: 0, animation: 'default' }); const written = JSON.parse(new TextDecoder().decode(atlas.files[1].data)); assert.deepEqual(strip(written), ['frames', 'meta']); const engine = await loadEngine(engineURL); assert.equal(engine.core.exportAtlas, exportAtlas); }); // An MCP session whose export directory is /output, calling `tool`. async function session(t, project, tool = 'pixel_render') { const input = new PassThrough(), output = new PassThrough(), waiting = new Map(); let buffer = '', next = 0; output.on('data', chunk => { buffer += chunk; for (let end; (end = buffer.indexOf('\n')) !== -1; buffer = buffer.slice(end + 1)) { const message = JSON.parse(buffer.slice(0, end)); waiting.get(message.id)?.(message); } }); const running = startMCP({ input, output, directory: path.join(project, 'output'), root: project }); t.after(async () => { input.end(); await running; }); const request = (method, params) => new Promise(resolve => { waiting.set(++next, resolve); input.write(JSON.stringify({ jsonrpc: '2.0', id: next, method, params }) + '\n'); }); await request('initialize', { protocolVersion: '2025-11-25' }); return async args => { const { result } = await request('tools/call', { name: tool, arguments: args }); return { isError: result.isError === true, info: JSON.parse(result.content[0].text) }; }; } test('pixel_render on stills refuses an animation and saveAs aliases stills cannot have, pointing at sheet, atlas or a frame', async t => { const project = await temp(t), render = await session(t, project); const refused = await render({ project: bar, animation: 'default' }); assert.equal(refused.isError, true); assert.equal(refused.info.path, 'animation'); assert.match(refused.info.error, /^animation: the frames are stills/); const saveAs = /^saveAs\.[^:]+: the frames are stills \("animations": \{\}\), so this export has no SpriteFrames, animated PNGs or GIFs: save sheet, atlas or a still's own PNG, such as frames\/s1\.png$/; for (const key of ['godot', 'gif', 'apng', 'gifs/default.gif', 'animations/default.png']) { const { isError, info } = await render({ project: bar, saveAs: { [key]: `x${path.extname(key) || (key === 'godot' ? '.tres' : key === 'gif' ? '.gif' : '.png')}` } }); assert.equal(isError, true, key); assert.match(info.error, saveAs, key); assert.doesNotMatch(info.error.slice(`saveAs.${key}: `.length), /default/); } // A saveAs gif key does not ask for GIFs of stills: no gif note, only the saveAs refusal above. The sheet saves. const saved = await render({ project: bar, saveAs: { sheet: 'hp.png', 'frames/s4.png': 'full.png' } }); assert.equal(saved.isError, false, JSON.stringify(saved.info)); assert.deepEqual([saved.info.saved.map(item => item.file), saved.info.warnings], [['hp.png', 'frames/s4.png'], []]); });