@vgai/engine 0.2.0 → 0.3.0

package/dist/scene/particles-factory.js

@@ -0,0 +1,282 @@
+// biome-ignore-all lint/suspicious/noExplicitAny: quarks' API uses untyped FunctionJSON internally; our Zod types are structurally compatible but TS can't unify them
+/**
+ * Converts SceneParticles JSON → three.quarks ParticleSystem.
+ *
+ * Shared between the editor entity-factory and the runtime scene-loader.
+ * The schema mirrors quarks' native JSON format, so most fields pass through
+ * directly to quarks' fromJSON or constructor methods.
+ */
+import { ApplyForce, ChangeEmitDirection, CircleEmitter, ColorGeneratorFromJSON, ColorOverLife, ConeEmitter, DonutEmitter, ForceOverLife, FrameOverLife, GravityForce, GridEmitter, HemisphereEmitter, LimitSpeedOverLife, Noise, OrbitOverLife, PointEmitter, Vector3 as QVector3, RectangleEmitter, RotationOverLife, SizeOverLife, SpeedOverLife, SphereEmitter, TurbulenceField, ValueGeneratorFromJSON, WidthOverLength, } from 'quarks.core';
+import * as THREE from 'three';
+import { ParticleSystem, RenderMode } from 'three.quarks';
+// --- Render mode mapping ---
+const RENDER_MODE_MAP = {
+    billboard: RenderMode.BillBoard,
+    stretchedBillboard: RenderMode.StretchedBillBoard,
+    mesh: RenderMode.Mesh,
+    trail: RenderMode.Trail,
+    horizontalBillboard: RenderMode.HorizontalBillBoard,
+    verticalBillboard: RenderMode.VerticalBillBoard,
+};
+// --- Texture loader (shared cache) ---
+import { textureLoader } from '../loader';
+const particleTexCache = new Map();
+function loadParticleTexture(url) {
+    const cached = particleTexCache.get(url);
+    if (cached)
+        return cached;
+    const tex = textureLoader.load(url);
+    particleTexCache.set(url, tex);
+    return tex;
+}
+// --- Helpers ---
+/** Strip keys with undefined values so exactOptionalPropertyTypes is satisfied. */
+function defined(obj) {
+    const result = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (v !== undefined)
+            result[k] = v;
+    }
+    return result;
+}
+// --- Emitter shape ---
+function createEmitterShape(json) {
+    switch (json.type) {
+        case 'point':
+            return new PointEmitter();
+        case 'sphere':
+            return new SphereEmitter(defined({ radius: json.radius, arc: json.arc, thickness: json.thickness }));
+        case 'hemisphere':
+            return new HemisphereEmitter(defined({ radius: json.radius, arc: json.arc, thickness: json.thickness }));
+        case 'cone':
+            return new ConeEmitter(defined({
+                radius: json.radius,
+                arc: json.arc,
+                thickness: json.thickness,
+                angle: json.angle,
+            }));
+        case 'circle':
+            return new CircleEmitter(defined({ radius: json.radius, arc: json.arc, thickness: json.thickness }));
+        case 'donut':
+            return new DonutEmitter(defined({
+                radius: json.radius,
+                arc: json.arc,
+                thickness: json.thickness,
+                donutRadius: json.donutRadius,
+            }));
+        case 'rectangle':
+            return new RectangleEmitter(defined({ width: json.width, height: json.height, thickness: json.thickness }));
+        case 'grid':
+            return new GridEmitter(defined({ width: json.width, height: json.height, column: json.column, row: json.row }));
+    }
+}
+// --- Value / Color generators ---
+// Our Zod-inferred types are structurally identical to quarks' FunctionJSON
+// but TypeScript can't unify them, so we cast through the untyped bridge.
+function valueGen(json) {
+    return ValueGeneratorFromJSON(json);
+}
+function colorGen(json) {
+    return ColorGeneratorFromJSON(json);
+}
+// --- Behaviors ---
+function createBehavior(json) {
+    switch (json.type) {
+        case 'ApplyForce':
+            return new ApplyForce(new QVector3(json.direction[0], json.direction[1], json.direction[2]), valueGen(json.magnitude));
+        case 'ColorOverLife':
+            return new ColorOverLife(colorGen(json.color));
+        case 'SizeOverLife':
+            return new SizeOverLife(valueGen(json.size));
+        case 'SpeedOverLife':
+            return new SpeedOverLife(valueGen(json.speed));
+        case 'RotationOverLife':
+            return new RotationOverLife(valueGen(json.angularVelocity));
+        case 'ForceOverLife':
+            return new ForceOverLife(valueGen(json.x), valueGen(json.y), valueGen(json.z));
+        case 'OrbitOverLife':
+            return new OrbitOverLife(valueGen(json.orbitSpeed), json.axis ? new QVector3(json.axis[0], json.axis[1], json.axis[2]) : undefined);
+        case 'Noise':
+            return new Noise(valueGen(json.frequency), valueGen(json.power), json.positionAmount ? valueGen(json.positionAmount) : undefined, json.rotationAmount ? valueGen(json.rotationAmount) : undefined);
+        case 'TurbulenceField':
+            return new TurbulenceField(new QVector3(json.scale[0], json.scale[1], json.scale[2]), json.octaves, new QVector3(json.velocityMultiplier[0], json.velocityMultiplier[1], json.velocityMultiplier[2]), new QVector3(json.timeScale[0], json.timeScale[1], json.timeScale[2]));
+        case 'FrameOverLife':
+            return new FrameOverLife(valueGen(json.frame));
+        case 'LimitSpeedOverLife':
+            return new LimitSpeedOverLife(valueGen(json.speed), json.dampen);
+        case 'ChangeEmitDirection':
+            return new ChangeEmitDirection(valueGen(json.angle));
+        case 'GravityForce':
+            return new GravityForce(new QVector3(json.center[0], json.center[1], json.center[2]), json.magnitude);
+        case 'WidthOverLength':
+            return new WidthOverLength(valueGen(json.width));
+    }
+}
+// --- Material ---
+function createParticleMaterial(mat) {
+    const textures = {};
+    if (mat.map)
+        textures['map'] = loadParticleTexture(mat.map);
+    const blending = mat.blending === 'normal' ? THREE.NormalBlending : THREE.AdditiveBlending;
+    const transparent = mat.transparent !== false;
+    const depthWrite = mat.depthWrite ?? false;
+    const side = mat.side === 'back'
+        ? THREE.BackSide
+        : mat.side === 'double'
+            ? THREE.DoubleSide
+            : THREE.FrontSide;
+    if (mat.type === 'standard') {
+        return new THREE.MeshStandardMaterial({
+            color: mat.color ?? '#ffffff',
+            ...textures,
+            blending,
+            transparent,
+            depthWrite,
+            side,
+        });
+    }
+    return new THREE.MeshBasicMaterial({
+        color: mat.color ?? '#ffffff',
+        ...textures,
+        blending,
+        transparent,
+        depthWrite,
+        side,
+    });
+}
+// --- Default sprite texture (soft radial gradient) ---
+let _defaultSpriteTex = null;
+function getDefaultSpriteTex() {
+    if (_defaultSpriteTex)
+        return _defaultSpriteTex;
+    const canvas = document.createElement('canvas');
+    canvas.width = 16;
+    canvas.height = 16;
+    const c2d = canvas.getContext('2d');
+    const grad = c2d.createRadialGradient(8, 8, 0, 8, 8, 8);
+    grad.addColorStop(0, 'rgba(255,255,255,1)');
+    grad.addColorStop(1, 'rgba(255,255,255,0)');
+    c2d.fillStyle = grad;
+    c2d.fillRect(0, 0, 16, 16);
+    _defaultSpriteTex = new THREE.CanvasTexture(canvas);
+    return _defaultSpriteTex;
+}
+/**
+ * Create a three.quarks ParticleSystem from SceneParticles JSON data.
+ */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: straightforward field-by-field mapping
+export function createParticleSystemFromData(data) {
+    const material = createParticleMaterial(data.material);
+    // Apply default sprite if no texture specified
+    if (!data.material.map && 'map' in material) {
+        material.map = getDefaultSpriteTex();
+    }
+    // Build params, strip undefined keys for exactOptionalPropertyTypes compat
+    const params = { material };
+    if (data.autoDestroy != null)
+        params['autoDestroy'] = data.autoDestroy;
+    if (data.looping != null)
+        params['looping'] = data.looping;
+    if (data.prewarm != null)
+        params['prewarm'] = data.prewarm;
+    if (data.duration != null)
+        params['duration'] = data.duration;
+    if (data.shape)
+        params['shape'] = createEmitterShape(data.shape);
+    if (data.startLife)
+        params['startLife'] = valueGen(data.startLife);
+    if (data.startSpeed)
+        params['startSpeed'] = valueGen(data.startSpeed);
+    if (data.startSize)
+        params['startSize'] = valueGen(data.startSize);
+    if (data.startRotation)
+        params['startRotation'] = valueGen(data.startRotation);
+    if (data.startColor)
+        params['startColor'] = colorGen(data.startColor);
+    if (data.startTileIndex)
+        params['startTileIndex'] = valueGen(data.startTileIndex);
+    // Trail mode requires startLength inside rendererEmitterSettings, not as a top-level param
+    if (data.renderMode === 'trail' && data.startLength) {
+        params['rendererEmitterSettings'] = { startLength: valueGen(data.startLength) };
+    }
+    if (data.emissionOverTime)
+        params['emissionOverTime'] = valueGen(data.emissionOverTime);
+    if (data.emissionOverDistance)
+        params['emissionOverDistance'] = valueGen(data.emissionOverDistance);
+    if (data.emissionBursts) {
+        params['emissionBursts'] = data.emissionBursts.map((b) => ({
+            time: b.time,
+            count: valueGen(b.count),
+            cycle: b.cycle ?? 1,
+            interval: b.interval ?? 0,
+            probability: b.probability ?? 1,
+        }));
+    }
+    if (data.behaviors)
+        params['behaviors'] = data.behaviors.map(createBehavior);
+    if (data.renderMode != null)
+        params['renderMode'] = RENDER_MODE_MAP[data.renderMode];
+    if (data.worldSpace != null)
+        params['worldSpace'] = data.worldSpace;
+    if (data.renderOrder != null)
+        params['renderOrder'] = data.renderOrder;
+    if (data.uTileCount != null)
+        params['uTileCount'] = data.uTileCount;
+    if (data.vTileCount != null)
+        params['vTileCount'] = data.vTileCount;
+    if (data.blendTiles != null)
+        params['blendTiles'] = data.blendTiles;
+    if (data.softParticles != null)
+        params['softParticles'] = data.softParticles;
+    if (data.softFarFade != null)
+        params['softFarFade'] = data.softFarFade;
+    if (data.softNearFade != null)
+        params['softNearFade'] = data.softNearFade;
+    const ps = new ParticleSystem(params);
+    return { emitter: ps.emitter, system: ps };
+}
+/**
+ * Register a particle system with a BatchedRenderer.
+ */
+export function registerParticleSystem(batchedRenderer, system) {
+    batchedRenderer.addSystem(system);
+}
+/**
+ * Unregister a particle system from a BatchedRenderer.
+ */
+export function unregisterParticleSystem(batchedRenderer, system) {
+    batchedRenderer.deleteSystem(system);
+}
+/**
+ * Default particle data for creating a new particle emitter via AddSectionMenu.
+ */
+export function defaultParticlesData() {
+    return {
+        looping: true,
+        duration: 2,
+        shape: { type: 'cone', radius: 0.1, angle: 0.3 },
+        startLife: { type: 'IntervalValue', a: 0.5, b: 1.5 },
+        startSpeed: { type: 'IntervalValue', a: 1, b: 3 },
+        startSize: { type: 'IntervalValue', a: 0.05, b: 0.15 },
+        startColor: {
+            type: 'ConstantColor',
+            color: { r: 1, g: 0.8, b: 0.2, a: 1 },
+        },
+        emissionOverTime: { type: 'ConstantValue', value: 30 },
+        behaviors: [
+            {
+                type: 'SizeOverLife',
+                size: {
+                    type: 'PiecewiseBezier',
+                    functions: [{ function: { p0: 1, p1: 0.67, p2: 0.33, p3: 0 }, start: 0 }],
+                },
+            },
+        ],
+        material: {
+            type: 'basic',
+            blending: 'additive',
+            transparent: true,
+            depthWrite: false,
+        },
+    };
+}

package/dist/scene/scene-apply.d.ts

@@ -0,0 +1,109 @@
+/**
+ * `applyDiff` — the exact inverse of `diffScene` (T4.5, `vgai apply-diff`).
+ *
+ * `diffScene` (packages/editor/src/scene-diff.ts) computes a `SceneDiff` from
+ * two `SceneFile`s. This module does the other direction: given ONE
+ * `SceneFile` and a `SceneDiff`, produce the `SceneFile` the diff describes —
+ * a pure function, no editor/live-scene state involved.
+ *
+ * DEPENDENCY-DIRECTION NOTE (why this lives in the engine, not next to
+ * `diffScene`): the natural home for `applyDiff` is beside `diffScene` in
+ * `packages/editor/src/`. But the CLI (`packages/vgai-cli`) is the caller —
+ * `vgai apply-diff <scene> <patch>` — and `packages/vgai-cli/package.json`
+ * does not depend on `@vgai/editor` today (it depends on `@vgai/editor-sdk`,
+ * a thin RPC client for a *running* editor server, and `create-vgai-project`
+ * — neither pulls in editor source). Adding a cli→editor edge purely to reach
+ * one pure function would be a real, new dependency inversion (the T3.7 row
+ * for `deploy.ts` recorded the opposite call deliberately staying out for the
+ * same reason). `@vgai/engine`, by contrast, is already a dependency of
+ * `@vgai/editor` (one-directional: editor → engine) and is trivially addable
+ * to vgai-cli (mirroring `packages/editor/template/validate-scenes.ts`, which
+ * already imports `@vgai/engine/scene/parse` by its real published subpath).
+ * So: `DiffOp`/`SceneDiff` (the shared TYPES) and `applyDiff`/`SceneDiffSchema`
+ * (the new CODE) live in the engine; `scene-diff.ts` keeps its `diffScene`
+ * implementation where it is and re-exports the two type names, so no editor
+ * call site changes. Net edge added: vgai-cli → @vgai/engine (already the
+ * direction every other package depends on engine). Zero new editor edges.
+ *
+ * ROUND-TRIP LAW: for any two scenes A, B — `applyDiff(A, diffScene(A, B))`
+ * is deep-equal to B, WITH ONE NORMALIZATION: an entity whose `children`
+ * becomes empty is left with `children` omitted (not `children: []`) —
+ * matching the convention `cleanDocument`/`serializeScene`
+ * (packages/editor/src/scene-serializer.ts) already use for saved scene
+ * files. If B's own file happened to spell "no children" as a literal
+ * `children: []` rather than omitting the key, a byte-level diff would show
+ * that one field; every other field, and the full entity tree/order, matches
+ * exactly. This holds because `diffScene` emits an explicit `move` op for
+ * ANY entity whose absolute sibling index changes for ANY reason — not just
+ * reparenting, but also a sibling being added/removed/reordered earlier in
+ * the same array — so `applyDiff` never has to guess whether an untouched
+ * entity's position shifted; every position-relevant entity carries an
+ * explicit target index in the FINAL array.
+ *
+ * OP-ORDERING RULE (why applying `diff.ops` in array order would be wrong,
+ * and what this function does instead):
+ *
+ *   1. Detach every `move` target from wherever it currently sits — BEFORE
+ *      processing any `remove`. Proof this matters: consider "remove parent
+ *      with moved-out child" — parent P is deleted in the new doc, but one
+ *      of P's old children, C, survives (reparented elsewhere). `diffScene`
+ *      necessarily emits BOTH `{ remove: P }` and `{ move: C, parentId: ... }`
+ *      (C's parentId can't still be P, since P doesn't exist in the new doc,
+ *      so a parentId change — hence a move op — is guaranteed). If `remove P`
+ *      ran first, it would delete P's whole subtree, including C, before C's
+ *      `move` op ever got to detach it. Detaching every mover first means C
+ *      is already pulled out of P's subtree by the time `remove P` runs, so
+ *      only what's genuinely being deleted is deleted.
+ *   2. Process `remove` ops. A remove target that's already gone (not found)
+ *      is NOT an error IF it was swept away as a descendant of an earlier
+ *      remove in the SAME diff — `diffScene` lists every removed id
+ *      independently (both a removed parent AND its removed descendants each
+ *      get their own `remove` op, since `flattenEntities` flattens every
+ *      level regardless of ancestor state). A remove target not found and
+ *      not swept is a genuine error (bad id).
+ *   3. Build a complete id → node resolution map covering EVERY entity that
+ *      will exist in the output: the stationary survivors (walked fresh from
+ *      what's left of the tree), then a freshly-created node object for each
+ *      `add` (children stripped — see below), then the already-detached node
+ *      for each `move`. Because this map is built in full before any
+ *      placement happens, a node object exists (and is resolvable as a
+ *      parent) from the moment it's created, independent of whether it has
+ *      itself been spliced into ITS OWN parent's array yet. This is what
+ *      makes "add-under-added-parent" (a newly-added parent with newly-added
+ *      children in the same diff) work with no dependency/topological-sort
+ *      logic: a child's `add`/`move` op resolves its `parentId` against this
+ *      map regardless of which op appears first in `diff.ops`.
+ *   4. Placement: group `add` + `move` ops by target parentId, sort each
+ *      group ascending by `index`, then splice one at a time into the target
+ *      array in that order. Inserting in ascending order of FINAL target
+ *      index into an array that already holds every untouched sibling in
+ *      their final relative order (untouched siblings never move — any
+ *      absolute-index change gets its own `move` op, per the round-trip-law
+ *      note above) reconstructs the exact final array: by induction, every
+ *      element with a smaller final index than the one being inserted is
+ *      already in the array, so splicing at `index` places it correctly
+ *      relative to all of them, whether the array started empty (a brand
+ *      new parent) or partially populated (survivors of an existing parent).
+ *   5. `update` ops last (order relative to placement doesn't matter — they
+ *      mutate an object by reference, found via the same id map, regardless
+ *      of where in the tree that reference currently lives).
+ *
+ * Every thrown error is an `ApplyDiffError` naming the 0-based index into
+ * `diff.ops`, the op's `type`, and the entity id involved — enough for an
+ * agent to locate and fix the offending op from the message alone.
+ */
+import type { DiffOp, SceneDiff } from './scene-diff-types';
+import type { SceneFile } from './scene-types';
+export declare class ApplyDiffError extends Error {
+    readonly opIndex: number;
+    readonly opType: DiffOp['type'];
+    readonly entityId: string;
+    constructor(message: string, opIndex: number, opType: DiffOp['type'], entityId: string);
+}
+/**
+ * Apply a `SceneDiff` to a `SceneFile`, returning a NEW `SceneFile` (input is
+ * not mutated). See the module jsdoc above for the round-trip law and the
+ * op-ordering rule/proof.
+ */
+export declare function applyDiff(scene: SceneFile, diff: SceneDiff): SceneFile;
+//# sourceMappingURL=scene-apply.d.ts.map

package/dist/scene/scene-apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene-apply.d.ts","sourceRoot":"","sources":["../../src/scene/scene-apply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6FG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EAAe,SAAS,EAAE,MAAM,eAAe,CAAC;AAE5D,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,MAAM;CAOvF;AAmDD;;;;GAIG;AAEH,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,GAAG,SAAS,CA4LtE"}