@galacean/effects-core 2.9.0-alpha.0 → 2.9.0-alpha.2

package/dist/material/types.d.ts

@@ -2,6 +2,7 @@ import type * as spec from '@galacean/effects-specification';
 import type { Matrix3, Matrix4, Vector2, Vector3, Vector4 } from '@galacean/effects-math/es/core/index';
 import type { Texture } from '../texture';
 import type { DestroyOptions } from '../utils';
+import type { VFXItem } from '../vfx-item';
 export type UniformSemantic = 'VIEW' | 'MODEL' | 'MODELVIEW' | 'PROJECTION' | 'VIEWPROJECTION' | 'VIEWINVERSE' | 'EDITOR_TRANSFORM' | 'MODELVIEWPROJECTION';
 export interface MaterialBlendingStates {
     blending?: boolean;
@@ -63,6 +64,7 @@ export declare enum ShaderType {
  *
  */
 export interface Maskable {
+    item: VFXItem;
     drawStencilMask(maskRef: number): void;
 }
 /**

package/dist/math/shape/build-adaptive-bezier.d.ts

@@ -1 +1 @@
-export declare function buildAdaptiveBezier(points: number[], sX: number, sY: number, cp1x: number, cp1y: number, cp2x: number, cp2y: number, eX: number, eY: number, smoothness?: number): number[];
+export declare function buildAdaptiveBezier(points: number[], sX: number, sY: number, cp1x: number, cp1y: number, cp2x: number, cp2y: number, eX: number, eY: number, smoothness?: number, scale?: number): number[];

package/dist/math/shape/circle.d.ts

@@ -191,6 +191,6 @@ export declare class Circle extends ShapePrimitive {
      * @see {@link Circle.clone} For creating new circle copy
      */
     copyTo(circle: Circle): Circle;
-    build(points: number[]): void;
+    build(points: number[], screenScale?: number): void;
     triangulate(points: number[], vertices: number[], verticesOffset: number, indices: number[], indicesOffset: number): void;
 }

package/dist/math/shape/ellipse.d.ts

@@ -74,6 +74,6 @@ export declare class Ellipse extends ShapePrimitive {
     copyTo(ellipse: Ellipse): Ellipse;
     getX(): number;
     getY(): number;
-    build(points: number[]): number[];
+    build(points: number[], screenScale?: number): number[];
     triangulate(points: number[], vertices: number[], verticesOffset: number, indices: number[], indicesOffset: number): void;
 }

package/dist/math/shape/graphics-path.d.ts

@@ -23,7 +23,7 @@ export declare class GraphicsPath {
      * @param smoothness - Optional parameter to adjust the smoothness of the curve.
      * @returns The instance of the current object for chaining.
      */
-    bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number, smoothness?: number): GraphicsPath;
+    bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number, smoothness?: number, scale?: number): GraphicsPath;
     /**
      * Connects the current point to a new point with a straight line. This method updates the current path.
      * @param x - The x-coordinate of the new point to connect to.

package/dist/math/shape/poly-star.d.ts

@@ -35,7 +35,7 @@ export declare class PolyStar extends ShapePrimitive {
     clone(): ShapePrimitive;
     copyFrom(source: PolyStar): void;
     copyTo(destination: PolyStar): void;
-    build(points: number[]): void;
+    build(points: number[], screenScale?: number): void;
     triangulate(points: number[], vertices: number[], verticesOffset: number, indices: number[], indicesOffset: number): void;
     private buildStarPath;
     private buildPolygonPath;

package/dist/math/shape/polygon.d.ts

@@ -58,7 +58,7 @@ export declare class Polygon extends ShapePrimitive {
      * @readonly
      */
     getY(): number;
-    build(points: number[]): void;
+    build(points: number[], screenScale?: number): void;
     triangulate(points: number[], vertices: number[], verticesOffset: number, indices: number[], indicesOffset: number): void;
     /**
      * 获取直线上最远的两个端点坐标组成的三角形

package/dist/math/shape/rectangle.d.ts

@@ -57,6 +57,6 @@ export declare class Rectangle extends ShapePrimitive {
      * @returns Returns given parameter.
      */
     copyTo(rectangle: Rectangle): Rectangle;
-    build(points: number[]): void;
+    build(points: number[], screenScale?: number): void;
     triangulate(points: number[], vertices: number[], verticesOffset: number, indices: number[], indicesOffset: number): void;
 }

package/dist/math/shape/shape-path.d.ts

@@ -26,7 +26,7 @@ export declare class ShapePath {
      * @param smoothness - Optional parameter to adjust the smoothness of the curve.
      * @returns The instance of the current object for chaining.
      */
-    bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number, smoothness?: number): ShapePath;
+    bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number, smoothness?: number, scale?: number): ShapePath;
     moveTo(x: number, y: number): ShapePath;
     /**
      * Connects the current point to a new point with a straight line. This method updates the current path.

package/dist/math/shape/shape-primitive.d.ts

@@ -10,6 +10,6 @@ export declare abstract class ShapePrimitive {
     /** Returns the framing rectangle of the ShapePrimitive as a Rectangle object. */
     /** The X coordinate of the shape */
     /** The Y coordinate of the shape */
-    abstract build(points: number[]): void;
+    abstract build(points: number[], screenScale?: number): void;
     abstract triangulate(points: number[], vertices: number[], verticesOffset: number, indices: number[], indicesOffset: number): void;
 }

package/dist/math/shape/triangle.d.ts

@@ -84,6 +84,6 @@ export declare class Triangle extends ShapePrimitive {
     getBounds(out?: Rectangle): Rectangle;
     getX(): number;
     getY(): number;
-    build(points: number[]): void;
+    build(points: number[], screenScale?: number): void;
     triangulate(points: number[], vertices: number[], verticesOffset: number, indices: number[], indicesOffset: number): void;
 }

package/dist/plugins/interact/click-handler.d.ts

@@ -3,6 +3,7 @@ import { Vector2 } from '@galacean/effects-math/es/core/vector2';
 import type * as spec from '@galacean/effects-specification';
 import type { VFXItem } from '../../vfx-item';
 import type { Composition } from '../../composition';
+import type { Maskable } from '../../material';
 export declare enum HitTestType {
     triangle = 1,
     box = 2,
@@ -28,23 +29,27 @@ export interface HitTestTriangleParams {
     type: HitTestType.triangle;
     triangles: TriangleLike[];
     backfaceCulling?: boolean;
+    clipMasks: Maskable[];
     behavior?: spec.InteractBehavior;
 }
 export interface HitTestBoxParams {
     type: HitTestType.box;
     center: Vector3;
     size: Vector3;
+    clipMasks: Maskable[];
     behavior?: spec.InteractBehavior;
 }
 export interface HitTestSphereParams {
     type: HitTestType.sphere;
     center: Vector3;
     radius: number;
+    clipMasks: Maskable[];
     behavior?: spec.InteractBehavior;
 }
 export interface HitTestCustomParams {
     type: HitTestType.custom;
     collect(ray: Ray, pointInCanvas: Vector2): Vector3[] | void;
+    clipMasks: Maskable[];
     behavior?: spec.InteractBehavior;
 }
 export type Region = {

package/dist/plugins/text/text-component-base.d.ts

@@ -10,6 +10,9 @@ import type { TextStyle } from './text-style';
  */
 export interface IRichTextComponent {
 }
+/**
+ * 文本组件基础类，包含文本组件和富文本组件的共有逻辑
+ */
 export declare class TextComponentBase {
     textStyle: TextStyle;
     textLayout: BaseLayout;
@@ -23,20 +26,67 @@ export declare class TextComponentBase {
     renderer: ItemRenderer;
     protected maxLineWidth: number;
     protected readonly ALPHA_FIX_VALUE: number;
+    /**
+     * 设置文本内容
+     * @param value - 文本内容
+     */
     setText(value: string): void;
+    /**
+     * 设置文本水平布局
+     * @param value - 布局选项
+     */
     setTextAlign(value: spec.TextAlignment): void;
+    /**
+     * 设置文本垂直布局
+     * @param value - 布局选项
+     */
     setTextVerticalAlign(value: spec.TextVerticalAlign): void;
     /**
      * @deprecated 2.8.0 本方法已废弃，请使用 setTextVerticalAlign 替代。
      */
     setTextBaseline(value: spec.TextBaseline): void;
+    /**
+     * 设置文本颜色
+     * @param value - 颜色内容
+     * @default [1, 1, 1, 1]
+     */
     setTextColor(value: spec.RGBAColorValue): void;
+    /**
+     * 设置字体
+     * @param value - 字体名称，如："Arial", "Times New Roman" 等
+     * @default "sans-serif"
+     */
     setFontFamily(value: string): void;
+    /**
+     * 设置字重
+     * @param value - 字重类型
+     */
     setFontWeight(value: spec.TextWeight): void;
+    /**
+     * 设置字体样式
+     * @param value - 字体样式
+     * @default "normal"
+     */
     setFontStyle(value: spec.FontStyle): void;
+    /**
+     * 设置外描边文本颜色
+     * @param value - 颜色内容
+     */
     setOutlineColor(value: spec.RGBAColorValue): void;
+    /**
+     * 设置是否启用外描边
+     * @param value - 是否启用外描边
+     */
     setOutlineEnabled(value: boolean): void;
+    /**
+     * 设置字体清晰度
+     * @param value - 字体清晰度
+     */
     setFontScale(value: number): void;
+    /**
+     * 设置文本溢出方式
+     * @param overflow - 溢出方式
+     */
     setOverflow(overflow: spec.TextOverflow): void;
     protected getFontDesc(size?: number): string;
     protected setupOutline(): void;

package/dist/plugins/text/text-item.d.ts

@@ -41,6 +41,11 @@ export declare class TextComponent extends MaskableGraphic {
      * 根据配置更新文本样式和布局
      */
     updateWithOptions(options: spec.TextContentOptions): void;
+    /**
+     * 获取文本行数
+     * @param text - 文本内容
+     * @returns 行数
+     */
     getLineCount(text: string): number;
     /**
      * 设置行高
@@ -48,46 +53,8 @@ export declare class TextComponent extends MaskableGraphic {
      * @param value - 行高像素值
      */
     setLineHeight(value: number): void;
-    /**
-     * 设置字重
-     * @param value - 字重类型
-     * @returns
-     */
-    setFontWeight(value: spec.TextWeight): void;
-    /**
-     * 设置字体样式
-     * @param value 设置字体样式
-     * @default "normal"
-     * @returns
-     */
-    setFontStyle(value: spec.FontStyle): void;
-    /**
-     * 设置文本水平布局
-     * @param value - 布局选项
-     * @returns
-     */
-    setTextAlign(value: spec.TextAlignment): void;
-    /**
-     * 设置文本颜色
-     * @param value - 颜色内容
-     * @returns
-     */
-    setTextColor(value: spec.RGBAColorValue): void;
-    /**
-     * 设置外描边文本颜色
-     * @param value - 颜色内容
-     * @returns
-     */
-    setOutlineColor(value: spec.RGBAColorValue): void;
-    /**
-     * 设置字体清晰度
-     * @param value - 字体清晰度
-     * @returns
-     */
-    setFontScale(value: number): void;
     /**
      * 更新文本
-     * @returns
      */
     protected updateTexture(flipY?: boolean): void;
     renderText(options: spec.TextContentOptions): void;
@@ -119,24 +86,54 @@ export declare class TextComponent extends MaskableGraphic {
      * @param value - 文本框高度
      */
     setTextHeight(value: number): void;
+    /**
+     * 设置字体大小
+     * @param value - 字体大小
+     * @default 40
+     */
     setFontSize(value: number): void;
+    /**
+     * 设置描边宽度
+     * @param value - 描边宽度
+     * @default 0
+     */
     setOutlineWidth(value: number): void;
     /**
      * 设置是否启用文本描边
      * @param value - 是否启用描边
-     * @returns
      */
     setOutlineEnabled(value: boolean): void;
+    /**
+     * 设置阴影模糊度
+     * @param value - 阴影模糊度
+     * @default 0
+     */
     setShadowBlur(value: number): void;
+    /**
+     * 设置阴影颜色
+     * > setupShadow 使用 outlineColor 作为阴影颜色，更新 shadowColor 不影响阴影颜色
+     * @param value - 阴影颜色
+     * @returns
+     */
     setShadowColor(value: spec.RGBAColorValue): void;
+    /**
+     * 设置阴影偏移 X
+     * @param value - 阴影偏移值
+     * @returns
+     */
     setShadowOffsetX(value: number): void;
+    /**
+     * 设置阴影偏移 Y
+     * @param value - 阴影偏移值
+     * @returns
+     */
     setShadowOffsetY(value: number): void;
     /**
      * 计算文本在当前样式与布局规则下的建议宽度（逻辑像素）。
      *
      * 说明：
      * - 使用 Canvas 2D 的 measureText，并按当前实现的逐字符排版规则累加宽度（与 updateTexture 保持一致）。
-     * - 结果为"逻辑宽度"（已除去 fontScale，并扣除 fontOffset），可直接写回 options.textWidth。
+     * - 结果为"逻辑宽度"（扣除 fontOffset），可直接写回 options.textWidth。，可直接写回 options.textWidth。
      * - 通过 padding 追加少量冗余像素，用于降低边缘裁切风险。
      *
      * @returns 文本宽度（>= 0）

package/dist/plugins/timeline/playable.d.ts

@@ -56,5 +56,6 @@ export interface FrameContext {
 }
 export declare enum PlayState {
     Playing = 0,
-    Paused = 1
+    Paused = 1,
+    Stopped = 2
 }

package/dist/plugins/timeline/timeline-asset.d.ts

@@ -14,12 +14,9 @@ export declare class TimelineAsset extends EffectsObject {
     private addSubTracksRecursive;
 }
 export declare class TimelineInstance {
-    private time;
     private clips;
     constructor(timelineAsset: TimelineAsset, sceneBindings: SceneBinding[]);
-    setTime(time: number): void;
-    getTime(): number;
-    evaluate(deltaTime: number): void;
+    evaluate(time: number, deltaTime: number): void;
     compileTracks(tracks: TrackAsset[], sceneBindings: SceneBinding[]): void;
     private tickTrack;
     private updateTrackAnimatedObject;

package/dist/precompositions/index.d.ts

@@ -0,0 +1,2 @@
+export * from './precomposition';
+export * from './precomposition-manager';

package/dist/precompositions/precomposition-manager.d.ts

@@ -0,0 +1,13 @@
+import type { Composition } from '../composition';
+import { VFXItem } from '../vfx-item';
+import type { Precomposition } from './precomposition';
+export declare class PrecompositionManager {
+    /**
+     * 从预合成数据实例化一棵 VFXItem 树。
+     * 可挂载到现有合成的节点下。
+     * @param precomposition 预合成数据
+     * @param composition 目标合成
+     * @returns 实例化生成的根 VFXItem，其子树包含指定合成的所有元素
+     */
+    static instantiate(precomposition: Precomposition, composition: Composition): VFXItem;
+}

package/dist/precompositions/precomposition.d.ts

@@ -0,0 +1,7 @@
+import type { Scene, SceneLoadOptions } from '../scene';
+/**
+ * 预合成数据类，包含预合成 Json 数据和加载选项。
+ */
+export declare class Precomposition {
+    constructor(scene: Scene, options?: SceneLoadOptions);
+}

package/dist/scene-loader.d.ts

@@ -1,6 +1,9 @@
 import { Composition } from './composition';
 import type { Engine } from './engine';
 import type { Scene, SceneLoadOptions } from './scene';
+/**
+ * @hidden
+ */
 export declare class SceneLoader {
     static load(scene: Scene.LoadType, engine: Engine, options?: SceneLoadOptions): Promise<Composition>;
     private static createComposition;

package/dist/scene.d.ts

@@ -12,7 +12,6 @@ export interface Scene {
     readonly storage: Record<string, any>;
     renderLevel?: SceneRenderLevel;
     textureOptions: Record<string, any>[];
-    textures: Texture[];
     images: ImageLike[];
     assets: Record<string, ImageLike>;
     consumed?: boolean;
@@ -80,7 +79,6 @@ export interface SceneLoadOptions {
     /**
      * 渲染分级。
      * 分级之后，只会加载当前渲染等级的资源。
-     * 当渲染等级被设置为 B 后，player 的 fps 会降到 30 帧
      * @default 'S'
      */
     renderLevel?: SceneRenderLevel;

package/dist/vfx-item.d.ts

@@ -1,11 +1,12 @@
+import type { Ray } from '@galacean/effects-math/es/core/ray';
 import { Vector3 } from '@galacean/effects-math/es/core/vector3';
 import * as spec from '@galacean/effects-specification';
 import type { Component } from './components';
-import { Composition } from './composition';
+import type { Composition, CompositionHitTestOptions } from './composition';
 import { EffectsObject } from './effects-object';
 import type { Engine } from './engine';
 import type { EventEmitterListener, EventEmitterOptions, ItemEvent } from './events';
-import type { BoundingBoxData, HitTestBoxParams, HitTestCustomParams, HitTestSphereParams, HitTestTriangleParams } from './plugins';
+import type { BoundingBoxData, HitTestBoxParams, HitTestCustomParams, HitTestSphereParams, HitTestTriangleParams, Region } from './plugins';
 import { Transform } from './transform';
 import type { Constructor, Disposable } from './utils';
 /**
@@ -49,10 +50,18 @@ export declare class VFXItem extends EffectsObject implements Disposable {
      * @deprecated 2.7.0 Please use `getInstanceId` instead
      */
     id: string;
+    /**
+     * 元素类型
+     */
     type: spec.ItemType;
+    /**
+     * @deprecated 2.9.0 Please use `definition` instead
+     */
     props: spec.VFXItemData;
+    /**
+     * 元素绑定的组件列表
+     */
     components: Component[];
-    isDuringPlay: boolean;
     /**
      * 元素是否激活
      */
@@ -64,9 +73,6 @@ export declare class VFXItem extends EffectsObject implements Disposable {
     private listIndex;
     private isEnabled;
     private eventProcessor;
-    /**
-     * 合成属性
-     */
     private _composition;
     /**
      *
@@ -127,6 +133,7 @@ export declare class VFXItem extends EffectsObject implements Disposable {
     set composition(value: Composition);
     /**
      * 播放完成后是否需要再使用，是的话生命周期结束后不会 dispose
+     * @deprecated
      */
     get compositionReusable(): boolean;
     /**
@@ -269,6 +276,19 @@ export declare class VFXItem extends EffectsObject implements Disposable {
      * @param force - 元素没有开启交互也返回参数
      */
     getHitTestParams(force?: boolean): void | HitTestBoxParams | HitTestTriangleParams | HitTestSphereParams | HitTestCustomParams;
+    /**
+     * 对当前元素及其子节点进行射线命中测试
+     *
+     * @param ray - 射线
+     * @param x - 归一化屏幕坐标 x
+     * @param y - 归一化屏幕坐标 y
+     * @param regions - 命中结果收集数组
+     * @param hitPositions - 共享的命中位置数组，所有 region 共享同一引用
+     * @param force - 是否强制测试无交互信息的元素
+     * @param options - 额外选项（maxCount、stop、skip）
+     * @returns 是否有任何命中
+     */
+    hitTest(ray: Ray, x: number, y: number, regions: Region[], hitPositions: Vector3[], force?: boolean, options?: CompositionHitTestOptions): boolean;
     /**
      * 获取元素当前世界坐标
      */
@@ -280,6 +300,7 @@ export declare class VFXItem extends EffectsObject implements Disposable {
      * @returns 复制的新 VFXItem
      */
     duplicate(): VFXItem;
+    private onParentChanged;
     fromData(data: spec.VFXItemData): void;
     toData(): void;
     /**
@@ -287,8 +308,6 @@ export declare class VFXItem extends EffectsObject implements Disposable {
      */
     dispose(): void;
     private resetChildrenParent;
-    private instantiatePreComposition;
-    private resetGUID;
     private gatherPreviousObjectID;
     private getDescendantsInternal;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@galacean/effects-core",
-  "version": "2.9.0-alpha.0",
+  "version": "2.9.0-alpha.2",
   "description": "Galacean Effects runtime core for the web",
   "module": "./dist/index.mjs",
   "main": "./dist/index.js",
@@ -42,7 +42,7 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@galacean/effects-specification": "2.7.2",
+    "@galacean/effects-specification": "2.8.0-alpha.0",
     "@galacean/effects-math": "1.1.0",
     "flatbuffers": "24.3.25",
     "uuid": "9.0.1",