An open-source TypeScript game engine on three.js, made for coding agents to build on.
Tell Claude Code, Codex or Cursor "Make a game that … with jgengine" and it has the parts, the docs and the tools to finish the job.
jgengine.com · Play the games · The API · Start · npm · Apache-2.0
Ten games run on the engine, all in games/ on the engine source of the same commit. Play
them in the browser at jgengine.com/games.
- Game rules are plain data and plain functions. A run, an inventory, a wave is JSON in a typed
store slot. Rules are functions from state to state, with no engine object and no renderer. The
same code runs in the browser, on a Node host and in
bun test, and saves, replays and multiplayer snapshots carry the state without extra code. - Eleven parts instead of a thousand features. A boss fight or a supply drop isn't an engine feature. The game builds it from eleven small parts: a meter, a ladder, a table, a schedule… Each can be turned off, swapped or retuned, and each works on its own in a game that doesn't use the rest of the engine.
- The file name says what it may import.
name.tsis model,name.view.tsxis UI,name.draw.tsxis three.js. Core compiles each layer on its own (model with no DOM or three.js), so a wrong import is a type error and a server that imports model files never loads UI code or three.js. - Agents can find, check, see and play what they build. The skills ship inside the npm packages.
The CLI answers an agent's questions:
jgengine find <words>(where does this live),has <feature>(does the engine do it already),recipe <name>(a wired snippet),shoot(a real screenshot) anddrive(play the game with keys and read its numbers). - Tested on ten real games in one repo. No version pins between the engine and the games. A change that breaks one is fixed in the same pull request.
- Measured, not claimed. One frame budget for every game, checked by
bun run perf gate: p95 ≤ 16.7 ms on an RTX 3070 at 1600×900. Experiments ship only when the numbers say so. A native Rust renderer went from 73 to 182–272 fps on one game and nothing on another, so it stayed an experiment. The full log, with dates and numbers, is at jgengine.com/decisions.
A complete game: walk around, press E to gather, energy drains over time, and ranks go up. These
four files are compiled against the engine on every commit (apps/web/src/snippets/tour-*), so
they're the real API.
1. Rules are pure functions over plain data, built from the engine's parts.
import { pickWeighted } from "@jgengine/core/random/pick";
import { changeMeter, createMeter, tickMeter, type MeterState } from "@jgengine/core/stats/statPool";
import { tierAt, type ThresholdBoundary } from "@jgengine/core/threshold/thresholds";
// Rules are plain functions over plain JSON, built from the engine's parts:
// a meter, a ladder, a weighted table. No engine object and no renderer, so the
// same code runs in the browser, on a Node host and in `bun test`.
export interface Run {
energy: MeterState;
gathered: number;
finds: string[];
}
const RANKS: readonly ThresholdBoundary<string>[] = [
{ id: "Wanderer", at: 0 },
{ id: "Forager", at: 2 },
{ id: "Pathfinder", at: 5 },
];
const FINDS = [
{ id: "timber", weight: 5 },
{ id: "amber", weight: 1 },
] as const;
export const newRun = (): Run => ({
energy: createMeter({ max: 100, current: 60 }),
gathered: 0,
finds: [],
});
export function gather(run: Run, rng: () => number): Run {
const find = pickWeighted(rng, FINDS, (entry) => entry.weight) ?? FINDS[0];
return {
energy: changeMeter(run.energy, 20).meter,
gathered: run.gathered + 1,
finds: [...run.finds, find.id],
};
}
export const drain = (run: Run, dt: number): Run => ({
...run,
energy: tickMeter(run.energy, { decay: 0.4 }, dt).meter,
});
export const rankOf = (run: Run): string => tierAt(RANKS, run.gathered)?.id ?? "Wanderer";2. State and systems. A store slot holds the state; a system says when the rules run.
import { defineStore, defineSystem } from "@jgengine/core/shell/gameKit.draw";
import { drain, gather, newRun, type Run } from "./tour-rules";
// State is one typed slot in the game store, so saves, replays and
// multiplayer snapshots carry it.
export const run = defineStore<Run>("run", newRun);
// A system is a schedule plus a function. The engine owns the frame loop.
export const gatherLoop = defineSystem({
id: "gather-loop",
tick: { type: "frame" },
update(ctx, dt) {
let next = drain(run.read(ctx), dt);
if (ctx.input.justPressed("interact")) next = gather(next, ctx.rng);
run.write(ctx, next);
},
});3. UI is JSX that reads the store through selectors.
/** @jsxImportSource @jgengine/core/ui/jsx */
import { bind, type RuneTheme } from "@jgengine/core/ui/rune/primitives";
import { RuneLabel, RuneRoot, RuneView } from "@jgengine/core/ui/rune/primitives.view";
import { useGameStore } from "@jgengine/core/ui/hooks.view";
import { useGameContext } from "@jgengine/core/ui/provider.view";
import { run } from "./tour-loop";
import { rankOf } from "./tour-rules";
const theme = {
colors: { panel: "#10202ae6", track: "#ffffff22", energy: "#4fd1c5" },
text: { body: { size: 14, color: "#e6f4f1" }, title: { size: 18, weight: 700, color: "#ffffff" } },
variants: { panel: { padding: 16, gap: 8, fill: "#10202ae6", radius: 10 } },
motion: { duration: 160, distance: 8, bounce: 0 },
} satisfies RuneTheme;
// JSX, but not React: the engine's own runtime, drawn on the game canvas by Rune (Rust compiled to
// wasm). The rank re-renders only when it changes; the energy bar is bound, so it moves with no render.
export function GameUI() {
const ctx = useGameContext();
const rank = useGameStore((game) => rankOf(run.read(game)));
const energy = () => run.read(ctx).energy.pool.current / 100;
return (
<RuneRoot context={ctx} theme={theme}>
<RuneView anchor="top-left" safe inset={16} variant="panel" width={220}>
<RuneLabel textStyle="title" value="Tide Runner" />
<RuneLabel value={rank} />
<RuneView height={6} radius={3} fill={theme.colors.track}>
<RuneView height={6} radius={3} fill={theme.colors.energy} width={bind(() => ({ fraction: Math.max(0, Math.min(1, energy())) }))} />
</RuneView>
</RuneView>
</RuneRoot>
);
}4. The game is one defineGame call.
import { DEFAULT_WALK_CODES, defineGame } from "@jgengine/core/shell/gameKit.draw";
import { GameUI } from "./tour-hud";
import { gatherLoop } from "./tour-loop";
// One call wires it up. Binding walk keys gives the player a walk controller;
// the world, camera, menus, saves and the scene editor (F2+E) come with it.
export const game = defineGame({
name: "Tide Runner",
rendering: { look: "cinematic", mood: "golden" },
input: { ...DEFAULT_WALK_CODES, interact: ["KeyE"] },
systems: [gatherLoop],
GameUI,
});The world itself (terrain, props, spawn points, triggers) is authored in the scene editor (F2+E in
the browser), which writes editor.scene.json. Code reads it; nobody types coordinates by hand.
packages/core/src/map/
waypoints.ts model plain data and functions; no UI runtime, no three.js
ping.ts model
waypointMarkers.view.tsx view JSX on the engine runtime; no three.js
pingBeacons.draw.tsx draw three.js
Import any file by its path: @jgengine/core/map/waypoints. ws and sql import only model
files; shell is the only package that renders.
Most game features are built from these parts (@jgengine/core/parts re-exports their model layer),
plus the engine's entities, containers and world. Each part has one home in the engine.
| Part | What it is | Examples | Home |
|---|---|---|---|
| Meter | a number with a range that drains, fills or regenerates, and takes doses | health, hunger, ammo, shield; a meal or potion | stats/statPool.ts, stats/vitals.ts, stats/doseTable.ts |
| Ladder | ordered steps over a number | rarity, tiers, ranks, levels, wanted stars | threshold/thresholds.ts |
| Phases | named states one after another, by time or event | growth stages, boss phases, day parts | time/stateSchedule.ts |
| Schedule | something happens at a pace from a start time | waves, supply drops, weather, respawns | time/pacedSchedule.ts |
| Slots | named spots that each hold one thing and refill | crates, resource nodes, boss spawns | time/refillSlots.ts |
| Placement | where something appears | spawn points, scatter, drop zones | world/spatialSample.ts, game/spawnPoints.ts |
| Table | a weighted choice the game fills | loot per rarity, which enemy | random/pick.ts |
| Requirement | a condition over facts the game names | level gates, keys, unlocks | rules/predicate.ts |
| Modifiers | stacked add, multiply, override and clamp | buffs, gear stats, difficulty | progression/statGraph.ts |
| Inheritance | a child's values from its parents with variation | breeding, crossing plants | inheritance/inheritance.ts |
| Motion track | a thing follows a path over time and arrives | a falling crate, a thrown item, a door | movement/motionTrack.ts |
A supply drop is Schedule (when), Placement (where), Ladder (rarity), Requirement (who may open it),
Table (loot), Motion track (the fall) and Slots (one crate per site), so a game writes
spawnSupplyDrop(x, y, "purple") itself in a few lines.
Ask your agent. Say this to Claude Code, Codex, Cursor or any agent that runs commands:
Make a game that is a tower defense on two mountain roads, with jgengine
Or scaffold it yourself. The game is its own project on the npm packages; don't clone this repo to make one.
npx jgengine create "Tide Runner" # --template 3d (default) | 2d | builder
cd Tide-Runner && bun install && bun devYou get a walkable 3D world with menus, a HUD, the scene editor (F2+E) and the agent skills installed in the project.
Or take one part into a game you already have. Model files have no dependencies:
import { changeMeter, createMeter, tickMeter } from "@jgengine/core/stats/statPool";
let stamina = createMeter({ max: 100 });
stamina = changeMeter(stamina, -30).meter; // sprinting
stamina = tickMeter(stamina, { regen: 10, regenDelay: 1 }, 2).meter; // 90 after two secondsA game that doesn't use defineGame can still host the engine's systems on createGameContext
(@jgengine/core/runtime/gameContext). jgengine.com/adopt adds health,
XP, saves and a minimap to an existing three.js game, one at a time.
Or play the games in this repo (needs Bun):
git clone https://github.com/Noisemaker111/jgengine && cd jgengine
bun run agent:bootstrap # install, link workspaces, prepare generated files
bun run dev:site # jgengine.com locally; every game plays at /games/<id>One game on its own: bun run games:provision <id> (links its asset packs), then
bun --cwd=games/<id> run dev.
| 3D | Plain three.js on a frame loop the engine owns. WebGL by default; a WebGPU preview with ?renderer=webgpu. |
| UI | JSX on the engine's own runtime (@jgengine/core/ui/jsx), never React. Drawn by Rune, a Rust UI library compiled to wasm, on the game canvas. |
| Physics | A built-in solver, or Rapier through @jgengine/rapier (capsules, shapecasts, CCD, joints). |
| Multiplayer | One protocol over WebSocket, socket.io, WebRTC P2P, LAN or Convex, with an authoritative host on Node and Postgres persistence. |
| Ships to | The browser, a Windows .exe (npx jgengine desktop, Tauri) and npm. A React, Next or TanStack page embeds a game with mountGamePlayer (examples/). |
| Package | What it is |
|---|---|
jgengine |
The CLI: create, find, has, recipe, shoot, drive, desktop, editor, doctor and more (npx jgengine help). |
@jgengine/core |
The engine: feature folders with model, view and draw files, GameContext, entities, combat, HUD, saves, inventory, world. Game UI on the engine's JSX runtime is @jgengine/core/ui.view (GameProvider, hooks, primitives); the game player (defineGame, the canvas on the frame loop, cameras, input, HUD mounting) is @jgengine/core/shell/*. No dependencies; three.js is an optional peer. |
@jgengine/editor |
The scene, world and asset editor; npx jgengine editor on its own, jgengine editor-mcp for agents. |
@jgengine/rapier |
Rapier physics backend. |
@jgengine/ws · node · sql · convex |
Multiplayer client, Node host, Postgres persistence, Convex transports. |
@jgengine/navbake |
Deterministic navigation-mesh baking. |
@jgengine/assets |
A license-checked index of CC0 3D models with a pull CLI. |
@jgengine/{core,rapier,ws,node,sql,convex,assets,editor,navbake} are versioned together.
Agents start with AGENTS.md. From the repo root:
bun run agent:bootstrap # setup; @jgengine/* resolves to package source, no build step
bun run test <path> # tests; no path runs all of them
bun test games # every game's tests and scripts
bun run verify:fast # the checks your branch's diff reaches, in seconds
bun run gen # regenerate committed files after a public API change
bun run find <words> # which package and folder owns a concept
bun run perf <game> # frame scorecard: p50/p95/p99, main thread, GC
bun run shoot <game> # a real screenshot of a game; drive plays itOn Windows, if bun isn't found after installing, add %USERPROFILE%\.bun\bin to PATH and reopen
the terminal. The website's own notes are in apps/web/README.md.
The procedural buildings, water, rain and snow renderers were shaped from achrefelouafi's MIT-licensed three.js projects. Rune is by Anomaly (MIT). Full list: CREDITS.md.
Apache-2.0 with a NOTICE file. Commercial and closed-source games are fine;
keep the NOTICE in what you ship. Third-party code and assets keep their own licenses
(LICENSING.md). Not related to the automotive "JG Engines".








