PixelScript

Why PixelScript

• One canonical JSON document model for every output.
• Programmatic authoring from numeric arrays, compact strings, or shareable JSON files.
• Built-in 64-slot palette keyed to the Base64 character set, including transparency at slot 0.
• Browser-first runtime plus Node-friendly rendering for docs, pipelines, and asset generation.
• Inline HTML support through <pixel-art>.

Install

npm install @ibimspumo/pixelscript

Same Art, Different Outputs

import { createAnimation, renderGIF, renderPNG, renderSVG } from '@ibimspumo/pixelscript';

const comet = createAnimation({
  width: 6,
  height: 3,
  frames: [
    { pixels: [0, 0, 0, 6, 1, 0, 0, 0, 6, 1, 0, 0, 0, 6, 1, 0, 0, 0] },
    { pixels: [0, 0, 6, 1, 0, 0, 0, 6, 1, 0, 0, 0, 6, 1, 0, 0, 0, 0] }
  ],
  animation: { fps: 8, loop: true }
});

const svg = renderSVG(comet, { scale: 18 });
const png = await renderPNG(comet, { scale: 18 });
const gif = await renderGIF(comet, { scale: 18, iterations: 'infinite' });

Sprite Shelf

Compact At The Core

PixelScript stores each frame as a compact row-major string over the Base64 alphabet. That keeps the source small, diffable, and easy to share.

{
  "version": 1,
  "width": 8,
  "height": 8,
  "palette": {
    "kind": "default64",
    "name": "PixelScript-64"
  },
  "frames": [
    {
      "pixels": "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
    }
  ],
  "meta": {
    "name": "PixelScript-64 Grid"
  }
}

• A is palette index 0, reserved for transparency.
• B is palette index 1, the first visible slot.
• The full built-in palette is visualized above and can be replaced with custom palettes up to 64 entries.

JavaScript API

import {
  createArt,
  createAnimation,
  mountPixelArt,
  renderPNG,
  renderSVG
} from '@ibimspumo/pixelscript';

const checker = createArt({
  width: 2,
  height: 2,
  pixels: [0, 1, 0, 1]
});

const beacon = createAnimation({
  width: 4,
  height: 4,
  frames: [
    { pixels: 'ABABABABABABABAB', durationMs: 120 },
    { pixels: 'BABABABABABABABA', durationMs: 120 }
  ],
  animation: {
    fps: 8,
    loop: true
  }
});

const svg = renderSVG(checker, { scale: 24 });
const png = await renderPNG(checker, { scale: 24 });

const controller = mountPixelArt(document.querySelector('#target'), beacon, {
  render: 'canvas',
  scale: 20,
  autoplay: true
});

const firstPixel = controller.getPixel(0, 1, 1);
console.log('Frame 0, pixel (1,1):', firstPixel);

controller.setPixel(0, 4, 4, 8);
controller.setPixels(0, [
  { x: 3, y: 3, paletteIndex: 2 },
  { x: 4, y: 3, paletteIndex: 3 }
]);

controller.play({ iterations: 2 });

Inline HTML

<script src="./dist/pixelscript.min.js"></script>

<pixel-art
  render="gif"
  scale="18"
  autoplay
  loop
  src="./docs/readme-assets/comet-burst.json"
></pixel-art>

Module usage can register the element explicitly:

import { registerPixelArtElement } from '@ibimspumo/pixelscript/element';

registerPixelArtElement();

Per-Pixel Interaktion (Canvas only)

Pointer interactions are supported on <pixel-art render="canvas">:

• pixelscript:pixel-hover
• pixelscript:pixel-enter
• pixelscript:pixel-leave
• pixelscript:pixel-down
• pixelscript:pixel-up
• pixelscript:pixel-click
• pixelscript:pixel-drag
• pixelscript:pixel-hold
• pixelscript:pixel-change when pixels are changed programmatically

const hero = document.querySelector('pixel-art#hero-art');

hero.addEventListener('pixelscript:pixel-click', (event) => {
  const detail = event.detail;
  console.log('clicked pixel', detail.sourceX, detail.sourceY, detail.paletteIndex);
  hero.setPixel(detail.sourceX, detail.sourceY, 0);
});

hero.addEventListener('pixelscript:pixel-change', (event) => {
  const detail = event.detail;
  console.log('pixel changed', detail.previousIndex, '->', detail.paletteIndex, 'at', detail.sourceX, detail.sourceY);
});

Shareable Documents

Every visual in this README is generated from PixelScript documents in docs/readme-assets:

• hero-arcade-night.json
• ghost-wave.json
• comet-burst.json
• palette-grid.json

That same JSON can be used in:

• JavaScript code
• inline HTML via data or src
• docs generation
• static asset pipelines

Public API

• createArt(input)
• createAnimation(input)
• parseDocument(json)
• validateDocument(json)
• stringifyDocument(doc)
• parseCompact({ width, height, pixels, palette? })
• fromArray({ width, height, pixels, palette? })
• getDefaultPalette()
• definePalette({ name?, colors })
• validatePalette(palette)
• renderSVG(doc, options)
• renderCanvas(doc, options)
• renderPNG(doc, options)
• renderGIF(doc, options)
• renderDataURL(doc, options)
• mountPixelArt(target, doc, options)
• registerPixelArtElement()
• PixelArtController APIs returned by mountPixelArt
  • getPixel(frameIndex, x, y)
  • setPixel(frameIndex, x, y, paletteIndex)
  • setPixels(frameIndex, updates)
  • getCurrentFrame()
  • play(options)
  • pause()
  • stop()
  • seek(frameIndex)
• <pixel-art> element instance methods
  • getPixel(x, y, frameIndex?)
  • setPixel(x, y, paletteIndex, frameIndex?)
  • setPixels(updates, frameIndex?)

Development

npm install
npm run dev
npm run typecheck
npm test
npm run readme:assets

README visuals are generated by scripts/generate-readme-assets.mjs.

Links

• Demo/docs app: demo/main.ts
• JSON schema: schema/pixelscript.schema.json
• Example docs: examples/checker.json, examples/comet.json
• GitHub Pages demo: https://ibimspumo.github.io/PixelScript/

License

MIT