A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(ui): Text.shadowBlur softens the shadow instead of documenting that it cannot
yhh3d2db1922268
diff --git a/docs/astro/src/content/docs/guides/ui-text.mdx b/docs/astro/src/content/docs/guides/ui-text.mdxindex 565bbfa28..a2cc488a4 100644--- a/docs/astro/src/content/docs/guides/ui-text.mdx+++ b/docs/astro/src/content/docs/guides/ui-text.mdx@@ -86,8 +86,8 @@ Defaults below are the component defaults (what the inspector shows).| `strokeColor` | Color | `{0,0,0,1}` | Outline color. || `strokeWidth` | number | `0` | Outline width in px; `0` disables. Drawn as recolored glyph copies fanned out in 8 directions. || `shadowColor` | Color | `{0,0,0,1}` | Drop-shadow color. |-| `shadowOffsetX` / `shadowOffsetY` | number | `0` | Shadow offset in px. The shadow draws only when the color has alpha and at least one offset is non-zero. |-| `shadowBlur` | number | `0` | Reserved — the current renderer draws the shadow as a hard-edged offset copy and does not apply blur. |+| `shadowOffsetX` / `shadowOffsetY` | number | `0` | Shadow offset in px. |+| `shadowBlur` | number | `0` | Softens the shadow, in px. `0` is a hard offset copy; above that the shadow spreads into a ring, so it reads as a soft mass under the glyphs rather than a second stamp of them. A blur with no offset is a halo. || `richText` | boolean | `false` | Parse inline [rich-text markup](#rich-text). || `renderMode` | `TextRenderMode` | `Auto` | Glyph pipeline: `Auto` / `Bitmap` / `Sdf` (see above). || `enabled` | boolean | `true` | Render toggle (the editor's eye icon uses it too). |diff --git a/docs/astro/src/content/docs/zh-cn/guides/ui-text.mdx b/docs/astro/src/content/docs/zh-cn/guides/ui-text.mdxindex f3001dfa0..e6469a3bd 100644--- a/docs/astro/src/content/docs/zh-cn/guides/ui-text.mdx+++ b/docs/astro/src/content/docs/zh-cn/guides/ui-text.mdx@@ -80,8 +80,8 @@ const pulseBanner = defineSystem([Query(Mut(Transform), Text), Res(Time)], (q, t| `strokeColor` | Color | `{0,0,0,1}` | 描边颜色。 || `strokeWidth` | number | `0` | 描边宽度(px);`0` 关闭。以 8 方向扇形展开的换色字形副本绘制。 || `shadowColor` | Color | `{0,0,0,1}` | 投影颜色。 |-| `shadowOffsetX` / `shadowOffsetY` | number | `0` | 投影偏移(px)。仅当颜色有 alpha 且至少一个偏移非零时绘制。 |-| `shadowBlur` | number | `0` | 保留字段——当前渲染器把投影画成硬边偏移副本,不应用模糊。 |+| `shadowOffsetX` / `shadowOffsetY` | number | `0` | 投影偏移(px)。 |+| `shadowBlur` | number | `0` | 投影柔度(px)。`0` 是硬边偏移副本;大于 0 时投影摊成一圈,读起来是字下面一团柔和的暗,而不是又盖了一遍字。只给柔度不给偏移就是一圈光晕。 || `richText` | boolean | `false` | 解析内联[富文本标记](#富文本)。 || `renderMode` | `TextRenderMode` | `Auto` | 字形管线:`Auto` / `Bitmap` / `Sdf`(见上文)。 || `enabled` | boolean | `true` | 渲染开关(编辑器的眼睛图标也用它)。 |diff --git a/sdk/src/ui/text/plugin.ts b/sdk/src/ui/text/plugin.tsindex df07bf130..0191f0e5b 100644--- a/sdk/src/ui/text/plugin.ts+++ b/sdk/src/ui/text/plugin.ts@@ -178,11 +178,15 @@ export class TextPlugin implements Plugin {layer = order >= 0 ? UI_BASE_LAYER + order : UI_BASE_LAYER;}- const shadow = t.shadowColor.a > 0 && (t.shadowOffsetX !== 0 || t.shadowOffsetY !== 0)+ // A blur with no offset is still a shadow — a halo centred on the+ // glyphs — so it counts as one for the "is there a shadow" test.+ const shadow = t.shadowColor.a > 0+ && (t.shadowOffsetX !== 0 || t.shadowOffsetY !== 0 || t.shadowBlur > 0)? {color: [t.shadowColor.r, t.shadowColor.g, t.shadowColor.b, t.shadowColor.a] as RGBA,dx: t.shadowOffsetX,dy: t.shadowOffsetY,+ blur: t.shadowBlur,}: undefined;const outline = t.strokeWidth > 0 && t.strokeColor.a > 0diff --git a/sdk/src/ui/text/text-renderer.ts b/sdk/src/ui/text/text-renderer.tsindex 1bcb1286f..7db0c60ca 100644--- a/sdk/src/ui/text/text-renderer.ts+++ b/sdk/src/ui/text/text-renderer.ts@@ -46,8 +46,12 @@ export interface DrawTextParams {verticalAlign?: number;/** Box height (px) for vertical alignment; 0/undefined = boxless (anchor to origin). */boxHeight?: number;- /** Drop shadow: an offset, recolored copy of the glyphs drawn behind the fill. */- shadow?: { color: RGBA; dx: number; dy: number };+ /**+ * Drop shadow: an offset, recolored copy of the glyphs drawn behind the fill.+ * `blur` (px, 0 = hard) spreads that copy into a ring so the shadow reads as+ * a soft mass rather than a second stamp of the text.+ */+ shadow?: { color: RGBA; dx: number; dy: number; blur?: number };/** Outline: recolored glyph copies fanned out by `width` px around the fill. */outline?: { color: RGBA; width: number };}@@ -59,6 +63,32 @@ const OUTLINE_OFFSETS: ReadonlyArray<readonly [number, number]> = [[-1, 1], [0, 1], [1, 1],];+/**+ * A blurred shadow is the glyphs stamped around a ring, which is the same shape+ * the outline already takes — one mechanism for "spread these glyphs out", not+ * two. Two rings plus the centre approximate a Gaussian closely enough at the+ * sizes UI text uses; a true one-pass soft edge wants a per-draw threshold the+ * batch path cannot carry yet (the vertex format is shared with every sprite),+ * and both effects collapse into it on the day it can.+ */+const SHADOW_RING: ReadonlyArray<readonly [number, number, number]> = [+ // [x, y, radius fraction] — the inner ring carries most of the mass.+ [0, 0, 0],+ [-0.55, -0.55, 1], [0, -0.78, 1], [0.55, -0.55, 1],+ [-0.78, 0, 1], [0.78, 0, 1],+ [-0.55, 0.55, 1], [0, 0.78, 1], [0.55, 0.55, 1],+];++/**+ * Per-tap alpha for `n` stacked copies that should composite to `target`.+ * Straight division under-shoots badly: eight layers of `a/8` reach+ * 1-(1-a/8)^8, not `a`. This is that inverted.+ */+export function tapAlpha(target: number, n: number): number {+ if (n <= 1) return target;+ return 1 - Math.pow(1 - Math.min(1, Math.max(0, target)), 1 / n);+}+/*** Lay out `text` against `atlas` and emit one quad batch per atlas page to* `sink`. Pure given the atlas — no engine/Canvas dependency — so the grouping@@ -120,7 +150,17 @@ export function drawTextWith(atlas: GlyphAtlas, sink: GlyphBatchSink, p: DrawTex// Shadow (offset drop copy). y-up local space: a positive screen-down offset// moves the copy toward -y.if (p.shadow && p.shadow.color[3] > 0) {- emitPass(p.shadow.color, p.shadow.dx, -p.shadow.dy);+ const { color, dx, dy } = p.shadow;+ const blur = p.shadow.blur ?? 0;+ if (blur > 0) {+ const a = tapAlpha(color[3], SHADOW_RING.length);+ const tap: RGBA = [color[0], color[1], color[2], a];+ for (const [rx, ry, r] of SHADOW_RING) {+ emitPass(tap, dx + rx * blur * r, -dy + ry * blur * r);+ }+ } else {+ emitPass(color, dx, -dy);+ }}// Outline (8-direction fan around the glyph).if (p.outline && p.outline.width > 0 && p.outline.color[3] > 0) {@@ -221,7 +261,9 @@ export class SdfTextRenderer {/** Serialize every DrawTextParams field that affects the laid-out, colored geometry. */export function signatureOf(p: DrawTextParams): string {- const shadow = p.shadow ? `${p.shadow.color.join(',')}:${p.shadow.dx}:${p.shadow.dy}` : '';+ const shadow = p.shadow+ ? `${p.shadow.color.join(',')}:${p.shadow.dx}:${p.shadow.dy}:${p.shadow.blur ?? 0}`+ : '';const outline = p.outline ? `${p.outline.color.join(',')}:${p.outline.width}` : '';return [p.text, p.fontFamily, p.fontSizePx, p.style ?? 0,diff --git a/sdk/tests/ui-text-renderer.test.ts b/sdk/tests/ui-text-renderer.test.tsindex 4e46cd51d..e4af5ccd7 100644--- a/sdk/tests/ui-text-renderer.test.ts+++ b/sdk/tests/ui-text-renderer.test.ts@@ -9,7 +9,7 @@ import { describe, it, expect, vi } from 'vitest';import {GlyphAtlas, type GlyphRasterizer, type AtlasPageStore, type RasterGlyph,} from '../src/ui/text/glyph-atlas';-import { drawTextWith, signatureOf } from '../src/ui/text/text-renderer';+import { drawTextWith, signatureOf, tapAlpha } from '../src/ui/text/text-renderer';import type { DrawTextParams } from '../src/ui/text/text-renderer';function makeAtlas(pageSize: number): GlyphAtlas {@@ -66,6 +66,43 @@ describe('REARCH_GUI P1.3b: drawTextWith', () => {expect(shadowX - fillX).toBeCloseTo(2, 5);});+ it('spreads a blurred shadow into a ring, still behind the fill', () => {+ const atlas = makeAtlas(1024);+ const sink = vi.fn();+ drawTextWith(atlas, sink, {+ text: 'AB', fontFamily: 'Arial', fontSizePx: 24, color: [1, 1, 1, 1],+ shadow: { color: [0, 0, 0, 0.5], dx: 0, dy: 4, blur: 3 },+ });+ // 9 shadow taps + 1 fill.+ expect(sink).toHaveBeenCalledTimes(10);+ // Every tap sits within the blur radius of the offset, and none of them+ // is the full-strength colour — that is what stops a blurred shadow from+ // reading as several stamps of the text.+ const fillX = sink.mock.calls[9][0][0];+ for (let i = 0; i < 9; i++) {+ const verts = sink.mock.calls[i][0];+ expect(Math.abs(verts[0] - fillX)).toBeLessThanOrEqual(3.0001);+ expect(verts[7]).toBeLessThan(0.5); // per-tap alpha+ }+ });++ it('composites the ring back to the requested shadow alpha', () => {+ // Nine layers of a/9 would land at 1-(1-a/9)^9, well under a.+ expect(1 - Math.pow(1 - tapAlpha(0.5, 9), 9)).toBeCloseTo(0.5, 6);+ expect(1 - Math.pow(1 - tapAlpha(0.37, 9), 9)).toBeCloseTo(0.37, 6);+ expect(tapAlpha(0.5, 1)).toBe(0.5);+ });++ it('a blur with no offset is a halo, not a skipped shadow', () => {+ const atlas = makeAtlas(1024);+ const sink = vi.fn();+ drawTextWith(atlas, sink, {+ text: 'AB', fontFamily: 'Arial', fontSizePx: 24, color: [1, 1, 1, 1],+ shadow: { color: [0, 0, 0, 1], dx: 0, dy: 0, blur: 2 },+ });+ expect(sink).toHaveBeenCalledTimes(10);+ });+it('skips shadow/outline passes when transparent or zero-width', () => {const atlas = makeAtlas(1024);const sink = vi.fn();@@ -147,6 +184,9 @@ describe('text cache signature completeness', () => {['originY', { originY: 5 }],['color', { color: [1, 0, 0, 1] }],['shadow', { shadow: { color: [0, 0, 0, 1], dx: 2, dy: 2 } }],+ // The blur changes the geometry (a ring instead of one copy), so a label+ // whose blur alone changed must not keep the cached quads.+ ['shadow blur', { shadow: { color: [0, 0, 0, 1], dx: 2, dy: 2, blur: 3 } }],['outline', { outline: { color: [0, 0, 0, 1], width: 1 } }],])('changes when %s changes', (_field, override) => {expect(signatureOf({ ...base, ...override })).not.toBe(signatureOf(base));