Skip to content

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.

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.mdx
index 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.mdx
index 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.ts
index 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 > 0
diff --git a/sdk/src/ui/text/text-renderer.ts b/sdk/src/ui/text/text-renderer.ts
index 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.ts
index 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));