ExoJS

A TypeScript-first 2D engine for games and interactive apps. Explicit scene graph, WebGPU/WebGL2 rendering, native physics, spatial audio, and a strict type system — measured and verified, not just claimed.

Guide · API Reference · Playground

Pre-1.0. The public API is under active design — minor versions may include breaking changes. Pin exact versions in downstream projects. 1.0.0 marks the first stable API contract.

Packages

Package	Description
@codexo/exojs	Core runtime — scene graph, rendering, audio, UI, serialization
@codexo/exojs-physics	Native 2D physics — shapes, constraints, TGS-Soft solver
@codexo/exojs-particles	GPU-driven particles (WebGPU compute) with CPU fallback
@codexo/exojs-tilemap	Format-independent tilemap runtime and object layers
@codexo/exojs-tiled	Tiled JSON adapter and scene-graph conversion
@codexo/exojs-aseprite	Aseprite adapter — sprite sheets, tags, frame direction/repeat, slices
@codexo/exojs-ldtk	LDtk adapter — multi-world levels, entities, structured field values
@codexo/exojs-audio-fx	Audio effects — biquad filters, analyser, beat detection, worklets
@codexo/exojs-react	React bindings — run an ExoJS Application inside React components

Features

Rendering

• WebGPU-first with automatic WebGL2 fallback; force either backend with one option
• Drawables: Sprite, AnimatedSprite, NineSliceSprite, RepeatingSprite, Graphics, Text (SDF), BitmapText, Video
• Rendering composition: RenderTexture, RenderPipeline, filter chains, visual masks, cache-as-bitmap
• Immediate-mode rendering: one-off drawGeometry and instanced RenderBatch collapsing to a single draw call
• Linear and radial gradients, pixel snapping, view/camera helpers (follow, shake, zoom, bounds clamp)
• Render stats with GPU memory accounting (gpuMemoryBytes, texture/buffer upload bytes)

Scene & UI

• Application, Scene, SceneDirector — one active scene with change/restore/preload/unload navigation, pause/resume, and fade, slide, or cross-fade transitions (or your own SceneTransition)
• scene.ui — screen-fixed widget layer with Label, Panel, Button, ProgressBar, Stack, ScrollContainer, Tooltip, and anchoring
• Keyboard focus through app.interaction — focus, blur, focusNext/focusPrevious Tab traversal, and scoped focus traps for modals

Physics (@codexo/exojs-physics)

• Circles, boxes, capsules, and convex polygons; static, kinematic, and dynamic bodies
• SAP broadphase, manifold narrow-phase, warm-started TGS-Soft solver (sub-stepped, stable to 20+ box stacks)
• Contact graph, collision events, spatial queries; allocation-free per step (V8-sampler verified)
• Scene-graph binding and a /debug draw subpath

Audio

• Voice capability matrix across Sound, AudioStream, and AudioGenerator
• Spatial panning, audio sprites, frequency and waveform analysis, BiquadEffect filters
• @codexo/exojs-audio-fx: AudioAnalyser, BeatDetector, worklets, and DSP helpers

Assets & Storage

• Typed Loader with a declarative asset catalog (Assets.from, Asset.type, defineAsset) and a de-duplicating LoadingQueue
• Binary asset containers (loader.loadContainer) for bundled distribution
• Key-value persistence: WebStorageStore (localStorage/sessionStorage), IndexedDbKeyValueStore (structured-clone, binary-safe), MemoryStore (tests/ephemeral)

Serialization

• Scene.serialize / deserialize captures scene structure — nodes, drawables, UI, tilemap
• SerializationRegistry and Prefab for templates; pairs with any KeyValueStore for save-slot persistence

Architecture

• noUncheckedIndexedAccess + exactOptionalPropertyTypes across the full codebase — zero as any, zero ts-ignore
• Ordered SystemRegistry (app.systems, scene.systems) with deterministic tick bands
• Deterministic disposal via Destroyable / DisposalScope; all managers are app-owned, not process singletons

Getting Started

Scaffold a new project with one command:

npm create exo-app@latest my-game

Or pick a template explicitly:

npm create exo-app@latest my-game -- --template minimal
npm create exo-app@latest my-game -- --template game-starter
npm create exo-app@latest my-game -- --template audio-reactive

Then:

cd my-game
npm install
npm run dev

Installation

npm install @codexo/exojs

ExoJS ships as ESM — use import syntax with a modern bundler or runtime. A prebuilt IIFE bundle (dist/exo.iife.js, global Exo) is included for CDN and script-tag usage. Optional packages install independently — add only what your project needs:

npm install @codexo/exojs-physics
npm install @codexo/exojs-particles
npm install @codexo/exojs-tilemap @codexo/exojs-tiled
npm install @codexo/exojs-aseprite @codexo/exojs-ldtk
npm install @codexo/exojs-audio-fx
npm install @codexo/exojs-react

Quickstart

import{Application,Scene,Graphics,Color,typeRenderingContext,typeTime}from'@codexo/exojs';classHelloSceneextendsScene{privatereadonlybox=newGraphics();publicoverrideinit(): void{this.box.fillColor=Color.white;this.box.drawRectangle(-32,-32,64,64);this.box.setPosition(400,300);this.addChild(this.box);}publicoverrideupdate(delta: Time): void{this.box.rotation+=delta.seconds*45;}publicoverridedraw(context: RenderingContext): void{context.render(this.root);}}constapp=newApplication({scenes: { HelloScene },canvas: {element: document.querySelector('canvas')!,width: 800,height: 600},clearColor: Color.cornflowerBlue,});awaitapp.start(HelloScene);

See the Guide for physics, audio, UI, and more, or browse the live examples.

Roadmap

Directional work toward the 1.0.0 API freeze. Priorities may shift — nothing here is a release commitment.

• Platform adapters for DOM, Worker, and headless runtimes
• Screen-level post-processing (bloom, CRT, vignette, chromatic aberration)
• Path following with Bézier and Catmull-Rom splines
• Coroutine helpers
• Localization primitive
• Final pre-1.0 API audit and stabilization pass

WebGPU and WebGL2

Application auto-selects the best available backend. Force one when needed:

newApplication({backend: {type: 'webgpu'}});newApplication({backend: {type: 'webgl2'}});newApplication({backend: {type: 'auto'}});// default

Development

pnpm bootstrap
pnpm typecheck
pnpm lint
pnpm test
pnpm build
pnpm verify:package

Package-internal imports use Node package.json#imports subpath imports: ./X for the same directory, #dir/X for any other path in the same package, and the public bare specifier (@codexo/exojs) across packages. See CONTRIBUTING.md for the full import policy, per-package commands, and the shared @codexo/exojs-config tooling. Building the library requires TypeScript 6.

This repository uses pnpm workspaces (site/ is a workspace package). Use root-level commands as the source of truth — avoid running pnpm install inside site/ directly:

pnpm bootstrap
pnpm site:build
pnpm site:build:api

Links

• Repository: https://github.com/Exoridus/ExoJS
• Issues: https://github.com/Exoridus/ExoJS/issues
• Changelog: CHANGELOG.md