Meet ForgeaX Engine

ForgeaX is a TypeScript game engine with AI agents as its primary users. Data, lifecycles, APIs, and tools serve one goal: help AI understand the system, act precisely, inspect results, and repair failures.

Efficiency is the goal; design is the method. Complete more verified game-development work with less context, fewer failed attempts, and shorter feedback cycles.

AI efficiency Design principles Architecture Get started Explore

AI efficiency

Efficiency means verified useful work, accounting for diagnosis and rework, context, and tool round trips.

Capability	How it improves AI efficiency
Transparent rendering	RHI-debug records and replays self-contained frames, exposing draw/dispatch work, bindings, resources, and pixels to locate incorrect inputs
Transparent runtime logic and data	ECS makes components, queries, and schedules explicit; Remote queries live instances to locate failures from actual state
Authorable, traceable assets	ScriptablePack / Pack generate content in TypeScript or declare it in JSON; stable GUIDs connect sources and artifacts, with repair routed through the producer
Reversible plugin changes	Native Cordis unifies dependencies, activation, and cleanup; failed configuration updates can restore the last working Fiber
Measurable performance and results	Profiler provides bounded CPU captures and offline comparison; Preview, browser captures, and project tests supply runtime evidence
CLI-first operation	DevKit unifies `forgeax` discovery, JSON input/output, and persistent instances for repeatable, composable operations
Context on demand	Skills, package contracts, and tool descriptions reveal only the knowledge needed for the task
Structured failure and recovery	`Result` and closed error unions provide codes, expectations, hints, and details; capabilities, execution tiers, and recovery state are explicit

Screenshots, structural checks, and real GPU execution answer different questions. CPU captures cannot substitute for GPU performance measurements.

Design principles

Compression is intelligence: reduce the concepts needed to understand local behavior. Avoid duplicate state, extra lifecycles, and implicit branches.

Design principle	How ForgeaX applies it
AI is the primary user	Prioritize discoverable, callable, verifiable machine contracts; AI usability takes precedence over human convention
One source of truth	World owns game state, Renderer owns render projections, and source assets plus Meta own author facts; other layers consume or derive
Derive from declarations	Material `paramSchema` derives layouts; RenderGraph derives dependencies and lifetimes from accesses; project declarations generate the Catalog
Compose within domain boundaries	Physics, rendering, assets, and audio own their execution data; plugins assemble capabilities and ECS schedules frame work
Native lifecycle and unified cleanup	Cordis `Context / Entry / Fiber` manage capability existence; `inject / provide / effect` express dependencies, services, and cleanup
Explicit states and failures	Closed unions, structured errors, and reported capability absence and fallback reduce hidden branches
Prepare at build time, consume at runtime	Import, WGSL composition and reflection, and VFX compilation produce published content for runtime loading

See the AI-first design axiom and module ownership map for the full constraints.

Architecture

One authoritative World. Runtime assembles services, Render maintains render projections, and build tools produce resources.

Project and build

Game projectforge.json · code · asset sources

DevKit / CLIproject operations · build · inspect

Build-time productionimport · cook · shader / VFX compilation

AssetRegistryGUID → published content

↓ DevKit starts the App; cooked artifacts enter AssetRegistry

Runtime assembly

App + native Cordisrealm assembly · input · frame pacing · lifecycle

ECS Worldstate · time · Update / FixedUpdate

Domain systemsscene · animation · physics · audio intents · net

Runtimeselect backends and services · assemble Renderer

↓ World changes and assets enter Render; Runtime assembles the Renderer

Render and GPU

Renderpersistent projection · extract / prepare / record

RenderGraphresource accesses · pass dependencies · lifetimes

RHIopaque handles · capabilities

rhi-webgpu / rhi-wgpubrowser WebGPU / wgpu WASM

rhi-nullstructural validation

RHI-debugoptional: capture · replay · inspect

Rendering and GPU

Subsystem	Key design and responsibility	Read more
Render / RenderGraph	Persistent CPU projection and capability-gated GPU Scene; programmable pipelines and RenderFeatures; derived dependencies, usages, and lifetimes with raster / compute / copy passes executed in declaration order	Render · RenderGraph
Shader / Material	Schema-derived parameter and binding layouts; WGSL composition, Naga validation and reflection; runtime lookup of content-addressed compiled artifacts	Shader · Compiler
GPU VFX	GPU simulation and indirect rendering; code authoring and build-time compilation; particles, ribbons, trails, beams, billboards, and meshes	VFX · VFX render
RHI / Backends	Capability-gated operations across browser WebGPU, wgpu WASM, and null backends; a spec-aligned, math-free interface with opaque handles	RHI · wgpu

ECS and multiple Workers

ECS World owns entities, components, relationships, resources, and time. Systems declare access and scheduling in Update / FixedUpdate. Scene owns hierarchy and transforms; State owns state-scoped entity lifetimes. Renderer consumes World changes into a persistent projection.

HostDOM / UI · input · Web Audio · frame credit

Engine WorkerWorld + Renderer + Assets + game plugins

Kernel Worker poolQuerySpan shards over shared numeric columns

Host supplies input and one frame credit → Engine returns results and audio intents → eligible numeric work goes to Kernel, then a completion barrier returns to Engine.

Execution tier	Placement	Constraints and scope
`shared`	Engine Worker plus persistent Kernel Worker pool	Requires cross-origin isolation, SharedArrayBuffer, and related capabilities; only eligible numeric work runs in parallel
`engine-worker`	World, Renderer, assets, and game plugins in one Worker	Host retains DOM, input, and audio; requires Worker rendering capabilities
`main-serial`	World and Renderer on the main thread	The direct serial execution path
`auto`	Selects an available tier from capabilities	Reports the actual selection and reason; explicitly requesting an unavailable tier returns an error

Multiple Workers preserve one logical World with serial structural changes, no live-object transfer, and no split RenderGraph. Partial shared writes require World rebuild. See App execution and the multithreaded example.

Text and scripted assets

Procedural generation and parameter reuse bring content into the code workflow. AI can generate assets in batches, edit text directly, review diffs, and validate automatically.

Authoring form	Purpose
ScriptablePack · `.pack.ts`	Generate asset collections with functions, loops, and composition; reuse scene and geometry logic
Parameterized instances	Independent package identity, parent source, and sparse overrides for reusable variants
Pack · `.pack.json`	Declare assets, references, and instance parameters for direct field editing and diff review
Imported assets and sidecars	External glTF / FBX / image sources and metadata share the identity and cooking path

ScriptablePack.pack.ts

Pack.pack.json

External sources + Metamodels · images · fonts

↓ Producer validation and cook → published content (stable GUID · receipt · Catalog)

Producer validation and cook

Published contentstable GUID · receipt · Catalog

Runtimeload by GUID

Sources and artifacts are separate. .pack.ts executes at build time; runtime loads cooked content by stable GUID. Textures, models, and audio can still use binary sources. Repair source inputs, then cook again. See the Pack authoring contract.

Game and engine plugins

Game and engine plugins share native Cordis dependencies, activation, updates, and disposal.

Plugin layer	Typical responsibility	Composition
Project assembly	Installed plugins, configuration, and realm placement	`forge.json.plugins[]` declares Entries; DevKit generates a static Catalog for native Loader activation
Engine plugins	Scene, input, physics, audio, and ECS capabilities	Native `inject / provide` declare dependencies and services; `effect` registers contributions and their inverses
Game plugins	Player movement, camera, game UI, and gameplay systems	The reference template combines children through `definePluginGroup` / `usePlugin` in `assets/plugin.ts`

Effects unwind when their Fiber exits. ECS schedules frame work; plugin assembly stays outside hot paths. See the plugin contract and game-3d root plugin.

Simulation and interaction

Subsystem	Key design and responsibility	Read more
Networking	Sessions own replication, ACKs, retries, baselines/deltas, and connection recovery; WebSocket supplies transport	Net · WebSocket
Physics	ECS physics contracts separated from Rapier 2D / 3D backends; input synchronization, simulation stepping, and state writeback	Physics
Animation / Skinning	Renderer-independent animation graphs, clips, and playback; Skin binding and joint-path resolution	Animation · Skinning
Runtime intelligence	Optional provider-neutral Activity / Session; bounded output, cancellation, and polling; asynchronous services stay outside the ECS frame loop	Intelligence
Input / UI / Audio	Frozen frame-start input snapshots; Shadow DOM UI; realm-neutral audio intents played by Host Web Audio	Input · UI · Audio

Get started

Install @forgeax/engine, use focused subpaths such as /ecs and /app, and operate through forgeax.

pnpm dlx @forgeax/engine project new my-game --template game-3d
cd my-game
pnpm exec forgeax help --tree --json
pnpm exec forgeax project check
pnpm exec forgeax dev start --headless false --json

game-3d is a third-person reference; empty is a minimal start. Read the generated README and skills. See Engine and the CLI guide.

Run and verify

pnpm exec forgeax dev status --json
pnpm exec forgeax dev capture --json
pnpm exec forgeax dev stop --json
pnpm exec forgeax project test
pnpm exec forgeax project package --format web-zip

Observations carry a revision; captures return PNG and report references. For entity lookup, camera control, and runtime identity constraints, see persistent live control.

Source and SDK

Toolchain versions are defined in .nvmrc, .pnpm-version, and .bun-version in the repository.

pnpm install
pnpm build:engine
pnpm test

Scenario	Entry
Install the SDK	`pnpm dlx @forgeax/engine sdk install ./forgeax-sdk`
SDK `source/engine/`	Independent public source with `.forgeax-public-distribution` and prebuilt WASM; run the install/build commands above without private submodules
Full contributor checkout	Clone with `--recurse-submodules` for authorized private asset access; run `pnpm build` for the complete application fleet
Single demo iteration	`pnpm build:app hello/triangle`; broader acceptance follows the Smoke gate

The SDK includes built packages, templates, skills, and Engine source. See the SDK guide.

Explore

Entry	Purpose
AGENTS.md	Design axioms, module ownership, errors, source-work rules, and verification constraints
Packages	Package READMEs defining APIs, lifecycles, and capability contracts
Schemas / CI guide	Machine-readable contracts and verification workflows
Engine skills	Task-oriented capability discovery and operating paths
Apps / Templates	Examples, regression scenarios, and game starting points
Forbidden City showcase	`pack.ts` architecture, lighting, and continuous CLI inspection; visual quality remains a work in progress

This page is adapted from the engine README. Linked package contracts define precise capabilities and limitations.

License

The engine is licensed under Apache-2.0.