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

package/dist/math/index.d.ts

@@ -3,9 +3,10 @@ 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/rectangle';
+export * from './shape/triangle';
 export * from './shape/poly-star';
+export * from './shape/circle';
 export * from './shape/polygon';
-export * from './shape/shape-path';
 export * from './bezier';

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, scale?: 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, tValues?: number[]): number[];

package/dist/plugins/index.d.ts

@@ -17,4 +17,5 @@ export * from './particle/particle-system';
 export * from './particle/particle-system-renderer';
 export * from './timeline';
 export * from './text';
+export * from './shape';
 export * from './animation-graph';

package/dist/plugins/shape/contour-measure.d.ts

@@ -0,0 +1,43 @@
+import { Vector2 } from '@galacean/effects-math/es/core/vector2';
+import type { GraphicsPath } from './graphics-path';
+export type ContourMeasureSegmentType = 'line' | 'cubic';
+export type ContourMeasureSegment = {
+    distance: number;
+    pointIndex: number;
+    tValue: number;
+    type: ContourMeasureSegmentType;
+    smoothness?: number;
+    scale?: number;
+};
+export type ContourMeasurePosTan = {
+    pos: Vector2;
+    tan: Vector2;
+};
+export declare class ContourMeasure {
+    private readonly segments;
+    private readonly points;
+    private readonly contourLength;
+    private readonly contourClosed;
+    constructor(segments: ContourMeasureSegment[], points: Vector2[], contourLength: number, contourClosed: boolean);
+    length(): number;
+    isClosed(): boolean;
+    getPosTan(distance: number): ContourMeasurePosTan;
+    getSegment(startDistance: number, endDistance: number, destination: GraphicsPath, startWithMove: boolean): void;
+    warp(source: Vector2): Vector2;
+    dump(): void;
+    private findSegment;
+    private computeT;
+    private extractWholeSegment;
+    private extractSegment;
+}
+export declare class ContourMeasureIter {
+    static readonly defaultTolerance = 0.5;
+    private contourPath;
+    private cursor;
+    private screenScale;
+    constructor(source: GraphicsPath, screenScale?: number);
+    rewind(source: GraphicsPath, screenScale?: number): void;
+    private tryNext;
+    next(): ContourMeasure | null;
+    toArray(): ContourMeasure[];
+}

package/dist/plugins/shape/contour-path-utils.d.ts

@@ -0,0 +1,10 @@
+import { Vector2 } from '@galacean/effects-math/es/core/vector2';
+export declare function clampNumber(value: number, min: number, max: number): number;
+export declare function lerpNumber(start: number, end: number, t: number): number;
+export declare function pointsEqual(left: Vector2, right: Vector2): boolean;
+export declare function clonePoint(point: Vector2): Vector2;
+export declare function normalizeVector2(x: number, y: number): Vector2;
+export declare function cubicPointAt(points: readonly Vector2[], t: number): Vector2;
+export declare function lineExtract(points: readonly Vector2[], startT: number, endT: number): [Vector2, Vector2];
+export declare function cubicSubdivide(points: readonly Vector2[], t: number): [Vector2[], Vector2[]];
+export declare function cubicExtract(points: readonly Vector2[], startT: number, endT: number): Vector2[];

package/dist/plugins/shape/contour-path.d.ts

@@ -0,0 +1,20 @@
+import { Vector2 } from '@galacean/effects-math/es/core/vector2';
+import type { GraphicsPath } from './graphics-path';
+import type { ShapePath } from './shape-path';
+export type ContourPathCommand = {
+    action: 'moveTo';
+    data: [Vector2];
+} | {
+    action: 'lineTo';
+    data: [Vector2];
+} | {
+    action: 'bezierCurveTo';
+    data: [Vector2, Vector2, Vector2];
+    smoothness?: number;
+    scale?: number;
+} | {
+    action: 'closePath';
+    data: [];
+};
+export declare function tryMakeContourPathFromGraphicsPath(source: GraphicsPath): ContourPathCommand[] | null;
+export declare function makeContourPathFromShapePath(shapePath: ShapePath, screenScale: number): ContourPathCommand[];

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

@@ -1,6 +1,6 @@
 import type { Matrix4 } from '@galacean/effects-math/es/core/matrix4';
 import { ShapePath } from './shape-path';
-import type { StarType } from './poly-star';
+import type { StarType } from '../../math';
 export declare class GraphicsPath {
     instructions: PathInstruction[];
     private dirty;

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

@@ -0,0 +1,2 @@
+export * from './shape-component';
+export * from './trim-path';

package/dist/{components → plugins/shape}/shape-component.d.ts

@@ -1,13 +1,15 @@
 import { Color } from '@galacean/effects-math/es/core/color';
 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, BoundingBoxInfo } from '../plugins';
-import type { Renderer } from '../render';
-import type { GradientValue } from '../math';
-import { RendererComponent } from './renderer-component';
-import type { Texture } from '../texture/texture';
+import type { Engine } from '../../engine';
+import type { Maskable } from '../../material';
+import type { Renderer } from '../../render';
+import type { GradientValue } from '../../math';
+import { RendererComponent } from '../../components';
+import type { Texture } from '../../texture/texture';
+import { TrimPath } from './trim-path';
+import type { BoundingBoxInfo } from '../interact/mesh-collider';
+import type { BoundingBoxTriangle, HitTestTriangleParams } from '../interact/click-handler';
 export interface SolidPaint {
     type: spec.FillType.Solid;
     color: Color;
@@ -134,11 +136,15 @@ export declare class ShapeComponent extends RendererComponent implements Maskabl
     private strokeJoin;
     private strokes;
     private shapeAttributes;
+    private _strokeTrimPath;
+    private _fillTrimPath;
     private rendererOptions;
     private geometry;
     private fillMaterials;
     private strokeMaterials;
     get shape(): ShapeAttributes;
+    get strokeTrimPath(): TrimPath | null;
+    get fillTrimPath(): TrimPath | null;
     /**
      *
      * @param engine

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

@@ -1,8 +1,8 @@
 import type { Matrix4 } from '@galacean/effects-math/es/core/matrix4';
-import { Polygon } from './polygon';
 import type { GraphicsPath } from './graphics-path';
-import type { ShapePrimitive } from './shape-primitive';
-import type { StarType } from './poly-star';
+import type { ShapePrimitive } from '../../math/shape/shape-primitive';
+import type { StarType } from '../../math';
+import { Polygon } from '../../math';
 export declare class ShapePath {
     private graphicsPath;
     currentPoly: Polygon | null;

package/dist/plugins/shape/trim-path.d.ts

@@ -0,0 +1,25 @@
+import { GraphicsPath } from './graphics-path';
+export interface TrimPathData {
+    start: number;
+    end: number;
+    offset: number;
+    mode: TrimPathMode;
+}
+export declare enum TrimPathMode {
+    Synchronized = 0,
+    Sequential = 1
+}
+export declare class TrimPath {
+    start: number;
+    end: number;
+    offset: number;
+    mode: TrimPathMode;
+    private trimmedGraphicsPath;
+    clone(): TrimPath;
+    createTrimmedPath(source: GraphicsPath, screenScale: number): GraphicsPath;
+    isIdentity(): boolean;
+    fromData(data: TrimPathData): void;
+    private normalizeTrimOffset;
+    private applySequentialTrimPath;
+    private applySynchronizedTrimPath;
+}

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

@@ -92,6 +92,7 @@ export declare class TextComponentBase {
     protected setupOutline(fontScale?: number): void;
     protected setupShadow(): void;
     protected disposeTextTexture(): void;
+    protected releaseTextCanvas(): void;
     /**
      * 通用纹理渲染辅助方法
      */

package/dist/rect-transform.d.ts

@@ -0,0 +1,145 @@
+import { Vector2 } from '@galacean/effects-math/es/core/vector2';
+import type * as spec from '@galacean/effects-specification';
+import { Transform } from './transform';
+/**
+ * 2D 矩形，`position` 为左下角（Y 向上），`size` 为宽高
+ */
+export type Rect = {
+    position: Vector2;
+    size: Vector2;
+};
+/**
+ * 16 个内建锚点预设，字面意义对应屏幕视觉位置（Y 向上）
+ */
+export type LayoutPreset = 'topLeft' | 'topRight' | 'bottomLeft' | 'bottomRight' | 'centerLeft' | 'centerTop' | 'centerRight' | 'centerBottom' | 'center' | 'leftWide' | 'topWide' | 'rightWide' | 'bottomWide' | 'vcenterWide' | 'hcenterWide' | 'fullRect';
+/**
+ * 锚点布局变换。`RectTransform extends Transform`，在 Transform 的 position/rotation/scale/size/anchor（=pivot 偏移）
+ * 之上额外维护 4 边锚点 + 4 边像素偏移，提供 rect 解算与编辑 API。
+ *
+ * 解算公式（Y 向上，父 vertex 坐标原点 = 父 rect 左下角）：
+ * ```
+ * left   = offsetMin.x + anchorMin.x * parentSize.x
+ * bottom = offsetMin.y + anchorMin.y * parentSize.y
+ * right  = offsetMax.x + anchorMax.x * parentSize.x
+ * top    = offsetMax.y + anchorMax.y * parentSize.y
+ * ```
+ *
+ * 写回 Transform：
+ * - `position` ← `(left, bottom)`（rect 左下角，父 vertex 坐标）
+ * - `size`     ← rect 尺寸
+ * - `anchor`（Vector3 像素 pivot 偏移）由用户独立设置，仅作旋转/缩放中心
+ *
+ * **解算入口** 是 `sizeChanged()` 方法：
+ * - 父是 RectTransform → 用 `parent.size` 作 parentSize 解算自身，写回 `position` / `size`
+ * - 否则（顶层 / 没父）：自身 size 视为权威值（由外部 — 通常是 CanvasLayer — 直接写），不再自解算
+ * - 末尾遍历 `children` 中的 RectTransform，直接调它们的 `sizeChanged()`，链式向下传播
+ *
+ * **重写 `setPosition` / `setSize`** 让其语义变为"用户输入 rect 位置 / 尺寸"：
+ * - 顶层（无 RectTransform 父）：直接写 `super.setPosition / super.setSize`，然后 `sizeChanged` 传播给子节点
+ * - 否则：反推 offset 维持当前 anchor，然后 `sizeChanged` 重算并向下传
+ */
+export declare class RectTransform extends Transform {
+    /**
+     * 父 rect 上的归一化最小角 `(anchorLeft, anchorBottom)`
+     */
+    readonly anchorMin: Vector2;
+    /**
+     * 父 rect 上的归一化最大角 `(anchorRight, anchorTop)`
+     */
+    readonly anchorMax: Vector2;
+    /**
+     * rect 左/下边相对 anchorMin 锚点的像素偏移 `(offsetLeft, offsetBottom)`
+     */
+    readonly offsetMin: Vector2;
+    /**
+     * rect 右/上边相对 anchorMax 锚点的像素偏移 `(offsetRight, offsetTop)`
+     */
+    readonly offsetMax: Vector2;
+    /**
+     * 自身 rect 上的归一化轴心 `(0..1)`，默认 `(0.5, 0.5)`(中心)。两层效果：
+     * 1. **Layout**：`setSize` 时 rect 围绕此点对称缩放（pivot=(0.5, 0.5) → 居中扩展；pivot=(0, 0) → 从左下扩展；pivot=(1, 1) → 向左下缩）
+     * 2. **矩阵**：`pivot` 自动同步到 `transform.anchor = pivot * size`（像素值，矩阵旋转/缩放中心），
+     *    所以旋转/缩放也围绕同一点。`setPivot` 和每次 `sizeChanged`（size 重算后）都会刷新 `transform.anchor`
+     */
+    readonly pivot: Vector2;
+    /**
+     * 用既有 Transform 的状态创建 RectTransform。
+     * 用于 Control / CanvasLayer 接管 VFXItem 时，把 VFXItem 自带的 Transform 升级为 RectTransform 而不丢失 position/rotation/scale 等已设置好的状态。
+     */
+    static fromTransform(t: Transform): RectTransform;
+    /**
+     * 反序列化：在 `Transform.fromData` 基础上还原 RectTransform 特有的 `pivot` /
+     * `anchorMin` / `anchorMax` / `offsetMin` / `offsetMax`。
+     *
+     * 顺序：
+     * 1. `super.fromData` 还原 `position` / `rotation` / `scale` / `size` / `anchor`
+     * 2. 若数据有 size，从 `anchor / size` 反推 `pivot`，保持 `anchor = pivot * size` 一致
+     * 3. 应用 `anchorMin/Max` / `offsetMin/Max`，每个 setter 末尾会触发 `sizeChanged`
+     *    重新解算 rect 与同步 `transform.anchor`
+     */
+    fromData(data: spec.TransformData): void;
+    setAnchorMin(x: number, y: number): void;
+    setAnchorMax(x: number, y: number): void;
+    setOffsetMin(x: number, y: number): void;
+    setOffsetMax(x: number, y: number): void;
+    /**
+     * 设置 rect 内的归一化轴心 `(0..1)`，同时把 `transform.anchor`（矩阵旋转/缩放中心）同步到 `pivot * size`。
+     * 不重算 rect（pivot 只决定 setSize 行为，不直接影响当前 rect 位置 / 尺寸）
+     */
+    setPivot(x: number, y: number): void;
+    /**
+     * 重写父类 `setPosition`：
+     * - 顶层（无 RectTransform 父）：直接 `super.setPosition` 写位置，触发 `sizeChanged` 传播
+     * - 非顶层：语义为"设置 rect 左下角到 (x, y)"，反推 offset 维持当前 anchor，然后 `sizeChanged` 重算
+     *
+     * @param keepOffsets - 默认 false。true 时反推 anchor 而非 offset（rect 在屏幕上不动，但 anchor 比例改变）
+     */
+    setPosition(x: number, y: number, z: number, keepOffsets?: boolean): void;
+    /**
+     * 重写父类 `setSize`：
+     * - 顶层：直接 `super.setSize`，触发 `sizeChanged` 传播
+     * - 非顶层：反推 offset 维持当前 anchor，然后 `sizeChanged` 重算
+     */
+    setSize(x: number, y: number): void;
+    /**
+     * 当前自身 rect（在父 vertex 坐标下，Y 向上）。`sizeChanged` 之后才有意义
+     */
+    getRect(): Rect;
+    private onCanvasResize;
+    /**
+     * 解算入口：
+     *
+     * 1. 父是 RectTransform → 从 `parent.size` 求自身 rect，通过 `super.setPosition / super.setSize` 写回
+     *    （避免触发本类 setPosition / setSize 重写）
+     * 2. 顶层（无 RectTransform 父）：自身 size 视为权威值（由 CanvasLayer 等外部直接写），不自解算
+     * 3. 遍历 `children` 中所有 RectTransform 子节点，直接调它们的 `sizeChanged()` 链式传播
+     */
+    sizeChanged(): void;
+    /**
+     * 给定目标 rect 反推 offsetMin/Max，保持当前 anchor 不变
+     */
+    private computeOffsets;
+    /**
+     * 给定目标 rect 反推 anchorMin/Max，保持当前 offset 不变。父 size 为 0 的方向不修改
+     */
+    private computeAnchors;
+    /**
+     * 把 anchorMin/Max 设为内建预设。
+     * @param keepOffsets - 默认 true：offset 不动，rect 实际位置会跳到新 anchor 计算的位置（要求保留视觉位置请用 setAnchorsAndOffsetsPreset）
+     */
+    setAnchorsPreset(preset: LayoutPreset, keepOffsets?: boolean): void;
+    /**
+     * 把 offsetMin/Max 设为预设值，使 rect 在父 rect 内落在视觉上对应的位置（留 margin 像素边距）。
+     * 当 anchor 已经按相同 preset 设定时，等价于“贴边放置带 margin 的 rect”。
+     * 使用当前 size 作为 rect 尺寸。
+     */
+    setOffsetsPreset(preset: LayoutPreset, margin?: number): void;
+    /**
+     * 同时设置 anchor 和 offset，达到“按 preset 摆放并贴边带 margin”的效果。
+     *
+     * 注意第一步用 `keepOffsets=false`（反推 offset 维持 rect 视觉位置），不能用默认 `true`：
+     * 后者会让 rect 的 size 在中间步先跳到错值（因为 anchor 改了 offset 没改），
+     * 第二步 `setOffsetsPreset` 又用这个错 size 算 offset，最终 rect size 不对
+     */
+    setAnchorsAndOffsetsPreset(preset: LayoutPreset, margin?: number): void;
+}

package/dist/render/graphics.d.ts

@@ -1,15 +1,37 @@
 import { Color } from '@galacean/effects-math/es/core/color';
 import { Matrix3 } from '@galacean/effects-math/es/core/matrix3';
 import type { Engine } from '../engine';
+import type { Texture } from '../texture';
+import type { FontStyle, FontWeight } from './text-cache';
+/**
+ * 纹理 UV 子矩形(Y 向上,Y=0 在底部)。 全图为 `{u0:0, v0:0, u1:1, v1:1}`
+ */
+export type TextureRegion = {
+    u0: number;
+    v0: number;
+    u1: number;
+    v1: number;
+};
 export declare class Graphics {
     private engine;
     private geometry;
-    private material;
-    private graphicsPath;
+    private coloredMaterial;
+    private texturedMaterial;
+    private readonly lineShape;
+    private readonly bezierShape;
+    private readonly triangleShape;
+    private readonly rectangleShape;
+    private readonly circleShape;
+    private readonly buildPoints;
     private vertices;
     private colors;
+    private uvs;
     private indices;
     private lineStyle;
+    private currentBatchType;
+    private currentBatchTexture;
+    /** 文本纹理 LRU 缓存,drawText 用 */
+    private textCache;
     private transformStack;
     private currentTransform;
     private get currentVertexCount();
@@ -21,7 +43,7 @@ export declare class Graphics {
     begin(): void;
     /**
      * 将当前变换压入栈，并设置新的变换
-     * @param transform - 新的变换矩阵（会与当前变换相乘）
+     * @param transform - 新的变换矩阵(会与当前变换相乘)
      */
     pushTransform(transform: Matrix3): void;
     /**
@@ -32,47 +54,55 @@ export declare class Graphics {
      * 刷新并渲染所有累积的绘制命令
      */
     end(): void;
+    /**
+     * 切换到指定批次类型/纹理。若与当前批次不一致，先 flush 已累积顶点
+     */
+    private ensureBatch;
+    /**
+     * 提交当前累积的顶点到 renderer，清空缓冲(批次内部 flush 不重置 batchType)
+     */
+    private flushBatch;
     /**
      * 线段顶点按顺序连接 (p0-p1, p1-p2, p2-p3, ...)
-     * @param points - 点数组，格式 [x1,y1,x2,y2,...]，至少需要2个点（4个数值）
+     * @param points - 点数组，格式 [x1,y1,x2,y2,...]，至少需要2个点(4个数值)
      * @param color - 线条颜色，范围 0-1
-     * @param thickness - 线宽（像素）
+     * @param thickness - 线宽(像素)
      */
     drawLines(points: number[], color?: Color, thickness?: number): void;
     /**
      * 绘制单条线段
-     * @param x1 - 起点x
-     * @param y1 - 起点y
-     * @param x2 - 终点x
-     * @param y2 - 终点y
-     * @param color - 线条颜色
-     * @param thickness - 线宽
+     * @param x1 - 起点 X 坐标
+     * @param y1 - 起点 Y 坐标
+     * @param x2 - 终点 X 坐标
+     * @param y2 - 终点 Y 坐标
+     * @param color - 线条颜色，默认白色，范围 0-1
+     * @param thickness - 线宽(像素)，默认 1
      */
     drawLine(x1: number, y1: number, x2: number, y2: number, color?: Color, thickness?: number): void;
     /**
-     * 绘制贝塞尔曲线
-     * @param x1 - 起点x
-     * @param y1 - 起点y
-     * @param x2 - 控制点1x
-     * @param y2 - 控制点1y
-     * @param x3 - 控制点2x
-     * @param y3 - 控制点2y
-     * @param x4 - 终点x
-     * @param y4 - 终点y
-     * @param color - 线条颜色
-     * @param thickness - 线宽
+     * 绘制三阶贝塞尔曲线（P0 起点，P1/P2 控制点，P3 终点）
+     * @param x1 - P0 起点 X 坐标
+     * @param y1 - P0 起点 Y 坐标
+     * @param x2 - P1 第一控制点 X 坐标
+     * @param y2 - P1 第一控制点 Y 坐标
+     * @param x3 - P2 第二控制点 X 坐标
+     * @param y3 - P2 第二控制点 Y 坐标
+     * @param x4 - P3 终点 X 坐标
+     * @param y4 - P3 终点 Y 坐标
+     * @param color - 曲线颜色，默认白色，范围 0-1
+     * @param thickness - 线宽(像素)，默认 1
      */
     drawBezier(x1: number, y1: number, x2: number, y2: number, x3: number, y3: number, x4: number, y4: number, color?: Color, thickness?: number): void;
     /**
-     * 绘制三角形边框
-     * @param x1 - 顶点1x
-     * @param y1 - 顶点1y
-     * @param x2 - 顶点2x
-     * @param y2 - 顶点2y
-     * @param x3 - 顶点3x
-     * @param y3 - 顶点3y
-     * @param color - 线条颜色
-     * @param thickness - 线宽
+     * 绘制三角形边框（闭合连接 3 个顶点）
+     * @param x1 - 顶点 1 X 坐标
+     * @param y1 - 顶点 1 Y 坐标
+     * @param x2 - 顶点 2 X 坐标
+     * @param y2 - 顶点 2 Y 坐标
+     * @param x3 - 顶点 3 X 坐标
+     * @param y3 - 顶点 3 Y 坐标
+     * @param color - 边框颜色，默认白色，范围 0-1
+     * @param thickness - 线宽(像素)，默认 1
      */
     drawTriangle(x1: number, y1: number, x2: number, y2: number, x3: number, y3: number, color?: Color, thickness?: number): void;
     /**
@@ -81,27 +111,28 @@ export declare class Graphics {
      * @param y - 矩形左下角 Y 坐标
      * @param width - 矩形宽度
      * @param height - 矩形高度
-     * @param color - 矩形颜色
+     * @param color - 边框颜色，默认白色，范围 0-1
+     * @param thickness - 线宽(像素)，默认 1
      */
     drawRectangle(x: number, y: number, width: number, height: number, color?: Color, thickness?: number): void;
     /**
      * 绘制圆形边框
-     * @param cx - 圆心x
-     * @param cy - 圆心y
-     * @param radius - 半径
-     * @param color - 线条颜色
-     * @param thickness - 线宽
+     * @param cx - 圆心 X 坐标
+     * @param cy - 圆心 Y 坐标
+     * @param radius - 半径(像素)
+     * @param color - 边框颜色，默认白色，范围 0-1
+     * @param thickness - 线宽(像素)，默认 1
      */
     drawCircle(cx: number, cy: number, radius: number, color?: Color, thickness?: number): void;
     /**
-     * 绘制填充三角形
-     * @param x1 - 顶点1x
-     * @param y1 - 顶点1y
-     * @param x2 - 顶点2x
-     * @param y2 - 顶点2y
-     * @param x3 - 顶点3x
-     * @param y3 - 顶点3y
-     * @param color - 填充颜色
+     * 绘制填充三角形（实心）
+     * @param x1 - 顶点 1 X 坐标
+     * @param y1 - 顶点 1 Y 坐标
+     * @param x2 - 顶点 2 X 坐标
+     * @param y2 - 顶点 2 Y 坐标
+     * @param x3 - 顶点 3 X 坐标
+     * @param y3 - 顶点 3 Y 坐标
+     * @param color - 填充颜色，默认白色，范围 0-1
      */
     fillTriangle(x1: number, y1: number, x2: number, y2: number, x3: number, y3: number, color?: Color): void;
     /**
@@ -110,21 +141,66 @@ export declare class Graphics {
      * @param y - 矩形左下角 Y 坐标
      * @param width - 矩形宽度
      * @param height - 矩形高度
-     * @param color - 矩形颜色
+     * @param color - 填充颜色，默认白色，范围 0-1
+     *
+     * 直接用 pushQuad（2 三角形分割）而不是 setRectangleShape + buildShape，
+     * 后者走 Rectangle.triangulate 的中心 fan，中心顶点连到 4 角的 4 条对角内边
+     * 在 MSAA / 亚像素精度下会暴露 1-2 像素缝隙，叠层时底层颜色透出形成可见对角痕迹
      */
     fillRectangle(x: number, y: number, width: number, height: number, color?: Color): void;
     /**
-     * 绘制填充圆形
-     * @param cx - 圆心x
-     * @param cy - 圆心y
-     * @param radius - 半径
-     * @param color - 填充颜色
+     * 绘制填充圆形（实心）
+     * @param cx - 圆心 X 坐标
+     * @param cy - 圆心 Y 坐标
+     * @param radius - 半径(像素)
+     * @param color - 填充颜色，默认白色，范围 0-1
      */
     fillCircle(cx: number, cy: number, radius: number, color?: Color): void;
+    /**
+     * 绘制纹理矩形（本地坐标，Y 向上，(x, y) 为左下角）
+     * @param x - 矩形左下角 X 坐标
+     * @param y - 矩形左下角 Y 坐标
+     * @param width - 矩形宽度
+     * @param height - 矩形高度
+     * @param texture - 要采样的纹理。同纹理连续绘制会合批，纹理切换会自动 flush 当前批次
+     * @param region - 纹理 UV 子矩形，默认全图。Y 向上，(u0,v0) 为左下角 UV
+     * @param color - 乘色，默认白色
+     */
+    drawTexture(x: number, y: number, width: number, height: number, texture: Texture, region?: TextureRegion, color?: Color): void;
+    /**
+     * 绘制文本（本地坐标，Y 向上，(x, y) 为文本左下角）。
+     *
+     * 文本走字符级 bitmap atlas（同一字体下每个字只渲染一次，任意文本组合复用 atlas）;
+     * `color` 作为乘色与白色字形 alpha 相乘，任意颜色都不会污染 atlas。
+     *
+     * 字体参数全部展开，避免调用方每帧创建临时 style 对象触发 GC
+     * @param x - 文本左下角 X 坐标
+     * @param y - 文本左下角 Y 坐标（对齐 baseline 上方 ascent 处）
+     * @param text - 要绘制的文本内容，空串直接 return
+     * @param fontSize - 字号（逻辑像素）
+     * @param color - 乘色，默认白色，范围 0-1
+     * @param fontFamily - 字体族，默认 `sans-serif`
+     * @param fontWeight - 字重，默认 `normal`，支持 `'bold'` 或数字
+     * @param fontStyle - 字形，默认 `normal`，支持 `'italic'`
+     */
+    drawText(x: number, y: number, text: string, fontSize: number, color?: Color, fontFamily?: string, fontWeight?: FontWeight, fontStyle?: FontStyle): void;
     dispose(): void;
     private buildShape;
     private buildShapeLine;
+    private setTriangleShape;
+    private setRectangleShape;
+    private setCircleShape;
     private applyTransformAndColor;
+    /**
+     * 推一个 quad（4 顶点 + 6 索引，2 个三角形）。
+     *
+     * - colored 批次：`region` 省略 → UV 写 0（shader 不读）
+     * - textured 批次：传 `region` → UV 按 region 写
+     *
+     * 之所以用 2 三角形而不是中心 fan（像 Rectangle.triangulate），是因为 fan 的中心顶点连到 4 角的对角内边
+     * 在像素级亚像素精度下会暴露 1-2 像素缝隙，叠层时底层颜色透出形成可见的对角痕迹
+     */
+    private pushQuad;
     /**
      * 应用自定义变换到点
      * @param x - 点的 x 坐标

package/dist/render/index.d.ts

@@ -11,3 +11,4 @@ export * from './framebuffer';
 export * from './renderer';
 export * from './graphics';
 export * from './draw-object-pass';
+export * from './text-cache';