Documentation

ForgeaX is an AI-native game development studio. You describe the game in plain language; an AI lead called Forge plans it, designs it, and writes it into running game code itself, hot-reloading the result into your browser — what you say is what you play.

Two in-house foundations sit underneath: an engine redesigned for the AI's point of view (see Why an AI-native engine) and a development loop that converges features on a correct result (see How AI gets a feature right).

It suits 2D / 2.5D / 3D web games. Playable FPS, Diablo-style ARPG, two-level survival and shooter demos already exist (see the showcase); the engine covers PBR / IBL / SSAO rendering, 2D/3D physics, skeletal animation and dual RHI (see "Engine capabilities" at the bottom of the showcase).

Everything runs in the browser (WebGPU), web and desktop on one stack; open source under Apache License 2.0 (see the license).

Prerequisites: git, bun ≥ 1.3, node ≥ 22, curl. (On a clean host, bun fx setup can also bootstrap bun / node 22+ / pnpm / the Rust+wasm toolchain — zero-prompt by default; --interactive asks per tool, --skip-bootstrap skips it.)

git clone --recurse-submodules \
  https://github.com/ForgeaX-Games/forgeax-studio.git
cd forgeax-studio
bun fx setup          # one-time setup
bun fx start          # → http://localhost:18920

What bun fx setup does: verifies prereqs → inits submodules → builds the engine packages → runs bun install in each sub-repo → builds the marketplace plugins → scaffolds $ROOT/.env from .env.example. With --interactive it also prompts for ANTHROPIC_API_KEY; otherwise it warns and you edit .env later.

bun fx start boots three services: server (:18900, the runtime core — chat / backends / sessions), interface (:18920, the Studio UI with vite HMR), and engine (:15173, the renderer). Override ports in .env via FORGEAX_{SERVER,INTERFACE,ENGINE}_PORT. Then open http://localhost:18920.

Everyday commands (one entry, bun fx): run bun fx setup once to prepare the environment; later pull updates with bun fx update (updates the root repo + syncs submodules, no reinstall / rebuild); bun fx start / bun fx start app launch web / desktop; bun fx stop and bun fx restart stop / restart; bun fx status and bun fx doctor diagnose your setup; bun fx build app packages the desktop app. Run bun fx with no arguments to list every command.

Desktop app: bun fx start app opens a native window on the live source (first run auto-installs and starts the stack; closing it stops the stack); bun fx build app packages a self-contained .app / .dmg. See Run & preview for all modes.

Platform support (macOS / Linux / Windows, first-class): install and launch are one set of cross-platform Bun scripts, so all three systems run the same bun fx commands with identical behavior — and Windows no longer needs Git-Bash (the old dual .sh / .bat / .ps1 scripts were deleted). Specifically: web dev (bun fx start) and desktop dev (bun fx start app, a native Tauri window on live source) work on macOS / Linux / Windows; packaging a game into a double-clickable .app / .dmg (bun fx build app) is currently done on macOS. Common Windows-specific issues (black preview, a console window per turn, processes not closing cleanly, the system's stub Python) are all fixed — see Changelog · 2026-06-28.

Prefer not to do it by hand? Let your AI coding CLI clone & launch it — see Have your AI CLI clone & launch it; then build your first game with Quick start. For API keys, see Advanced · Switch / configure the AI backend.

The interface is three parts: a top bar, the chat on the left, and the preview/workbench on the right.

• Top bar — the ⊕ new menu, a project switcher (move between games — what a "project" is is covered in Core concepts), and a session switcher (review / switch past conversations).
• Left · chat (ChatPanel) — a team rail (Forge and the sub-agents), a message stream (sub-agent cards, Forge's thinking and tool calls), and a composer at the bottom with a backend switch at its bottom-right (see Advanced).
• Right · main area (MainArea) — toggles between the preview (your game live in an iframe) and the workbench (file editing / design docs); see Scenes & editor.

The top-right cog opens Settings: API keys, model choice, CLI backend, and plugin management. The desktop app also shows a first-run overlay that prompts for the key the first time you open it.

In ForgeaX, "project" and "game" are the same thing — a game is one games/<slug>/ folder. A real game folder usually looks like this:

• forge.json — the game manifest. Minimally three fields: id, name, and entry (pointing at the entry code, e.g. src/main.ts).
• FORGE.md — the game's own readme / gameplay overview (controls, mechanics, story beats).
• src/ — the game code. Besides the main.ts entry, it's usually split into modules by concern (e.g. player.ts, enemies/, effects.ts, setup.ts).
• design/ · assets/ — design documents and art / audio assets.
• package.json · tsconfig.json — standard TS project files.

The main.ts entry imports engine capabilities from @forgeax/engine-runtime / engine-ecs / engine-app and exports a GameEntry — the contract by which the engine loads a game. For the full capability set, see "Engine capabilities" on the showcase.

Multiple games = multiple projects, switched in the top-bar project switcher. For how scenes / levels are organized, see Scenes & editor.

Forge (the main agent) is the only one that writes game code directly — it writes games/<slug>/src/main.ts, the preview hot-reloads, and it sees the running result to decide the next step. That edit → see → edit loop has to stay with whoever can see the preview, i.e. Forge (see Build by chatting).

Sub-agents (e.g. Iori gameplay, Suzu design, Kotone narrative, Iro art, Tsumugi build) only plan / design / make assets / write docs and never touch src/ — they have no live-preview feedback, so any code they wrote would have nothing to steer it. See the full cast in the marketplace and Chapter 10 · The agent team.

How dispatch works: Forge dispatches a sub-agent with one tool call (shaped like subagent(type="iori", task="…")); the server's /api/subagent stream bridges its output back into the main conversation in real time — that's the embedded sub-agent card you see in the message stream. A sub-agent's design docs are filed under its own section in the workbench (see Scenes & editor).

A session is an agent's memory — an append-only stream of events (each one is a user message / assistant message / thinking / tool call / tool result). Forge (main) and each sub-agent each keep their own.

The UI splits events by who emitted them into the main thread vs sub-agents, rendering each sub-agent's slice as an embedded card. So on one screen you see both Forge's main thread and what the sub-agents it dispatched actually did.

Use the top-bar session switcher to review and switch past sessions. Switching a session restarts nothing — the UI just reads a different agent's event stream.

The more specific you are, the better Forge nails it first try with fewer redos. A good prompt usually covers:

• Genre & view — top-down / first-person / 2.5D side-scroller…
• Core loop — the one thing the player keeps doing
• Controls, win/lose, enemies / obstacles, and the feel

Start small, get it running, then layer mechanics on. For example:

A top-down game: a character runs around an arena,
space fires bullets, enemies keep spawning,
hits remove them and add score.

For a step-by-step first game, see Quick start; for what's achievable, browse the showcase. For heavier design, Forge pulls in design sub-agents (see Core concepts).

Once you send a request, the chain is:

• Understand + plan — Forge clarifies the requirement, dispatching design / gameplay sub-agents for heavier work (see Core concepts).
• Write code — Forge writes itself into games/<slug>/src/main.ts (and its split-out modules).
• Hot-reload — on save, the engine's vite detects the change and the preview hot-replaces the module in place — no full reload, the picture updates almost instantly.
• See the result — Forge sees the running result through the preview (which also forwards the game's console back), and decides the next step.

The whole process is transparent: the message stream shows Forge's thinking, each tool call, and the cards of the sub-agents it dispatched. For switching/controlling preview vs workbench, see Scenes & editor; for how hot-reload works, see Run & preview.

Not happy? Keep talking — each bit of feedback becomes another change, visible instantly via hot-reload:

Faster bullets, double enemy health, night background.

The preview has play / pause / reload controls for testing as you go; to pin the preview to a specific game, switch in the project switcher (see Open the studio, learn the interface).

The basic loop is describe → generate → play → describe again. Run it smoothly and you go from a sentence to a playable game — the full onboarding is in Quick start.

The right-hand main area toggles between two views:

• Preview — your game runs live in an iframe, with an FPS readout and play / pause / reload controls. When Forge writes code, it hot-reloads here instantly (see Build by chatting).
• Workbench — a file browser + editor: view / edit / save text & code, render markdown design docs, and preview images, audio, video and 3D models. It also surfaces file activity and "who's editing" locks, so you and the AI edit the same files without clobbering.

With no file open, the workbench shows entries for every creation workbench (character / animation / 3D / scene / UI / music…) — see Creation tools and the marketplace. For making assets, see Assets.

The scene editor saves a level's contents to a scene data file in the game folder (scene.pack.json) — the single source of truth for that level: what's on disk is what runs in the game.

When you place objects and leave edit mode, the changes are flushed to disk and the running game re-reads them, so the preview reflects your edits immediately — the edit→play round-trip. Conversely, when Forge changes code by chat it rides the same hot-reload path (see Build by chatting and Run & preview).

A game can have multiple scenes / levels, each its own scene data, switched and reused as needed — the "Cow Survivor" demo switches between a day pasture and a night graveyard (see the showcase).

How to organize: objects live in the scene data, while art / audio assets live in the game folder (project layout in Core concepts, asset generation in Assets). Splitting by scene keeps a growing game maintainable.

Use the character editor (wb-character) for character concept design: write a one-line brief, get a portrait + turnaround. No drawing skills needed to get a game-ready character.

Its outputs (a character manifest + portrait / turnaround) are stored per character inside your game and feed straight into the animation workbench as downstream input — so "design the character → make it move" is one continuous pipeline (see the next item).

Each workbench is a panel plus a set of tools; you-by-hand and AI-by-dispatch edit the same artifact. Full list in the marketplace and the workbenches tutorial.

2D: the animation workbench (wb-anim) uses the character portrait as a template and turns it into walking, attacking, four-direction motion, even short clips — without face drift, so it stays the same character once it moves.

3D: the engine natively supports skeletal animation — import a rigged, skinned model plus animation clips from FBX, with smooth crossfades between idle / walk / run / cast / death. This pipeline is real and shipped — it's how the dark-fantasy witch in the showcase moves: see the skeletal-animation milestone and the showcase (Hellforge).

Beyond characters, there are workbenches across the whole pipeline:

Item-by-item coverage is in Chapter 9 · Creation tools, the workbenches tutorial, and the marketplace.

An actual ForgeaX engine example running live on this page (WebGPU — Chrome / Edge recommended). More runnable demos in Examples and Games.

Open full screen ↗

The same codebase runs in three forms:

• Web dev — bun fx start boots three services (server / UI / engine); open http://localhost:18920 in a browser, edits hot-reload live. Works on macOS / Linux / Windows. Install in Before you start.
• Desktop dev — bun fx start app opens a native window loading the same dev server, with identical live source and HMR; first run auto-installs and starts the stack, closing the window stops it. Available on macOS / Linux / Windows.
• Desktop .app (packaged) — bun fx build app produces a self-contained .app / .dmg that runs on double-click with its own sidecar (ports 18810 / 15273, deliberately offset from dev's 18900 / 15173 so both can coexist); its key lives in ~/ForgeaxProjects/.env, with a first-run overlay. Packaging is in Publish & share.

All three ports are overridable in .env via FORGEAX_{SERVER,INTERFACE,ENGINE}_PORT. ⚠️ The desktop window uses the system WebView, so 3D runs on WebKit's WebGPU — a bit weaker than Chrome's. For the best visuals, use the browser.

Save and it takes effect — no manual refresh:

• Edit game code (games/<slug>/src/…) → the engine hot-swaps the module in place and the preview updates instantly (Forge's edits ride this too — see Build by chatting).
• Changes in the scene editor flush to disk and flow back into the running game (see Scenes & editor).

• Blank preview / engine error — the engine isn't built; re-run bun fx setup.
• SSL error on :18920 — access via http://localhost (WebGPU still works on localhost).
• Port in use — a busy port errors out (it won't auto-pick another); run bun fx stop then bun fx start, or change ports in .env.
• Chat says no API key — set ANTHROPIC_API_KEY in .env (the desktop app prompts on first run); key setup is in Advanced.
• 3D looks weaker on desktop — a limitation of the system WebView's WebGPU; use the Chrome browser build for best rendering.

bun fx build app packages the whole studio together with your game into a self-contained desktop bundle (macOS .app / .dmg): a trimmed runtime, the server, the Studio UI, the marketplace and your game content are all inside, so it runs on double-click with zero setup for the user.

It runs on a built-in sidecar at its own ports (18810 / 15273), so it never collides with your dev stack (see Run & preview). Packaging must run on macOS; the packaged .app opens on double-click.

A game is one self-contained games/<slug>/ folder (forge.json + src/ + design docs + assets, see Core concepts). Share or commit that folder and someone else opens it in their studio to keep playing or building — the demo library stores several games side by side (fps, hellforge, cow-survivor, shoot-opt), see the showcase.

For now the most reliable way to hand a game to players is the desktop package above; a smoother "one-click web publish / play online" is still in the works.

Switch backends (swap the chip): pick the kernel from the backend switch at the composer's bottom-right, or under the CLI section of Settings — Claude Code / Codex / Cursor / Kimi Code / CodeBuddy / DeepSeek Harness / forgeax-cli. The CLI section shows each backend's health and a Test button. Switching a backend also swaps its default persona (see The agent team); details per backend in the marketplace.

Keys / models: set your model API key (e.g. ANTHROPIC_API_KEY) under Settings → Keys — it applies live, no restart (you can also edit .env directly); choose the model under Settings → Models. Missing-key troubleshooting is in Run & preview.

Almost every capability in ForgeaX is a runtime-loaded plugin (overview in the marketplace), so you can add your own.

The quickest path today: copy an existing workbench plugin and adapt it, with the plugin author (wb-plugin-author) helping; a fuller in-app visual editor (file tree + code editor, save → auto-reload) is on the way. Once built, enable and reorder it in the admin panel — plugins are mounted by the CLI at runtime. See the kinds of workbench in Creation tools.

Use the persona editor (wb-agent-persona): pick an agent from the list, edit its persona in a text area, and save → hot-reload, no restart. You can give an agent a different character or voice without touching any code.

For who's the main vs sub-agents and where default personas come from, see Core concepts and The agent team; the full cast is in the marketplace.

All of these are loadable plugins; the full, filterable catalog is in the marketplace, and a tutorial walkthrough is in the workbenches tutorial.

Arin · producer — an all-round producer who coordinates design / code / art / audio and owns the whole game.

Reia · reel director — interactive FMV director who forges prompts, paces QTEs and weaves branches and endings, driving the wb-reel Reel Studio to turn one idea into a clickable, playable suspense film.

These are named agents dispatched on demand by Forge (the main vs sub-agent relationship is in Core concepts); the full cast is in the marketplace.

These specialists only plan and design — they never touch game code (Forge writes code, see Core concepts); their output lands in the workbench (see Scenes & editor), and art assets are produced as in Assets.

There's also a set of art / asset specialist agents (2D character / animation, 3D low-poly / VFX, interactive-film director, and more), each wired to its matching creation workbench (see Creation tools).

Each CLI backend ships with an out-of-the-box persona: Claude (Claude Code), Codex, Cursor, and ForgeaX (the self-built forgeax-cli). Switching the backend swaps the default persona — no setup needed; whichever kernel you pick comes with its default persona.

How to switch backends and edit personas is in Advanced; the full agent cast and loadable personas are in the marketplace.