three-base 2.0.134 → 2.0.142

package/SpriteText2.ts

@@ -0,0 +1,258 @@
+/*
+ * @Author: xiaosihan
+ * @Date: 2023-04-24 15:31:02
+ * @Last Modified by: xiaosihan
+ * @Last Modified time: 2023-04-24 16:18:47
+ */
+import { LinearFilter, Sprite, Texture, Raycaster, Intersection } from 'three';
+import type { ColorString } from "./types";
+
+// 带箭头的精灵文字
+export default class SpriteText2 extends Sprite {
+    constructor(text: string = '', textHeight: number = 10, color: ColorString = 'rgba(255, 255, 255, 1)') {
+        super();
+        this.material.alphaTest = 0.1;
+        this._text = `${text}`;
+        this._textHeight = textHeight;
+        this._color = color;
+        this._backgroundColor = false; // no background color
+        this._padding = 0;
+        this._borderWidth = 0;
+        this._borderRadius = 0;
+        this._borderColor = 'white';
+        this._strokeWidth = 0;
+        this._strokeColor = 'white';
+        this._fontFace = 'Arial';
+        this._fontSize = 90; // defines text resolution
+        this._fontWeight = 'normal';
+        this._genCanvas();
+    }
+
+    _text: string = "";
+    _textHeight: number = 0;
+    _color: ColorString = "#ffffff";
+    _backgroundColor: ColorString | false = false; // no background color
+    _padding: number = 0;
+    _borderWidth: number = 0;
+    _borderRadius: number = 0;
+    _borderColor: string = 'white';
+    _strokeWidth: number = 0;
+    _strokeColor: string = 'white';
+    _fontFace: string = 'Arial';
+    _fontSize: number = 90; // defines text resolution
+    _fontWeight: string = 'normal';
+    _canvas: HTMLCanvasElement = document.createElement('canvas');
+
+    get text(): string { return this._text; }
+    set text(text: string) { this._text = text; this._genCanvas(); }
+
+    get textHeight(): number { return this._textHeight; }
+    set textHeight(textHeight: number) { this._textHeight = textHeight; this._genCanvas(); }
+
+    get color(): ColorString { return this._color; }
+    set color(color: ColorString) { this._color = color; this._genCanvas(); }
+
+    get backgroundColor(): ColorString | false { return this._backgroundColor; }
+    set backgroundColor(color: ColorString | false) { this._backgroundColor = color; this._genCanvas(); }
+
+    get padding(): number { return this._padding; }
+    set padding(padding: number) { this._padding = padding; this._genCanvas(); }
+
+    get borderWidth(): number { return this._borderWidth; }
+    set borderWidth(borderWidth: number) { this._borderWidth = borderWidth; this._genCanvas(); }
+
+    get borderRadius(): number { return this._borderRadius; }
+    set borderRadius(borderRadius: number) { this._borderRadius = borderRadius; this._genCanvas(); }
+
+    get borderColor(): string { return this._borderColor; }
+    set borderColor(borderColor: string) { this._borderColor = borderColor; this._genCanvas(); }
+
+    get fontFace(): string { return this._fontFace; }
+    set fontFace(fontFace: string) { this._fontFace = fontFace; this._genCanvas(); }
+
+    get fontSize(): number { return this._fontSize; }
+    set fontSize(fontSize: number) { this._fontSize = fontSize; this._genCanvas(); }
+
+    get fontWeight(): string { return this._fontWeight; }
+    set fontWeight(fontWeight: string) { this._fontWeight = fontWeight; this._genCanvas(); }
+
+    get strokeWidth(): number { return this._strokeWidth; }
+    set strokeWidth(strokeWidth: number) { this._strokeWidth = strokeWidth; this._genCanvas(); }
+
+    get strokeColor(): string { return this._strokeColor; }
+    set strokeColor(strokeColor: string) { this._strokeColor = strokeColor; this._genCanvas(); }
+
+    _genCanvas(): void {
+        const canvas = this._canvas;
+        const ctx = canvas.getContext('2d');
+        if (!ctx) return;
+
+        const border = Array.isArray(this.borderWidth) ? this.borderWidth : [this.borderWidth, this.borderWidth]; // x,y border
+        const relBorder = border.map(b => b * this.fontSize * 0.1); // border in canvas units
+        const borderRadius = Array.isArray(this.borderRadius) ? this.borderRadius : [this.borderRadius, this.borderRadius, this.borderRadius, this.borderRadius]; // tl tr br bl corners
+        const relBorderRadius = borderRadius.map(b => b * this.fontSize * 0.1); // border radius in canvas units
+        const padding = Array.isArray(this.padding) ? this.padding : [this.padding, this.padding]; // x,y padding
+        const relPadding = padding.map(p => p * this.fontSize * 0.1); // padding in canvas units
+        const lines = this.text.split('\n');
+        const font = `${this.fontWeight} ${this.fontSize}px ${this.fontFace}`;
+
+        ctx.font = font; // measure canvas with appropriate font
+        const innerWidth = Math.max(...lines.map(line => ctx.measureText(line).width));
+        const innerHeight = this.fontSize * lines.length;
+
+        // 内容框尺寸（含 border + padding）
+        const contentW = innerWidth + relBorder[0] * 2 + relPadding[0] * 2;
+        const contentH = innerHeight + relBorder[1] * 2 + relPadding[1] * 2;
+
+        // 箭头区：底部预留 arrowZone 给向下箭头（raycast 用 uv.y 判定点击区）。
+        // 顶部同样预留等量空间，使内容框在画布中【垂直居中】，不再因底部箭头区而整体偏上、视觉不居中。
+        const arrowZone = 40;
+        const boxTop = arrowZone;             // 内容框顶边（顶留白 = arrowZone）
+        const boxBottom = boxTop + contentH; // 内容框底边（箭头从此处向下延伸）
+
+        canvas.width = contentW;
+        canvas.height = boxBottom + arrowZone; // 顶 arrowZone + 内容 + 底 arrowZone
+
+        // 统一平移到内容框坐标系：之后所有绘制都以 (0, boxTop) 为内容框左上角。
+        ctx.translate(0, boxTop);
+
+        // paint border
+        if (this.borderWidth) {
+            ctx.strokeStyle = this.borderColor;
+
+            if (relBorder[0]) { // left + right borders
+                const hb = relBorder[0] / 2;
+                ctx.lineWidth = relBorder[0];
+                ctx.beginPath();
+                ctx.moveTo(hb, relBorderRadius[0]);
+                ctx.lineTo(hb, contentH - relBorderRadius[3]);
+                ctx.moveTo(contentW - hb, relBorderRadius[1]);
+                ctx.lineTo(contentW - hb, contentH - relBorderRadius[2]);
+                ctx.stroke();
+            }
+
+            if (relBorder[1]) { // top + bottom borders
+                const hb = relBorder[1] / 2;
+                ctx.lineWidth = relBorder[1];
+                ctx.beginPath();
+                ctx.moveTo(Math.max(relBorder[0], relBorderRadius[0]), hb);
+                ctx.lineTo(contentW - Math.max(relBorder[0], relBorderRadius[1]), hb);
+                ctx.moveTo(Math.max(relBorder[0], relBorderRadius[3]), contentH - hb);
+                ctx.lineTo((contentW / 2 - 20), contentH - hb);
+                ctx.lineTo((contentW / 2), contentH + 20 - hb);
+                ctx.lineTo((contentW / 2 + 20), contentH - hb);
+                ctx.lineTo(contentW - Math.max(relBorder[0], relBorderRadius[2]), contentH - hb);
+                ctx.stroke();
+            }
+
+            if (this.borderRadius) { // strike rounded corners
+                const cornerWidth = Math.max(...relBorder);
+                const hb = cornerWidth / 2;
+                ctx.lineWidth = cornerWidth;
+                ctx.beginPath();
+                [
+                    !!relBorderRadius[0] && [relBorderRadius[0], hb, hb, relBorderRadius[0]],
+                    !!relBorderRadius[1] && [contentW - relBorderRadius[1], contentW - hb, hb, relBorderRadius[1]],
+                    !!relBorderRadius[2] && [contentW - relBorderRadius[2], contentW - hb, contentH - hb, contentH - relBorderRadius[2]],
+                    !!relBorderRadius[3] && [relBorderRadius[3], hb, contentH - hb, contentH - relBorderRadius[3]]
+                ].filter((d): d is number[] => !!d).forEach(([x0, x1, y0, y1]) => {
+                    ctx.moveTo(x0, y0);
+                    ctx.quadraticCurveTo(x1, y0, x1, y1);
+                });
+                ctx.stroke();
+            }
+        }
+
+        // paint background
+        if (this.backgroundColor) {
+            ctx.fillStyle = this.backgroundColor;
+            if (!this.borderRadius) {
+                ctx.fillRect(relBorder[0], relBorder[1], contentW - relBorder[0] * 2, contentH - relBorder[1] * 2);
+            }
+            else { // fill with rounded corners
+                ctx.beginPath();
+                ctx.moveTo(relBorder[0], relBorderRadius[0]);
+                ctx.quadraticCurveTo(relBorder[0], relBorder[1], relBorderRadius[0], relBorder[1]);
+                ctx.lineTo(contentW - relBorderRadius[1], relBorder[1]);
+                ctx.quadraticCurveTo(contentW - relBorder[0], relBorder[1], contentW - relBorder[0], relBorderRadius[1]);
+                ctx.lineTo(contentW - relBorder[0], contentH - relBorderRadius[2]);
+                ctx.quadraticCurveTo(contentW - relBorder[0], contentH - relBorder[1], contentW - relBorderRadius[2], contentH - relBorder[1]);
+                ctx.lineTo((contentW / 2 + 20), contentH - relBorder[1]);
+                ctx.lineTo((contentW / 2), contentH + 20 - relBorder[1]);
+                ctx.lineTo((contentW / 2 - 20), contentH - relBorder[1]);
+                ctx.lineTo(relBorderRadius[3], contentH - relBorder[1]);
+                ctx.quadraticCurveTo(relBorder[0], contentH - relBorder[1], relBorder[0], contentH - relBorderRadius[3]);
+                ctx.closePath();
+                ctx.fill();
+            }
+        }
+
+        // 文字区：在内容框内（已平移到 boxTop）再叠加 border + padding 偏移，使文字在框内居中。
+        ctx.translate(relBorder[0], relBorder[1]);
+        ctx.translate(relPadding[0], relPadding[1]);
+
+        // paint text
+        ctx.font = font; // Set font again after canvas is resized, as context properties are reset
+        ctx.fillStyle = this.color;
+        // 精确垂直居中：用 measureText 的 actualBoundingBox 实测字形上下沿，
+        // 不再依赖 textBaseline='middle'（middle 是 em 盒中线，与真实字形视觉中线常偏差，
+        // 导致整行文字偏上/偏下、看着不居中）。改为 alphabetic 基线 + 实测字形高度，
+        // 把每行字形放进其 fontSize 高的槽中心。
+        ctx.textAlign = 'center';
+        ctx.textBaseline = 'alphabetic';
+
+        const drawTextStroke = this.strokeWidth > 0;
+        if (drawTextStroke) {
+            ctx.lineWidth = this.strokeWidth * this.fontSize / 10;
+            ctx.strokeStyle = this.strokeColor;
+        }
+
+        const slotH = this.fontSize; // 每行槽高
+        lines.forEach((line, index) => {
+            const metrics = ctx.measureText(line);
+            const ascent = metrics.actualBoundingBoxAscent;   // 字形顶部到基线
+            const descent = metrics.actualBoundingBoxDescent; // 基线到字形底部
+            const glyphH = (ascent || 0) + (descent || 0);
+            const slotTop = index * slotH;                    // 本行槽顶（内容框坐标系，已平移）
+            // 让字形在槽中垂直居中：先平移到槽中线，再上移 ascent 回到基线
+            const baselineY = slotTop + (slotH - glyphH) / 2 + (ascent || slotH / 2);
+            const lineX = innerWidth / 2;
+            drawTextStroke && ctx.strokeText(line, lineX, baselineY);
+            ctx.fillText(line, lineX, baselineY);
+        });
+
+        // Inject canvas into sprite
+        if (this.material.map)
+            this.material.map.dispose(); // gc previous texture
+        const texture = this.material.map = new Texture(canvas);
+        texture.minFilter = LinearFilter;
+        texture.needsUpdate = true;
+
+        const yScale = this.textHeight * lines.length + border[1] * 2 + padding[1] * 2;
+        this.scale.set(yScale * canvas.width / canvas.height, yScale, 0);
+    }
+
+    //鼠标拾取计算
+    raycast(raycaster: Raycaster, intersects: Intersection[]): void {
+        let intersect: Intersection[] = [];
+        super.raycast(raycaster, intersect);
+        let inte = intersect[0];
+        if (inte && (inte.uv && inte.uv.y > 0.55)) {
+            intersects.push(inte);
+        }
+    }
+
+    copy(source: SpriteText2): this {
+        this.color = source.color;
+        this.backgroundColor = source.backgroundColor;
+        this.padding = source.padding;
+        this.borderWidth = source.borderWidth;
+        this.borderColor = source.borderColor;
+        this.fontFace = source.fontFace;
+        this.fontSize = source.fontSize;
+        this.fontWeight = source.fontWeight;
+        this.strokeWidth = source.strokeWidth;
+        this.strokeColor = source.strokeColor;
+        return this;
+    }
+}

package/SpriteText3.d.ts

@@ -0,0 +1,86 @@
+import { Mesh } from "three";
+import type { ColorString } from "./types";
+/**
+ * 箭头（2026-09-14 皇上旨"箭头看不清楚了"，前一轮"接缝"已由 11-slice 连续取源修好）：
+ * 源图箭头 cell（TIP_SRC_X=441…）左右边界 x441/500 与左右带子 [8]/[10] 逐行 RGBA 完全一致(均带子蓝)，
+ * 且 cell 是整块青蓝渐变：边缘=带子蓝低透明(α≈32~43)、箭身/尖点=亮青(≈47,168,225)高透明(α≈248)。
+ * [9] 用 **「先 clearRect 局部清空 + source-over 画原始 cell」**（等价"局部 copy"）：
+ *   · 清空：先清掉 [9] 矩形内的带子 → 箭头边距不会与带子 α 相加 → 无缝；
+ *   · 绘制：source-over 画原始 cell，箭身=亮青 α≈248 → 清晰可见。
+ * ⚠️ 三个已验证的坑（2026-09-14 各踩一次，真实 Chrome 无头实测）：
+ *   · source-over：边距 α 与带子 α 相加(32+33≈60) → 又现台阶(皇上反馈的"接缝")；
+ *   · source-atop：箭头 α 被压到带子的≈43 → 整块与带子同透明 → 箭头糊没(皇上反馈"看不清楚")；
+ *   · **copy：canvas 的 copy 是"清空整个画布、只保留本次绘制"**（不是只替换目标矩形！）→
+ *     前面 11-slice 画的边框全被清掉、只剩箭头(皇上反馈"其他边框全没了"；实测整块只剩 2700 像素)。
+ */
+export default class SpriteText3 extends Mesh {
+    constructor(text?: string, textHeight?: number, color?: ColorString);
+    /** 自定义着色器材质（类型收窄用） */
+    private _shader;
+    /** 气泡+文字纹理（_genText 重建） */
+    private _textTexture;
+    /** 绘制用离屏 canvas */
+    private _textCanvas;
+    /** 气泡背景图源图（加载完成后在 canvas 上做 11-slice） */
+    private _bgImage;
+    _text: string;
+    _textHeight: number;
+    _color: ColorString;
+    _fontFace: string;
+    _fontSize: number;
+    _fontWeight: string;
+    _padding: number;
+    /**
+     * 边框带边长（画布像素，4 角 + R0/R2 行高 + C0/C4 列宽 共享）
+     * 源边框带 = 外辉光 42 + 圆角 38 = 82；默认 82 = 1:1 复刻原图（辉光完整保留）
+     */
+    _cornerSize: number;
+    /**
+     * 箭头目标凸出高度（画布像素，尖角块[9]的箭头段在画布上的最终高度）
+     * 源图箭头 ARROW_SRC_H=41 像素，此属性控制缩放后的视觉大小（不可变形等比缩放）
+     * 默认 41 = 1:1 最锐利（原图箭头比例）；调大超过 41 才开始放大变糊
+     */
+    _arrowTargetH: number;
+    /**
+     * 箭头水平视觉微调偏移（像素，相对 canvas 中心；负值左移、正值右移）
+     * 源图箭头中心 x=471 相对气泡中心 461 偏右约 10px；尖角块以【箭头】为中心取块，
+     * 画布上块居中 → 该偏置被自然消除，默认 0；此属性供按视觉需求再做微调
+     */
+    _arrowOffsetX: number;
+    /** 是否显示 11-slice 分割线（默认开启） */
+    _showGrid: boolean;
+    /** 是否显示调试描边（默认关闭，画整个 canvas 红色边框） */
+    _showOutline: boolean;
+    get text(): string;
+    set text(value: string);
+    get textHeight(): number;
+    set textHeight(value: number);
+    get color(): ColorString;
+    set color(value: ColorString);
+    get fontFace(): string;
+    set fontFace(value: string);
+    get fontSize(): number;
+    set fontSize(value: number);
+    get fontWeight(): string;
+    set fontWeight(value: string);
+    get padding(): number;
+    set padding(value: number);
+    get cornerSize(): number;
+    set cornerSize(value: number);
+    get arrowTargetH(): number;
+    set arrowTargetH(value: number);
+    get arrowOffsetX(): number;
+    set arrowOffsetX(value: number);
+    get showOutline(): boolean;
+    set showOutline(value: boolean);
+    get showGrid(): boolean;
+    set showGrid(value: boolean);
+    /** 异步载入背景图源图（base64 data URL），加载完成后触发 11-slice 重绘 */
+    private _loadBg;
+    /**
+     * 重新生成 canvas 纹理并同步 sprite 世界尺寸。
+     * 主体流程：计算文字/气泡尺寸 → 计算 11 切片的目标位置/大小 → 依次 drawImage 11 个部件
+     *         → 画 showGrid 分割线 → 画 showOutline 边框 → 画文字 → 更新 Texture。
+     */
+    private _genText;
+}