@caperjs/core

An opinionated HTML game framework built on PixiJS v8.

@caperjs/core is the framework package of Caper, a personal fork of dill-pixel by Relish Studios that narrows scope, modernizes the dependency stack, and ships fewer half-finished things.

It sits on top of PixiJS — a renderer, not a game engine — and adds the parts you'd otherwise rebuild for every project: scenes, plugins, asset pipeline, build config, type-safe IDs, signals, and a project layout that scales from a 48-hour jam to something you ship.

Status

Published on npm as @caperjs/core.

For AI agents

• npx caper agent init installs the caper skill + AGENTS.md pointers for this project.
• The reference is node_modules/@caperjs/core/extras/llms.txt — read it by section (grep -n '^## '), not whole.
• Engine source ships in the package under src/.

Highlights

• Pixi v8 native, pinned to the latest 8.x
• Auto-discovered scenes / plugins / popups / entities via the bundled Vite plugin — drop a file in the right directory, the build picks it up
• Type-safe IDs for scenes, plugins, popups, entities, locale keys (string-literal unions on every API that takes one)
• Per-bundle asset types generated from your AssetPack manifest
• Plugin requires: [...] declarations + topological sort at bootstrap
• Build-time validation for asset bundles, plugin IDs, dependency cycles, duplicate IDs
• A Vite preset (@caperjs/core/vite) — plugins: [caper()], then plain vite / vite build
• caper add CLI for scaffolding scenes, plugins, entities, popups
• Signals via typed-signals
• Tested — Vitest covers Plugin, Store, Scene, SignalRegistry

Minimal example

// src/scenes/MenuScene.ts
import { defineScene, Scene } from '@caperjs/core';

export const scene = defineScene({
  id: 'menu',
  assets: { preload: { bundles: ['ui'] } },
});

export default class MenuScene extends Scene {
  initialize() {
    this.add.text({
      text: 'Caper',
      anchor: 0.5,
      style: { fontFamily: 'system-ui', fontSize: 64, fill: 0xffffff },
    });
  }
}

The Vite plugin discovers this file on next reload. The id 'menu' flows into the generated AppScenes union, so app.scenes.load('menu') is fully typed.

Documentation

There's no docs site yet — the upstream apps/docs/ was deleted in Phase 6 because it almost entirely described pre-fork state. A new docs surface will land when there's enough audience to justify it. Until then, the plan/ directory + JSDoc on Scene and IPlugin are the documentation:

• plan/fork-plan.md — long-form architectural rationale
• plan/tasks.md — execution log of what's shipped and why
• CLAUDE.md — repo conventions and common commands

The kitchen-sink (apps/kitchen-sink/) is the canonical reference implementation — every plugin, every UI primitive, scenes, popups, entities, signals, storage all exercised end-to-end.

License

MIT. Original dill-pixel framework architecture credit to Relish Studios.