@vgai/engine 0.5.41 → 0.5.44

package/src/canvas-react/pixi-react-root-factory.tsx

@@ -150,19 +150,19 @@ function canvasWorldAdapter(id: string, component: ComponentType): RootAdapter<'
       const unmounted = new Promise<void>((resolve) => {
         resolveUnmounted = resolve;
       });
+      let resolveEffectsUnmounted!: () => void;
+      const effectsUnmounted = new Promise<void>((resolve) => {
+        resolveEffectsUnmounted = resolve;
+      });
       /**
-       * Signals the tree's FIRST COMMIT and its LAST. A layout effect,
-       * deliberately, and rendered as the LAST child, deliberately:
+       * Signals the tree's FIRST COMMIT and both unmount cleanup phases. Rendered as the LAST
+       * child deliberately:
        *
        *  - mount: layout effects run synchronously inside the commit, before
        *    any passive effect and before any tick can be scheduled;
-       *  - unmount: React commits deletion effects in tree order, each node
-       *    before its own children, so the LAST sibling's cleanup is the last
-       *    to run. That is what makes this a reliable "every component has
-       *    finished tearing down" signal — and it is load-bearing, because
-       *    `useTick`'s own cleanup calls `ticker.remove()`. Destroying the
-       *    Application before that cleanup lands throws inside React's commit
-       *    on every teardown of any world with a tick hook.
+       *  - unmount: the layout cleanup fences `useTick` and the passive cleanup fences ordinary
+       *    project effects. Native destruction waits for BOTH; resolving only from layout left
+       *    passive listener/resource cleanup racing an Application whose renderer was null.
        */
       function Lifecycle(): null {
         useLayoutEffect(() => {
@@ -172,7 +172,10 @@ function canvasWorldAdapter(id: string, component: ComponentType): RootAdapter<'
         // This component is the last sibling. Reaching its passive effect
         // means the initial tree's provider/command effects have registered,
         // so mount() can truthfully back Play's ack.
-        useEffect(resolveEffectsReady, []);
+        useEffect(() => {
+          resolveEffectsReady();
+          return resolveEffectsUnmounted;
+        }, []);
         return null;
       }
 
@@ -282,7 +285,14 @@ function canvasWorldAdapter(id: string, component: ComponentType): RootAdapter<'
       // Adapter surface: the host's shared debug registry. The game's own
       // capabilities arrive as the entry module's declared `systems`.
       const systemAdapters: SystemAdapters = registry ? { debug: registry.adapter } : {};
-      const disposeComplete = unmounted.then(() => {
+      const disposeComplete = Promise.all([unmounted, effectsUnmounted]).then(() => {
+        // React can tear the root down itself after a fatal layout/effect error. In that path the
+        // host has not called dispose() yet, but Application.destroy() still clears Pixi's ticker
+        // and renderer. Wait for both layout and passive cleanup first: project effects may own
+        // window/document listeners and can still read the Pixi Application while React drains
+        // passive deletion effects. Fence the mounted root before clearing the native slots so
+        // subsequent host frames and the eventual host teardown cannot re-enter them.
+        disposed = true;
         mountedApp.destroy(false, { children: true });
       });
 

package/src/data/vite-plugin-data.ts

@@ -27,7 +27,7 @@
  *    target file" hole, closed for declared refs — see
  *    `collectDeclaredRefFields`/`findMissingRefTargets` in `data-check-core.ts`).
  * 3. **Tools never ship** (`generateBundle`): no emitted chunk may contain a
- *    module from `src/tools/` or a `*.tool.*` file (§4: tester serves and
+ *    module from `src/contributions/`, `src/tools/` or a `*.tool.*` file (§4: tester serves and
  *    standalone builds strip tools entirely; W4 made this true by
  *    construction — nothing imports tools — and this check PINS it against
  *    the day some game module imports a tool "just for a helper").
@@ -268,7 +268,9 @@ export async function collectDataCheckProblems(options: VgaiDataCheckOptions): P
 /** True iff a bundled module id is tool code that must never ship (§4). Pure, unit-tested. */
 export function isToolModuleId(id: string): boolean {
   const normalized = id.split('\\').join('/');
-  return /\/src\/tools\//.test(normalized) || /\.tool\.[tj]sx?(\?|$)/.test(normalized);
+  return (
+    /\/src\/(?:tools|contributions)\//.test(normalized) || /\.tool\.[tj]sx?(\?|$)/.test(normalized)
+  );
 }
 
 /**

package/src/ecs/user-data.ts

@@ -82,6 +82,9 @@
  *                           association; unlike the label, never user-facing copy.
  * - `authoringDocument`   — generic reference to the project-tool document
  *                           that owns this scene instance's authored asset.
+ * - `authoringHierarchyId`, `authoringHierarchyParentId`,
+ *   `authoringHierarchyOrder` — source-owned semantic identity, parent identity,
+ *                           and sibling ordinal shared across native surfaces.
  * - `editorHelper`        — `true` for editor-only helper objects (gizmos, wireframes).
  *
  * Hierarchy-presentation convention (written by GAME code, read by the editor —
@@ -195,6 +198,8 @@ export interface UserDataSchema {
   };
   /** Project-owned identity used to join authored hierarchy rows across adapter roots. */
   authoringHierarchyId: string;
+  /** Project-owned parent identity when the authored parent can live on another surface. */
+  authoringHierarchyParentId: string;
   /** Source-owned sibling ordinal used when hierarchy rows cross native roots. */
   authoringHierarchyOrder: number;
   editorHelper: boolean;
@@ -254,6 +259,7 @@ export const UserDataKeys = {
   authoringComponent: 'authoringComponent',
   authoringDocument: 'authoringDocument',
   authoringHierarchyId: 'authoringHierarchyId',
+  authoringHierarchyParentId: 'authoringHierarchyParentId',
   authoringHierarchyOrder: 'authoringHierarchyOrder',
   editorHelper: 'editorHelper',
   editorHelperType: 'editorHelperType',

package/src/index.ts

@@ -32,7 +32,7 @@ export type {
   ResolvedGameManifest,
   RootAdapter,
 } from './manifest';
-export { DEFAULT_SERVER_MODULE, loadGameManifest } from './manifest';
+export { loadGameManifest } from './manifest';
 export type { GameSession } from './runtime/create-runtime';
 export type {
   MountEntry,

package/src/input/host-pointer.ts

@@ -72,6 +72,8 @@ export interface HostPointerTouch {
    * differently is holding a button nothing will ever release.
    */
   readonly phase: 'start' | 'move' | 'end';
+  /** True only when the browser ended this contact with `pointercancel`. */
+  readonly canceled: boolean;
   /**
    * DENSE finger index — the lowest slot free when this finger went down, and
    * free again the moment it lifts. NOT the browser's `pointerId`, which never
@@ -80,6 +82,22 @@ export interface HostPointerTouch {
   readonly index: number;
   /** Position in the design space (see {@link HostPointerOptions.designSize}). */
   readonly position: Vector2;
+  /** Position before design-resolution scaling, in surface CSS pixels. */
+  readonly screenPosition: Vector2;
+  /** Delta since this contact's preceding sample, in design pixels. */
+  readonly relative: Vector2;
+  /** Delta since this contact's preceding sample, in surface CSS pixels. */
+  readonly screenRelative: Vector2;
+  /** Design-pixel velocity derived from the browser event timestamps. */
+  readonly velocity: Vector2;
+  /** Surface CSS-pixel velocity derived from the browser event timestamps. */
+  readonly screenVelocity: Vector2;
+  /** Native PointerEvent pressure in the normalized [0, 1] range. */
+  readonly pressure: number;
+  /** Native PointerEvent tilt, in degrees. Touch contacts normally report zero. */
+  readonly tilt: Vector2;
+  /** Touch pointers are never an inverted pen; retained for Godot's event value contract. */
+  readonly penInverted: false;
 }
 
 /** What {@link createHostPointer} needs. */
@@ -141,6 +159,14 @@ export function createHostPointer(options: HostPointerOptions): HostPointer {
   const touches: HostPointerTouch[] = [];
   /** Browser `pointerId` -> dense finger index, for fingers currently down. */
   const fingerOfPointer = new Map<number, number>();
+  const sampleOfPointer = new Map<
+    number,
+    {
+      readonly position: Vector2;
+      readonly screenPosition: Vector2;
+      readonly timestamp: number;
+    }
+  >();
   const freeFinger = (): number => {
     const taken = new Set(fingerOfPointer.values());
     let index = 0;
@@ -152,11 +178,52 @@ export function createHostPointer(options: HostPointerOptions): HostPointer {
     if (touches.length > TOUCH_QUEUE_MAX) touches.shift();
   };
 
-  const queueTouch = (event: PointerEvent, point: Vector2): void => {
+  const queueTouch = (event: PointerEvent, point: Vector2, screenPoint: Vector2): void => {
+    const previous = sampleOfPointer.get(event.pointerId);
+    const relative =
+      previous === undefined
+        ? { x: 0, y: 0 }
+        : { x: point.x - previous.position.x, y: point.y - previous.position.y };
+    const screenRelative =
+      previous === undefined
+        ? { x: 0, y: 0 }
+        : {
+            x: screenPoint.x - previous.screenPosition.x,
+            y: screenPoint.y - previous.screenPosition.y,
+          };
+    const elapsedSeconds =
+      previous === undefined ? 0 : Math.max(0, event.timeStamp - previous.timestamp) / 1000;
+    const velocity =
+      elapsedSeconds > 0
+        ? { x: relative.x / elapsedSeconds, y: relative.y / elapsedSeconds }
+        : { x: 0, y: 0 };
+    const screenVelocity =
+      elapsedSeconds > 0
+        ? { x: screenRelative.x / elapsedSeconds, y: screenRelative.y / elapsedSeconds }
+        : { x: 0, y: 0 };
+    const common = {
+      position: point,
+      screenPosition: screenPoint,
+      relative,
+      screenRelative,
+      velocity,
+      screenVelocity,
+      pressure: Number.isFinite(event.pressure) ? Math.max(0, Math.min(1, event.pressure)) : 0,
+      tilt: {
+        x: Number.isFinite(event.tiltX) ? event.tiltX : 0,
+        y: Number.isFinite(event.tiltY) ? event.tiltY : 0,
+      },
+      penInverted: false as const,
+    };
     if (event.type === 'pointerdown') {
       const index = freeFinger();
       fingerOfPointer.set(event.pointerId, index);
-      queue({ phase: 'start', index, position: point });
+      sampleOfPointer.set(event.pointerId, {
+        position: point,
+        screenPosition: screenPoint,
+        timestamp: event.timeStamp,
+      });
+      queue({ phase: 'start', canceled: false, index, ...common });
       return;
     }
     // A move or a release from a pointer that never went down on this surface
@@ -165,10 +232,21 @@ export function createHostPointer(options: HostPointerOptions): HostPointer {
     if (index === undefined) return;
     if (event.type === 'pointerup' || event.type === 'pointercancel') {
       fingerOfPointer.delete(event.pointerId);
-      queue({ phase: 'end', index, position: point });
+      sampleOfPointer.delete(event.pointerId);
+      queue({
+        phase: 'end',
+        canceled: event.type === 'pointercancel',
+        index,
+        ...common,
+      });
       return;
     }
-    queue({ phase: 'move', index, position: point });
+    sampleOfPointer.set(event.pointerId, {
+      position: point,
+      screenPosition: screenPoint,
+      timestamp: event.timeStamp,
+    });
+    queue({ phase: 'move', canceled: false, index, ...common });
   };
 
   /** A client-space event as a point in the design space, via the surface rect
@@ -188,6 +266,7 @@ export function createHostPointer(options: HostPointerOptions): HostPointer {
     if (surface === null) return;
     const rect = surface.getBoundingClientRect();
     if (rect.width <= 0 || rect.height <= 0) return;
+    const screenPoint = { x: event.clientX - rect.left, y: event.clientY - rect.top };
     const point = toDesignSpace(event, rect);
 
     if (event.type === 'pointermove') {
@@ -199,7 +278,7 @@ export function createHostPointer(options: HostPointerOptions): HostPointer {
     }
     // A mouse or a pen is not a finger. A control that answered them here would
     // steal the clicks of a player who cannot see it.
-    if (event.pointerType === 'touch') queueTouch(event, point);
+    if (event.pointerType === 'touch') queueTouch(event, point, screenPoint);
   };
 
   const KINDS = ['pointerdown', 'pointermove', 'pointerup', 'pointercancel'] as const;