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.

fix(ui): apply inherited opacity to all text passes

yhh5c73b4b6680d
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b736c12fa..f1475836f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@ published separately; it ships inside the editor.
### Fixed
+- **UI text effects follow inherited opacity.** Parent transparency now fades text shadows, outlines and explicit rich-text colors together with the fill. Opacity changes invalidate cached batches, and fully transparent subtrees skip glyph layout and submission until they become visible again.
+
- **Release websites wait for mirrored download metadata.** Documentation deployment starts after the release mirror completes and rejects a latest.json version that differs from the site build, preventing a freshly published page from reverting its version label and download sizes to the previous release.
- **Hidden text and skeletal batches skip vertex conversion.** Camera masks and empty scissors are checked before transforming caller-provided vertices, allocating transient storage or resolving shaders. The same visibility helper preserves SortingGroup layers and explicit text culling bits; visible batches retain their original geometry and per-type statistics.
diff --git a/sdk/src/ui/text/plugin.ts b/sdk/src/ui/text/plugin.ts
index afa2899fa..d6478e3c9 100644
--- a/sdk/src/ui/text/plugin.ts
+++ b/sdk/src/ui/text/plugin.ts
@@ -162,6 +162,7 @@ export class TextPlugin implements Plugin {
// display:none anywhere up the UI tree hides this text too.
if (api?.getUINodeHiddenInTree?.(registry, entity)) continue;
const groupAlpha = api?.getUINodeAlphaInTree?.(registry, entity) ?? 1;
+ if (groupAlpha <= 0) continue;
seen.add(entity as number);
const tr = world.get(entity, Transform) as TransformData;
@@ -229,7 +230,8 @@ export class TextPlugin implements Plugin {
// Subtree opacity (UINode.opacity) is resolved in C++ by the
// layout pass; text is drawn here, so it multiplies the same
// inherited alpha in and fades with its panel like visuals do.
- color: [t.color.r, t.color.g, t.color.b, t.color.a * groupAlpha],
+ color: [t.color.r, t.color.g, t.color.b, t.color.a],
+ opacity: groupAlpha,
style,
richText: t.richText,
align: t.align,
diff --git a/sdk/src/ui/text/text-renderer.ts b/sdk/src/ui/text/text-renderer.ts
index 79b4c3172..bd7533b27 100644
--- a/sdk/src/ui/text/text-renderer.ts
+++ b/sdk/src/ui/text/text-renderer.ts
@@ -18,7 +18,7 @@ import { NativeGlyphRasterizer } from './native-glyph-rasterizer';
import { EngineAtlasPageStore } from './atlas-page-store';
import { TextAlign, TextVerticalAlign, TextOverflow } from '../core/text';
import { layoutText, buildGlyphVertices, type LaidGlyph, type RGBA } from './layout';
-import { submitTextBatch } from './submit';
+import { submitTextBatch, TEXT_VERTEX_FLOATS } from './submit';
/** Receives one (vertices, indices) batch per atlas page used by the text. */
export type GlyphBatchSink = (vertices: Float32Array, indices: Uint16Array, pageId: number) => void;
@@ -28,6 +28,8 @@ export interface DrawTextParams {
fontFamily: string;
fontSizePx: number;
color: RGBA;
+ /** Inherited opacity applied to every fill, rich-color, shadow and outline vertex. */
+ opacity?: number;
originX?: number;
originY?: number;
style?: number;
@@ -172,6 +174,8 @@ export function textBlockOriginY(
* and geometry are unit-testable.
*/
export function drawTextWith(atlas: GlyphAtlas, sink: GlyphBatchSink, p: DrawTextParams): void {
+ const opacity = p.opacity ?? 1;
+ if (opacity <= 0) return;
const layout = layoutText(p.text, atlas, p.fontFamily, {
fontSizePx: p.fontSizePx,
letterSpacing: p.letterSpacing,
@@ -212,6 +216,9 @@ export function drawTextWith(atlas: GlyphAtlas, sink: GlyphBatchSink, p: DrawTex
const emitPass = (color: RGBA, dx: number, dy: number, bias = 0): void => {
for (const [pageId, glyphs] of byPage) {
const { vertices, indices } = buildGlyphVertices(glyphs, color, baseX + dx, originY + dy, bias);
+ if (opacity !== 1) {
+ for (let i = 7; i < vertices.length; i += TEXT_VERTEX_FLOATS) vertices[i] *= opacity;
+ }
sink(vertices, indices, pageId);
}
};
@@ -347,6 +354,6 @@ export function signatureOf(p: DrawTextParams): string {
p.maxWidth ?? 0, p.boxWidth ?? 0, p.boxHeight ?? 0,
p.overflow ?? TextOverflow.Visible,
p.originX ?? 0, p.originY ?? 0,
- p.color.join(','), shadow, outline,
+ p.color.join(','), p.opacity ?? 1, shadow, outline,
]);
}
diff --git a/sdk/tests/native-text.test.ts b/sdk/tests/native-text.test.ts
index cabeb02a9..fdfb2c5ff 100644
--- a/sdk/tests/native-text.test.ts
+++ b/sdk/tests/native-text.test.ts
@@ -177,6 +177,34 @@ function buildScene(app: ReturnType<typeof createNativeApp>, setScene: (canvas:
}
describe('a frame on the native core', () => {
+ it('fades text fill, shadow and outline together and skips transparent subtrees', async () => {
+ const { scope, submitSpy, setScene } = makeHostScope();
+ let alpha = 0.5;
+ scope.es_getUINodeAlphaInTree = () => alpha;
+ const app = createNativeApp(makeBridge(scope), scope);
+ await app.tick(0);
+ const label = buildScene(app, setScene);
+ app.world.insert(label, Text, {
+ content: 'Fade', fontSize: 32, renderMode: TextRenderMode.Sdf,
+ color: { r: 1, g: 1, b: 1, a: 0.8 },
+ shadowOffsetX: 1, shadowColor: { r: 0, g: 0, b: 0, a: 0.6 },
+ strokeWidth: 1, strokeColor: { r: 0, g: 0, b: 0, a: 0.4 },
+ });
+ await app.tick(1 / 60);
+ expect(submitSpy).toHaveBeenCalledTimes(3);
+ expect((submitSpy.mock.calls[0][0] as Float32Array)[7]).toBeCloseTo(0.3);
+ expect((submitSpy.mock.calls[1][0] as Float32Array)[7]).toBeCloseTo(0.2);
+ expect((submitSpy.mock.calls[2][0] as Float32Array)[7]).toBeCloseTo(0.4);
+ alpha = 0;
+ submitSpy.mockClear();
+ await app.tick(1 / 60);
+ expect(submitSpy).not.toHaveBeenCalled();
+ alpha = 1;
+ await app.tick(1 / 60);
+ expect(submitSpy).toHaveBeenCalledTimes(3);
+ expect((submitSpy.mock.calls[2][0] as Float32Array)[7]).toBeCloseTo(0.8);
+ });
+
it('renders the scene through the SDK pipeline, text and all', async () => {
const { scope, uploads, calls, rasterizeSpy, submitSpy, beginSpy, setScene } = makeHostScope();
const app = createNativeApp(makeBridge(scope), scope);
diff --git a/sdk/tests/ui-text-renderer.test.ts b/sdk/tests/ui-text-renderer.test.ts
index b5a47b2e2..1caaccd17 100644
--- a/sdk/tests/ui-text-renderer.test.ts
+++ b/sdk/tests/ui-text-renderer.test.ts
@@ -29,6 +29,23 @@ function makeAtlas(pageSize: number): GlyphAtlas {
}
describe('REARCH_GUI P1.3b: drawTextWith', () => {
+ it('applies inherited opacity to explicit rich colors and invalidates cached geometry', () => {
+ const atlas = makeAtlas(1024);
+ const sink = vi.fn();
+ const params: DrawTextParams = {
+ text: '<color=#ff000080>A</color>', fontFamily: 'Arial', fontSizePx: 24,
+ color: [1, 1, 1, 1], richText: true, opacity: 0.5,
+ };
+ drawTextWith(atlas, sink, params);
+ expect(sink).toHaveBeenCalledTimes(1);
+ expect((sink.mock.calls[0][0] as Float32Array)[7]).toBeCloseTo(128 / 255 * 0.5);
+ expect(signatureOf(params)).not.toBe(signatureOf({ ...params, opacity: 1 }));
+ expect(signatureOf({ ...params, opacity: undefined })).toBe(signatureOf({ ...params, opacity: 1 }));
+ sink.mockClear();
+ drawTextWith(atlas, sink, { ...params, opacity: 0 });
+ expect(sink).not.toHaveBeenCalled();
+ });
+
it('emits one batch covering all glyphs when they fit on a single page', () => {
const atlas = makeAtlas(1024);
const sink = vi.fn();
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index e3a9c75f4..d633b0854 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'fix(ui): apply inherited opacity to all text passes':
+ { note: 'UI text effects follow inherited opacity.' },
'test(renderer): cover clip recovery between camera passes':
{ internal: 'adds cross-camera regression coverage for empty text and skeletal clips and their recovery; no runtime behavior changes' },
'fix(release): deploy website after mirrored metadata is ready':