Language: English · 简体中文

ForgeaX Engine

An AI-native game engine designed to maximize AI efficiency.

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.

[!IMPORTANT] 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.

[!NOTE] 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.

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.

flowchart TB
    PROJECT["Game projectforge.json · code · asset sources"]
    DEVKIT["DevKit / CLIproject operations · build · inspect"]
    COOK["Build-time productionimport · cook · shader / VFX compilation"]
    ASSETS["AssetRegistryGUID → published content"]
    APP["App + native Cordisrealm assembly · input · frame pacing · lifecycle"]
    WORLD["ECS Worldstate · time · Update / FixedUpdate"]
    DOMAINS["Domain systemsscene · animation · physics · audio intents · net"]
    RUNTIME["Runtimeselect backends and services · assemble Renderer"]
    RENDER["Renderpersistent projection · extract / prepare / record"]
    GRAPH["RenderGraphresource accesses · pass dependencies · lifetimes"]
    RHI["RHIopaque handles · capabilities"]
    GPU["rhi-webgpu / rhi-wgpubrowser WebGPU / wgpu WASM"]
    NULL["rhi-nullstructural validation"]
    DEBUG["RHI-debugcapture · replay · inspect"]
    PROJECT --> DEVKIT
    DEVKIT --> COOK
    COOK --> ASSETS
    DEVKIT --> APP
    APP --> WORLD
    APP --> RUNTIME
    WORLD  DOMAINS
    RUNTIME --> RENDER
    WORLD -->|"Change evidence and scene data"| RENDER
    ASSETS --> RENDER
    RENDER --> GRAPH
    GRAPH --> RHI
    RHI --> GPU
    RHI --> NULL
    RHI -.->|"Optional recording"| DEBUG

Rendering and GPU

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.

flowchart LR
    HOST["HostDOM / UI · input · Web Audio · frame credit"]
    ENGINE["Engine WorkerWorld + Renderer + Assets + game plugins"]
    KERNEL["Kernel Worker poolQuerySpan shards over shared numeric columns"]
    HOST -->|"Input and one frame credit"| ENGINE
    ENGINE -->|"Results and audio intents"| HOST
    ENGINE -->|"Eligible numeric work"| KERNEL
    KERNEL -->|"Completion barrier"| ENGINE

[!NOTE] 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.

flowchart LR
    SCRIPT["ScriptablePack.pack.ts"]
    TEXT["Pack.pack.json"]
    IMPORT["External sources + Metamodels · images · fonts"]
    COOK["Producer validation and cook"]
    PUBLISH["Published contentstable GUID · receipt · Catalog"]
    RUNTIME["Runtimeload by GUID"]
    SCRIPT --> COOK
    TEXT --> COOK
    IMPORT --> COOK
    COOK --> PUBLISH
    PUBLISH --> RUNTIME

[!IMPORTANT] 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.

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

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.

Explore

[!NOTE] This README has an English canonical version and a Simplified Chinese mirror. Update both in the same commit. Linked package contracts define precise capabilities and limitations.

License

Apache-2.0.