@vgai/editor-sdk

Typed client for the editor dev server's control API. This is the layer the vgai CLI and tooling use to drive a running editor: commands are POSTed to /__editor/command, relayed to the browser editor over SSE, executed there, and the real result (or an explicit "no editor connected" timeout) comes back to the caller.

Usage

import { EditorClient } from '@vgai/editor-sdk';

const editor = new EditorClient(); // default http://127.0.0.1:20173
const projectEditor = new EditorClient({ url: 'http://127.0.0.1:25786' });
await editor.play();

// Present the same editor subject/view to the connected human and get a
// compact share URL. This does not serialize document contents or layout.
const shown = await editor.present({
  version: 1,
  document: { kind: 'tool', id: 'walking-castle-builder' },
  viewport: { camera: 'isometric', frame: 'document' },
  utility: 'profiler',
});
console.log(shown.url);
await editor.waitForState((s) => s.playState === 'playing');
const entries = await editor.getLogEntries(); // proves frames actually ran

Surface

One export, EditorClient, plus its types (EditorState, ProjectInfo, AssetKind, ShadingMode, ...). Methods, by group:

• Play control: play, restart, stop, pause, resume, step
• Selection: select(id | null), selectMultiple, selectAll
• Viewport: focusEntity, focusSelection, viewPreset, setCamera, captureViewport
• Asset preview: captureAssetPreview for deterministic front, right, top, and three-quarter captures of a project model or authored entity hierarchy
• Panels: showViewport('scene'|'game'), showInspector, openAsset, closeAsset, toggleConsole, toggleCommandPalette, showBuild, and present(EditorView) for an atomic human-visible view plus share URL
• Display: setGrid, setHelpers, setStats, setShadingMode (solid for authored materials, clay for neutral flat shading, unlit, wireframe, normals, or overdraw), setHelperType (including the independent bounds category). Shading targets the active Scene/Game viewport and remains render-only, session-local state.
• Transform tools: setTransformMode, setTransformSpace, setSnap
• Project: createProject, openProject, getProject, listRecentProjects
• State/logs: getState, waitForState(predicate, timeoutMs), getLogEntries
• Project tools: listProjectTools, runProjectTool

Commands throw on { ok: false } responses, including the server's timeout when no browser editor is connected — failures are never silently swallowed.

Editor contributions for project tools

An optional React contribution is a normal default-exported component. Import its props from @vgai/editor-sdk/contributions; the editor supplies the exact registered tool and an already-configured client:

import { Button } from '@editor/widgets';
import type { ToolContributionProps } from '@vgai/editor-sdk/contributions';

export default function MapBuilder({ tool, client, account }: ToolContributionProps) {
  return (
    <Button
      variant="primary"
      onClick={() => void client.runProjectTool(tool.name, { seed: 42 }, { confirm: true })}
      title={`Default execution: ${account.preferredRoute}`}
    >
      Build map
    </Button>
  );
}

The package registration chooses workspace.document, workspace.utility, workspace.analytics, selection.inspector, asset.inspector, or generation.result. Selection Inspector contributions receive node/nodeId and export match(node, adapter); asset Inspector contributions receive asset and export match(asset). A generation-result contribution receives the durable job and raw native poll result inside the editor-owned result document and must export match(job, result); registration order never selects a renderer. All contributions receive account, a validated global projection containing plan, credits, spend policy, and provider-specific route availability. It never contains an access token. There is no extension class, lifecycle, or proprietary UI description.

Use ordinary React/CSS for composition and @editor/widgets for controls. Shape the UI for its contribution point: a bounded workspace for documents, a dense single column for inspector sections, and a compact row/status block for utilities. Badges are for short statuses and counts, not headings.

Extension contract (@vgai/editor-sdk/extension)

The typed contract for everything a game project contributes TO the editor — three surfaces, one outcome vocabulary (ExtensionContributionState: active / absent / failed). An absent contribution hides its surface (the editor never fabricates placeholder data); a failing one is contained per-contribution and reported loudly on the editor console — never a crashed editor, never silent fake output.

1. Editor panels — workspace.document / workspace.utility tool contributions (previous section). Panels join the Dockview workspace; there is no parallel rail.
2. Inspector sections — selection.inspector / asset.inspector tool contributions with an exported match.
3. System adapters — runtime capabilities registered from game code via ctx.registerSystemAdapter?.(kind, impl) (SystemAdapters in @vgai/engine). Deliberately not re-exported here: the engine already publishes that seam and every consumer of it also imports the engine.

Asset Lab capture

captureAssetPreview accepts exactly one source: an authored entity hierarchy already loaded in the editor, or a same-origin project .glb/.gltf path. Rendering happens in an isolated native editor scene and returns deterministic front, right, top, and three-quarter PNGs plus a labeled contact sheet:

const sketch = await editor.captureAssetPreview(
  { entityId: 'storefront-sketch' },
  { width: 768, height: 768, background: 'neutral' },
);

const model = await editor.captureAssetPreview(
  { assetPath: '/models/storefront.glb' },
  { background: 'transparent' },
);

Project model input is bounded to 64 MiB and 25 seconds. External .gltf buffers and images must resolve on the same project origin. The thin CLI equivalent writes the four views and contact sheet to disk:

npm run vgai -- screenshot /models/storefront.glb --out artifacts/storefront

Limitations

• The published package exports raw TypeScript (exports: "./src/index.ts"), so consumers need a TypeScript-aware runner/bundler such as tsx or Vite.
• Requires the editor dev server (npm run dev or npx @vgai/cli@latest edit <project>); there is no offline mode.