A TypeScript-first 2D runtime for browser games and interactive applications.

Try the Playground · Read the Guide · Browse the API

Benchmarks · Release notes · Download the Full ZIP

ExoJS brings scenes, rendering, input, audio, UI, and asset lifetimes into one application model. Build a game, a visualization, or an interactive canvas inside an existing web application. Keep the surrounding page in your web framework; use ExoJS for the canvas.

Pre-1.0: minor releases may change public APIs. Pin exact package versions, keep official runtime packages on a compatible release line, and read the release notes before upgrading. main tracks the latest release; next can contain work that is not yet published on npm. The CI and coverage badges above describe main.

Start a project

npm create exo-app@latest my-game -- --template minimal
cd my-game
npm install
npm run dev

The starter is a Vite + TypeScript project with a visible, animated scene. Choose minimal, game-starter, platformer, top-down, ui-app, or audio-reactive. The Setup guide explains the templates, project layout, and installation into an existing application.

A scene contains ordinary TypeScript state and renders whatever is attached to its root; override draw when it should render something else. This example needs no external assets:

import { Application, Color, Graphics, Scene, type Seconds } from '@codexo/exojs';

class MainScene extends Scene {
  private readonly box = new Graphics();

  override init(): void {
    this.box.fillColor = Color.white;
    this.box.drawRectangle(-40, -40, 80, 80);
    this.box.setPosition(this.app.width / 2, this.app.height / 2);
    this.root.addChild(this.box);
  }

  override update(delta: Seconds): void {
    this.box.rotate(90 * delta);
  }
}

const app = new Application({
  scenes: { MainScene },
  canvas: { width: 800, height: 600, mount: 'body' },
  clearColor: new Color(0x6495ed),
});

await app.start(MainScene);

Follow Your first scene for the walkthrough. Use the Playground to experiment and the API reference to check exact contracts.

Why ExoJS

| Capability | What it means for your project | | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | One runtime, explicit lifetimes | Scene-scoped assets, input, systems, animation, and audio follow scene teardown. Application-level resources can outlive an individual scene. | | WebGPU and WebGL2 | Choose a backend or use automatic selection. Share the high-level scene API and check capability-specific features on target devices. | | Rendering beyond sprites | Compose text, geometry, masks, filters, render targets, multiple views, and custom materials. Reach for the renderer SDK when the high-level paths do not fit. | | Optional gameplay and visual systems | Add physics, tilemaps, pathfinding, particles, lighting, or editor-format adapters without making them mandatory Core dependencies. | | TypeScript throughout | Typed scene navigation, asset loading, extension contracts, and declarations fit an ordinary editor and build pipeline. | | Measured performance | Structural gates and browser benchmark profiles describe specific workloads, with provenance and limitations alongside the results. |

ExoJS is a code-first runtime, not a visual game editor. Its benchmarks describe particular workloads, not a guarantee that every application will be faster than one built with another engine.

Packages

Core owns the application, scenes, scene graph, rendering, input, UI, asset loading, and basic audio. Install only the optional systems you use. Runtime packages follow the Core release line; check their declared peer dependencies when choosing versions.

Runtime and integrations

| Package | Purpose | Documentation | | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | @codexo/exojs | Core runtime: scenes, rendering, input, UI, assets, and audio | Guide | | @codexo/exojs-physics | 2D rigid bodies, colliders, joints, and queries | README | | @codexo/exojs-particles | Particle emitters, CPU simulation, and eligible WebGPU compute paths | README | | @codexo/exojs-tilemap | Format-neutral tilemaps, chunk rendering, and world loading | README | | @codexo/exojs-tiled | Tiled JSON maps, tilesets, and authored objects | README | | @codexo/exojs-ldtk | LDtk worlds, levels, IntGrid data, and level streaming | README | | @codexo/exojs-aseprite | Aseprite sprite sheets and tagged animations | README | | @codexo/exojs-tilemap-physics | Static physics colliders from tilemap geometry | README | | @codexo/exojs-lighting | Forward, shadowed lightmap, and radiance-cascade lighting | README | | @codexo/exojs-pathfinding | A* search over weighted grids and waypoint graphs | README | | @codexo/exojs-audio-fx | Audio effects, analysis, worklets, and beat detection | README | | @codexo/exojs-react | React canvas hosting, declarative scenes, and hooks | README |

Project tooling

| Package | Purpose | Documentation | | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | create-exo-app | Project scaffolding and maintained starters | README | | @codexo/exojs-cli | Static serving, project checks, scaffolding, and asset packs | README | | @codexo/exojs-build | Vite/Rollup transforms for shaders, workers, and AudioWorklets | README | | @codexo/eslint-plugin-exojs | Lifecycle and engine-specific correctness checks | README |

Package names open npm; documentation links describe the released packages. In a checkout of next, read the matching local package README for unreleased changes. Runtime libraries such as physics and pathfinding are constructed directly; renderer and asset extensions use explicit application descriptors. Each package documents its setup.

Installation and distribution

For a bundler-based application:

npm install --save-exact @codexo/exojs

The package provides ESM and TypeScript declarations. It also includes script-tag bundles:

| Bundle | Contents | | ----------------------- | ---------------------------------------------------------------------------------------------------- | | dist/exo.iife.js | Core runtime on the Exo global | | dist/exo.full.iife.js | Core plus the official runtime extensions except React and tilemap physics, on the same Exo global |

Minified variants are provided alongside them. Use one Core instance per application; do not load both bundles into the same page.

The Full Release ZIP includes a built runtime, examples, and documentation. See Deployment for static hosting and script-tag setup.

Performance evidence

The benchmark pages show measured scenarios and their limitations. The versioned profiles preserve provenance, and the harness documentation explains reproduction. Structural counters and browser timings answer different questions; neither produces an overall engine winner.

Contributing

Repository development requires Node 24 and the pnpm version pinned in package.json:

pnpm bootstrap:dev
pnpm doctor

Read CONTRIBUTING.md for package boundaries, code conventions, and change-specific validation. Product changes belong in the relevant Guide, package README, or source JSDoc; development history belongs in pull requests, releases, CHANGELOG.md, and Git.

Report a reproducible problem in GitHub Issues.

License

MIT © Codexo