@vvfx/ge-ir 0.0.1-beta.11 → 0.0.1-beta.12

package/dist/ir2ge/assemble-source-preserved-data.d.ts

@@ -0,0 +1,5 @@
+import type { IRScene } from '@vvfx/animation-ir';
+import type { IRToGEOptions } from '../conversion';
+import { type GEToIRPreservedData } from '../preserved-data';
+/** Reconcile source-local GE payloads with identities already assigned by the IR converter. */
+export declare function assembleSourcePreservedData(scene: IRScene, options: IRToGEOptions): GEToIRPreservedData;

package/dist/ir2ge/converter/bezier.d.ts

@@ -19,10 +19,10 @@ export interface IRToGETimeContext {
 interface GEPositionAnimationData {
     /** One-dimensional timing curves in BezierKeyframeValue format. */
     curves: BezierKeyframeValue[][];
-    /** Segment endpoints as `[[startX, startY], [endX, endY]]`. */
-    pathPoints: [[number, number], [number, number]][];
-    /** Segment control offsets as `[[outX, outY], [inX, inY]]`. */
-    controlPoints: [[number, number], [number, number]][];
+    /** Segment start and end positions, including depth. */
+    pathPoints: [IRVec3, IRVec3][];
+    /** Outgoing and incoming control offsets in the same coordinates as the endpoints. */
+    controlPoints: [IRVec3, IRVec3][];
 }
 /** Convert a scalar property to a single GE Bezier curve. */
 export declare function convertIRScalarKeyframesToGE(property: IRAnimatedProperty<number>, timeContext: IRToGETimeContext): BezierKeyframeValue[][] | undefined;
@@ -30,6 +30,4 @@ export declare function convertIRScalarKeyframesToGE(property: IRAnimatedPropert
 export declare function convertIRVectorKeyframesToGE(property: IRAnimatedProperty<IRVec3>, timeContext: IRToGETimeContext): BezierKeyframeValue[][] | undefined;
 /** Convert position keyframes to GE path, control-point, and timing payloads. */
 export declare function convertIRPositionKeyframesToGE(property: IRAnimatedProperty<IRVec3>, timeContext: IRToGETimeContext): GEPositionAnimationData | undefined;
-/** Return whether GE's compact keyframe fields are required for this property. */
-export declare function shouldUseKeyframeMode(property: IRAnimatedProperty): boolean;
 export {};

package/dist/ir2ge/converter/precomp.d.ts

@@ -1,5 +1,5 @@
-import { type IRAnimatedProperty, type IRComposition, type IRScene, type IRPrecompLayer } from '@vvfx/animation-ir';
-import type { ConversionDiagnostic } from '@vvfx/animation-ir/adapter';
+import type { IRAnimatedProperty, IRComposition, IRPrecompLayer, IRScene } from '@vvfx/animation-ir';
+import { type ConversionDiagnostic } from '@vvfx/animation-ir/adapter';
 interface CompositionGenerationRequest {
     id: string;
     ir: IRComposition;
@@ -10,7 +10,7 @@ interface CompositionGenerationPlan {
     compositionById: ReadonlyMap<string, IRComposition>;
     requests: CompositionGenerationRequest[];
 }
-/** Plan source Compositions and the instance-specific variants required by GE. */
+/** Plan only Compositions and instance-specific variants reachable from the playback entry. */
 export declare function buildCompositionGenerationPlan(irScene: IRScene, diagnostics: ConversionDiagnostic[]): CompositionGenerationPlan;
 /** Report GE runtime limitations that apply to a source Precomp instance. */
 export declare function collectPrecompExportDiagnostics(layer: IRPrecompLayer, compositionById: ReadonlyMap<string, IRComposition>, composition: IRComposition, diagnostics: ConversionDiagnostic[]): void;

package/dist/ir2ge/generator/{component.d.ts → append-component.d.ts}

@@ -1,6 +1,6 @@
 import type { IRLayer, IRShape, IRShapePaint, IRShapeStroke } from '@vvfx/animation-ir';
 import type { LayerGenerationContext } from '../types';
-export declare function buildComponent(layer: IRLayer, itemId: string, anchorScaleX: number, anchorScaleY: number, ctx: LayerGenerationContext): string | undefined;
+export declare function appendComponent(layer: IRLayer, itemId: string, anchorScaleX: number, anchorScaleY: number, ctx: LayerGenerationContext): string | undefined;
 export declare function buildShapeOptions(shapeData: IRShape, ratio: number, ctx?: LayerGenerationContext, renderStyle?: ShapeRenderStyle): Record<string, unknown>;
 export interface ShapeRenderStyle {
     fills: IRShapePaint[];

package/dist/ir2ge/generator/append-particle-component.d.ts

@@ -0,0 +1,3 @@
+import type { IRParticleLayer } from '@vvfx/animation-ir';
+import type { LayerGenerationContext } from '../types';
+export declare function appendParticleComponent(layer: IRParticleLayer, itemId: string, anchorScaleX: number, anchorScaleY: number, ctx: LayerGenerationContext): string;

package/dist/ir2ge/generator/append-timeline-tracks.d.ts

@@ -0,0 +1,15 @@
+import type { IRComposition } from '@vvfx/animation-ir';
+import type { EffectsLayerPreservedData } from '../../preserved-data';
+import type { DataPath } from '@galacean/effects-specification';
+import { type EndBehavior, ItemType } from '@galacean/effects-specification';
+import type { ECSCollector, GeneratedItemBinding, TransformAnimation } from '../types';
+interface TimelineTrackCollector {
+    miscs: Record<string, unknown>[];
+}
+/** Append binding, activation, transform, and supported renderer-color tracks for one Item. */
+export declare function appendTimelineTracks(collector: TimelineTrackCollector, delay: number, duration: number, endBehavior: EndBehavior, animation: TransformAnimation, itemType: ItemType, precompTimeOffset?: number): string;
+export declare function restoreComponentTimelines(collector: ECSCollector, ir: IRComposition, itemBindings: GeneratedItemBinding[], layerDataById: Readonly<Record<string, EffectsLayerPreservedData>>): {
+    key: DataPath;
+    value: DataPath;
+}[];
+export {};

package/dist/ir2ge/generator/component-preservation.d.ts

@@ -3,3 +3,4 @@ import type { GeneratedComponentData, LayerGenerationContext } from '../types';
 export declare function resolveComponentId(layer: IRLayer, ctx: LayerGenerationContext): string;
 /** Copy a preserved GE mask whose target references are remapped after generation. */
 export declare function copyPreservedMaskToComponent(layer: IRLayer, component: GeneratedComponentData, ctx: LayerGenerationContext): void;
+export declare function restoreComponentRenderData(layer: IRLayer, component: GeneratedComponentData, ctx: LayerGenerationContext): void;

package/dist/ir2ge/generator/layer-strategy.d.ts

@@ -4,7 +4,7 @@ import type { EffectsLayerPreservedData } from '../../preserved-data';
  * Anchor encoding strategy.
  *
  * - `inline-anchor` encodes the renderer anchor and compensates item position.
- * - `split-null-sprite` places transforms on a null parent and visual content
+ * - `split-null-visual` places transforms on a null parent and visual content
  *   on an anchor-offset child.
  * Effects passthrough data may request the source hierarchy.
  */
@@ -13,7 +13,7 @@ type LayerGenerationStrategy = {
     anchorScale: [number, number];
     anchorOffset: [number, number];
 } | {
-    kind: 'split-null-sprite';
+    kind: 'split-null-visual';
 };
 export declare function resolveLayerGenerationStrategy(layer: IRLayer, preservedData?: EffectsLayerPreservedData): LayerGenerationStrategy;
 export {};

package/dist/ir2ge/post-process/mask.d.ts

@@ -3,8 +3,9 @@
  * or descendant renderer components.
  */
 import { type IRComposition, type IRMask } from '@vvfx/animation-ir';
+import type { ConversionDiagnostic } from '@vvfx/animation-ir/adapter';
 import { type RuntimeMaskGeometry } from './mask-geometry';
-import type { ECSCollector, GeneratedItemBinding } from '../types';
+import type { ECSCollector, GeneratedComponentData, GeneratedItemBinding } from '../types';
 /** Resolve stable IR Layer IDs to generated items and components. */
 export interface MaskLayerLookup {
     getItemId(layerId: string): string | undefined;
@@ -13,21 +14,26 @@ export interface MaskLayerLookup {
     getComponentId(layerId: string): string | undefined;
     isParentLayer(layerId: string): boolean;
 }
-type MaskOrigin = 'authored' | 'clip';
-/** Internal ownership metadata for each renderer's single Runtime mask slot. */
+/** Internal metadata used to deduplicate and simplify generated Runtime references. */
 export interface RuntimeMaskSourceMeta {
-    origin: MaskOrigin;
-    area: number;
     geometry?: RuntimeMaskGeometry;
-    specificity: number;
+    /** Identity of the local coordinate space used by geometry. */
+    geometrySpaceId?: string;
+    inverted: boolean;
 }
-/** Shared single-mask arbitration state across every generated Composition. */
+interface RuntimeMaskTargetReference {
+    componentId: string;
+    source: RuntimeMaskSourceMeta;
+}
+/** Shared multi-mask state across every generated Composition. */
 export interface RuntimeMaskState {
-    slots: Map<string, RuntimeMaskSourceMeta>;
+    references: Map<string, RuntimeMaskTargetReference[]>;
     sources: Map<string, RuntimeMaskSourceMeta>;
 }
 export declare function createRuntimeMaskState(): RuntimeMaskState;
-export declare function applyMasks(ir: IRComposition, collector: ECSCollector, itemBindings: GeneratedItemBinding[], ratio: number, _width: number, _height: number, frameRate: number, lookup: MaskLayerLookup, compositionById?: ReadonlyMap<string, IRComposition>, runtimeMaskState?: RuntimeMaskState): void;
-/** Fold the source-neutral Mask operation and path polarity into GE's single inversion flag. */
+export declare function applyMasks(ir: IRComposition, collector: ECSCollector, itemBindings: GeneratedItemBinding[], ratio: number, _width: number, _height: number, frameRate: number, lookup: MaskLayerLookup, compositionById?: ReadonlyMap<string, IRComposition>, runtimeMaskState?: RuntimeMaskState, diagnostics?: ConversionDiagnostic[]): void;
+/** Fold the source-neutral Mask operation and path polarity into one GE reference direction. */
 export declare function resolveGEMaskInverted(mask: Pick<IRMask, 'mode' | 'inverted'>): boolean;
+/** Append one target reference while removing provably redundant positive masks. */
+export declare function appendRuntimeMaskReference(component: GeneratedComponentData, maskComponentId: string, sourceMeta: RuntimeMaskSourceMeta, runtimeMaskState: RuntimeMaskState): boolean;
 export {};

package/dist/ir2ge/post-process/matte.d.ts

@@ -1,5 +1,6 @@
 import { type IRComposition } from '@vvfx/animation-ir';
 import type { ConversionDiagnostic } from '@vvfx/animation-ir/adapter';
 import type { ECSCollector } from '../types';
+import { type RuntimeMaskState } from './mask';
 /** Lower Layer-reference mattes to GE's component mask source/target relationship. */
-export declare function applyLayerMattes(ir: IRComposition, collector: ECSCollector, layerToComponentId: Readonly<Record<string, string>>, diagnostics: ConversionDiagnostic[]): void;
+export declare function applyLayerMattes(ir: IRComposition, collector: ECSCollector, layerToComponentId: Readonly<Record<string, string>>, runtimeMaskState: RuntimeMaskState, diagnostics: ConversionDiagnostic[]): void;

package/dist/ir2ge/post-process/merge-preserved-resources.d.ts

@@ -1,3 +1,4 @@
 import type { GEToIRPreservedData } from '../../preserved-data';
 /** Merge source GE objects that are outside Composition graphs regenerated from IR. */
 export declare function mergePreservedResources(generated: Record<string, unknown>, preservedData?: GEToIRPreservedData): Record<string, unknown>;
+export declare function mergeGEPlayerVersion(hostScene: Record<string, unknown>, sourceScene: Record<string, unknown>): void;

package/dist/ir2ge/post-process/{visibility.d.ts → normalize-activation-intervals.d.ts}

@@ -1,12 +1,12 @@
 import type { VFXItemData } from '@galacean/effects-specification';
 import type { GeneratedMiscData } from '../types';
-type VisibilityItem = Pick<VFXItemData, 'id' | 'delay' | 'duration' | 'parentId'>;
+type ActivationItem = Pick<VFXItemData, 'id' | 'delay' | 'duration' | 'parentId'>;
 interface GeneratedItemBindingRef {
     itemId: string;
     objectBindingTrackId?: string;
 }
-interface NormalizeVisibilityParams {
-    items: VisibilityItem[];
+interface NormalizeHierarchyActivationOptions {
+    items: ActivationItem[];
     miscs: GeneratedMiscData[];
     itemBindings: GeneratedItemBindingRef[];
     /** Generated item IDs corresponding to IR Layers with a Transform Parent. */
@@ -18,5 +18,5 @@ interface NormalizeVisibilityParams {
  * normalize internal generated child items in parent-first order. Parent
  * activation changes do not alter Transform keyframe time domains.
  */
-export declare function normalizeChildVisibilityByParentDelays({ items, miscs, itemBindings, transformParentChildItemIds, roundNumber, }: NormalizeVisibilityParams): void;
+export declare function normalizeHierarchyActivationIntervals({ items, miscs, itemBindings, transformParentChildItemIds, roundNumber, }: NormalizeHierarchyActivationOptions): void;
 export {};

package/dist/ir2ge/post-process/restore-runtime-graph.d.ts

@@ -0,0 +1,4 @@
+import type { GEToIRPreservedData } from '../../preserved-data';
+import type { GeneratedCompositionData } from '../types';
+/** Reconnect GE-only objects without replacing entities regenerated from editable IR. */
+export declare function restoreRuntimeGraph(generated: Record<string, unknown>, compositions: GeneratedCompositionData[], preservedData?: GEToIRPreservedData): void;

package/dist/ir2ge/types.d.ts

@@ -6,6 +6,16 @@ import type { EffectsLayerPreservedData } from '../preserved-data';
 export type GeneratedVFXItemData = Omit<VFXItemData, 'content' | 'transform'> & Partial<Pick<VFXItemData, 'content'>> & Required<Pick<VFXItemData, 'transform'>>;
 /** Generated component with specification fields and preserved extension data. */
 export type GeneratedComponentData = ComponentData & Record<string, unknown>;
+/** Multi-mask wire format consumed by the updated GE Runtime but not yet exposed by specification 2.8.1. */
+export interface GeneratedMaskReference {
+    mask: DataPath;
+    inverted?: boolean;
+}
+export interface GeneratedMaskOptions {
+    isMask?: boolean;
+    alphaMaskEnabled?: boolean;
+    references?: GeneratedMaskReference[];
+}
 /** Generated misc object with specification fields and timeline payloads. */
 export type GeneratedMiscData = EffectsObjectData & Record<string, unknown>;
 /** Pools collected while building a GE JSONScene. */

package/dist/particle/assemble-particle-source-data.d.ts

@@ -0,0 +1,11 @@
+import type { IRScene } from '@vvfx/animation-ir';
+import type { GEToIRPreservedData } from '../preserved-data';
+/** Each placed instance owns its identities, including references inside opaque GE payloads. */
+export declare function namespaceParticleSource(input: {
+    scene: IRScene;
+    preservedData: GEToIRPreservedData;
+}, idMap: Readonly<Record<string, string>>): typeof input & {
+    ids: ReadonlyMap<string, string>;
+};
+/** Combine only source pools; generated Items and Timelines are assembled by the regular exporter. */
+export declare function appendParticleSourceResources(target: GEToIRPreservedData, source: GEToIRPreservedData): void;

package/dist/particle/particle-fragment.d.ts

@@ -1,10 +1,7 @@
 import type { GEToIRPreservedData } from '../preserved-data';
-import type { ResolvedGEParticlePlacement } from './merge-particle-scenes';
-export interface ParticleFragment {
-    scene: Record<string, unknown>;
-    sourceCompositionId: string;
-    rootItemIds: string[];
-}
-/** Extract one complete particle effect group from a restored GE scene. */
-export declare function buildParticleFragment(sourceScene: Record<string, unknown>, preservedData: GEToIRPreservedData, placement: ResolvedGEParticlePlacement): ParticleFragment;
-export declare function resolveCompositionRuntime(composition: Record<string, unknown>, componentById: ReadonlyMap<string, Record<string, unknown>>): Record<string, unknown>;
+/** Retain one particle system or its complete group with source dependencies. */
+export declare function buildParticleFragment(sourceScene: Record<string, unknown>, preservedData: GEToIRPreservedData, selection: {
+    effectGroupId: string;
+    irCompositionId: string;
+    irLayerId?: string;
+}): Record<string, unknown>;

package/dist/preserved-data.d.ts

@@ -32,8 +32,21 @@ export interface EffectsLayerPreservedData {
     positionOverLifetime?: Record<string, unknown>;
     rotationOverLifetime?: Record<string, unknown>;
     sizeOverLifetime?: Record<string, unknown>;
+    transformBaseScale?: [number, number, number];
     colorOverLifetime?: Record<string, unknown>;
     spriteStartColor?: IRColor;
+    spriteTexture?: {
+        image: Record<string, unknown>;
+        texture: Record<string, unknown>;
+    };
+    renderer?: Record<string, unknown>;
+    geometry?: Record<string, unknown>;
+    componentTimeline?: {
+        root: {
+            id: string;
+        };
+        objects: Record<string, unknown>[];
+    };
     spriteSplits?: EffectsSpriteSplit[];
     textureSheetAnimation?: EffectsTextureSheetAnimation;
     textSizeMode?: EffectsTextSizeMode;
@@ -41,17 +54,29 @@ export interface EffectsLayerPreservedData {
     itemAnchorById?: Record<string, [x: number, y: number]>;
     itemEulerHintById?: Record<string, [x: number, y: number, z: number]>;
     sourceComponentId?: string;
+    /** Additional runtime components owned by the source item, such as FFD or AnimationComponent. */
+    additionalComponentIds?: string[];
+    /** Parent outside the editable IR graph. */
+    runtimeParentId?: string;
     mask?: Record<string, unknown>;
     precompContent?: Record<string, unknown>;
     /** GE ParticleSystem payload excluding identity and generic mask fields; normalized IR fields override it on export. */
     particleContent?: Record<string, unknown>;
     /** Activation clip behavior retained independently from the normalized GE Item behavior. */
     timelineEndBehavior?: EndBehavior;
+    itemTiming?: {
+        delay: number;
+        duration: number;
+    };
     sourceHierarchy?: 'single-item' | 'null-sprite-pair';
 }
 export interface GECompositionSourceBinding {
     sourceCompositionId: string;
+    camera?: Record<string, unknown>;
     sourceItemOrder: string[];
+    /** GE-only items and composition components restored from sourceScene. */
+    runtimeItemIds?: string[];
+    runtimeComponentIds?: string[];
     layerDataById: Record<string, EffectsLayerPreservedData>;
 }
 /** GE-owned data retained outside the source-neutral Animation IR contract. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vvfx/ge-ir",
-  "version": "0.0.1-beta.11",
+  "version": "0.0.1-beta.12",
   "description": "Bidirectional Galacean Effects and Animation IR conversion with GE fidelity preservation",
   "module": "./dist/index.mjs",
   "main": "./dist/index.js",
@@ -16,9 +16,9 @@
     }
   },
   "dependencies": {
-    "@galacean/effects-specification": "2.7.2",
+    "@galacean/effects-specification": "2.8.1",
     "uuid": "^13.0.0",
-    "@vvfx/animation-ir": "0.0.1-beta.11"
+    "@vvfx/animation-ir": "0.0.1-beta.12"
   },
   "contributors": [
     {
@@ -44,7 +44,7 @@
     "converter"
   ],
   "engines": {
-    "node": ">=22"
+    "node": ">=24"
   },
   "scripts": {
     "prebuild": "pnpm clean",

package/dist/ir2ge/generator/build-particle-component.d.ts

@@ -1,3 +0,0 @@
-import type { IRParticleLayer } from '@vvfx/animation-ir';
-import type { LayerGenerationContext } from '../types';
-export declare function buildParticleComponent(layer: IRParticleLayer, itemId: string, anchorScaleX: number, anchorScaleY: number, ctx: LayerGenerationContext): string;

package/dist/ir2ge/generator/timeline.d.ts

@@ -1,8 +0,0 @@
-import { type EndBehavior, ItemType } from '@galacean/effects-specification';
-import type { TransformAnimation } from '../types';
-interface TimelineTrackCollector {
-    miscs: Record<string, unknown>[];
-}
-/** Build binding, activation, transform, and supported renderer-color tracks for one Item. */
-export declare function buildTimelineTracks(collector: TimelineTrackCollector, delay: number, duration: number, endBehavior: EndBehavior, animation: TransformAnimation, itemType: ItemType, precompTimeOffset?: number): string;
-export {};

package/dist/ir2ge/map-particle-layout-to-ge-transform.d.ts

@@ -1,30 +0,0 @@
-export interface GEParticleTargetRegion {
-    width: number;
-    height: number;
-    center: readonly [x: number, y: number];
-}
-export interface ParticleLayoutMappingOptions {
-    targetRegion: GEParticleTargetRegion;
-    hostComposition: Record<string, unknown>;
-    sourceComposition: Record<string, unknown>;
-    authoringBounds: readonly [x: number, y: number, width: number, height: number];
-}
-export interface GEParticleLayoutTransform {
-    position: {
-        x: number;
-        y: number;
-        z: 0;
-    };
-    eulerHint: {
-        x: 0;
-        y: 0;
-        z: 0;
-    };
-    scale: {
-        x: number;
-        y: number;
-        z: 1;
-    };
-}
-/** Map one planned particle region from pixel layout into a GE transform. */
-export declare function mapParticleLayoutToGETransform(options: ParticleLayoutMappingOptions): GEParticleLayoutTransform;

package/dist/particle/merge-particle-fragment.d.ts

@@ -1,12 +0,0 @@
-import type { ResolvedGEParticlePlacement } from './merge-particle-scenes';
-import { type ParticleFragment } from './particle-fragment';
-interface AppendParticleFragmentOptions {
-    usedIds: Set<string>;
-    itemZById: Map<string, number>;
-    wrapperItemIds: Set<string>;
-}
-/** Append one dependency-closed particle effect fragment to a GE host. */
-export declare function appendParticleFragmentToGE(hostScene: Record<string, unknown>, fragment: ParticleFragment, placement: ResolvedGEParticlePlacement, options: AppendParticleFragmentOptions): void;
-export declare function collectGEIds(value: unknown, ids?: Set<string>, visited?: WeakSet<object>): Set<string>;
-export declare function mergeGEPlayerVersion(hostScene: Record<string, unknown>, sourceScene: Record<string, unknown>): void;
-export {};

package/dist/particle/merge-particle-scenes.d.ts

@@ -1,21 +0,0 @@
-import type { JSONScene } from '@galacean/effects-specification';
-import type { GEParticleAuthoringBounds, GEToIRPreservedData } from '../preserved-data';
-/** Host-canvas placement for an effect group or one bound particle system. */
-export interface GEParticlePlacement {
-    effectGroupId: string;
-    irLayerId?: string;
-    width: number;
-    height: number;
-    position: readonly [x: number, y: number, z: number];
-}
-export interface ParticleSceneMergeInput {
-    scene: unknown;
-    preservedData: GEToIRPreservedData;
-    placements: readonly GEParticlePlacement[];
-}
-export interface ResolvedGEParticlePlacement extends GEParticlePlacement {
-    irCompositionId: string;
-    authoringBounds: Readonly<GEParticleAuthoringBounds>;
-}
-/** Merge multiple restored particle GE scenes while preserving one shared painter-order calculation. */
-export declare function mergeParticleScenes(hostScene: unknown, sources: readonly ParticleSceneMergeInput[], hostStackingOrder?: ReadonlyMap<string, number>): JSONScene;