What is vgai?

vgai is a game engine built on Three.js, shipped together with a visual editor and a scaffolded game template — all in one monorepo. Its defining choice is the Object3D-as-truth model.

The core idea: the Object3D is the entity

Most engines put a separate entity layer next to the renderer (an ECS, a scene-node wrapper, a “VNode” bridge). vgai does not. The Three.js Object3D you add to the scene is the entity. There is no parallel world to keep in sync.

Gameplay behavior is attached to an Object3D with a GameComponent — a small class with init / update / dispose methods (and optional onTriggerEnter / onTriggerExit). If something needs per-frame logic, it gets a GameComponent; if it is static scenery, a light, or UI, it stays a plain Three.js object with no component at all.

Why this matters

One scene graph means no desync bugs between “the entity” and “the thing on screen,” hot-reloadable behavior, and an editor that edits the exact objects the game runs.

Use libraries directly — no wrappers

vgai deliberately avoids wrappers, adapters, or helper abstractions around its dependencies. You call the real APIs as documented:

• Three.js for rendering and the scene graph.
• Rapier for physics (rigid bodies, colliders, joints).
• Colyseus for multiplayer (rooms + schema sync).

When you need something the engine doesn’t pre-package, you reach into the library directly through the GameContext — ctx.scene, ctx.rapierWorld, ctx.composer, and so on.

What’s in the box

Package	What it is
packages/engine	The engine: game loop, GameComponent model, physics, scene loader + Zod schemas, animation, audio, input, networking.
packages/editor	The visual editor (viewport, inspector, hierarchy, asset browser, prefab system, and native React-root authoring) and its e2e suite.
packages/editor/template	The project template used by the public @vgai/cli create command — adapter-specific roots, a trimmed component registry, and a generic server/.
examples/<id>/	Standalone example game projects (multiplayer arena, vehicle, RTS, and more) — open one directly in the editor, or scaffold a NEW project from one with --example <id>.
packages/create-vgai-project, packages/vgai-cli, packages/editor-sdk	Scaffolding and CLI tooling.

The engine source is meant to be read and edited directly — it is not a black-box library.

Where to go next

• Install & set up a project — get a project running.
• Design philosophy — the principles behind the model.
• Foundations — learn GameComponent hands-on.