Route Graphics

Route Graphics is a declarative 2D UI/rendering system built on PixiJS. You describe states with JSON, then Route Graphics handles element lifecycle, animations, audio, and interaction events for you.

This README stays intentionally short. The hosted docs are the source of truth for setup guides, node reference pages, events, asset loading, plugin authoring, and live examples.

Start Here

• Documentation
• Playground
• Tasks & Roadmap

Installation

bun install route-graphics

Minimal Usage

import createRouteGraphics, {
  createAssetBufferManager,
  textPlugin,
  rectPlugin,
  spritePlugin,
  containerPlugin,
  tweenPlugin,
  soundPlugin,
} from "route-graphics";

const assets = {
  "circle-red": { url: "/public/circle-red.png", type: "image/png" },
  "bgm-1": { url: "/public/bgm-1.mp3", type: "audio/mpeg" },
};

const assetBufferManager = createAssetBufferManager();
await assetBufferManager.load(assets);

const app = createRouteGraphics();
await app.init({
  width: 1280,
  height: 720,
  backgroundColor: 0x000000,
  plugins: {
    elements: [textPlugin, rectPlugin, spritePlugin, containerPlugin],
    animations: [tweenPlugin],
    audio: [soundPlugin],
  },
  eventHandler: (eventName, payload) => {
    console.log(eventName, payload);
  },
});

await app.loadAssets(assetBufferManager.getBufferMap());
document.body.appendChild(app.canvas);

app.render({
  id: "hello-state",
  elements: [
    {
      id: "title",
      type: "text",
      x: 40,
      y: 40,
      content: "Hello Route Graphics",
      textStyle: {
        fill: "#ffffff",
        fontSize: 36,
      },
    },
  ],
  animations: [],
  audio: [],
});

createAssetBufferManager() may keep image and video assets as direct source URLs when possible, while audio and font assets remain buffer-backed.

For complete usage details, go to:

• Getting Started
• Assets & Loading
• Events & Render Complete
• Custom Plugins

PNG Render CLI Scaffold

This repo now includes a repo-local CLI scaffold that renders YAML into a PNG by:

1. reading YAML in Node,
2. launching headless Chromium through Playwright,
3. rendering with the bundled dist/RouteGraphics.js, and
4. exporting pixels with app.extractBase64().

It is intentionally scaffolded as a repo workflow first, not a published package entrypoint yet.

Full CLI reference: docs/png-render-cli.md

# one-time browser install if Chromium is not already available
npx playwright install chromium

# render a YAML file to PNG
bun run render:png -- ./examples/hello.yaml -o ./out/hello.png

Supported top-level YAML shapes:

• A single state object
• An array of states
• A wrapper object with width, height, backgroundColor, optional assets, and either state or states
• Multiple YAML documents separated by --- (treated as a state list)

Minimal example:

width: 1280
height: 720
backgroundColor: "#101820"
elements:
  - id: title
    type: text
    x: 80
    y: 80
    content: "Hello PNG"
    textStyle:
      fill: "#ffffff"
      fontSize: 48
  - id: bar
    type: rect
    x: 80
    y: 160
    width: 320
    height: 24
    fill: "#4fd1c5"

Asset handling:

• Asset-bearing render-state fields such as src, thumbSrc, barSrc, inactiveBarSrc, and soundSrc must reference top-level assets aliases.
• Direct file paths and URLs are allowed inside top-level assets values.
• Direct asset references inside elements, audio, or nested interaction config are rejected.

Example with asset aliases:

width: 1280
height: 720
assets:
  hero: ./assets/hero.png
  uiFont:
    path: ./assets/fonts/NotoSans-Regular.ttf
    type: font/ttf
elements:
  - id: title
    type: text
    x: 60
    y: 60
    content: "Alias-backed render"
    textStyle:
      fill: "#ffffff"
      fontSize: 42
      fontFamily: uiFont
  - id: avatar
    type: sprite
    x: 60
    y: 140
    width: 128
    height: 128
    src: hero

Invalid example:

elements:
  - id: avatar
    type: sprite
    x: 60
    y: 140
    width: 128
    height: 128
    src: ./assets/hero.png # rejected by the CLI

Useful flags:

• --state <index> selects a state from an array or multi-document YAML file.
• --time <ms> samples animations at a specific manual timeline position.
• --wait-for-render-complete waits for a renderComplete event before capture.
• --browser-executable <path> uses a system Chrome/Chromium instead of Playwright's managed browser.

Development

# Run tests
bun run test

# Render a YAML file into a PNG
bun run render:png -- ./examples/hello.yaml -o ./out/hello.png

# Ensure VT assets are real binaries, not Git LFS pointer files
git lfs pull
git lfs checkout

# Build the local docs/playground site
cd playground
bun install
bun run build

The docs site and playground source live under playground/.

Visual regression assets under vt/static/public and vt/reference are stored in Git LFS. If those files are not checked out, VT pages will render blank and browser logs will show image/audio decode errors.

Community

Join us on Discord to ask questions, report bugs, and stay up to date.

License

This project is licensed under the MIT License.