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

package/dist/material/mask-ref-manager.d.ts

@@ -1,16 +1 @@
-import type { Engine } from '../engine';
-import type * as spec from '@galacean/effects-specification';
-import type { Maskable } from './types';
-import { MaskMode } from './types';
-import type { Renderer } from '../render/renderer';
-export declare class MaskProcessor {
-    engine: Engine;
-    alphaMaskEnabled: boolean;
-    maskMode: MaskMode;
-    maskable: Maskable | null;
-    private stencilClearAction;
-    constructor(engine: Engine);
-    getRefValue(): number;
-    setMaskOptions(data: spec.MaskOptions): void;
-    drawStencilMask(renderer: Renderer): void;
-}
+export {};

package/dist/material/types.d.ts

@@ -2,7 +2,6 @@ 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 { Renderer } from '../render';
 export type UniformSemantic = 'VIEW' | 'MODEL' | 'MODELVIEW' | 'PROJECTION' | 'VIEWPROJECTION' | 'VIEWINVERSE' | 'EDITOR_TRANSFORM' | 'MODELVIEWPROJECTION';
 export interface MaterialBlendingStates {
     blending?: boolean;
@@ -64,7 +63,20 @@ export declare enum ShaderType {
  *
  */
 export interface Maskable {
-    drawStencilMask(renderer: Renderer): void;
+    drawStencilMask(maskRef: number): void;
+}
+/**
+ * 蒙版引用信息，支持正面和反面蒙版
+ */
+export interface MaskReference {
+    /**
+     * 蒙版对象
+     */
+    maskable: Maskable;
+    /**
+     * 是否反向蒙版（true: 反向遮挡，false: 正向遮挡）
+     */
+    inverted: boolean;
 }
 export declare enum MaskMode {
     /**

package/dist/math/index.d.ts

@@ -2,3 +2,9 @@ export * from './float16array-wrapper';
 export * from './translate';
 export * from './utils';
 export * from './value-getters';
+export * from './shape/build-line';
+export * from './shape/graphics-path';
+export * from './shape/ellipse';
+export * from './shape/poly-star';
+export * from './shape/polygon';
+export * from './shape/shape-path';

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

@@ -0,0 +1,196 @@
+import { Rectangle } from './rectangle';
+import { ShapePrimitive } from './shape-primitive';
+/**
+ * The Circle object represents a circle shape in a two-dimensional coordinate system.
+ * Used for drawing graphics and specifying hit areas for containers.
+ * @example
+ * ```ts
+ * // Basic circle creation
+ * const circle = new Circle(100, 100, 50);
+ *
+ * // Use as hit area
+ * container.hitArea = new Circle(0, 0, 100);
+ *
+ * // Check point containment
+ * const isInside = circle.contains(mouseX, mouseY);
+ *
+ * // Get bounding box
+ * const bounds = circle.getBounds();
+ * ```
+ * @remarks
+ * - Defined by center (x,y) and radius
+ * - Supports point containment tests
+ * - Can check stroke intersections
+ * @see {@link Rectangle} For rectangular shapes
+ * @standard
+ */
+export declare class Circle extends ShapePrimitive {
+    /**
+     * The X coordinate of the center of this circle
+     * @example
+     * ```ts
+     * // Basic x position
+     * const circle = new Circle();
+     * circle.x = 100;
+     *
+     * // Center circle on point
+     * circle.x = point.x;
+     * ```
+     * @default 0
+     */
+    x: number;
+    /**
+     * The Y coordinate of the center of this circle
+     * @example
+     * ```ts
+     * // Basic y position
+     * const circle = new Circle();
+     * circle.y = 200;
+     *
+     * // Center circle on point
+     * circle.y = point.y;
+     * ```
+     * @default 0
+     */
+    y: number;
+    /**
+     * The radius of the circle
+     * @example
+     * ```ts
+     * // Basic radius setting
+     * const circle = new Circle(100, 100);
+     * circle.radius = 50;
+     *
+     * // Calculate area
+     * const area = Math.PI * circle.radius * circle.radius;
+     * ```
+     * @default 0
+     */
+    radius: number;
+    /**
+     * @param x - The X coordinate of the center of this circle
+     * @param y - The Y coordinate of the center of this circle
+     * @param radius - The radius of the circle
+     */
+    constructor(x?: number, y?: number, radius?: number);
+    /**
+     * Creates a clone of this Circle instance.
+     * @example
+     * ```ts
+     * // Basic circle cloning
+     * const original = new Circle(100, 100, 50);
+     * const copy = original.clone();
+     *
+     * // Clone and modify
+     * const modified = original.clone();
+     * modified.radius = 75;
+     *
+     * // Verify independence
+     * console.log(original.radius); // 50
+     * console.log(modified.radius); // 75
+     * ```
+     * @returns A copy of the Circle
+     * @see {@link Circle.copyFrom} For copying into existing circle
+     * @see {@link Circle.copyTo} For copying to another circle
+     */
+    clone(): Circle;
+    /**
+     * Checks whether the x and y coordinates given are contained within this circle.
+     *
+     * Uses the distance formula to determine if a point is inside the circle's radius.
+     *
+     * Commonly used for hit testing in PixiJS events and graphics.
+     * @example
+     * ```ts
+     * // Basic containment check
+     * const circle = new Circle(100, 100, 50);
+     * const isInside = circle.contains(120, 120);
+     *
+     * // Check mouse position
+     * const circle = new Circle(0, 0, 100);
+     * container.hitArea = circle;
+     * container.on('pointermove', (e) => {
+     *     // only called if pointer is within circle
+     * });
+     * ```
+     * @param x - The X coordinate of the point to test
+     * @param y - The Y coordinate of the point to test
+     * @returns Whether the x/y coordinates are within this Circle
+     * @see {@link Circle.strokeContains} For checking stroke intersection
+     * @see {@link Circle.getBounds} For getting bounding box
+     */
+    contains(x: number, y: number): boolean;
+    /**
+     * Checks whether the x and y coordinates given are contained within this circle including the stroke.
+     * @example
+     * ```ts
+     * // Basic stroke check
+     * const circle = new Circle(100, 100, 50);
+     * const isOnStroke = circle.strokeContains(150, 100, 4); // 4px line width
+     *
+     * // Check with different alignments
+     * const innerStroke = circle.strokeContains(150, 100, 4, 1);   // Inside
+     * const centerStroke = circle.strokeContains(150, 100, 4, 0.5); // Centered
+     * const outerStroke = circle.strokeContains(150, 100, 4, 0);   // Outside
+     * ```
+     * @param x - The X coordinate of the point to test
+     * @param y - The Y coordinate of the point to test
+     * @param width - The width of the line to check
+     * @param alignment - The alignment of the stroke, 0.5 by default
+     * @returns Whether the x/y coordinates are within this Circle's stroke
+     * @see {@link Circle.contains} For checking fill containment
+     * @see {@link Circle.getBounds} For getting stroke bounds
+     */
+    strokeContains(x: number, y: number, width: number, alignment?: number): boolean;
+    /**
+     * Returns the framing rectangle of the circle as a Rectangle object.
+     * @example
+     * ```ts
+     * // Basic bounds calculation
+     * const circle = new Circle(100, 100, 50);
+     * const bounds = circle.getBounds();
+     * // bounds: x=50, y=50, width=100, height=100
+     *
+     * // Reuse existing rectangle
+     * const rect = new Rectangle();
+     * circle.getBounds(rect);
+     * ```
+     * @param out - Optional Rectangle object to store the result
+     * @returns The framing rectangle
+     * @see {@link Rectangle} For rectangle properties
+     * @see {@link Circle.contains} For point containment
+     */
+    getBounds(out?: Rectangle): Rectangle;
+    /**
+     * Copies another circle to this one.
+     * @example
+     * ```ts
+     * // Basic copying
+     * const source = new Circle(100, 100, 50);
+     * const target = new Circle();
+     * target.copyFrom(source);
+     * ```
+     * @param circle - The circle to copy from
+     * @returns Returns itself
+     * @see {@link Circle.copyTo} For copying to another circle
+     * @see {@link Circle.clone} For creating new circle copy
+     */
+    copyFrom(circle: Circle): this;
+    /**
+     * Copies this circle to another one.
+     * @example
+     * ```ts
+     * // Basic copying
+     * const source = new Circle(100, 100, 50);
+     * const target = new Circle();
+     * source.copyTo(target);
+     * ```
+     * @param circle - The circle to copy to
+     * @returns Returns given parameter
+     * @see {@link Circle.copyFrom} For copying from another circle
+     * @see {@link Circle.clone} For creating new circle copy
+     */
+    copyTo(circle: Circle): Circle;
+    build(points: number[]): void;
+    triangulate(points: number[], vertices: number[], verticesOffset: number, indices: number[], indicesOffset: number): void;
+}

package/dist/{plugins → math}/shape/graphics-path.d.ts

@@ -24,6 +24,13 @@ export declare class GraphicsPath {
      * @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;
+    /**
+     * 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.
+     * @param y - The y-coordinate of the new point to connect to.
+     * @returns The instance of the current object for chaining.
+     */
+    lineTo(x: number, y: number): GraphicsPath;
     /**
      * Sets the starting point for a new sub-path. Any subsequent drawing commands are considered part of this path.
      * @param x - The x-coordinate for the starting point.
@@ -48,6 +55,15 @@ export declare class GraphicsPath {
      * @returns The instance of the current object for chaining.
      */
     ellipse(x: number, y: number, radiusX: number, radiusY: number, transform?: Matrix4): this;
+    /**
+     * Draws a circle shape. This method adds a new circle path to the current drawing.
+     * @param x - The x-coordinate of the center of the circle.
+     * @param y - The y-coordinate of the center of the circle.
+     * @param radius - The radius of the circle.
+     * @param transform - An optional `Matrix` object to apply a transformation to the circle.
+     * @returns The instance of the current object for chaining.
+     */
+    circle(x: number, y: number, radius: number, transform?: Matrix4): this;
     /**
      * Draws a rectangle shape. This method adds a new rectangle path to the current drawing.
      * @param x - The x-coordinate of the upper-left corner of the rectangle.
@@ -58,10 +74,22 @@ export declare class GraphicsPath {
      * @returns The instance of the current object for chaining.
      */
     rect(x: number, y: number, w: number, h: number, roundness: number, transform?: Matrix4): this;
+    /**
+     * Draws a triangle shape. This method adds a new triangle path to the current drawing.
+     * @param x1 - The x-coordinate of the first vertex of the triangle.
+     * @param y1 - The y-coordinate of the first vertex of the triangle.
+     * @param x2 - The x-coordinate of the second vertex of the triangle.
+     * @param y2 - The y-coordinate of the second vertex of the triangle.
+     * @param x3 - The x-coordinate of the third vertex of the triangle.
+     * @param y3 - The y-coordinate of the third vertex of the triangle.
+     * @param transform - An optional `Matrix` object to apply a transformation to the triangle.
+     * @returns The instance of the current object for chaining.
+     */
+    triangle(x1: number, y1: number, x2: number, y2: number, x3: number, y3: number, transform?: Matrix4): this;
     polyStar(pointCount: number, outerRadius: number, innerRadius: number, outerRoundness: number, innerRoundness: number, starType: StarType, transform?: Matrix4): this;
     clear(): GraphicsPath;
 }
 export interface PathInstruction {
-    action: 'moveTo' | 'lineTo' | 'quadraticCurveTo' | 'bezierCurveTo' | 'arc' | 'closePath' | 'addPath' | 'arcTo' | 'ellipse' | 'rect' | 'roundRect' | 'arcToSvg' | 'poly' | 'circle' | 'regularPoly' | 'roundPoly' | 'roundShape' | 'filletRect' | 'chamferRect' | 'polyStar';
+    action: 'moveTo' | 'lineTo' | 'quadraticCurveTo' | 'bezierCurveTo' | 'arc' | 'closePath' | 'addPath' | 'arcTo' | 'ellipse' | 'rect' | 'roundRect' | 'arcToSvg' | 'poly' | 'circle' | 'regularPoly' | 'roundPoly' | 'roundShape' | 'filletRect' | 'chamferRect' | 'polyStar' | 'triangle';
     data: any[];
 }

package/dist/{plugins → math}/shape/shape-path.d.ts

@@ -28,6 +28,13 @@ export declare class ShapePath {
      */
     bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number, smoothness?: 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.
+     * @param x - The x-coordinate of the new point to connect to.
+     * @param y - The y-coordinate of the new point to connect to.
+     * @returns The instance of the current object for chaining.
+     */
+    lineTo(x: number, y: number): this;
     /**
      * Closes the current path by drawing a straight line back to the start.
      * If the shape is already closed or there are no points in the path, this method does nothing.
@@ -45,6 +52,15 @@ export declare class ShapePath {
      * @returns The instance of the current object for chaining.
      */
     ellipse(x: number, y: number, radiusX: number, radiusY: number, transform?: Matrix4): this;
+    /**
+     * Draws a circle shape. This method adds a new circle path to the current drawing.
+     * @param x - The x-coordinate of the center of the circle.
+     * @param y - The y-coordinate of the center of the circle.
+     * @param radius - The radius of the circle.
+     * @param transform - An optional `Matrix` object to apply a transformation to the circle.
+     * @returns The instance of the current object for chaining.
+     */
+    circle(x: number, y: number, radius: number, transform?: Matrix4): this;
     polyStar(pointCount: number, outerRadius: number, innerRadius: number, outerRoundness: number, innerRoundness: number, starType: StarType, transform?: Matrix4): this;
     /**
      * Draws a rectangle shape. This method adds a new rectangle path to the current drawing.
@@ -56,6 +72,18 @@ export declare class ShapePath {
      * @returns The instance of the current object for chaining.
      */
     rect(x: number, y: number, w: number, h: number, roundness: number, transform?: Matrix4): this;
+    /**
+     * Draws a triangle shape. This method adds a new triangle path to the current drawing.
+     * @param x1 - The x-coordinate of the first vertex of the triangle.
+     * @param y1 - The y-coordinate of the first vertex of the triangle.
+     * @param x2 - The x-coordinate of the second vertex of the triangle.
+     * @param y2 - The y-coordinate of the second vertex of the triangle.
+     * @param x3 - The x-coordinate of the third vertex of the triangle.
+     * @param y3 - The y-coordinate of the third vertex of the triangle.
+     * @param transform - An optional `Matrix` object to apply a transformation to the triangle.
+     * @returns The instance of the current object for chaining.
+     */
+    triangle(x1: number, y1: number, x2: number, y2: number, x3: number, y3: number, transform?: Matrix4): this;
     /**
      * Draws a given shape on the canvas.
      * This is a generic method that can draw any type of shape specified by the `ShapePrimitive` parameter.

package/dist/math/utils.d.ts

@@ -1,4 +1,5 @@
 import type { vec2, vec3, vec4 } from '@galacean/effects-specification';
+import type { Vector2 } from '@galacean/effects-math/es/core/vector2';
 import { Vector3 } from '@galacean/effects-math/es/core/vector3';
 import { Ray } from '@galacean/effects-math/es/core/ray';
 import type { TriangleLike } from '@galacean/effects-math/es/core/type';
@@ -13,3 +14,22 @@ export declare function setRayFromCamera(x: number, y: number, camera: Camera):
 export declare function trianglesFromRect(position: Vector3, halfWidth: number, halfHeight: number): TriangleLike[];
 export declare function decimalEqual(a: number, b: number, epsilon?: number): boolean;
 export declare function numberToFix(a: number, fixed?: number): number;
+/**
+ * 最小最大值结果
+ */
+export interface MinMaxResult {
+    /** 最小值向量 */
+    minimum: Vector3;
+    /** 最大值向量 */
+    maximum: Vector3;
+}
+/**
+ * 从位置数组中提取最小和最大值
+ * @param positions - 位置数据数组
+ * @param start - 起始索引
+ * @param count - 要处理的顶点数量
+ * @param bias - 可选的偏移值
+ * @param stride - 步长（默认为 3，即 x, y, z）
+ * @returns 包含 minimum 和 maximum Vector3 的对象
+ */
+export declare function extractMinAndMax(positions: number[] | Float32Array, start: number, count: number, bias?: Vector2 | null, stride?: number): MinMaxResult;

package/dist/plugins/animation-graph/graph-context.d.ts

@@ -1,3 +1,4 @@
+import type { AnimationEventReference } from '../../animation';
 import type { GraphDataSet } from './graph-data-set';
 import type { GraphNode, GraphNodeData } from './graph-node';
 import type { Skeleton } from './skeleton';
@@ -10,6 +11,7 @@ export declare class GraphContext {
     updateID: number;
     skeleton: Skeleton;
     branchState: BranchState;
+    activeEvents: AnimationEventReference[];
     update(deltaTime: number): void;
 }
 export declare class InstantiationContext {

package/dist/plugins/animation-graph/graph-instance.d.ts

@@ -1,3 +1,4 @@
+import type { AnimationEventReference } from '../../animation';
 import type { VFXItem } from '../../vfx-item';
 import type { AnimationGraphAsset } from './animation-graph-asset';
 import type { GraphNode, PoseNodeDebugInfo } from './graph-node';
@@ -8,6 +9,7 @@ export declare class GraphInstance {
     private graphAsset;
     nodes: GraphNode[];
     skeleton: Skeleton;
+    activeEvents: AnimationEventReference[];
     private rootNode;
     private context;
     private result;

package/dist/plugins/animation-graph/nodes/animation-clip-node.d.ts

@@ -16,6 +16,7 @@ export declare class AnimationClipNode extends PoseNode {
     animation: AnimationClip | null;
     private animatable;
     evaluate(context: GraphContext, result: PoseResult): PoseResult;
+    private sampleEvents;
     protected initializeInternal(context: GraphContext): void;
 }
 declare enum TransformCurveType {

package/dist/plugins/index.d.ts

@@ -15,12 +15,6 @@ export * from './particle/particle-mesh';
 export * from './particle/particle-vfx-item';
 export * from './particle/particle-system';
 export * from './particle/particle-system-renderer';
-export * from './shape/build-line';
-export * from './shape/graphics-path';
-export * from './shape/ellipse';
-export * from './shape/poly-star';
-export * from './shape/polygon';
-export * from './shape/shape-path';
 export * from './timeline';
 export * from './text';
 export * from './animation-graph';

package/dist/plugins/interact/mesh-collider.d.ts

@@ -1,15 +1,38 @@
 import { Matrix4 } from '@galacean/effects-math/es/core/matrix4';
+import { Vector3 } from '@galacean/effects-math/es/core/vector3';
 import type { Geometry } from '../../render/geometry';
 import type { BoundingBoxTriangle } from './click-handler';
+import type { Vector2 } from '@galacean/effects-math/es/core';
+import { BoundingBox } from '../../culling/bounding-box';
 /**
- *
+ * 包围盒信息
  */
-export declare class MeshCollider {
-    private boundingBoxData;
+export declare class BoundingBoxInfo {
+    /**
+     * 包围盒
+     */
+    readonly boundingBox: BoundingBox;
     private triangles;
+    private boundingBoxTriangle;
     private worldMatrix;
-    getBoundingBoxData(): BoundingBoxTriangle;
-    getBoundingBox(): BoundingBoxTriangle;
+    /**
+     * 重新构建包围盒信息
+     * @param min - 新的最小点（局部空间）
+     * @param max - 新的最大点（局部空间）
+     * @param worldMatrix - 新的世界矩阵
+     */
+    reConstruct(min: Vector3, max: Vector3, worldMatrix?: Matrix4): void;
+    /**
+     * @deprecated
+     */
+    getRawBoundingBoxTriangle(): BoundingBoxTriangle;
+    /**
+     * @deprecated
+     */
+    getBoundingBoxTriangle(size?: Vector2): BoundingBoxTriangle;
+    /**
+     * @deprecated
+     */
     setGeometry(geometry: Geometry, worldMatrix?: Matrix4): void;
     private geometryToTriangles;
     private assemblyTriangles;

package/dist/plugins/particle/particle-system-renderer.d.ts

@@ -7,14 +7,12 @@ import { ParticleMesh } from './particle-mesh';
 import type { Mesh, Renderer } from '../../render';
 import type { Engine } from '../../engine';
 import { RendererComponent } from '../../components';
-import type { MaskProcessor } from '../../material/mask-ref-manager';
 /**
  * @since 2.0.0
  */
 export declare class ParticleSystemRenderer extends RendererComponent {
     meshes: Mesh[];
     particleMesh: ParticleMesh;
-    maskManager: MaskProcessor;
     private trailMesh?;
     constructor(engine: Engine, particleMeshProps?: ParticleMeshProps, trailMeshProps?: TrailMeshProps);
     onStart(): void;

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

@@ -5,7 +5,7 @@ import * as spec from '@galacean/effects-specification';
 import { Component } from '../../components';
 import type { Engine } from '../../engine';
 import type { ValueGetter } from '../../math';
-import type { Mesh, Renderer } from '../../render';
+import type { Mesh } from '../../render';
 import type { Maskable } from '../../material';
 import { MaskProcessor } from '../../material';
 import type { ShapeGenerator, ShapeParticle } from '../../shape';
@@ -184,8 +184,9 @@ export declare class ParticleSystem extends Component implements Maskable {
     reset(): void;
     onStart(): void;
     onUpdate(dt: number): void;
-    update(delta: number): void;
-    drawStencilMask(renderer: Renderer): void;
+    simulate(time: number): void;
+    private update;
+    drawStencilMask(maskRef: number): void;
     onDestroy(): void;
     getParticleBoxes(): {
         center: Vector3;

package/dist/plugins/particle/particle-vfx-item.d.ts

@@ -5,9 +5,8 @@ import { ParticleSystem } from './particle-system';
  * @since 2.0.0
  */
 export declare class ParticleBehaviourPlayable extends Playable {
-    lastTime: number;
-    particleSystem: ParticleSystem;
-    start(context: FrameContext): void;
+    private particleSystem;
+    getParticleSystem(context: FrameContext): ParticleSystem | null;
     processFrame(context: FrameContext): void;
 }
 export declare class ParticleBehaviourPlayableAsset extends PlayableAsset {

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

@@ -5,23 +5,10 @@ import type { ItemRenderer } from '../../components';
 import type { VFXItem } from '../../vfx-item';
 import type { BaseLayout } from './base-layout';
 import type { TextStyle } from './text-style';
-/**
- * 纯文本组件特有 API
- */
-export interface ITextComponent {
-    setOutlineWidth(value: number): void;
-    setOutlineEnabled(value: boolean): void;
-    setShadowBlur(value: number): void;
-    setShadowColor(value: spec.RGBAColorValue): void;
-    setShadowOffsetX(value: number): void;
-    setShadowOffsetY(value: number): void;
-    setAutoWidth(value: boolean): void;
-    setFontSize(value: number): void;
-}
 /**
  * 富文本组件特有 API
  */
-export interface IRichTextComponent extends ITextComponent {
+export interface IRichTextComponent {
 }
 export declare class TextComponentBase {
     textStyle: TextStyle;
@@ -34,7 +21,6 @@ export declare class TextComponentBase {
     material: Material;
     item: VFXItem;
     renderer: ItemRenderer;
-    lineCount: number;
     protected maxLineWidth: number;
     protected readonly ALPHA_FIX_VALUE: number;
     setText(value: string): void;

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

@@ -3,15 +3,15 @@ import { MaskableGraphic } from '../../components';
 import type { Engine } from '../../engine';
 import { TextLayout } from './text-layout';
 import { TextStyle } from './text-style';
-import type { ITextComponent } from './text-component-base';
 import { TextComponentBase } from './text-component-base';
+import type { Renderer } from '../../render/renderer';
 export declare const DEFAULT_FONTS: string[];
 export interface TextComponent extends TextComponentBase {
 }
 /**
  * @since 2.0.0
  */
-export declare class TextComponent extends MaskableGraphic implements ITextComponent {
+export declare class TextComponent extends MaskableGraphic {
     isDirty: boolean;
     /**
      * 文本行数
@@ -31,21 +31,12 @@ export declare class TextComponent extends MaskableGraphic implements ITextCompo
      * 每一行文本的最大宽度
      */
     protected maxLineWidth: number;
-    /**
-     * 初始文本宽度，用于计算缩放比例
-     */
-    private baseTextWidth;
-    /**
-     * 初始 `transform.size.x`，用于按比例更新显示宽度
-     */
-    private baseScaleX;
-    private getDefaultProps;
     constructor(engine: Engine);
     onUpdate(dt: number): void;
+    render(renderer: Renderer): void;
     onDestroy(): void;
     fromData(data: spec.TextComponentData): void;
     private resetState;
-    setText(value: string): void;
     /**
      * 根据配置更新文本样式和布局
      */
@@ -115,7 +106,7 @@ export declare class TextComponent extends MaskableGraphic implements ITextCompo
         padT: number;
         padB: number;
     };
-    setAutoWidth(value: boolean): void;
+    setAutoResize(value: spec.TextSizeMode): void;
     /**
      * 设置文本框宽度
      * 手动设置宽度时会自动关闭 `autoWidth`
@@ -140,4 +131,16 @@ export declare class TextComponent extends MaskableGraphic implements ITextCompo
     setShadowColor(value: spec.RGBAColorValue): void;
     setShadowOffsetX(value: number): void;
     setShadowOffsetY(value: number): void;
+    /**
+     * 计算文本在当前样式与布局规则下的建议宽度（逻辑像素）。
+     *
+     * 说明：
+     * - 使用 Canvas 2D 的 measureText，并按当前实现的逐字符排版规则累加宽度（与 updateTexture 保持一致）。
+     * - 结果为"逻辑宽度"（已除去 fontScale，并扣除 fontOffset），可直接写回 options.textWidth。
+     * - 通过 padding 追加少量冗余像素，用于降低边缘裁切风险。
+     *
+     * @returns 文本宽度（>= 0）
+     */
+    getTextWidth(): number;
+    private getDefaultProps;
 }

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

@@ -8,15 +8,14 @@ export declare class TextLayout implements BaseLayout {
     overflow: spec.TextOverflow;
     width: number;
     height: number;
-    /**
-     * 自适应宽高开关
-     */
-    autoWidth: boolean;
-    maxTextWidth: number;
     /**
      * 行高
      */
     lineHeight: number;
+    /**
+     * 自动宽高模式
+     */
+    autoResize: spec.TextSizeMode;
     constructor(options: spec.TextContentOptions);
     update(options: spec.TextContentOptions): void;
     /**

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

@@ -16,7 +16,6 @@ export declare class TimelineAsset extends EffectsObject {
 export declare class TimelineInstance {
     private time;
     private clips;
-    private masterTrackInstances;
     constructor(timelineAsset: TimelineAsset, sceneBindings: SceneBinding[]);
     setTime(time: number): void;
     getTime(): number;