@vgai/engine 0.5.4 → 0.5.6

package/dist/ecs/user-data.js

@@ -0,0 +1,145 @@
+/**
+ * Typed registry for `Object3D.userData` keys used by the engine and editor.
+ *
+ * Three.js lets any code stash arbitrary values on `object.userData`, and over
+ * time the engine + editor accumulated ~20 stringly-typed keys that together
+ * form a *parallel object model* — meaning carried entirely in undocumented
+ * string literals. This module is the ONE documented place that lists every
+ * such key, its value type, and what it means. All engine/editor-internal
+ * `userData` access for these keys must go through {@link getUserData} /
+ * {@link setUserData} / {@link hasUserData} / {@link deleteUserData} so the key
+ * strings live in exactly one place and are type-checked at every call site.
+ *
+ * NOTE: This covers engine/editor *internal* keys only. User game code in the
+ * example template may stash its own ad-hoc keys; those are out of scope.
+ *
+ * ## Key reference
+ *
+ * Serialization / identity (load-bearing — editor identity):
+ * - `entityId`            — the entity's stable string id. Presence also marks an
+ *                           Object3D as a "real" entity (vs editor helper/env object).
+ *
+ * Runtime scene-query metadata (read by `scene-query.ts` and `scene-index.ts`):
+ * - `tags`                — string[] tags for `queryByTag` and the live index.
+ * - `attributes`          — per-object `Record<string, string|number|boolean>`
+ *                           of game-defined attributes (P2 `observe`). Written
+ *                           through `SceneIndex.setAttribute`, which emits an
+ *                           `attributechanged` signal; JSON-simple values only,
+ *                           so an attribute survives serialization unchanged.
+ *
+ * Runtime gameplay metadata:
+ * - `forward`             — `[x,y,z]` model-space visual forward exported as
+ *                           ordinary glTF extras for asset-facing validation.
+ * - `navRole`             — `'walkable' | 'obstacle'` navmesh role; collected at runtime.
+ * - `pivot`              — `[x,y,z]` local-space pivot for rotate/scale-around-pivot.
+ * - `splineCurve`         — resolved THREE curve for a spline-following object.
+ * - `_camera`             — THREE.Camera owned by a camera entity (collected on load).
+ * - `_particleSystem`     — three.quarks ParticleSystem (scene-sync registration + census).
+ * - `gaussianSplat`       — native Spark splat metadata used for renderer discovery,
+ *                           inspector facts, bounds, and deterministic disposal.
+ *
+ * Animation (load-bearing — ED5 disposal contract):
+ * - `_animMixer`          — THREE.AnimationMixer driving this subtree's clips.
+ * - `_animClips`          — Map<string, AnimationClip> discovered on the GLTF (E5 —
+ *                           lets game code build its own XState-driven
+ *                           binding via `bindXStateAnimation` over the SAME
+ *                           mixer; see xstate-animation-binding.ts).
+ * - `_availableClips`     — string[] of clip names discovered on the GLTF
+ *                           (inspector dropdown; same names as `_animClips`' keys).
+ * - `_xstateAnimation`    — live native XState/Three binding exposed for
+ *                           play-mode inspection; removed when binding disposes.
+ *
+ * Disposal contract:
+ * - `__sharedGeometry`    — `true` when a mesh's geometry is shared/cached and MUST
+ *                           NOT be disposed by per-object cleanup (P0.2 contract).
+ *
+ * Editor shading overrides (editor-only, see `scene-sync.ts`):
+ * - `__shadeOrig`         — original material(s) stashed before a shading override.
+ * - `__shadeUnlit`        — generated unlit material(s) for the unlit view mode.
+ *
+ * Unmodified-game ingestion (editor-only, see `editor/src/ingest/`):
+ * - `__ingest`            — `true` on every Object3D minted by ingestion; routes
+ *                           edits to live mutation.
+ * - `__ingestNextId`      — monotonic id counter stashed on the captured Scene
+ *                           root so re-reflects keep minting unique ids.
+ *
+ * Editor scene-graph tagging (editor-only):
+ * - `engineInternal`      — `true` on engine-owned infrastructure in the game scene
+ *                           (particle BatchedRenderer, debug-draw + its subtree).
+ *                           The editor's play-mode hierarchy skips these so they
+ *                           don't show up as selectable "entities".
+ * - `authoringRoot`       — explicit opt-in for a runtime descendant to become
+ *                           its own authoring object instead of a part of the
+ *                           nearest ancestor owner.
+ * - `authoringInstance`   — source OID of the custom-component callsite that
+ *                           rendered this existing Object3D. Used to group
+ *                           implementation parts without adding wrappers.
+ * - `authoringLabel`      — authored literal name (or component tag fallback)
+ *                           for that source-backed component instance.
+ * - `editorHelper`        — `true` for editor-only helper objects (gizmos, wireframes).
+ * - `editorHelperType`    — which kind of helper (lights/particles/pivot/navmesh/...).
+ * - `editorIcon`          — `true` for editor billboard icon sprites.
+ * - `skeletonVisible`     — per-entity editor preference for its bone overlay.
+ * - `skeletonEnabled`     — resolved visibility preference on a skeleton helper.
+ * - `envObject`           — `true` for environment objects (ambient light, etc.).
+ * - `splineControlPoint`  — index of a spline control-point drag handle.
+ * - `vcDirIdx`            — view-cube face direction index (0=+X,1=-X,2=+Y,...).
+ */
+/**
+ * Canonical name → literal `userData` string key. The accessor names match the
+ * raw string keys 1:1 (this is the documented set referenced by the AC), so the
+ * literal strings appear in exactly this one place.
+ */
+export const UserDataKeys = {
+    entityId: 'entityId',
+    forward: 'forward',
+    tags: 'tags',
+    attributes: 'attributes',
+    navRole: 'navRole',
+    pivot: 'pivot',
+    splineCurve: 'splineCurve',
+    splineControlPoint: 'splineControlPoint',
+    _camera: '_camera',
+    _particleSystem: '_particleSystem',
+    gaussianSplat: 'gaussianSplat',
+    _animMixer: '_animMixer',
+    _animClips: '_animClips',
+    _availableClips: '_availableClips',
+    _xstateAnimation: '_xstateAnimation',
+    __sharedGeometry: '__sharedGeometry',
+    __shadeOrig: '__shadeOrig',
+    __shadeUnlit: '__shadeUnlit',
+    __ingest: '__ingest',
+    __ingestNextId: '__ingestNextId',
+    engineInternal: 'engineInternal',
+    authoringRoot: 'authoringRoot',
+    authoringInstance: 'authoringInstance',
+    authoringLabel: 'authoringLabel',
+    editorHelper: 'editorHelper',
+    editorHelperType: 'editorHelperType',
+    editorIcon: 'editorIcon',
+    skeletonVisible: 'skeletonVisible',
+    skeletonEnabled: 'skeletonEnabled',
+    envObject: 'envObject',
+    vcDirIdx: 'vcDirIdx',
+    navPathPoints: 'navPathPoints',
+};
+/**
+ * Read a typed `userData` value. Returns `undefined` when the key is unset or
+ * when `obj` is nullish (so call sites can pass an optionally-resolved object).
+ */
+export function getUserData(obj, key) {
+    return obj ? obj.userData[UserDataKeys[key]] : undefined;
+}
+/** Write a typed `userData` value. */
+export function setUserData(obj, key, value) {
+    obj.userData[UserDataKeys[key]] = value;
+}
+/** True when `key` is set (not `undefined`) on the object's `userData`. */
+export function hasUserData(obj, key) {
+    return obj ? obj.userData[UserDataKeys[key]] !== undefined : false;
+}
+/** Remove a `userData` key. */
+export function deleteUserData(obj, key) {
+    delete obj.userData[UserDataKeys[key]];
+}

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `@vgai/engine`'s package `"."` entry — what `import '@vgai/engine'`
+ * resolves to.
+ *
+ * This is a SMALL, CURATED barrel, not a re-export-everything convenience
+ * import. The engine's own doctrine (CLAUDE.md: "the engine code in
+ * `packages/engine/src/` is meant to be read and edited directly — it is
+ * not a black-box library") means subpath imports
+ * (`@vgai/engine/<path>`, matching this package's `"./*"` exports entry)
+ * remain the primary way to reach engine internals — reach for a subpath
+ * first. This barrel exists only so the package's bare-name entry point is
+ * HONEST (resolves to something real and useful) instead of dangling; it
+ * covers just the handful of symbols a game/consumer needs to author a
+ * first-party `setup()` and mount it, plus the scene/manifest file
+ * entry points. Keep it small when extending it — prefer a new subpath
+ * export over growing this file into a firehose.
+ *
+ * Groups (import order below is alphabetical-by-specifier, per the repo's
+ * biome `organizeImports` rule, not by group — see this list instead):
+ *   - game setup contract: `GameContext`/`GameCleanup`/`GameSetupFn`, `fromSetup`
+ *   - surface vocabulary: `AdapterSurface`
+ *   - manifest-driven mount: `mountManifestRoots` + its option/result types
+ *   - asset-format entry points: `parseMaterialFile` (.mat.json), `parseInstancesFile`
+ *   - game manifest (vgai.project.json) entry point: `loadGameManifest`
+ */
+export type { AdapterSurface } from './adapter/adapter-surface';
+export { fromSetup } from './adapter/setup-three-root-adapter';
+export { AssetParseError, parseInstancesFile, parseMaterialFile } from './asset-formats/parse';
+export type { AdapterRoot, GameManifest, ResolvedAdapter, ResolvedAdapterRoot, ResolvedGameManifest, RootAdapter, } from './manifest';
+export { CAPABILITY_CEILINGS, DEFAULT_SERVER_MODULE, loadGameManifest } from './manifest';
+export type { GameSession } from './runtime/create-runtime';
+export type { MountEntry, MountedManifestSession, MountManifestOptions, } from './runtime/mount-manifest';
+export { mountManifestRoots } from './runtime/mount-manifest';
+export type { GameCleanup, GameContext, GameSetupFn } from './runtime/types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,YAAY,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,SAAS,EAAE,MAAM,oCAAoC,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/F,YAAY,EACV,WAAW,EACX,YAAY,EACZ,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACpB,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC1F,YAAY,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,YAAY,EACV,UAAU,EACV,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,29 @@
+/**
+ * `@vgai/engine`'s package `"."` entry — what `import '@vgai/engine'`
+ * resolves to.
+ *
+ * This is a SMALL, CURATED barrel, not a re-export-everything convenience
+ * import. The engine's own doctrine (CLAUDE.md: "the engine code in
+ * `packages/engine/src/` is meant to be read and edited directly — it is
+ * not a black-box library") means subpath imports
+ * (`@vgai/engine/<path>`, matching this package's `"./*"` exports entry)
+ * remain the primary way to reach engine internals — reach for a subpath
+ * first. This barrel exists only so the package's bare-name entry point is
+ * HONEST (resolves to something real and useful) instead of dangling; it
+ * covers just the handful of symbols a game/consumer needs to author a
+ * first-party `setup()` and mount it, plus the scene/manifest file
+ * entry points. Keep it small when extending it — prefer a new subpath
+ * export over growing this file into a firehose.
+ *
+ * Groups (import order below is alphabetical-by-specifier, per the repo's
+ * biome `organizeImports` rule, not by group — see this list instead):
+ *   - game setup contract: `GameContext`/`GameCleanup`/`GameSetupFn`, `fromSetup`
+ *   - surface vocabulary: `AdapterSurface`
+ *   - manifest-driven mount: `mountManifestRoots` + its option/result types
+ *   - asset-format entry points: `parseMaterialFile` (.mat.json), `parseInstancesFile`
+ *   - game manifest (vgai.project.json) entry point: `loadGameManifest`
+ */
+export { fromSetup } from './adapter/setup-three-root-adapter';
+export { AssetParseError, parseInstancesFile, parseMaterialFile } from './asset-formats/parse';
+export { CAPABILITY_CEILINGS, DEFAULT_SERVER_MODULE, loadGameManifest } from './manifest';
+export { mountManifestRoots } from './runtime/mount-manifest';