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

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 坐标（首字 ink 起始处，含 padding 的 quad 会向左延伸）
+     * @param y - 文本左下角 Y 坐标（cell 底，含底部 padding；字形 ink 在其上方 padding+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';

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

@@ -0,0 +1,117 @@
+import type { Engine } from '../engine';
+import { Texture } from '../texture';
+/**
+ * 字重（对齐 canvas 2d font 字符串可接受值）
+ */
+export type FontWeight = 'normal' | 'bold' | number;
+/**
+ * 字形（对齐 canvas 2d font 字符串可接受值）
+ */
+export type FontStyle = 'normal' | 'italic';
+/**
+ * 字形纹理超采样倍数。canvas 按 `fontSize * FONT_SCALE` 渲染，纹理像素也是 scale 倍，
+ * 但 quad 仍按 1x 逻辑尺寸绘制 — 双线性 downsample 后比原 1x 渲染清晰得多
+ */
+export declare const FONT_SCALE = 2;
+/**
+ * 单张字符 atlas 的边长(像素,scale 后的实际像素,非逻辑尺寸)。
+ * 512×512 在 24px 字号下约可容纳 250+ 字形,常见 demo 文本足够
+ */
+export declare const ATLAS_SIZE = 512;
+/**
+ * 单个字形在 atlas 中的位置 / 度量。
+ *
+ * `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;
+    advance: number;
+    paddingLeft: number;
+};
+/**
+ * 一种字体（family + weight + style + size 唯一确定）对应一张 atlas。
+ *
+ * Skyline 风格 packer：行内堆字，行尾换行，cell 高 = ceil((fontHeight + padding*2) * 1)，
+ * 所有字共用同一 cell 高与 baseline，实现同行 baseline 对齐。
+ * atlas 满后 `ensureChar` 返回 null，调用方应跳过该字（不再扩页，v1 范围）。
+ *
+ * canvas 内容变更后需要 `uploadIfDirty` 重新上传到纹理 — 由调用方在使用纹理前主动触发，
+ * 避免每加一字都 upload 一次造成的 GL 开销
+ */
+export declare class GlyphAtlas {
+    private engine;
+    private readonly scaledFontString;
+    /** atlas canvas（像素 = ATLAS_SIZE × ATLAS_SIZE，自有不进 canvasPool） */
+    readonly canvas: HTMLCanvasElement;
+    /** 与 canvas 绑定的纹理，内容变更后通过 updateSource 重传 */
+    readonly texture: Texture;
+    /** cell 高（逻辑像素，含 padding），用于 quad 高度 */
+    readonly lineHeight: number;
+    private readonly ctx;
+    private readonly glyphs;
+    /** 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;
+    /** atlas 已满，后续 ensureChar 全部失败（避免反复 measureText） */
+    private full;
+    /** 自上次 upload 以来 canvas 是否有新字写入 */
+    private dirty;
+    constructor(engine: Engine, scaledFontString: string, 
+    /** baseline 距 cell 顶距离（像素，scale 后，仅 ascent 部分，不含 padding） */
+    ascentPx: number, 
+    /** baseline 距 cell 底距离（像素，scale 后，仅 descent 部分） */
+    descentPx: number, fontStyle: FontStyle);
+    /**
+     * 取（必要时渲染并打包）单字。返回 GlyphInfo 或 null（atlas 已满）
+     */
+    ensureChar(char: string): GlyphInfo | null;
+    /**
+     * 若有新字写入 canvas，把整张 canvas 重新上传到纹理。调用方在使用纹理（flushBatch）前调用
+     */
+    uploadIfDirty(): void;
+    dispose(): void;
+}
+/**
+ * 字符 atlas 缓存。每种字体（family + weight + style + size）分配一张
+ * `ATLAS_SIZE × ATLAS_SIZE` 的离屏 canvas atlas，字符按需逐个绘制并打包，
+ * `Graphics.drawText` 通过逐字 quad 引用 atlas 子矩形渲染。
+ *
+ * - 同一段文本不同颜色不会重复 upload（颜色由顶点 `vColor` 乘上字形 alpha）
+ * - 同一字体/字号下重复字符只渲染一次，显著减少 canvas → texture 上传次数
+ *
+ * 入参全部展开（避免调用方每帧创建临时 style 对象触发 GC）
+ */
+export declare class TextCache {
+    private engine;
+    /** fontKey -> 该字体的字符 atlas */
+    private readonly atlases;
+    constructor(engine: Engine);
+    /**
+     * 取(必要时新建)对应字体的字符 atlas
+     */
+    getAtlas(fontSize: number, fontFamily: string, fontWeight: FontWeight, fontStyle: FontStyle): GlyphAtlas;
+    /**
+     * 把所有 dirty 的 atlas canvas 内容上传到对应纹理。
+     * 由 `Graphics.flushBatch` 在 drawGeometry 前调用，确保即将采样的 atlas 纹理是最新的；
+     * 一帧多次 drawText 共写同一 atlas 时，只在 flush 边界 upload 一次，避免逐 drawText 反复重传
+     */
+    uploadDirty(): void;
+    /**
+     * 清空所有 atlas 并 dispose 对应纹理。Engine dispose 时调用
+     */
+    dispose(): void;
+}

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/transform.d.ts

@@ -1,4 +1,5 @@
 import { Euler, Matrix4, Quaternion, Vector2, Vector3 } from '@galacean/effects-math/es/core/index';
+import { Matrix3 } from '@galacean/effects-math/es/core/matrix3';
 import type * as spec from '@galacean/effects-specification';
 import type { Disposable } from './utils';
 import type { Engine } from './engine';
@@ -53,7 +54,7 @@ export declare class Transform implements Disposable {
     /**
      * 子变换，可以有多个
      */
-    private children;
+    protected children: Transform[];
     /**
      * 父变换，只能有一个
      */
@@ -70,6 +71,10 @@ export declare class Transform implements Disposable {
      * 仅包含自身变换的模型矩阵
      */
     private localMatrix;
+    /**
+     * 自身变换在 2D 平面（XY）上的仿射部分缓存，按需从 localMatrix 提取
+     */
+    private localMatrix2D;
     /**
      * 变换是否需要生效，不生效返回的模型矩阵为单位矩阵，需要随元素生命周期改变
      */
@@ -90,8 +95,8 @@ export declare class Transform implements Disposable {
     constructor(props?: TransformProps, parent?: Transform);
     set parentTransform(transform: Transform | null);
     get parentTransform(): Transform | null;
-    set parentMatrixDirty(val: boolean);
-    get parentMatrixDirty(): boolean;
+    private set worldMatrixDirty(value);
+    private get worldMatrixDirty();
     /**
      * 设置位置
      * @param x
@@ -184,6 +189,12 @@ export declare class Transform implements Disposable {
      * @returns
      */
     getMatrix(): Matrix4;
+    /**
+     * 获取自身变换对应模型矩阵在 XY 平面上的 3x3 仿射矩阵
+     * 仅当 localMatrix 变化时才重新提取，否则返回缓存。返回的 Matrix3 在调用之间复用，调用方不应缓存其引用。
+     * @returns
+     */
+    getMatrix2D(): Matrix3;
     /**
      * 获取父矩阵，如果有多级父节点，返回整体变换
      * @returns

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.9.3",
+  "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"