@gizmo3d/engine

@gizmo3d/engine is the Gizmo browser/runtime package. It contains the 3D engine, editor-facing APIs, world initialization and serialization, automation command/resource definitions, headless automation sessions, and versioned browser runtime bundles.

Use this package when you want to embed Gizmo in a browser app or build directly against engine/editor APIs. If you primarily want to create and edit worlds from the terminal, start with @gizmo3d/cli.

Install

npm install @gizmo3d/engine

Minimal Browser Runtime

import { EngineMode, startEngine } from '@gizmo3d/engine';

const canvas = document.querySelector('canvas');

if (!canvas) {
  throw new Error('Missing canvas element');
}

const engine = startEngine(canvas, {
  mode: EngineMode.EDITOR,
});

Engine Modes

import { EngineMode } from '@gizmo3d/engine';

• EngineMode.GAME: gameplay mode with player controls and physics simulation.
• EngineMode.DISPLAY: view-only mode for presenting scenes.
• EngineMode.EDITOR: editing mode with fly controls, selection, transforms, and editor UI integration.

World Initialization and Serialization

import { initialize, serializeWorld } from '@gizmo3d/engine';

World definitions are the durable scene/simulation format shared by the engine, CLI, and MCP server. A world can include metadata, dimensions, entities, achievements, module definitions, stores, and runtime-facing configuration.

JavaScript/MJS world scripts can execute code. Only load world scripts from trusted workspaces. Prefer JSON worlds for data-only interchange.

Automation APIs

The package exports automation APIs under @gizmo3d/engine/automation and specific subpaths:

• @gizmo3d/engine/automation
• @gizmo3d/engine/automation/world
• @gizmo3d/engine/automation/definitions
• @gizmo3d/engine/automation/commands
• @gizmo3d/engine/automation/resources
• @gizmo3d/engine/automation/session
• @gizmo3d/engine/automation/headless

Automation commands are structured operations such as add-entity, set-transform, modify-component, and set-viewport-camera. Automation resources are read-only views such as world-state-summary, entity-list, component-catalog, entity-bundle, render-screenshot, and viewport-camera.

The source of truth for these surfaces is:

• src/automation/definitions.ts
• src/automation/commands.ts
• src/automation/resourceCatalog.ts
• src/automation/resources.ts

Generated references:

• Automation commands
• Automation resources

Browser Runtime Artifacts

The published npm package includes versioned browser runtime artifacts under:

node_modules/@gizmo3d/engine/dist/browser/<engine-version>/

Applications that load dynamic worlds should serve the runtime version that matches the package version they target. Local package builds emit the same files under engine/dist/browser/<engine-version>/ before publishing.

Local Development

From the repo root:

npm install
npm run build --workspace=engine
npm run test --workspace=engine

To build the publishable package artifacts:

npm run build:package --workspace=engine

Documentation

• Engine overview
• Automation API
• Concepts
• Architecture
• Examples
• Security

License

Apache-2.0