What is vgai?

vgai is a game engine, visual editor, and universal web-game host. First-party games usually use React Three Fiber, PixiJS, and React UI, while adapter roots can mount existing games without translating them into a private scene format.

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.

Behavior stays in the world’s native source. An R3F component calls useFrame; a Pixi component calls useTick; an ingested game keeps its own update loop. Static scenery and lights remain ordinary library objects with no engine wrapper.

Why this matters

One world graph means no desynchronization between “the entity” and “the thing on screen.” The editor inspects the actual objects the game runs and writes edits back to their source.

Use libraries directly — no wrappers

Project code calls ecosystem libraries directly:

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

The adapter boundary is the deliberate exception: it has multiple genuine implementers. Inside a world, use the context that root actually provides. An imperative setup(ctx) root receives GameContext; an R3F or Pixi TSX root receives the smaller explicit context its host can honestly construct.

What’s in the box

Package	What it is
packages/engine	Host loop, root adapters, observability contracts, input, runtime mounting, and first-party Three/Canvas substrates.
packages/editor	Viewport, hierarchy, inspector, source write-back, asset documents, Play mode, and project tools.
packages/editor/template	The neutral standalone project copied by vgai create.
examples/<id>/	Maintained standalone reference games that can be opened directly or copied 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 roots, source components, scenes, and prefabs.