@galacean/effects-core 2.10.0-alpha.0 → 2.10.0-alpha.1

package/dist/material/types.d.ts

@@ -80,6 +80,10 @@ export interface MaskReference {
      */
     inverted: boolean;
 }
+/**
+ * @deprecated 2.10 起蒙版模式不再通过单一枚举表达，runtime 内部已不再使用此枚举。
+ * 仅为兼容旧版本对外导出的接口而保留，请改用 `MaskProcessor` 的多蒙版 API。
+ */
 export declare enum MaskMode {
     /**
      * 无

package/dist/material/utils.d.ts

@@ -5,4 +5,8 @@ export declare function valIfUndefined<T>(val: any, def: T): T;
 export declare function getPreMultiAlpha(blending?: spec.BlendingMode): number;
 export declare function setBlendMode(material: Material, blendMode?: number): void;
 export declare function setSideMode(material: Material, side: spec.SideMode): void;
+/**
+ * @deprecated 2.10 起 runtime 内部已不再通过 `MaskMode` 设置模板测试参数。
+ * 仅为兼容旧版本对外导出的接口而保留，新代码请勿使用。
+ */
 export declare function setMaskMode(material: Material, maskMode: MaskMode): void;

package/dist/math/value-getters/index.d.ts

@@ -3,3 +3,4 @@ export * from './color-curve';
 export * from './vector-curves';
 export * from './bezier-curve';
 export * from './value-getter-map';
+export * from './reference-curve';

package/dist/math/value-getters/reference-curve.d.ts

@@ -0,0 +1,19 @@
+import type { EffectsObject } from '../../effects-object';
+import { ValueGetter } from './value-getter';
+/**
+ * 对象引用曲线运行时数据：[time, value][]，value 为已解析的 EffectsObject 实例。
+ */
+export type ReferenceCurveData<T extends EffectsObject> = [time: number, value: T][];
+/**
+ * 通用对象引用阶梯曲线（不插值）。对象引用不可插值，
+ * 按时间阶梯采样取 time ≤ t 的最近关键帧。
+ *
+ * 继承 ValueGetter 以复用 PropertyClipPlayable<T>；数值相关方法
+ * （toUniform/toData/getIntegrate*）保留基类 NOT_IMPLEMENT——对象引用 curve
+ * 不走 shader 通路。典型用例：T = Sprite（sprite 属性 K 帧切图）。
+ */
+export declare class ReferenceCurve<T extends EffectsObject> extends ValueGetter<T> {
+    private keyframes;
+    onCreate(props: ReferenceCurveData<T>): void;
+    getValue(time?: number): T;
+}

package/dist/math/value-getters/value-getter-map.d.ts

@@ -1,2 +1,7 @@
 import { ValueGetter } from './value-getter';
+/**
+ * 对象引用阶梯曲线（spec ValueType.REFERENCE_CURVE）。
+ * props 为 [[time, value], ...]，value 为已解析的对象引用实例。
+ */
+export declare const REFERENCE_CURVE = 28;
 export declare function createValueGetter(args: any): ValueGetter<any>;

package/dist/plugin-system.d.ts

@@ -17,9 +17,11 @@ export declare function registerPlugin(name: string, pluginClass: PluginConstruc
 export declare function unregisterPlugin(name: string): void;
 export declare class PluginSystem {
     static getPlugins(): Plugin[];
-    static initializeComposition(composition: Composition, scene?: Scene): void;
-    static destroyComposition(comp: Composition): void;
-    static onAssetsLoadStart(scene: Scene, options?: SceneLoadOptions): Promise<void[]>;
-    static onAssetsLoadFinish(scene: Scene, options: SceneLoadOptions, engine: Engine): void;
+    static notifyCompositionCreated(composition: Composition, scene?: Scene): void;
+    static notifyCompositionDestroy(composition: Composition): void;
+    static notifyEngineCreated(engine: Engine): void;
+    static notifyEngineDestroy(engine: Engine): void;
+    static notifyAssetsLoadStart(scene: Scene, options?: SceneLoadOptions): Promise<void[]>;
+    static notifyAssetsLoadFinish(scene: Scene, options: SceneLoadOptions, engine: Engine): void;
 }
 export declare function getPluginUsageInfo(name: string): string;

package/dist/plugins/index.d.ts

@@ -9,6 +9,7 @@ export * from './interact/interact-vfx-item';
 export * from './interact/interact-item';
 export * from './interact/mesh-collider';
 export * from './sprite/sprite-loader';
+export * from './sprite/sprite';
 export * from './sprite/sprite-item';
 export * from './particle/particle-loader';
 export * from './particle/particle-mesh';

package/dist/plugins/particle/particle-mesh.d.ts

@@ -63,8 +63,6 @@ export interface ParticleMeshData {
 export interface ParticleMeshProps extends ParticleMeshData {
     renderMode?: number;
     blending?: number;
-    mask: number;
-    maskMode: number;
     side: number;
     transparentOcclusion?: boolean;
     matrix?: Matrix4;

package/dist/plugins/particle/trail-mesh.d.ts

@@ -21,9 +21,7 @@ export type TrailMeshProps = {
     occlusion: boolean;
     transparentOcclusion: boolean;
     lifetime: ValueGetter<number>;
-    mask: number;
     shaderCachePrefix: string;
-    maskMode: number;
     name: string;
 };
 export type TrailPointOptions = {

package/dist/plugins/plugin.d.ts

@@ -38,4 +38,18 @@ export declare abstract class Plugin {
      * @param composition - 合成对象
      */
     onCompositionDestroy(composition: Composition): void;
+    /**
+     * 引擎创建完成后触发。
+     * 适用于注册引擎级单例、建立以引擎为键的映射、绑定全局监听等场景。
+     * @param engine - 引擎实例
+     * @since 2.10.0
+     */
+    onEngineCreated(engine: Engine): void;
+    /**
+     * 引擎销毁时触发。
+     * 适合解绑监听、释放引擎级资源或清理以引擎为键的映射。
+     * @param engine - 引擎实例
+     * @since 2.10.0
+     */
+    onEngineDestroy(engine: Engine): void;
 }

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

@@ -5,6 +5,7 @@ import type { FrameContext } from '../timeline';
 import { Playable, PlayableAsset, TrackMixerPlayable, TrackAsset } from '../timeline';
 import type { Geometry } from '../../render';
 import { MaskableGraphic } from '../../components';
+import type { Sprite } from './sprite';
 /**
  * 图层元素基础属性, 经过处理后的 spec.SpriteContent.options
  */
@@ -12,7 +13,14 @@ export type SpriteItemOptions = {
     startColor: spec.vec4;
     renderLevel?: spec.RenderLevel;
 };
-export type splitsDataType = [r: number, x: number, y: number, w: number, h: number | undefined][];
+/**
+ * SpriteComponent 数据。扩展 spec.SpriteComponentData，新增可选 sprite 资产引用。
+ * spec 包不可改，故本地扩展。
+ */
+interface SpriteComponentDataEx extends spec.SpriteComponentData {
+    /** 引用的 Sprite 资产（新版数据流）；老数据经 version37Migration 迁移而来 */
+    sprite?: spec.DataPath;
+}
 export declare class SpriteColorPlayableAsset extends PlayableAsset {
     data: ColorPlayableAssetData;
     createPlayable(): Playable;
@@ -40,15 +48,33 @@ export declare class SpriteComponent extends MaskableGraphic {
     time: number;
     duration: number;
     protected textureSheetAnimation?: spec.TextureSheetAnimation;
-    constructor(engine: Engine, props?: spec.SpriteComponentData);
+    /**
+     * 引用的 Sprite 资产（纹理 + 归一化 UV 矩形 + rotation），渲染唯一数据源。
+     */
+    protected _sprite: Sprite;
+    /**
+     * 当前 Sprite 资产。设置时同步纹理、重绑 _MainTex 并重建几何体 UV。
+     * @since 2.10.0
+     */
+    get sprite(): Sprite;
+    set sprite(sprite: Sprite);
+    constructor(engine: Engine, props?: SpriteComponentDataEx);
     onUpdate(dt: number): void;
     onDisable(): void;
     onDestroy(): void;
     protected updateGeometry(geometry: Geometry): void;
+    fromData(data: SpriteComponentDataEx): void;
+    /**
+     * 应用 Sprite 资产到渲染器：同步纹理并重绑 _MainTex。不重建几何体。
+     * fromData（后续自行 updateGeometry）与 sprite setter（随后 updateGeometry）共用。
+     * 直接写 _sprite，避免经 setter 触发 updateGeometry。
+     */
+    protected applySpriteToRenderer(sprite: Sprite): void;
     /**
      * @deprecated
-     * 原有打包纹理拆分逻辑，待移除
+     * 原有打包纹理拆分逻辑，仅在老数据 splits.length>1（2x2 纹理打包）时使用，保留向后兼容。
+     * 不依赖组件状态，splits 由参数传入（同时存在帧动画与多 split 的数据不存在）。
      */
-    protected updateGeometryFromMultiSplit(): void;
-    fromData(data: spec.SpriteComponentData): void;
+    protected updateGeometryFromMultiSplit(splits: spec.SplitParameter[]): void;
 }
+export {};

package/dist/plugins/sprite/sprite.d.ts

@@ -0,0 +1,42 @@
+import type * as spec from '@galacean/effects-specification';
+import { EffectsObject } from '../../effects-object';
+import type { Engine } from '../../engine';
+import type { Texture } from '../../texture';
+/**
+ * Sprite UV 旋转方式。序列化为整数（兼容老 splits 的 flip 0/1）。
+ * None 不旋转、Rotate90 将 UV 顺时针旋转 90°（width/height 互换）。
+ */
+export declare enum SpriteRotation {
+    /** 不旋转 */
+    None = 0,
+    /** UV 旋转 90°（对应老 splits flip=1） */
+    Rotate90 = 1
+}
+/**
+ * Sprite 资产数据
+ */
+export interface SpriteData extends spec.EffectsObjectData {
+    /** 关联纹理（DataPath 引用） */
+    texture?: spec.DataPath;
+    /** 归一化 UV 矩形 [x, y, w, h]，默认整张纹理 */
+    rect?: spec.vec4;
+    /** UV 旋转方式（0=None, 1=Rotate90），对齐老 splits 的 flip 语义 */
+    rotation?: SpriteRotation;
+}
+/**
+ * Sprite 资产：一张纹理 + 一个归一化 UV 矩形区域（不含 border/pivot）。
+ * 被 SpriteComponent 引用，替代直接引用 Texture + 散落的 splits。
+ *
+ * 反序列化全部集中在 fromData 手动解析（与 SpriteComponent 风格一致），
+ * 不使用 @serialize 装饰器，避免序列化/反序列化双路径带来的引用覆盖陷阱。
+ */
+export declare class Sprite extends EffectsObject {
+    /** 关联的纹理对象 */
+    texture: Texture;
+    /** 归一化 UV 矩形 [x, y, w, h]，默认整张纹理 */
+    rect: spec.vec4;
+    /** UV 旋转方式（对应老 splits 的 flip 0/1） */
+    rotation: SpriteRotation;
+    constructor(engine: Engine, props?: SpriteData);
+    fromData(data: SpriteData): void;
+}

package/dist/plugins/text/index.d.ts

@@ -1,4 +1,5 @@
 export * from './base-layout';
+export * from './line-break';
 export * from './text-item';
 export * from './text-layout';
 export * from './text-style';

package/dist/plugins/text/line-break.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 文本换行机会判定：UAX #14 风格的"换行机会"模型。
+ *
+ * - CJK 表意字 / 假名 / 韩文音节：任意两个字之间都是合法断点（字符级）
+ * - 空格 / 制表符 / NBSP：可断，且断行时被吞掉（不留在行尾 / 行首）
+ * - 西文字母 / 数字：词内不可断；整体超宽时由调用方退化到字符级断（overflow-wrap）
+ *
+ * 不含 kinsoku 禁则（句号 / 逗号不进行首等留作后续）。
+ */
+/** 换行机会类型（断点字符之后）：决定断点字符归属及断行时是否吞掉 */
+export type BreakAfter = 'swallow' | 'keep' | false;
+/**
+ * 是否为可换行断点字符（空格 / 制表符 / NBSP）。
+ * 断在此字符之前，且断行时该字符被吞掉（不进旧行也不进新行）。
+ * @param ch - 当前字符
+ */
+export declare function isBreakChar(ch: string): boolean;
+/**
+ * 是否为 CJK 类字符（中文表意字 / 假名 / 韩文音节）。可在其与相邻字符之间换行。
+ * 用码点判定以支持 CJK 扩展 B 等代理对字符（不能用 /u 正则，browserslist 为 iOS 9）。
+ * @param ch - 当前字符（须为完整码点，调用方应使用 Array.from 遍历）
+ */
+export declare function isCJKLike(ch: string): boolean;
+/**
+ * 计算 prev（已推入的字符）之后是否为换行机会。只看 prev，不看后续字符。
+ * @param prev - 前一字符（已推入旧行）
+ * @returns 'swallow'=prev 是空格类，断行时吞掉 prev；'keep'=prev 是 CJK，prev 留本行末、下行从其后起；false=不可断
+ */
+export declare function breakOpportunityAfter(prev: string): BreakAfter;

package/dist/plugins/timeline/playable-assets/index.d.ts

@@ -1,5 +1,6 @@
 export * from './activation-playable-asset';
 export * from './color-property-playable-asset';
 export * from './float-property-playable-asset';
+export * from './sprite-property-playable-asset';
 export * from './sub-composition-playable-asset';
 export * from './vector-property-playable-assets';

package/dist/plugins/timeline/playable-assets/sprite-property-playable-asset.d.ts

@@ -0,0 +1,23 @@
+import type * as spec from '@galacean/effects-specification';
+import type { Playable } from '../playable';
+import { PlayableAsset } from '../playable';
+import type { ReferenceCurveData } from '../../../math';
+import type { Sprite } from '../../sprite/sprite';
+/**
+ * 对象引用曲线序列化值：[REFERENCE_CURVE, [time, DataPath][]]，value 为 {id} 引用。
+ * 序列化形态，无泛型。
+ * TODO: update to spec.
+ */
+export type ReferenceCurveValue = [number, [number, spec.DataPath][]];
+export interface SpritePropertyAssetData extends spec.EffectsObjectData {
+    curveData: ReferenceCurveValue;
+}
+/**
+ * Sprite 属性 K 帧 PlayableAsset：curveData 为对象引用阶梯曲线，
+ * createPlayable 复用 PropertyClipPlayable<Sprite> + ReferenceCurve（阶梯采样，不插值）。
+ */
+export declare class SpritePropertyPlayableAsset extends PlayableAsset {
+    curveData: [number, ReferenceCurveData<Sprite>];
+    fromData(data: SpritePropertyAssetData): void;
+    createPlayable(): Playable;
+}

package/dist/plugins/timeline/playables/index.d.ts

@@ -5,6 +5,7 @@ export * from './float-property-mixer-playable';
 export * from './particle-mixer-playable';
 export * from './property-clip-playable';
 export * from './sprite-color-mixer-playable';
+export * from './sprite-property-mixer-playable';
 export * from './sub-composition-clip-playable';
 export * from './sub-composition-mixer-playable';
 export * from './track-mixer-playable';

package/dist/plugins/timeline/playables/sprite-property-mixer-playable.d.ts

@@ -0,0 +1,11 @@
+import type { FrameContext } from '../playable';
+import { TrackMixerPlayable } from './track-mixer-playable';
+/**
+ * Sprite 属性 K 帧 mixer。对象引用不混合：取首个激活 clip 的阶梯采样值，
+ * 赋值 boundObject.sprite 触发 setter（同步纹理 + 重建 UV）。
+ * 不继承 PropertyMixerPlayable（其 evaluate 开头"读当前值为 null 则 return"
+ * 会阻断无初始 sprite 组件的 K 帧）。
+ */
+export declare class SpritePropertyMixerPlayable extends TrackMixerPlayable {
+    evaluate(context: FrameContext): void;
+}

package/dist/plugins/timeline/playables/transform-mixer-playable.d.ts

@@ -1,5 +1,11 @@
 import type { FrameContext } from '../playable';
 import { TrackMixerPlayable } from './track-mixer-playable';
+/**
+ * TransformTrack 的 mixer。
+ * 收集当前激活的 Transform clip contribution，并委托 TransformClipMixer 合成当前帧输出。
+ */
 export declare class TransformMixerPlayable extends TrackMixerPlayable {
+    private readonly clipMixer;
+    dispose(): void;
     evaluate(context: FrameContext): void;
 }

package/dist/plugins/timeline/playables/transform-playable.d.ts

@@ -13,6 +13,14 @@ export type ItemBasicTransform = {
     scale: Vector3;
     path?: ValueGetter<Vector3>;
 };
+export type TransformContribution = {
+    hasPosition: boolean;
+    position: Vector3;
+    hasRotation: boolean;
+    rotation: Euler;
+    hasScale: boolean;
+    scale: Vector3;
+};
 /**
  * @since 2.0.0
  */
@@ -45,15 +53,22 @@ export declare class TransformPlayable extends Playable {
     gravity: Vector3;
     direction: Vector3;
     startSpeed: number;
+    pathGetter?: ValueGetter<Vector3>;
     data: TransformPlayableAssetData;
     private velocity;
-    private boundObject;
+    private started;
+    private readonly contribution;
     start(): void;
     processFrame(context: FrameContext): void;
     /**
-     * 应用时间轴K帧数据到对象
+     * 采样当前帧相对 base pose 的 transform contribution。
+     * 返回值为内部复用对象，调用方应在当前帧同步消费，不应缓存。
+     * @param basePosition - orbital position 计算 contribution 时使用的参考位置。
      */
+    getContribution(basePosition?: Vector3): TransformContribution;
+    private ensureStarted;
     private sampleAnimation;
+    private captureOriginalTransform;
 }
 export declare class TransformPlayableAsset extends PlayableAsset {
     transformAnimationData: TransformPlayableAssetData;

package/dist/plugins/timeline/tracks/index.d.ts

@@ -8,4 +8,5 @@ export * from './particle-track';
 export * from './property-track';
 export * from './vector-property-track';
 export * from './color-property-track';
+export * from './sprite-property-track';
 export * from './object-binding-track';

package/dist/plugins/timeline/tracks/sprite-property-track.d.ts

@@ -0,0 +1,11 @@
+import type { TrackMixerPlayable } from '../playables';
+import { PropertyTrack } from './property-track';
+/**
+ * Sprite 属性 K 帧 track。绑定到 SpriteComponent（updateAnimatedObject），
+ * mixer 取激活 clip 的 Sprite 采样值赋值 sprite 属性。
+ * path（'sprite'）为编辑器元数据，mixer 直接写 boundObject.sprite。
+ */
+export declare class SpritePropertyTrack extends PropertyTrack {
+    createTrackMixer(): TrackMixerPlayable;
+    updateAnimatedObject(boundObject: object): object;
+}

package/dist/plugins/timeline/transform-clip-mixer.d.ts

@@ -0,0 +1,33 @@
+import { Vector3 } from '@galacean/effects-math/es/core/vector3';
+import type { VFXItem } from '../../vfx-item';
+import type { TransformContribution } from './playables/transform-playable';
+/**
+ * 对 TransformTrack 当前激活的 Transform clip contribution 做帧内合成。
+ * position 与 rotation 使用增量语义，scale 使用乘子语义；结果由 flush 统一写回。
+ */
+export declare class TransformClipMixer {
+    private basePose?;
+    private boundInstanceId?;
+    private hasContribution;
+    private hasPosition;
+    private hasRotation;
+    private hasScale;
+    private appliedPosition;
+    private appliedRotation;
+    private appliedScale;
+    private readonly outPos;
+    private readonly outRot;
+    private readonly outScale;
+    private readonly weightedRot;
+    captureBasePose(item: VFXItem): void;
+    /**
+     * orbital position 的 contribution 依赖 base position。
+     * 这里返回 mixer 持有的 base，确保采样和合成使用同一份参考姿态。
+     */
+    getBasePosition(): Vector3 | undefined;
+    resetFrame(): void;
+    addContribution(item: VFXItem, contribution: TransformContribution, weight: number): void;
+    flush(item: VFXItem): void;
+    dispose(): void;
+    private ensureBasePose;
+}

package/dist/render/graphics.d.ts

@@ -174,8 +174,8 @@ export declare class Graphics {
      * `color` 作为乘色与白色字形 alpha 相乘，任意颜色都不会污染 atlas。
      *
      * 字体参数全部展开，避免调用方每帧创建临时 style 对象触发 GC
-     * @param x - 文本左下角 X 坐标
-     * @param y - 文本左下角 Y 坐标（对齐 baseline 上方 ascent 处）
+     * @param x - 文本左下角 X 坐标（首字 ink 起始处，含 padding 的 quad 会向左延伸）
+     * @param y - 文本左下角 Y 坐标（cell 底，含底部 padding；字形 ink 在其上方 padding+ascent 处）
      * @param text - 要绘制的文本内容，空串直接 return
      * @param fontSize - 字号（逻辑像素）
      * @param color - 乘色，默认白色，范围 0-1

package/dist/render/text-cache.d.ts

@@ -21,20 +21,24 @@ export declare const ATLAS_SIZE = 512;
 /**
  * 单个字形在 atlas 中的位置 / 度量。
  *
- * `px/py/pw/ph` 是 atlas canvas 像素（scale 后）。
- * `width` 是逻辑像素宽度（= pw / FONT_SCALE），用于 quad 宽 + cursor advance
+ * `px/py/pw/ph` 是 atlas canvas 像素（scale 后，含四周 padding）。
+ * `advance` 是逻辑像素光标前进量（1x，不含 padding）— quad 宽度含 padding，
+ * 但相邻字只按 advance 前进，padding 区透明因此重叠无妨。
+ * `paddingLeft` 是逻辑像素左侧留白（1x），quad 起点左偏此量使字形 ink 落在 cursorX
  */
 export type GlyphInfo = {
     px: number;
     py: number;
     pw: number;
     ph: number;
-    width: number;
+    advance: number;
+    paddingLeft: number;
 };
 /**
  * 一种字体（family + weight + style + size 唯一确定）对应一张 atlas。
  *
- * Skyline 风格 packer：行内堆字，行尾换行，行高 = (ascent+descent) * FONT_SCALE。
+ * Skyline 风格 packer：行内堆字，行尾换行，cell 高 = ceil((fontHeight + padding*2) * 1)，
+ * 所有字共用同一 cell 高与 baseline，实现同行 baseline 对齐。
  * atlas 满后 `ensureChar` 返回 null，调用方应跳过该字（不再扩页，v1 范围）。
  *
  * canvas 内容变更后需要 `uploadIfDirty` 重新上传到纹理 — 由调用方在使用纹理前主动触发，
@@ -47,18 +51,18 @@ export declare class GlyphAtlas {
     readonly canvas: HTMLCanvasElement;
     /** 与 canvas 绑定的纹理，内容变更后通过 updateSource 重传 */
     readonly texture: Texture;
-    /** 行高（逻辑像素，= ascent + descent），所有字共享 */
+    /** cell 高（逻辑像素，含 padding），用于 quad 高度 */
     readonly lineHeight: number;
-    /** 行 ascent（逻辑像素，baseline 距行顶距离） */
-    readonly ascent: number;
-    /** 行 descent（逻辑像素，baseline 距行底距离） */
-    readonly descent: number;
     private readonly ctx;
     private readonly glyphs;
-    /** 行高（像素，scale 后） */
-    private readonly lineHeightPx;
-    /** baseline 距行顶距离（像素，scale 后） */
-    private readonly ascentPx;
+    /** baseline 距 cell 顶距离（像素，scale 后，含顶部 padding） */
+    private readonly baselinePx;
+    /** cell 高（像素，scale 后，含 padding） */
+    private readonly cellHPx;
+    /** 四周留白（像素，scale 后） */
+    private readonly paddingPx;
+    /** italic 字形 cell 宽额外放大倍数（防斜体越界重叠） */
+    private readonly italicScale;
     /** packer 状态：下一字开始的左上角像素位置 */
     private currentX;
     private currentY;
@@ -66,7 +70,11 @@ export declare class GlyphAtlas {
     private full;
     /** 自上次 upload 以来 canvas 是否有新字写入 */
     private dirty;
-    constructor(engine: Engine, scaledFontString: string, ascent: number, descent: number);
+    constructor(engine: Engine, scaledFontString: string, 
+    /** baseline 距 cell 顶距离（像素，scale 后，仅 ascent 部分，不含 padding） */
+    ascentPx: number, 
+    /** baseline 距 cell 底距离（像素，scale 后，仅 descent 部分） */
+    descentPx: number, fontStyle: FontStyle);
     /**
      * 取（必要时渲染并打包）单字。返回 GlyphInfo 或 null（atlas 已满）
      */

package/dist/scene.d.ts

@@ -67,13 +67,16 @@ export interface SceneLoadOptions {
      */
     variables?: spec.TemplateVariables;
     /**
-     * 是否使用压缩纹理
-     * @default undefined
+     * 是否优先使用压缩纹理
+     * 当资源存在且当前环境支持时使用，否则回退到普通图片
+     * 需要注册 KTX2 loader，例如 import '@galacean/effects-plugin-ktx2'
+     * @default true
      */
     useCompressedTexture?: boolean;
     /**
-     * 是否使用 Hevc 视频
-     * @default undefined
+     * 是否优先使用 Hevc 视频
+     * 当资源存在且当前环境支持时使用，否则回退到普通视频
+     * @default true
      */
     useHevcVideo?: boolean;
     /**

package/dist/utils/index.d.ts

@@ -29,7 +29,7 @@ export interface Disposable {
     dispose(): void;
 }
 export interface RestoreHandler {
-    restore(): void;
+    restore(): void | Promise<void>;
 }
 export interface LostHandler {
     lost(e: Event): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@galacean/effects-core",
-  "version": "2.10.0-alpha.0",
+  "version": "2.10.0-alpha.1",
   "description": "Galacean Effects runtime core for the web",
   "module": "./dist/index.mjs",
   "main": "./dist/index.js",
@@ -43,7 +43,7 @@
   },
   "dependencies": {
     "@galacean/effects-specification": "^2.8.1",
-    "@galacean/effects-math": "1.1.0",
+    "@galacean/effects-math": "1.2.0",
     "flatbuffers": "24.3.25",
     "uuid": "9.0.1",
     "libtess": "1.2.2"