@galacean/effects-core 2.8.9 → 2.9.0-alpha.1

package/dist/animation/animation-clip.d.ts

@@ -4,6 +4,7 @@ import * as spec from '@galacean/effects-specification';
 import { EffectsObject } from '../effects-object';
 import type { ValueGetter, Vector3Curve, BezierCurve, ColorCurve } from '../math';
 import type { VFXItem } from '../vfx-item';
+import { type AnimationEventInfo } from './animation-events';
 export interface AnimationCurve {
     path: string;
     keyFrames: ValueGetter<any>;
@@ -38,6 +39,7 @@ export declare class AnimationClip extends EffectsObject {
     scaleCurves: ScaleAnimationCurve[];
     floatCurves: FloatAnimationCurve[];
     colorCurves: ColorAnimationCurve[];
+    events: AnimationEventInfo[];
     sampleAnimation(vfxItem: VFXItem, time: number): void;
     fromData(data: spec.AnimationClipData): void;
     private findTarget;

package/dist/animation/animation-events.d.ts

@@ -0,0 +1,29 @@
+import type { AnimationClip } from './animation-clip';
+import type { VFXItem } from '../vfx-item';
+export interface AnimationEventReference {
+    event: AnimationEventInfo;
+    currentTime: number;
+    deltaTime: number;
+}
+export interface AnimationEventInfo {
+    name: string;
+    startTime: number;
+    duration: number;
+    event: AnimationEvent;
+    clip: AnimationClip;
+}
+export interface AnimationEventData {
+    typeName: string;
+}
+export interface AnimationEventInfoData {
+    name: string;
+    startTime: number;
+    duration?: number;
+    eventData?: AnimationEventData;
+}
+export declare class AnimationEvent {
+    onEvent(item: VFXItem, animation: AnimationClip, eventReference: AnimationEventReference): void;
+}
+export declare class NotifyEvent extends AnimationEvent {
+    onEvent(item: VFXItem, animation: AnimationClip, eventReference: AnimationEventReference): void;
+}

package/dist/animation/index.d.ts

@@ -1,2 +1,3 @@
 export * from './color-playable';
 export * from './animation-clip';
+export * from './animation-events';

package/dist/asset-manager.d.ts

@@ -4,6 +4,7 @@ import type { ImageLike, SceneLoadOptions } from './scene';
 import { Scene } from './scene';
 import type { Disposable } from './utils';
 import type { Renderer } from './render';
+import { Precomposition } from './precompositions/precomposition';
 /**
  * 资源管理器
  * 用于加载和动效中所有的资源文件，包括图片、插件、图层粒子数据等
@@ -44,6 +45,7 @@ export declare class AssetManager implements Disposable {
      * @returns
      */
     static loadFontFamily(fonts: spec.FontDefine[], baseUrl?: string): Promise<void[] | undefined>;
+    static loadPrecomposition(jsonScene: spec.JSONScene | string, options?: SceneLoadOptions): Promise<Precomposition>;
     /**
      * 构造函数
      * @param options - 场景加载参数

package/dist/asset-service.d.ts

@@ -29,7 +29,6 @@ export declare class AssetService implements Disposable {
      * @param options
      */
     updateTextVariables(scene: Scene, variables?: spec.TemplateVariables): void;
-    initializeTexture(scene: Scene): void;
     prepareAssets(scene: Scene, assets: Record<string, ImageLike>): void;
     createShaderVariant(): void;
     private destroyBuiltinObjects;

package/dist/camera.d.ts

@@ -4,6 +4,7 @@ import { Matrix4 } from '@galacean/effects-math/es/core/matrix4';
 import { Euler } from '@galacean/effects-math/es/core/euler';
 import * as spec from '@galacean/effects-specification';
 import { Transform } from './transform';
+import type { Engine } from './engine';
 interface CameraOptionsBase {
     /**
      * 相机近平面
@@ -42,14 +43,6 @@ export interface CameraOptions extends CameraOptionsBase {
      * 相机的旋转，四元数
      */
     quat?: spec.vec4;
-    /**
-     * 画布的像素宽度
-     */
-    pixelWidth: number;
-    /**
-     * 画布的像素高度
-     */
-    pixelHeight: number;
 }
 export interface CameraOptionsEx extends CameraOptionsBase {
     /**
@@ -70,14 +63,7 @@ export interface CameraOptionsEx extends CameraOptionsBase {
  */
 export declare class Camera {
     name: string;
-    /**
-     * 画布的像素宽度
-     */
-    pixelWidth: number;
-    /**
-     * 画布的像素高度
-     */
-    pixelHeight: number;
+    engine: Engine;
     /**
      * 编辑器用于缩放画布
      */

package/dist/components/base-render-component.d.ts

@@ -2,9 +2,7 @@ import { Color } from '@galacean/effects-math/es/core/color';
 import * as spec from '@galacean/effects-specification';
 import type { Engine } from '../engine';
 import type { Maskable } from '../material';
-import { MaskProcessor } from '../material';
-import type { BoundingBoxTriangle, HitTestTriangleParams } from '../plugins';
-import { MeshCollider } from '../plugins';
+import type { BoundingBoxInfo, BoundingBoxTriangle, HitTestTriangleParams } from '../plugins';
 import type { Renderer } from '../render';
 import { Geometry } from '../render';
 import { Texture } from '../texture';
@@ -26,11 +24,6 @@ export declare class MaskableGraphic extends RendererComponent implements Maskab
     renderer: ItemRenderer;
     geometry: Geometry;
     protected visible: boolean;
-    protected readonly maskManager: MaskProcessor;
-    /**
-     * 用于点击测试的碰撞器
-     */
-    protected meshCollider: MeshCollider;
     protected defaultGeometry: Geometry;
     private _color;
     /**
@@ -89,7 +82,11 @@ export declare class MaskableGraphic extends RendererComponent implements Maskab
     render(renderer: Renderer): void;
     onStart(): void;
     getHitTestParams: (force?: boolean) => HitTestTriangleParams | undefined;
+    /**
+     * @deprecated 2.9.0 Please use getBoundingBoxInfo
+     */
     getBoundingBox(): BoundingBoxTriangle;
+    getBoundingBoxInfo(): BoundingBoxInfo;
     private configureMaterial;
     private draw;
     fromData(data: unknown): void;

package/dist/components/component.d.ts

@@ -47,6 +47,10 @@ export declare abstract class Component extends EffectsObject {
      * 生命周期函数，每帧调用一次，在 update 之后调用
      */
     onLateUpdate(dt: number): void;
+    /**
+     * 生命周期函数，每帧调用一次，在合成渲染之前调用
+     */
+    onPreRender(): void;
     /**
      * 生命周期函数，在组件销毁时调用
      */

package/dist/components/composition-component.d.ts

@@ -12,25 +12,45 @@ export interface SceneBindingData {
     key: spec.DataPath;
     value: spec.DataPath;
 }
+export declare enum UpdateModes {
+    EveryUpdate = 0,
+    Manual = 1
+}
 /**
  * @since 2.0.0
  */
 export declare class CompositionComponent extends Component {
-    time: number;
     items: VFXItem[];
-    private reusable;
+    /**
+     * 更新模式，决定了组件更新时间的方式
+     * - EveryUpdate：每帧自动更新，适用于大多数情况
+     * - Manual：需要手动调用 tick 接口更新，适用于需要精确控制更新时间的情况
+     */
+    updateMode: UpdateModes;
+    playOnStart: boolean;
+    endBehavior: spec.EndBehavior;
+    private time;
+    private lastTime;
     private sceneBindings;
     private timelineAsset;
-    private timelineInstance;
+    private _timelineInstance;
+    private nestedCompositions;
+    private get timelineInstance();
     onStart(): void;
-    getReusable(): boolean;
     pause(): void;
-    resume(): void;
+    play(): void;
+    stop(): void;
+    getTime(): number;
+    setTime(time: number): void;
     onUpdate(dt: number): void;
+    tick(deltaTime: number): void;
     onEnable(): void;
     onDisable(): void;
     onDestroy(): void;
     hitTest(ray: Ray, x: number, y: number, regions: Region[], force?: boolean, options?: CompositionHitTestOptions): boolean;
-    private hitTestRecursive;
+    /**
+     * 递归收集场景树中的直接子元素（DFS 前序）
+     */
+    private collectChildren;
     fromData(data: any): void;
 }

package/dist/components/frame-component.d.ts

@@ -0,0 +1,19 @@
+import { RendererComponent } from './renderer-component';
+import { type Maskable } from '../material';
+import type { Renderer } from '../render';
+import { Color } from '@galacean/effects-math/es/core/color';
+export declare class FrameComponent extends RendererComponent implements Maskable {
+    color: Color;
+    private clipGeometry;
+    private worldMatrix;
+    onAwake(): void;
+    onStart(): void;
+    onPreRender(): void;
+    render(renderer: Renderer): void;
+    onDestroy(): void;
+    drawStencilMask(maskRef: number): void;
+    fromData(data: any): void;
+    private getHitTestParams;
+    private setClipRectangle;
+    private setClipRectangleRecursive;
+}

package/dist/components/index.d.ts

@@ -8,3 +8,4 @@ export * from './post-process-volume';
 export * from './base-render-component';
 export * from './shape-component';
 export * from './fake-3d-component';
+export * from './frame-component';

package/dist/components/mesh-component.d.ts

@@ -1,9 +1,7 @@
 import type { Engine } from '../engine';
-import type { Maskable } from '../material/types';
-import type { BoundingBoxTriangle, HitTestTriangleParams } from '../plugins';
-import { MeshCollider } from '../plugins';
-import type { Geometry } from '../render/geometry';
-import type { Renderer } from '../render/renderer';
+import type { Maskable } from '../material';
+import type { BoundingBoxTriangle, HitTestTriangleParams, BoundingBoxInfo } from '../plugins';
+import type { Geometry, Renderer } from '../render';
 import { RendererComponent } from './renderer-component';
 /**
  * Mesh 组件
@@ -13,15 +11,11 @@ export declare class MeshComponent extends RendererComponent implements Maskable
      * 渲染的 Geometry
      */
     protected geometry: Geometry;
-    /**
-     * 用于点击测试的碰撞器
-     */
-    protected meshCollider: MeshCollider;
-    private readonly maskManager;
     constructor(engine: Engine);
     render(renderer: Renderer): void;
-    drawStencilMask(renderer: Renderer): void;
+    drawStencilMask(maskRef: number): void;
     getHitTestParams: (force?: boolean) => HitTestTriangleParams | void;
     getBoundingBox(): BoundingBoxTriangle | void;
+    getBoundingBoxInfo(): BoundingBoxInfo;
     fromData(data: any): void;
 }

package/dist/components/renderer-component.d.ts

@@ -1,18 +1,34 @@
 import type { Material } from '../material';
-import type { Renderer } from '../render';
+import { MaskProcessor } from '../material';
+import { BoundingBoxInfo } from '../plugins/interact/mesh-collider';
 import { Component } from './component';
+import type { Renderer } from '../render/renderer';
 /**
  * 所有渲染组件的基类
  * @since 2.0.0
  */
 export declare class RendererComponent extends Component {
     materials: Material[];
+    /**
+     * @hidden
+     * Internal utility.
+     * Not part of the public API — do not rely on this in your code.
+     */
+    maskManager: MaskProcessor;
     protected _priority: number;
+    /**
+     * 用于点击测试的碰撞器
+     */
+    protected boundingBoxInfo: BoundingBoxInfo;
     get priority(): number;
     set priority(value: number);
     get material(): Material;
     set material(material: Material);
-    render(renderer: Renderer): void;
     onEnable(): void;
     onDisable(): void;
+    /**
+     * 获取包围盒信息
+     */
+    getBoundingBoxInfo(): BoundingBoxInfo;
+    render(renderer: Renderer): void;
 }

package/dist/components/shape-component.d.ts

@@ -3,7 +3,7 @@ import { Vector2 } from '@galacean/effects-math/es/core/vector2';
 import * as spec from '@galacean/effects-specification';
 import type { Engine } from '../engine';
 import type { Maskable } from '../material';
-import type { BoundingBoxTriangle, HitTestTriangleParams } from '../plugins';
+import type { BoundingBoxTriangle, HitTestTriangleParams, BoundingBoxInfo } from '../plugins';
 import type { Renderer } from '../render';
 import type { GradientValue } from '../math';
 import { RendererComponent } from './renderer-component';
@@ -133,15 +133,10 @@ export declare class ShapeComponent extends RendererComponent implements Maskabl
     private strokeJoin;
     private strokes;
     private shapeAttributes;
-    /**
-     * 用于点击测试的碰撞器
-     */
-    private meshCollider;
     private rendererOptions;
     private geometry;
     private fillMaterials;
     private strokeMaterials;
-    private readonly maskManager;
     get shape(): ShapeAttributes;
     /**
      *
@@ -154,6 +149,7 @@ export declare class ShapeComponent extends RendererComponent implements Maskabl
     private draw;
     getHitTestParams: (force?: boolean) => HitTestTriangleParams | undefined;
     getBoundingBox(): BoundingBoxTriangle;
+    getBoundingBoxInfo(): BoundingBoxInfo;
     private buildGeometryFromPath;
     private buildPath;
     private updateMaterials;

package/dist/composition/scene-ticking.d.ts

@@ -5,6 +5,7 @@ import { Component } from '../components';
 export declare class SceneTicking {
     update: UpdateTickData;
     lateUpdate: LateUpdateTickData;
+    preRender: PreRenderTickData;
     /**
      *
      * @param obj
@@ -37,4 +38,7 @@ declare class UpdateTickData extends TickData {
 declare class LateUpdateTickData extends TickData {
     tickComponents(components: Component[], dt: number): void;
 }
+declare class PreRenderTickData extends TickData {
+    tickComponents(components: Component[], dt: number): void;
+}
 export {};

package/dist/composition.d.ts

@@ -143,6 +143,7 @@ export declare class Composition extends EventEmitter<CompositionEvent<Compositi
     renderOrder: number;
     /**
      * 播放完成后是否需要再使用，是的话生命周期结束后不会自动 dispose
+     * @deprecated
      */
     reusable: boolean;
     /**
@@ -190,10 +191,6 @@ export declare class Composition extends EventEmitter<CompositionEvent<Compositi
      * 合成根元素
      */
     readonly rootItem: VFXItem;
-    /**
-     * 预合成数组
-     */
-    readonly refContent: VFXItem[];
     /**
      * 合成的相机对象
      */
@@ -202,6 +199,10 @@ export declare class Composition extends EventEmitter<CompositionEvent<Compositi
      * 合成开始渲染的时间
      */
     readonly startTime: number;
+    /**
+     * 场景中视频列表
+     */
+    videos: HTMLVideoElement[];
     /**
      * 后处理渲染配置
      */
@@ -225,13 +226,13 @@ export declare class Composition extends EventEmitter<CompositionEvent<Compositi
     private paused;
     private isEndCalled;
     private _textures;
-    private videos;
     /**
      * Composition 构造函数
      * @param props - composition 的创建参数
      * @param scene
      */
     constructor(props: CompositionProps, scene: Scene);
+    get engine(): import("@galacean/effects-core").Engine;
     /**
      * 所有合成 Item 的根变换
      */
@@ -439,10 +440,12 @@ export declare class Composition extends EventEmitter<CompositionEvent<Compositi
     setScale(x: number, y: number, z: number): void;
     /**
      * 卸载贴图纹理方法，减少内存
+     * @deprecated
      */
     offloadTexture(): void;
     /**
      * 重新加载纹理
+     * @deprecated
      */
     reloadTexture(): Promise<void>;
 }

package/dist/culling/bounding-box.d.ts

@@ -0,0 +1,114 @@
+import { Matrix4 } from '@galacean/effects-math/es/core/matrix4';
+import { Vector3 } from '@galacean/effects-math/es/core/vector3';
+/**
+ * 包围盒类，用于存储和操作物体的边界信息
+ */
+export declare class BoundingBox {
+    /**
+     * 临时向量，用于避免频繁创建对象
+     */
+    private static tempVector0;
+    private static tempVector1;
+    private static tempVector2;
+    /**
+     * 局部空间的 8 个顶点
+     */
+    readonly vectors: Vector3[];
+    /**
+     * 世界空间的 8 个顶点
+     */
+    readonly vectorsWorld: Vector3[];
+    /**
+     * 局部空间的最小点
+     */
+    readonly minimum: Vector3;
+    /**
+     * 局部空间的最大点
+     */
+    readonly maximum: Vector3;
+    /**
+     * 世界空间的最小点
+     */
+    readonly minimumWorld: Vector3;
+    /**
+     * 世界空间的最大点
+     */
+    readonly maximumWorld: Vector3;
+    /**
+     * 局部空间的中心点
+     */
+    readonly center: Vector3;
+    /**
+     * 世界空间的中心点
+     */
+    readonly centerWorld: Vector3;
+    /**
+     * 局部空间的半尺寸（从中心到边界）
+     */
+    readonly extendSize: Vector3;
+    /**
+     * 世界空间的半尺寸
+     */
+    readonly extendSizeWorld: Vector3;
+    /**
+     * OBB 的方向向量
+     */
+    readonly directions: Vector3[];
+    private worldMatrix;
+    /**
+     * 创建包围盒
+     * @param minimum - 局部空间最小点
+     * @param maximum - 局部空间最大点
+     * @param worldMatrix - 世界变换矩阵
+     */
+    constructor(minimum: Vector3, maximum: Vector3, worldMatrix?: Matrix4);
+    /**
+     * 重新构建包围盒
+     * @param min - 新的最小点（局部空间）
+     * @param max - 新的最大点（局部空间）
+     * @param worldMatrix - 新的世界矩阵
+     */
+    reConstruct(min: Vector3, max: Vector3, worldMatrix?: Matrix4): void;
+    /**
+     * 更新世界空间数据
+     * @param world - 世界变换矩阵
+     */
+    update(world: Matrix4): void;
+    /**
+     * 缩放包围盒
+     * @param factor - 缩放因子
+     * @returns 返回自身以支持链式调用
+     */
+    scale(factor: number): BoundingBox;
+    /**
+     * 获取世界变换矩阵
+     * @returns 世界矩阵
+     */
+    getWorldMatrix(): Matrix4;
+    /**
+     * 测试点是否在包围盒内
+     * @param point - 要测试的点
+     * @returns 如果点在包围盒内返回 true
+     */
+    intersectsPoint(point: Vector3): boolean;
+    /**
+     * 测试包围盒是否与另一个包围盒相交
+     * @param box - 另一个包围盒
+     * @returns 如果相交返回 true
+     */
+    intersectsBox(box: BoundingBox): boolean;
+    /**
+     * 测试包围盒是否与 min/max 定义的区域相交
+     * @param min - 最小点
+     * @param max - 最大点
+     * @returns 如果相交返回 true
+     */
+    intersectsMinMax(min: Vector3, max: Vector3): boolean;
+    /**
+     * 静态方法：测试两个包围盒是否相交
+     * @param box0 - 第一个包围盒
+     * @param box1 - 第二个包围盒
+     * @returns 如果相交返回 true
+     */
+    static intersects(box0: BoundingBox, box1: BoundingBox): boolean;
+}

package/dist/engine.d.ts

@@ -89,6 +89,7 @@ export declare class Engine extends EventEmitter<EngineEvent> implements Disposa
     protected meshes: Mesh[];
     protected renderPasses: RenderPass[];
     private assetLoader;
+    private clearAction;
     get disposed(): boolean;
     /**
      *
@@ -109,7 +110,7 @@ export declare class Engine extends EventEmitter<EngineEvent> implements Disposa
     removeInstance(id: string): void;
     addPackageDatas(scene: Scene): void;
     runRenderLoop(renderFunction: (dt: number) => void): void;
-    render(dt: number): void;
+    mainLoop(dt: number): void;
     /**
      * 将渲染器重新和父容器大小对齐
      */

package/dist/events/types.d.ts

@@ -1,3 +1,4 @@
+import type { AnimationEventReference } from '../animation';
 import type { MessageItem } from '../composition';
 import type { PointerEventData, Region } from '../plugins';
 export type PointerEvent = {
@@ -27,6 +28,11 @@ export type ItemEvent = PointerEvent & {
      * 注意：仅对交互元素有效
      */
     ['message']: [message: Omit<MessageItem, 'compositionId'>];
+    /**
+     * 动画事件
+     * @since 2.9.0
+     */
+    ['animationevent']: [eventData: AnimationEventReference];
 };
 /**
  * Composition 可以绑定的事件
@@ -79,4 +85,9 @@ export type CompositionEvent<C> = PointerEvent & {
     ['goto']: [gotoInfo: {
         time: number;
     }];
+    /**
+     * 动画事件
+     * @since 2.9.0
+     */
+    ['animationevent']: [eventData: AnimationEventReference];
 };

package/dist/fallback/migration.d.ts

@@ -8,6 +8,14 @@ export declare function version21Migration(json: JSONSceneLegacy): JSONSceneLega
  * 2.2 以下版本数据适配（mars-player@2.5.0 及以上版本支持 2.2 以下数据的适配）
  */
 export declare function version22Migration(json: JSONSceneLegacy): JSONSceneLegacy;
+/**
+ * 2.5 以下版本 赫尔米特数据转换成贝塞尔数据
+ */
+export declare function version24Migration(json: JSONScene): JSONScene;
+/**
+ * 3.0 以下版本数据适配（runtime 2.0及以上版本支持）
+ */
+export declare function version30Migration(json: JSONSceneLegacy): JSONScene;
 /**
  * 3.1 版本数据适配
  * - 富文本插件名称的适配
@@ -17,16 +25,9 @@ export declare function version32Migration(json: JSONScene): JSONScene;
 export declare function version33Migration(json: JSONScene): JSONScene;
 export declare function version34Migration(json: JSONScene): JSONScene;
 export declare function version35Migration(json: JSONScene): JSONScene;
+export declare function version36Migration(json: JSONScene): JSONScene;
 export declare function processContent(composition: spec.CompositionData): void;
 export declare function processMask(renderContent: any): void;
-/**
- * 3.0 以下版本数据适配（runtime 2.0及以上版本支持）
- */
-export declare function version30Migration(json: JSONSceneLegacy): JSONScene;
-/**
- * 2.5 以下版本 赫尔米特数据转换成贝塞尔数据
- */
-export declare function version24Migration(json: JSONScene): JSONScene;
 export declare function convertParam(content?: BaseContent): void;
 export declare function convertBinaryAsset(bins: BinaryFile[], jsonScene: JSONScene): void;
 export declare function convertSpineData(resource: SpineResource, content: SpineContent, jsonScene: JSONScene): void;

package/dist/fallback/utils.d.ts

@@ -6,7 +6,6 @@ export declare function ensureFixedNumberWithRandom(a: any, p: number): FixedNum
 export declare function ensureRGBAValue(a: any): RGBAColorValue;
 export declare function ensureColorExpression(a: any, normalized?: boolean): ColorExpression | undefined;
 export declare function ensureNumberExpression(a: any): NumberExpression | undefined;
-export declare function ensureValueGetter(a: any): any;
 export declare function ensureGradient(a: any, normalized?: boolean): GradientColor | undefined;
 export declare function colorToArr(hex: string | number[], normalized?: boolean): vec4;
 export declare function normalizeColor(a: number[]): number[] | undefined;

package/dist/index.d.ts

@@ -39,4 +39,5 @@ export * from './effects-object';
 export * from './effects-package';
 export * from './events';
 export * from './pass-render-level';
+export * from './precompositions';
 export declare const version: string;