# Bundles and game engines

> The CLI turns a spec into a bundle for the web (one JSON file, every size, all the metadata) or into a sprite sheet with Aseprite-format JSON that PixiJS and Phaser load directly.

import LiveExample from '../../../../components/LiveExample.astro';

## From spec to files

```sh
npx pixel validate goose.json                       # errors with JSON paths, clipped parts, missed feet
npx pixel preview  goose.json --anim walk,jump      # contact sheet PNG of those animations
npx pixel bundle   goose.json --out site/goose.bundle.json
npx pixel export   goose.json --res 32 --out game/  # game/goose.32.png + game/goose.32.json
```

## What a bundle holds

<LiveExample
  title="Inspect a bundle"
  code={`<pre id="bx" style="margin:0;max-height:260px;overflow:auto;font-size:12px;width:100%"></pre>
<script type="module">
  const b = await (await fetch('../demo/assets/goose-root.bundle.json')).json();
  const short = {
    ...b,
    animations: Object.fromEntries(Object.entries(b.animations).slice(0, 5)),
    points: { beak: { idle: b.points.beak.idle.slice(0, 2) } },
    states: '{ … see State machines … }',
    variants: b.variants.map((v) => Object.fromEntries(Object.entries(v).map(([k, x]) =>
      [k, typeof x === 'string' && x.startsWith('data:') ? x.slice(0, 32) + '…' : Array.isArray(x) && x.length > 3 ? [...x.slice(0, 2), '…'] : x]))),
  };
  document.getElementById('bx').textContent = JSON.stringify(short, null, 1);
</script>`}
/>

Sheets are PNG data URLs, one per size. A skin is stored as a change to the plain sheet when that is smaller (`recolor`: colours swapped, `overlay`: pixels drawn on top), otherwise as its own sheet. Events, attachment points, the foot line, speeds and the state machine are stored in units, so one table serves every size. The full format is in [docs/runtime.md](/docs/reference/runtime/).

## PixiJS

`pixel export` writes frames named by index, a PixiJS `animations` map, and per-frame durations. This example loads PixiJS 8 from a CDN.

<LiveExample
  title="AnimatedSprite from an exported sheet"
  height={170}
  code={`<div id="pixi-box"></div>
<span class="readout" id="pixi-out">loading PixiJS…</span>
<script type="module">
  import * as PIXI from 'https://cdn.jsdelivr.net/npm/pixi.js@8.6.6/dist/pixi.min.mjs';
  const app = new PIXI.Application();
  await app.init({ width: 320, height: 140, backgroundAlpha: 0 });
  document.getElementById('pixi-box').append(app.canvas);
  const sheet = await PIXI.Assets.load('../demo/assets/goose-root.32.json');
  ['waddle', 'jump', 'climb'].forEach((name, i) => {
    const s = new PIXI.AnimatedSprite(sheet.animations[name]);
    s.texture.source.scaleMode = 'nearest';
    s.animationSpeed = 10 / 60; s.scale.set(3); s.x = 8 + i * 104; s.y = 30;
    s.play();
    app.stage.addChild(s);
  });
  document.getElementById('pixi-out').textContent = \`\${Object.keys(sheet.animations).length} animations loaded\`;
</script>`}
/>

## Phaser

Phaser reads the same JSON as an Aseprite file: every animation becomes a Phaser animation, with its frame durations.

```js
preload() {
  this.load.aseprite('goose', 'goose.32.png', 'goose.32.json');
}
create() {
  this.anims.createFromAseprite('goose');            // idle, waddle, run, honk, jump, …
  const goose = this.add.sprite(100, 100, 'goose').setScale(3);
  goose.play({ key: 'waddle', repeat: -1 });
}
```

Attachment points travel as Aseprite slices (one key per frame), and the extras (events, `speed`, `ground`) under `meta.pixelStudio`.
