Studio Foundation

What is Studio Foundation about?

Studio Foundation provides an AI‑native, open‑source toolkit for creating and running 3D games in the browser. It uses the official Godot 4.7.1 engine plus a SHA‑256‑locked WebGPU export path that renders full 3D scenes on real GPU hardware. An MCP server and documented agent workflows let AI assistants drive builds, exports, and verification.

How to use Studio Foundation?

1. Clone the repository.
2. Run just doctor to check prerequisites.
3. Execute just bootstrap to fetch the pinned Godot source, apply the WebGPU patches, and build export templates.
4. Use just export-browser-webgpu (or the pre‑built templates) to export a game for the browser.
5. Optionally start the MCP server with the tools in tools/studio-mcp and let an AI assistant interact via the .mcp.json configuration.

Key features of Studio Foundation

• Checksum‑locked WebGPU backend – ordered patch series (0001‑0017) verified by SHA‑256.
• MCP server exposing engine lifecycle, exports, and test commands to AI agents.
• AI‑driven Blender asset pipeline for automatic glTF generation.
• Reproducible builds – every artifact (engine, patches, templates) is byte‑and‑hash pinned.
• Live demo – The Chariot Club showcases a fully rendered Roman coliseum at 60 fps with 0 GPUValidationError.
• Fallback to WebGL 2 for browsers without WebGPU support.
• Optional Rust/Nakama backend for session and persistence scaffolding.

Use cases of Studio Foundation

• Building browser‑based 3D games where AI agents generate code, assets, and testing scripts.
• Prototyping interactive experiences quickly by scripting scene construction in GDScript via AI.
• Educational platforms demonstrating AI‑assisted game development pipelines.
• Developers needing a reproducible, auditable WebGPU export path for Godot before upstream support lands.

FAQ from Studio Foundation

Q: Do I need to compile Godot myself? A: No. Pre‑built WebGPU export templates are provided in the releases. You can also build them locally with the just engine-build workflow.

Q: Which browsers are supported? A: Chrome/Edge 113+, Safari 26+, and Firefox on Windows. The demo checks compatibility before loading.

Q: Is the project compatible with existing Godot projects? A: Yes. The toolkit provides a neutral Godot project template and a studio_core addon that can be added to any Godot 4.7.1 project.

Q: How does the MCP server communicate with AI assistants? A: The server reads configuration from .mcp.json and exposes a JSON‑RPC‑style API documented in docs/agents/mcp. Agents like Claude Code can automatically detect the file and issue commands.

Q: What is the status of WebGPU support? A: Currently beta. Core 3D rendering, lighting, and shadows are verified on real hardware. Some post‑processing effects are still disabled but fail gracefully.

Studio Foundation

An AI-native, open-source game-dev toolkit — with a Godot 4.7.1 WebGPU browser backend that actually renders 3D.

Official Godot is the base and stays the upstream. On top of it sits a WebGPU export path maintained as an ordered, SHA-256-locked patch series, plus the MCP server, agent workflows, and asset pipeline that make the whole thing drivable by AI assistants. WebGL 2 remains the supported fallback.

▶ Play it live — a Godot game running on WebGPU, in your browser

No install, no plugin. Needs a WebGPU-capable browser (Chrome/Edge 113+, Safari 26+, Firefox on Windows); the page tells you if yours qualifies before you click. First load takes roughly 15–30 seconds depending on your connection — most of it downloading the ~46 MB engine, not compiling shaders (pipelines build in about 2 seconds). It is cached afterwards. Details: webgpu-performance.md.

The Chariot Club — a real game, not a test scene: a Roman colosseum with crowded stands, chariot teams, and real-time shadows, rendered by Godot 4.7.1 through WebGPU. Verified on an NVIDIA Tesla P40 at a locked 60 fps, ~490–630 draw calls and ~23M primitives per frame, with 0 GPUValidationError. The published demo was re-rendered from its own public URL on that GPU as a final check.

What you can rebuild: all of it. The engine and the patch series are checksum-locked, and both demos are now in this repository — the minimal scene below, and The Chariot Club itself under games/chariot/. Note the game is published to make the demo reproducible and auditable, not to relicense it: per games/LICENSE a game directory without its own LICENSE stays all rights reserved. The Foundation itself (engine/, tools/, shared/, …) remains under the repository root LICENSE.

webgpu_showcase.gd builds six PBR meshes, a directional light, and real-time shadow mapping entirely in code with no external assets — 59–60 fps, 36 draws/frame, 0 GPUValidationError. It exists so the render path can be re-verified without any game content. Live at /showcase/.

Our lane: AI-native, open-source game development

Godot does not accept AI-generated code contributions, and has stated it does not intend to add AI features to the engine. That is a deliberate choice — and it leaves an open lane. Studio Foundation takes it: building games with AI, in the open, is the point of this toolkit, not a bolt-on.

The WebGPU backend is proof the model works: an AI-assisted capability the community wanted for years, carried as a transparent patch series on official Godot (MIT) and verified on real hardware. It could never land upstream under Godot's policy no matter how well it works — so it lives here instead. The AI-native surface is first-class throughout the repo, not just in the engine:

• An MCP server (tools/studio-mcp, config in .mcp.json) that exposes the toolkit to AI assistants and CLIs, with its own tests and a security boundary (studio_tools/mcp).
• Agent operating agreements (AGENTS.md, CLAUDE.md, docs/agents) so AI agents build, test, and verify against the repo predictably instead of ad hoc.
• An AI-driven Blender asset pipeline (ADR 0006).
• Reproducible by construction — every artifact is byte-and-SHA-256 pinned and every patch is checksum-locked, so "AI-built" never means "unauditable." You can rebuild and re-verify all of it yourself. That auditability is the whole answer to the slop critique.

Official Godot stays the upstream. We own the distribution, not the engine (ADR 0008).

Quick start

Prerequisites are reported by just doctor. The fast repository checks require Python 3.11; Godot and the engine toolchain are needed only for their suites.

git clone https://github.com/lxsolutions/studio-foundation.git
cd studio-foundation
just doctor
just bootstrap
just test

Without just, run powershell scripts/bootstrap.ps1 on Windows or sh scripts/bootstrap.sh on Linux, macOS, or WSL2.

Use the WebGPU backend without building it

Prebuilt web export templates are published, so you can try WebGPU 3D without a multi-hour engine build:

Download the templates (official Godot 4.7.1 + patch series 0001–0014, single-threaded so exports run on plain static hosts with no COOP/COEP headers). Point your web preset's custom_template/release and custom_template/debug at them, then export with just export-browser-webgpu — that step applies the WebGPU handoff the official editor cannot emit, and skipping it produces a build that fails to start. Both files are SHA-256 listed in the release notes and reproducible from source.

Build the WebGPU path yourself

just engine-versions          # show the pinned commits and patch series
just engine-fetch             # clone official Godot, verify + apply the patches
just engine-build             # build the WebGPU export templates
just engine-validate
just export-browser-webgpu

The pipeline is deliberately split, so each stage is independently checkable:

official Godot commit -> verified patch series -> release + debug WebGPU templates
    -> Godot export -> browser runtime probe -> visual evidence

engine-build requires the Emscripten version pinned in engine-lock.toml. Full procedure: the WebGPU runbook.

Drive it with an AI assistant

The repo ships an MCP server, so an assistant can run the engine lifecycle, exports, and checks directly. Point any MCP-capable client at .mcp.json (Claude Code picks it up automatically from the repo root), then see docs/agents/mcp for the exposed tools and WORKING_AGREEMENTS.md for how agents are expected to work here.

What is verifiable

Capability	Evidence in this repository
Official engine base	Godot 4.7.1 stable is pinned by full commit in engine-lock.toml
WebGPU source	An ordered patch series in engine/patches/, each checked by SHA-256 before application. just engine-verify-patches re-checks the whole series — checksums, ordering, and that nothing on disk is unlocked — with no toolchain required
WebGPU toolchain	The exact Emdawn source and Dawn namespace backport are independently versioned and checksum-locked under engine/toolchain/
Source preparation	engine-fetch clones official Godot only and creates a disposable patched worktree
Export templates	Accepted archives are recorded by filename, byte count, and SHA-256 in engine-lock.toml
Runtime verification	Browser smoke tests observe the engine's adapter, device, and WebGPU canvas requests and reject any WebGL context request
3D shader translation	Verified in-browser on an NVIDIA Tesla P40. Patches 0009–0012 fix four distinct translation crashes; the runtime-specialized scene shader translates without crashing
WebGPU shader coverage	199 of 205 shader modules translate to valid WGSL offline, with 0 GLSL compile failures, measured at the engine's real target env (Vulkan 1.1 / SPIR-V 1.3 — the harness previously measured 1.0 and so did not reproduce the engine; see patch 0016). None of the 6 remaining failures blocks Forward+ under WebGPU: two are Forward Mobile's subpass tonemap, one is FSR's 16-bit variant (the driver reports no half-float, so the engine picks the fallback, which translates), two are the subgroup variants WebGPU does not select, one is an editor debug gizmo
Renderer ceiling	Every WebGPU export ran Forward Mobile, which hard-disables SSAO, SSIL, SSR, SDFGI, VoxelGI and volumetric fog regardless of project settings. Patches 0015 and 0017 unblock Forward+ (clustered) — the renderer those effects need, and the better architectural fit for WebGPU, since Mobile's one untranslatable shader is also the engine's only user of subpasses. Every shader Forward+ needs now translates; not yet hardware-verified, so mobile stays the export default
3D render (lit + shadowed)	Verified in-browser on an NVIDIA Tesla P40. Patches 0013–0014 fix per-stage sampler visibility and depth-texture sampler types. A minimal PBR + shadow scene renders at 59–60 fps / 36 draws per frame, and a full game (The Chariot Club) holds a locked 60 fps at ~490–630 draws and ~23M primitives per frame — both with 0 GPUValidationError
Fallback	The same template project has an official WebGL 2 export preset
Template behavior	Headless GDScript tests cover the shared addon and neutral starter project
Optional services	Rust and Nakama components are independently tested and are not required for client-only use

Exact test counts, artifact state, and unverified areas are in the verification report.

Status and honest limits

WebGPU support is beta.

What works, verified on real GPU hardware: the engine boots the WebGPU backend (Forward Mobile), translates the runtime-specialized 3D scene shaders, and renders lit, shadowed 3D geometry with 0 validation errors. 2D/UI renders and was gated against the WebGL baseline at a 1.2% visual difference.

What does not, yet: several post-processing effects (tonemap variants, SSR, TAA, SDFGI/voxel-GI debug views) still fail Tint translation gracefully — they are skipped rather than crashing, so 3D renders without them. Getting to a visible frame took fourteen patches worth of shader-translation and binding-description fixes; each one is documented in engine/patches/README.md with the exact defect it addresses.

Godot's own WebGPU support is separately in development upstream. This project is not a competitor to that effort — it is a maintained, reproducible path that works today on Godot 4.7.1, and it stays a patch series precisely so it can be retired into upstream when upstream is ready.

The published demo downloads ~45 MB of engine (12 MB compressed) before it can draw. Measured breakdown, and why that is mostly Godot rather than the WebGPU stack, is in WebGPU payload and startup.

Not yet claimed: Safari/iOS behavior and native Android/iOS device runs. The full list is in BOOTSTRAP_REPORT.md; the running engineering log is in docs/architecture/webgpu-runtime-status.md.

Measured WebGPU-vs-WebGL 2 performance (same scene, same GPU) and per-game render verification live in docs/architecture/webgpu-performance.md.

Included components

• A neutral Godot 4.7.1 project template and reusable studio_core addon.
• WebGPU export tooling with an official WebGL 2 fallback.
• Browser smoke, screenshot, visual-regression, benchmark, and release checks.
• An MCP server and agent workflow documentation.
• Blender-to-glTF validation and export tools.
• Optional Rust API/session scaffolding and PostgreSQL development setup.
• An optional Nakama adapter that forwards opaque application payloads without defining game mechanics.

The optional backend is scaffolding, not a required architecture. A consuming game owns its content, rules, schemas, identity policy, persistence semantics, and deployment.

Repository layout

Path	Purpose
engine/	Official Godot pin, WebGPU patches, build commands, and artifact records
templates/godot-game/	Mechanics-neutral Godot client and optional server template
shared/godot-addons/studio_core/	Reusable Godot services and platform interfaces
services/	Optional Rust protocol, session, API, and persistence scaffolding
infra/	Optional local PostgreSQL, Nakama, and tracing services
tools/	Engine, asset, export, browser, release, MCP, and repository tooling
tests/	Cross-language, browser, integration, performance, and visual checks
docs/	Decisions, architecture notes, and runbooks

Common commands

Command	Purpose
just test / just lint	Run the fast test and lint suites
just test-godot / test-rust / test-python	Run one implementation suite
just NAME=my_game DISPLAY_NAME="My Game" new-game	Generate a neutral Godot project
just export-browser-webgl [GAME]	Export with official WebGL 2 templates
just export-browser-webgpu [GAME]	Export with the locally built WebGPU templates
just run-browser-smoke	Check browser boot, console output, canvas, and renderer
just ci-local	Run the full local acceptance suite

Run just to list every supported command.

Source and attribution

Official Godot is the sole active engine upstream. The WebGPU backend has MIT-licensed historical lineage from dwalter/godotwebgpu; Studio Foundation maintains the current Godot 4.7.1 patch series, build tooling, and validation surface in this repository. The lineage repository is never cloned by the build.

See NOTICE.md and WebGPU integration provenance for the exact source boundary and commit pins.

Contributing and license

Material engine changes require tests, updated evidence, and the relevant ADR. Contributor workflow is in WORKING_AGREEMENTS.md. Security scope and private reporting instructions are in SECURITY.md.

Foundation code, tooling, templates, documentation, and infrastructure are dual-licensed under MIT and CC BY 4.0; see LICENSE. Third-party attribution is in NOTICE.md and dependency-licenses.md.