Three.js and ThreeNative

ThreeNative does not replace Three.js — it is Three.js, with the game layer and the platform layer filled in. ctx.scene is a THREE.Scene, ctx.renderer is a WebGPURenderer, and every Three.js tutorial from the last decade still applies inside a ThreeNative scene.

The framework owns the wiring and never the look. Anything that decides how a frame looks — materials, lighting, tonemapping, post, camera framing — is scaffolded into your repo as ordinary Three.js you can read, edit, or delete.

Quickstart

pnpm create threenative my-game
cd my-game
pnpm install
pnpm dev

That is a complete game: a loop, physics, a React HUD, a playtest scenario, and a scene you can edit. Requires Node 20.19+ and a WebGPU-capable browser (WebGL2 fallback is automatic).

A small game

The real portable entry from the minimal template's src/game.ts:

import { defineGame } from "@threenative/core";
import { playtest } from "@threenative/core/playtest";
import type { IPhysicsContext } from "@threenative/physics";
import { rapier } from "@threenative/physics";
import config from "../threenative.config.js";
import { Play } from "./scenes/Play.js";
import type { GameState } from "./state.js";

const game = defineGame<GameState, IPhysicsContext>({
  input: {
    move: {
      down: ["ArrowDown", "KeyS"],
      left: ["ArrowLeft", "KeyA"],
      right: ["ArrowRight", "KeyD"],
      up: ["ArrowUp", "KeyW"],
    },
  },
  plugins: [rapier(), playtest()],
  render: config.renderer,
  scenes: { play: Play },
  start: "play",
});

export default game;

A scene is a class with three optional methods — load, enter, update. That is the whole lifecycle.

Features

• Godot-shaped conventions. RigidBody3D, CharacterBody3D, Area3D, CollisionShape3D — borrowed vocabulary, so there is nothing new to learn.
• Conventions on by default. Feet meet the floor, a weapon stays in the hand that holds it, an agent walks around a wall, one metre is one metre — each with a named override on the same object.
• React HUD bindings. Game state flows into React through an external store that never re-renders on the game loop.
• A real test harness. Playtest scenarios drive the actual build in a browser or on a device and assert what happened — frames, transforms, state, performance.
• An asset pipeline. Models and textures compile to hashed, manifest-tracked output.
• An owned native runtime. The same TypeScript runs on a C++ host for desktop and Android.
• Built for agents. A searchable capability manifest ships with the library and is exposed over MCP, so an authoring agent finds what already exists instead of rewriting it.

[!TIP] Picking the model that writes the scene. threejseval ranks AI coding agents on Three.js work — one prompt, blind arena votes on the scenes they build, Elo with cost and tokens beside each entry.

Templates

pnpm create threenative my-game --template <name>

Details in create-threenative.

Packages

Platform support

ThreeNative is alpha: the API is settling and versions are 0.x.

Supported targets: web, Windows, macOS, Linux and Android. iOS is not supported yet.

You sign your own game. A desktop or Android release is signed with your certificate and keys, because the signature names the publisher of the game a player downloads. ThreeNative ships no certificate; threenative build --mode release signs with yours. See docs/RELEASE-SIGNING.md.

Every claim here is backed by a run. The current numbers live in docs/verification/runtime-perf-state.md, and everything the framework does not yet do well — with what is being done about it — is in one place: docs/CURRENT-CHALLENGES.md.

Reverse engineering Unreal

The default look and frame budget follow a fresh Unreal 5.8.3 project. Each Unreal system is ported from what its source does, never from its code, under a PRD in docs/PRDs/Unreal/.

Every Unreal 5.8.3 system that sets the look or the frame cost, split into 380 subsystems and measured in lines of the Unreal source. Each one maps to the ThreeNative PRD that ports it.

20% done · 24% in progress · 33% not started · 16% deferred · 5% with no PRD (share of 676K Unreal lines; the tool-heavy Niagara, Landscape, World Partition, RHI and RenderCore modules are left out) · 82 open PRDs on this branch · 72 subsystems with no PRD

Pace: 118 PRD boxes ticked a week over the last 2 weeks. The port order runs waves 1-4 first, so at that pace the default look is done about Nov 17, 2026, and everything filed today about Dec 8, 2026. Scope grows as PRDs are filed, so read the dates as the earliest finish.

Select the map to open the interactive page in a browser. It lists the PRDs and gaps of every feature and the order to port them in.

Docs

• docs/README.md — the map: PRDs, verification, benchmarks, strategy, architecture, product, spikes.
• docs/architecture/CHARTER.md — what the framework is, what it refuses to be, and the rules that decide both. Binding.
• docs/architecture/AGENT-INTERFACE.md — the surface an authoring agent reads.
• CONTRIBUTING.md — what the public surface is, what each version number promises before and after 1.0, and how a symbol gets deprecated.
• packages/create-threenative/README.md — templates and the scaffold command.
• Unreal render feature map — the Unreal 5.8.3 visual and performance systems, sized by measured lines of code, rated for complexity, and colored by ThreeNative status. Open the file in a browser. The Markdown report has the same data.

Contributing

Contributions are welcome — issues, discussions and pull requests alike.

pnpm install --frozen-lockfile
pnpm typecheck && pnpm lint && pnpm test

Native compilation is opt-in; the default gate needs no CMake, NDK, or Xcode. There is no root pnpm dev — run an example by name, for example pnpm --filter abyss-framework dev.

Read CONTRIBUTING.md before opening a pull request, and AGENTS.md for the full working conventions. Everyone taking part is expected to follow the Code of Conduct.

Community and support

• Questions and ideas → GitHub Discussions
• Bugs and feature requests → Issues
• Security reports → SECURITY.md (please do not open a public issue)

Licence

MIT — see LICENSE. ThreeNative is MIT end to end, including the native runtime.

The name and logo are not covered by the MIT licence — see TRADEMARKS.md.