@vgai/engine 0.5.2 → 0.5.4

package/src/world2d/pixi-surface.ts

@@ -1,78 +0,0 @@
-import { Application, Container } from 'pixi.js';
-
-export interface PixiSurface {
-  app: Application;
-  /** The world container (the 2D "camera": pan/zoom by transforming this). */
-  world: Container;
-  /** Render one frame (called from the engine's `render` phase). */
-  render: () => void;
-  resize: (width: number, height: number) => void;
-  dispose: () => void;
-}
-
-export interface PixiSurfaceOptions {
-  canvas: HTMLCanvasElement;
-  width: number;
-  height: number;
-  background?: string;
-  resolution?: number;
-  antialias?: boolean;
-  /** Stacked-composition transparency (COMPOSITION-DESIGN.md D5 §1, T6.1
-   *  slice 1): when true, the surface clears with alpha 0
-   *  (`backgroundAlpha:0`) instead of an opaque `background`, so a world
-   *  layered ABOVE another shows the layer below through it. */
-  transparent?: boolean;
-  /** Capture tier cost (D5 §4): flat on `Application.init`, never nested
-   *  under `context:` (the documented pixi trap) — required for any later
-   *  `drawImage()`-based composite capture of this surface. */
-  preserveDrawingBuffer?: boolean;
-}
-
-/**
- * Create the world2d render surface — a PixiJS v8 `Application` whose auto-ticker
- * is DISABLED (`autoStart:false`), so the engine's fixed-timestep loop drives
- * rendering by calling `render()` from the `render` phase (mirroring how the
- * Three.js adapter calls `composer.render(dt)`).
- *
- * `app.stage` holds a single `world` Container — the 2D camera lives here as a
- * transform on `world` (pan = world.position, zoom = world.scale), per the spec's
- * backend-2d-camera resolution. Screen-space HUD stays in the React/DOM overlay.
- */
-export async function createPixiSurface(opts: PixiSurfaceOptions): Promise<PixiSurface> {
-  const app = new Application();
-  await app.init({
-    canvas: opts.canvas,
-    width: opts.width,
-    height: opts.height,
-    background: opts.background ?? '#10101a',
-    backgroundAlpha: opts.transparent ? 0 : 1,
-    resolution: opts.resolution ?? (typeof window !== 'undefined' ? window.devicePixelRatio : 1),
-    autoDensity: true,
-    antialias: opts.antialias ?? true,
-    autoStart: false, // engine loop drives rendering — NOT Pixi's ticker
-    preference: 'webgl',
-    // Capture tier cost (D5 §4) — FLAT here, never nested under `context:`
-    // (the documented pixi trap: nesting silently breaks GL bootstrap).
-    ...(opts.preserveDrawingBuffer ? { preserveDrawingBuffer: true } : {}),
-  });
-  // Stop the shared/internal ticker defensively (autoStart:false already prevents start).
-  app.ticker.stop();
-
-  const world = new Container();
-  world.label = 'world2d-root';
-  app.stage.addChild(world);
-
-  return {
-    app,
-    world,
-    render: () => app.render(),
-    resize: (width: number, height: number) => {
-      app.renderer.resize(width, height);
-    },
-    dispose: () => {
-      // Tear down the Pixi app + GPU context. Children are destroyed by the loader's
-      // own dispose; here we release the renderer/canvas binding.
-      app.destroy({ removeView: false }, { children: true });
-    },
-  };
-}

package/src/world2d/scene2d-identity.ts

@@ -1,49 +0,0 @@
-import type { Entity2D, Scene2DFile } from './schema/entity2d';
-
-/** Resolve every entity to one collision-free identity without mutating source. */
-export function resolveScene2DEntityIds(scene: Scene2DFile): Map<Entity2D, string> {
-  const authored = new Set<string>();
-  const collect = (entities: Entity2D[]): void => {
-    for (const entity of entities) {
-      if (entity.id) {
-        if (authored.has(entity.id)) throw new Error(`Duplicate world2d entity id: "${entity.id}"`);
-        authored.add(entity.id);
-      }
-      if (entity.children) collect(entity.children);
-    }
-  };
-  collect(scene.entities);
-
-  const used = new Set(authored);
-  const result = new Map<Entity2D, string>();
-  const visit = (entities: Entity2D[], parentPath: readonly number[]): void => {
-    entities.forEach((entity, index) => {
-      const path = [...parentPath, index];
-      let id = entity.id;
-      if (!id) {
-        const base = `scn2d:${path.join('.')}`;
-        id = base;
-        let suffix = 1;
-        while (used.has(id)) id = `${base}~${suffix++}`;
-        used.add(id);
-      }
-      result.set(entity, id);
-      if (entity.children) visit(entity.children, path);
-    });
-  };
-  visit(scene.entities, []);
-  return result;
-}
-
-/** Materialize the same identities the preview/hierarchy already project. */
-export function materializeScene2DEntityIds(scene: Scene2DFile): boolean {
-  const ids = resolveScene2DEntityIds(scene);
-  let changed = false;
-  for (const [entity, id] of ids) {
-    if (!entity.id) {
-      entity.id = id;
-      changed = true;
-    }
-  }
-  return changed;
-}

package/src/world2d/scene2d-loader.ts

@@ -1,433 +0,0 @@
-import type RAPIER from '@dimforge/rapier2d-compat';
-import { CompositeTilemap } from '@pixi/tilemap';
-import type { Ticker } from 'pixi.js';
-import {
-  AnimatedSprite,
-  Assets,
-  BlurFilter,
-  ColorMatrixFilter,
-  Container,
-  Sprite,
-  Text,
-  Texture,
-} from 'pixi.js';
-import type { ComponentManager } from '../ecs/component-manager';
-import { SceneParseError } from '../scene/parse';
-import {
-  assertMovingPhysicsParent2D,
-  computePhysicsPose2D,
-  scaleCollider2D,
-} from './physics2d-transform';
-import { resolveScene2DEntityIds } from './scene2d-identity';
-import { type Entity2D, type Scene2DFile, Scene2DSchema } from './schema/entity2d';
-import type { SceneSprite, SceneText2D } from './schema/sprite';
-import type { SceneTilemap } from './schema/tilemap';
-import type { Component2DRegistry, World2DContext } from './types';
-
-const BLEND: Record<string, 'normal' | 'add' | 'multiply' | 'screen'> = {
-  normal: 'normal',
-  add: 'add',
-  multiply: 'multiply',
-  screen: 'screen',
-};
-
-// Pixi implements Sprite width/height by mutating native scale. Keep that
-// implementation scale separate from authored transform2d.scale so the visual
-// and its pixel-authored collider compose the same way.
-const spriteBaseScales = new WeakMap<Container, readonly [number, number]>();
-const tilemapTextures = new WeakMap<CompositeTilemap, readonly Texture[]>();
-
-/** Native atlas sub-textures retained for source-backed tile painting. */
-export function getSceneTilemapTextures2D(display: Container): readonly Texture[] | null {
-  return display instanceof CompositeTilemap ? (tilemapTextures.get(display) ?? null) : null;
-}
-
-/** Refresh the native Sprite sizing scale after an authoring operation writes
- * `display.width`/`height` from new source dimensions. The next authored
- * transform application multiplies this base by transform2d.scale exactly once. */
-export function captureSceneSpriteBaseScale2D(
-  display: Container,
-  axes: { x: boolean; y: boolean } = { x: true, y: true },
-  authoredScale: readonly [number, number] = [1, 1],
-): void {
-  const previous = spriteBaseScales.get(display) ?? [display.scale.x, display.scale.y];
-  const authoredSignX = authoredScale[0] < 0 ? -1 : 1;
-  const authoredSignY = authoredScale[1] < 0 ? -1 : 1;
-  spriteBaseScales.set(display, [
-    axes.x ? display.scale.x * authoredSignX : previous[0],
-    axes.y ? display.scale.y * authoredSignY : previous[1],
-  ]);
-}
-
-function hexToNum(hex: string | undefined, fallback: number): number {
-  if (!hex) return fallback;
-  return Number.parseInt(hex.replace('#', ''), 16);
-}
-
-function applyFilter(display: Sprite | AnimatedSprite, filter: string | undefined): void {
-  if (!filter || filter === 'none') return;
-  if (filter === 'blur') display.filters = [new BlurFilter({ strength: 6 })];
-  else if (filter === 'desaturate') {
-    const cm = new ColorMatrixFilter();
-    cm.desaturate();
-    display.filters = [cm];
-  }
-}
-
-type LoadedSpriteAsset = Texture & {
-  animations?: Record<string, Texture[]>;
-  textures?: Record<string, Texture>;
-};
-
-function createAnimatedSprite(data: SceneSprite, loaded: LoadedSpriteAsset): AnimatedSprite {
-  const frames = loaded.animations?.[data.animation!];
-  if (!frames?.length) {
-    throw new Error(`Spritesheet "${data.texture}" does not contain animation "${data.animation}"`);
-  }
-  const display = new AnimatedSprite({ autoUpdate: false, textures: frames });
-  display.animationSpeed = (data.fps ?? 8) / 60;
-  display.loop = data.loop ?? true;
-  display.play();
-  return display;
-}
-
-function applySpriteAppearance(display: Sprite | AnimatedSprite, data: SceneSprite): void {
-  const [ax, ay] = data.anchor ?? [0.5, 0.5];
-  display.anchor.set(ax, ay);
-  if (data.width !== undefined) display.width = data.width;
-  if (data.height !== undefined) display.height = data.height;
-  captureSceneSpriteBaseScale2D(display);
-  display.tint = hexToNum(data.tint, 0xffffff);
-  if (data.alpha !== undefined) display.alpha = data.alpha;
-  if (data.blendMode) display.blendMode = BLEND[data.blendMode] ?? 'normal';
-  if (data.interactive) {
-    display.eventMode = 'static';
-    display.cursor = 'pointer';
-  }
-  applyFilter(display, data.filter);
-}
-
-function resolveStaticSpriteTexture(
-  data: SceneSprite,
-  loaded: LoadedSpriteAsset | undefined,
-): Texture {
-  if (!loaded) return Texture.WHITE;
-  if (!data.frame) return loaded as Texture;
-  const frame = loaded.textures?.[data.frame];
-  if (!frame) {
-    throw new Error(`Spritesheet "${data.texture}" does not contain frame "${data.frame}"`);
-  }
-  return frame;
-}
-
-/** Instantiate a PIXI.Sprite / AnimatedSprite from authored `sprite` data. */
-async function createSprite(data: SceneSprite): Promise<Sprite | AnimatedSprite> {
-  const loaded = data.texture
-    ? ((await Assets.load(data.texture)) as LoadedSpriteAsset)
-    : undefined;
-  const display = data.animation
-    ? createAnimatedSprite(data, loaded!)
-    : new Sprite(resolveStaticSpriteTexture(data, loaded));
-  applySpriteAppearance(display, data);
-  return display;
-}
-
-/** Instantiate a @pixi/tilemap CompositeTilemap from a native Pixi atlas. */
-async function createTilemap(data: SceneTilemap): Promise<CompositeTilemap> {
-  const loaded = (await Assets.load(data.texture)) as LoadedSpriteAsset;
-  const textures = data.frames.map((frame) => {
-    const texture = loaded.textures?.[frame];
-    if (!texture) {
-      throw new Error(`Spritesheet "${data.texture}" does not contain tile frame "${frame}"`);
-    }
-    return texture;
-  });
-  const tilemap = new CompositeTilemap();
-  tilemapTextures.set(tilemap, textures);
-  for (let y = 0; y < data.tiles.length; y++) {
-    const row = data.tiles[y]!;
-    for (let x = 0; x < row.length; x++) {
-      const index = row[x]!;
-      if (index === -1) continue;
-      tilemap.tile(textures[index]!, x * data.tileSize, y * data.tileSize);
-    }
-  }
-  return tilemap;
-}
-
-/** Instantiate a PIXI.Text from authored `text` data (world-space label). */
-function createText(data: SceneText2D): Text {
-  const text = new Text({
-    text: data.text,
-    style: { fontSize: data.fontSize ?? 24, fill: data.fill ?? '#ffffff' },
-  });
-  const [ax, ay] = data.anchor ?? [0.5, 0.5];
-  text.anchor.set(ax, ay);
-  return text;
-}
-
-/** Map the bodyType enum to a Rapier 2D RigidBodyDesc. */
-function bodyDesc(rapier2d: typeof RAPIER, type: string): RAPIER.RigidBodyDesc {
-  switch (type) {
-    case 'fixed':
-      return rapier2d.RigidBodyDesc.fixed();
-    case 'kinematicVelocity':
-      return rapier2d.RigidBodyDesc.kinematicVelocityBased();
-    case 'kinematicPosition':
-      return rapier2d.RigidBodyDesc.kinematicPositionBased();
-    default:
-      return rapier2d.RigidBodyDesc.dynamic();
-  }
-}
-
-interface MovingPhysicsAncestor2D {
-  bodyType: string;
-  name: string;
-}
-
-function entityLabel(entity: Entity2D): string {
-  return entity.id ? `${entity.name} (id: "${entity.id}")` : entity.name;
-}
-
-function isMovingBodyType(bodyType: string): boolean {
-  return bodyType !== 'fixed';
-}
-
-/** Create the Rapier 2D body + collider for an entity and register it. */
-function createPhysics2D(
-  ctx: World2DContext,
-  entity: Entity2D,
-  display: Container,
-  movingAncestor: MovingPhysicsAncestor2D | undefined,
-): void {
-  const p = entity.physics2d;
-  if (!p) return;
-  const { rapier2d, rapier2dWorld, physics2d } = ctx;
-  const label = entityLabel(entity);
-  if (movingAncestor) {
-    throw new Error(
-      `world2d physics entity "${label}" has a "${p.bodyType}" body nested under ` +
-        `"${movingAncestor.name}", which has a moving "${movingAncestor.bodyType}" body. ` +
-        'Rapier has no parent/child body relationship, so a moving ancestor cannot carry ' +
-        'another physics body. Move the nested body out of that hierarchy or make the ' +
-        'ancestor fixed.',
-    );
-  }
-  if (isMovingBodyType(p.bodyType)) assertMovingPhysicsParent2D(display, ctx.stage, label);
-  const pose = computePhysicsPose2D(entity, display, ctx.stage, label);
-  const colliderShape = scaleCollider2D(p.collider, pose.scale, label);
-
-  const rbDesc = bodyDesc(rapier2d, p.bodyType)
-    .setTranslation(pose.position[0], pose.position[1])
-    .setRotation(pose.rotation);
-  if (p.linearDamping !== undefined) rbDesc.setLinearDamping(p.linearDamping);
-  if (p.gravityScale !== undefined) rbDesc.setGravityScale(p.gravityScale);
-  if (p.lockRotations) rbDesc.lockRotations();
-  const body = rapier2dWorld.createRigidBody(rbDesc);
-
-  let colDesc: RAPIER.ColliderDesc;
-  if (colliderShape.shape === 'cuboid') {
-    colDesc = rapier2d.ColliderDesc.cuboid(
-      colliderShape.halfExtents[0],
-      colliderShape.halfExtents[1],
-    );
-  } else if (colliderShape.shape === 'ball') {
-    colDesc = rapier2d.ColliderDesc.ball(colliderShape.radius);
-  } else {
-    colDesc = rapier2d.ColliderDesc.capsule(colliderShape.halfHeight, colliderShape.radius);
-  }
-
-  if (p.density !== undefined) colDesc.setDensity(p.density);
-  if (p.friction !== undefined) colDesc.setFriction(p.friction);
-  if (p.restitution !== undefined) colDesc.setRestitution(p.restitution);
-  if (p.sensor) {
-    colDesc.setSensor(true);
-    colDesc.setActiveCollisionTypes(rapier2d.ActiveCollisionTypes.ALL);
-    colDesc.setActiveEvents(rapier2d.ActiveEvents.COLLISION_EVENTS);
-  } else {
-    colDesc.setActiveEvents(rapier2d.ActiveEvents.COLLISION_EVENTS);
-  }
-  const collider = rapier2dWorld.createCollider(colDesc, body);
-  physics2d.add(display, body, collider);
-}
-
-/** Hydrate the `components` field — schema.parse + Object.assign + attach (2D analog of applyComponents).
- *  `manager` is the unified `ComponentManager` (`ecs/component-manager.ts`), constructed
- *  for kind `'pixijs'` — the world2d silo manager this replaced (T7.3) is deleted. */
-function applyComponents2D(
-  registry: Component2DRegistry,
-  display: Container,
-  components: Record<string, Record<string, unknown>> | undefined,
-  manager: ComponentManager,
-): void {
-  if (!components) return;
-  for (const [name, data] of Object.entries(components)) {
-    const Cls = registry[name];
-    if (!Cls) throw new Error(`Unknown world2d component: "${name}"`);
-    const parsed = Cls.schema ? Cls.schema.parse(data ?? {}) : (data ?? {});
-    const instance = new Cls();
-    Object.assign(instance, parsed);
-    // T5.4: record the registry name + raw authored data — same reasoning as
-    // the 3D `applyComponents` (`scene/component-registry.ts`).
-    manager.attach(display, instance, { key: name, props: data ?? {} });
-  }
-}
-
-/** Apply authored entity state to its live Pixi object. Exported so the source
- * authoring adapter uses exactly the loader's Sprite-size/scale composition. */
-export function applySceneEntityTransform2D(display: Container, entity: Entity2D): void {
-  const t = entity.transform2d;
-  if (t?.position) display.position.set(t.position[0], t.position[1]);
-  if (t?.rotation !== undefined) display.rotation = t.rotation;
-  const authoredScale = t?.scale ?? [1, 1];
-  let baseScale = spriteBaseScales.get(display);
-  if (!baseScale) {
-    baseScale = entity.sprite ? [display.scale.x, display.scale.y] : [1, 1];
-    if (entity.sprite) spriteBaseScales.set(display, baseScale);
-  }
-  display.scale.set(baseScale[0] * authoredScale[0], baseScale[1] * authoredScale[1]);
-  const pivot = t?.pivot ?? entity.pivot;
-  if (pivot) display.pivot.set(pivot[0], pivot[1]);
-  if (entity.visible === false) display.visible = false;
-}
-
-/** A loaded world2d scene instance: the root display objects + an update/dispose. */
-export interface Scene2DInstance {
-  roots: Container[];
-  /** id → display object map for editor/lookup (the 2D analog of the loader's entity map). */
-  byId: Map<string, Container>;
-  /** Advance authored AnimatedSprites through Pixi's native update method from the engine loop. */
-  updateAnimations(dt: number): void;
-  dispose(): void;
-}
-
-type SpawnHook = (
-  entity: Entity2D,
-  display: Container,
-  movingAncestor: MovingPhysicsAncestor2D | undefined,
-) => void;
-
-async function spawnScene2DVisuals(
-  scene: Scene2DFile,
-  stage: Container,
-  onSpawn?: SpawnHook,
-): Promise<Scene2DInstance> {
-  const byId = new Map<string, Container>();
-  const animatedSprites: AnimatedSprite[] = [];
-  const roots: Container[] = [];
-  const ids = resolveScene2DEntityIds(scene);
-
-  async function spawn(
-    entity: Entity2D,
-    parent: Container,
-    path: readonly number[],
-    movingAncestor?: MovingPhysicsAncestor2D,
-  ): Promise<Container> {
-    let display: Container;
-    if (entity.sprite) display = await createSprite(entity.sprite);
-    else if (entity.text) display = createText(entity.text);
-    else if (entity.tilemap) display = await createTilemap(entity.tilemap);
-    else display = new Container();
-    if (display instanceof AnimatedSprite) animatedSprites.push(display);
-
-    display.label = entity.name;
-    // Authored ids are canonical. The path fallback is deterministic across
-    // edit-mode reloads, unlike the old process-global counter, while keeping
-    // id optional for existing source documents.
-    const id = ids.get(entity)!;
-    (display as Container & { __entityId?: string }).__entityId = id;
-    byId.set(id, display);
-
-    applySceneEntityTransform2D(display, entity);
-    parent.addChild(display);
-    onSpawn?.(entity, display, movingAncestor);
-
-    if (entity.children) {
-      const childMovingAncestor =
-        entity.physics2d && isMovingBodyType(entity.physics2d.bodyType)
-          ? { bodyType: entity.physics2d.bodyType, name: entityLabel(entity) }
-          : movingAncestor;
-      for (let index = 0; index < entity.children.length; index++) {
-        await spawn(entity.children[index]!, display, [...path, index], childMovingAncestor);
-      }
-    }
-    return display;
-  }
-
-  for (let index = 0; index < scene.entities.length; index++) {
-    roots.push(await spawn(scene.entities[index]!, stage, [index]));
-  }
-
-  return {
-    roots,
-    byId,
-    updateAnimations(dt) {
-      const ticker = { deltaTime: dt * 60 } as Ticker;
-      for (const display of animatedSprites) display.update(ticker);
-    },
-    dispose() {
-      for (const root of roots) {
-        root.removeFromParent();
-        root.destroy({ children: true });
-      }
-      roots.length = 0;
-      byId.clear();
-      animatedSprites.length = 0;
-    },
-  };
-}
-
-/**
- * Instantiate only authored Pixi display objects. This is the editor's
- * stopped-mode preview seam: no component construction/init, Rapier bodies,
- * input manager, systems, or gameplay loop are created.
- */
-export async function loadScene2DVisualsFromData(
-  data: Scene2DFile,
-  stage: Container,
-  sourceName?: string,
-): Promise<Scene2DInstance> {
-  const result = Scene2DSchema.safeParse(data);
-  if (!result.success) throw new SceneParseError(result.error.issues, sourceName);
-  return spawnScene2DVisuals(result.data, stage);
-}
-
-/**
- * Load a world2d scene from authored data — the 2D analog of `loadSceneFromData`.
- * Three passes: (1) spawn all entities (recursing into children), building an
- * id→display map and creating Rapier 2D bodies; (2) [no joints in 2D yet];
- * (3) `componentManager.initAll()` once everything exists.
- *
- * Re-validates `data` even though the fetch path (`fetchScene2DFile` in
- * `packages/editor/src/adapter-resolver.ts`) already validates before calling
- * in — not every caller goes through that path (test-constructed
- * `PixiSceneConfig.sceneData` literals reach here unvalidated), so a malformed
- * payload still throws a `SceneParseError` naming the file, not a raw
- * `ZodError` (T4.6 convention, closing §7.1-14). `sourceName` is optional
- * because not every caller knows the originating file path; callers that do
- * (or gain the ability to) should thread it through for a better message.
- */
-export async function loadScene2DFromData(
-  data: Scene2DFile,
-  ctx: World2DContext,
-  registry: Component2DRegistry,
-  sourceName?: string,
-): Promise<Scene2DInstance> {
-  const result = Scene2DSchema.safeParse(data);
-  if (!result.success) throw new SceneParseError(result.error.issues, sourceName);
-  const scene = result.data;
-  const instance = await spawnScene2DVisuals(
-    scene,
-    ctx.stage,
-    (entity, display, movingAncestor) => {
-      // Rapier bodies live in world space. The loader composes the Pixi parent
-      // chain at spawn; the post-physics writer converts the simulated pose back
-      // to parent-local display coordinates.
-      createPhysics2D(ctx, entity, display, movingAncestor);
-      applyComponents2D(registry, display, entity.components, ctx.components);
-    },
-  );
-
-  await ctx.components.initAll();
-  return instance;
-}