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(2d): the samples across a soft shadow's light source are a quality setting
yhh0ed6f1855c9c
diff --git a/desktop b/desktopindex cd4357743..8182250ad 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit cd4357743af9b0f4b7f2b27d2bd5ab1a80777d6d+Subproject commit 8182250ad857b8bf8063539b01a0a477b7aa5015diff --git a/docs/astro/src/content/docs/graphics/lighting.mdx b/docs/astro/src/content/docs/graphics/lighting.mdxindex 3a281a841..bfdeee779 100644--- a/docs/astro/src/content/docs/graphics/lighting.mdx+++ b/docs/astro/src/content/docs/graphics/lighting.mdx@@ -360,7 +360,10 @@ cmds.spawn()Shadow **quality** is controlled on the light, not the caster:- **`shadowSoftness`** — the light-source size. `0` is a crisp hard edge; larger values- give a soft penumbra (a bigger, closer light casts softer shadows).+ give a soft penumbra (a bigger, closer light casts softer shadows). The penumbra is that many+ silhouettes added up, so how smooth it is and what it costs is a quality setting: the profile's+ `shadowSoftSamples` (1 to 32; 8 low, 12 medium, 16 high; **Project Settings → Rendering → Quality**).+ Fewer is cheaper and shows the edge as bands; sixteen is where they stop reading as separate shadows.- **`shadowDistance`** — for a **Directional** light, how far its shadows extend; `0`leaves a directional light shadow-free.- **`shadowStrength`** — how much of the light a shadow takes away, `0..1`. A 2D scenediff --git a/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx b/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdxindex a052a33ed..bc9a6975e 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx@@ -287,7 +287,7 @@ cmds.spawn()阴影**质量**在光源上控制,而非遮挡体:- **`shadowSoftness`** — 光源尺寸。`0` 是锐利硬边;更大的值给出柔和半影(更大、更近的光投出更软的- 阴影)。+ 阴影)。半影是这么多个轮廓叠加出来的,所以它多平滑、花多少,是一个画质设置:档位的 `shadowSoftSamples`(1 到 32;低 8、中 12、高 16;在**项目设置 → 渲染 → 画质**里改)。更少更便宜,边缘会显出条带;十六是条带不再被看成一道道独立阴影的位置。- **`shadowDistance`** — 对 **Directional** 光,阴影延伸多远;`0` 让方向光不产生阴影。### 能放多少,代价是什么diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 09820ee21..439df9abc 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -7799,6 +7799,7 @@ shadowAtlasSize: numbershadowCascades: numbershadowCellSize: numbershadowDistance: number+shadowSoftSamples: numbershelterMaskSize: numberskipEffects: readonly string[]ssao: booleandiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 185074806..1f2a9bf10 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -8002,6 +8002,7 @@ shadowAtlasSize: numbershadowCascades: numbershadowCellSize: numbershadowDistance: number+shadowSoftSamples: numbershelterMaskSize: numberskipEffects: readonly string[]ssao: booleandiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 57ab91aa7..ca89d3c2e 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -7794,6 +7794,7 @@ shadowAtlasSize: numbershadowCascades: numbershadowCellSize: numbershadowDistance: number+shadowSoftSamples: numbershelterMaskSize: numberskipEffects: readonly string[]ssao: booleandiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 73c680d22..ed618c28d 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -8088,6 +8088,7 @@ shadowAtlasSize: numbershadowCascades: numbershadowCellSize: numbershadowDistance: number+shadowSoftSamples: numbershelterMaskSize: numberskipEffects: readonly string[]ssao: booleandiff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex ae33ddfe1..7a4e1028f 100644--- a/sdk/etc/wasm.api.md+++ b/sdk/etc/wasm.api.md@@ -529,6 +529,7 @@ renderer_setMeshEdgeBuffers: ((enabled: boolean) => void) | undefinedrenderer_setOrigin: ((x: number, y: number, z: number) => void) | undefinedrenderer_setPlanarReflectionQuality: ((scale: number, maxSize: number, updatesPerSecond: number) => void) | undefinedrenderer_setQualityBudgets: ((atlasSize: number, cellSize: number, cascades: number, particleLimit: number) => void) | undefined+renderer_setShadow2DSoftSamples: ((samples: number) => void) | undefinedrenderer_setShadowDistance: ((distance: number) => void) | undefinedrenderer_setStage: (stage: number) => voidrenderer_setTextureParams: (textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number) => voiddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex f7a7430de..c8d84e515 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -7801,6 +7801,7 @@ shadowAtlasSize: numbershadowCascades: numbershadowCellSize: numbershadowDistance: number+shadowSoftSamples: numbershelterMaskSize: numberskipEffects: readonly string[]ssao: booleandiff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.tsindex 38ab05a89..7dad759cb 100644--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts@@ -224,6 +224,7 @@ export interface NativeEngineApi {renderer_setOrigin?(x: number, y: number, z: number): void;renderer_setPlanarReflectionQuality?(scale: number, maxSize: number, updatesPerSecond: number): void;renderer_setQualityBudgets?(atlasSize: number, cellSize: number, cascades: number, particleLimit: number): void;+ renderer_setShadow2DSoftSamples?(samples: number): void;renderer_setShadowDistance?(distance: number): void;renderer_setStage?(stage: number): void;renderer_setTextureParams?(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void;@@ -558,6 +559,7 @@ export function createNativeEngineApi(bind('renderer_setOrigin', 'es_renderer_setOrigin', false);bind('renderer_setPlanarReflectionQuality', 'es_renderer_setPlanarReflectionQuality', false);bind('renderer_setQualityBudgets', 'es_renderer_setQualityBudgets', false);+ bind('renderer_setShadow2DSoftSamples', 'es_renderer_setShadow2DSoftSamples', false);bind('renderer_setShadowDistance', 'es_renderer_setShadowDistance', false);bind('renderer_setStage', 'es_renderer_setStage', false);bind('renderer_setTextureParams', 'es_renderer_setTextureParams', false);diff --git a/sdk/src/render/quality.ts b/sdk/src/render/quality.tsindex 2d1f23525..68cb17e36 100644--- a/sdk/src/render/quality.ts+++ b/sdk/src/render/quality.ts@@ -72,6 +72,11 @@ export interface QualityProfile {* a weak device spends less on a smaller one and gets rain whose dry edges are softer.*/shelterMaskSize: number;+ /**+ * How many samples across a light source a soft 2D shadow is drawn with, 1 to 32: a light's `shadowSoftness` is a source with width, and its penumbra+ * is that many silhouettes added up. Fewer is cheaper and shows the edge as bands; sixteen is where the bands stop reading as separate shadows.+ */+ shadowSoftSamples: number;}export interface DeviceQualityRule {@@ -120,7 +125,7 @@ const PROFILES: Record<QualityLevel, QualityProfile> = {shadowDistance: 0, detailScale: 0.5, particleLimit: 1000, postProcess: true, ssao: false,waterWaves: 2, waterRippleCells: 32, waterDisplacement: false, waterMirror: false, waterCaustics: false,skipEffects: ['ssr', 'taa', 'depthOfField', 'lightShafts', 'motionBlur', 'lensFlare', 'gtao', 'subsurface', 'voxelGI'],- shelterMaskSize: 256,+ shelterMaskSize: 256, shadowSoftSamples: 8,},medium: {renderScale: 1, minRenderScale: 0.65, msaaSamples: 2, antialiasing: 'temporal',@@ -129,7 +134,7 @@ const PROFILES: Record<QualityLevel, QualityProfile> = {shadowDistance: 0, detailScale: 0.8, particleLimit: 5000, postProcess: true, ssao: true,waterWaves: 3, waterRippleCells: 64, waterDisplacement: true, waterMirror: true, waterCaustics: true,skipEffects: ['ssr', 'depthOfField'],- shelterMaskSize: 512,+ shelterMaskSize: 512, shadowSoftSamples: 12,},high: {renderScale: 1, minRenderScale: 0.75, msaaSamples: 4, antialiasing: 'msaa',@@ -140,7 +145,7 @@ const PROFILES: Record<QualityLevel, QualityProfile> = {shadowDistance: 0, detailScale: 1, particleLimit: 20000, postProcess: true, ssao: true,waterWaves: 4, waterRippleCells: 128, waterDisplacement: true, waterMirror: true, waterCaustics: true,skipEffects: [],- shelterMaskSize: 1024,+ shelterMaskSize: 1024, shadowSoftSamples: 16,},};@@ -231,6 +236,7 @@ function resolveProfile(level: QualityLevel, value: unknown): QualityProfile {.map((e) => e.trim()).slice(0, 32): base.skipEffects,shelterMaskSize: Math.round(finite(r.shelterMaskSize, base.shelterMaskSize, 64, 2048)),+ shadowSoftSamples: Math.round(finite(r.shadowSoftSamples, base.shadowSoftSamples, 1, 32)),};}diff --git a/sdk/src/render/qualityRuntime.ts b/sdk/src/render/qualityRuntime.tsindex ae5d3f8bb..f121a621b 100644--- a/sdk/src/render/qualityRuntime.ts+++ b/sdk/src/render/qualityRuntime.ts@@ -42,6 +42,8 @@ export function installQuality(app: App, config: QualityConfig, authoredMsaa: nuquality.setLimitation('shadow-distance-unavailable',enabled && applied.shadowDistance > 0 && !api?.renderer_setShadowDistance);api?.renderer_setShadowDistance?.(enabled ? applied.shadowDistance : 0);+ // With no quality policy a soft 2D shadow is drawn with the sixteen samples it always was.+ api?.renderer_setShadow2DSoftSamples?.(enabled ? applied.shadowSoftSamples : 16);api?.renderer_setDepthPrepass?.(enabled && applied.depthPrepass);api?.renderer_setPlanarReflectionQuality?.(enabled ? applied.planarReflectionScale : 0.5,enabled ? applied.planarReflectionMaxSize : 1024,diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.tsindex 7ca1b0023..4902543a8 100644--- a/sdk/src/wasm.ts+++ b/sdk/src/wasm.ts@@ -715,6 +715,8 @@ export interface ESEngineModule {renderer_setQualityBudgets?(atlasSize: number, cellSize: number,cascades: number, particleLimit: number): void;renderer_setShadowDistance?(distance: number): void;+ /** How many samples across a light source a soft 2D shadow is drawn with (1 to 32). */+ renderer_setShadow2DSoftSamples?(samples: number): void;/** Draw the opaque scene twice, depth alone first, so a pixel is shaded for the surface in front of it. */renderer_setDepthPrepass?(on: boolean): void;renderer_setAsyncShaderCompile?(on: boolean): void;diff --git a/sdk/tests/atmosphere-2d.test.ts b/sdk/tests/atmosphere-2d.test.tsindex 099d58191..44895630f 100644--- a/sdk/tests/atmosphere-2d.test.ts+++ b/sdk/tests/atmosphere-2d.test.ts@@ -227,6 +227,9 @@ describe('the 2D rain', () => {expect(defaultQualityProfile('low').shelterMaskSize).toBe(256);expect(defaultQualityProfile('medium').shelterMaskSize).toBe(512);expect(defaultQualityProfile('high').shelterMaskSize).toBe(1024);+ expect([8, 12, 16]).toEqual(['low', 'medium', 'high'].map((l) => defaultQualityProfile(l as 'low').shadowSoftSamples));+ expect(parseQualityConfig({ mode: 'low', profiles: { low: { shadowSoftSamples: 99 }, medium: { shadowSoftSamples: 0 } } }).profiles?.low?.shadowSoftSamples).toBe(32);+ expect(parseQualityConfig({ mode: 'low', profiles: { medium: { shadowSoftSamples: 0 } } }).profiles?.medium?.shadowSoftSamples).toBe(1);const q = parseQualityConfig({ mode: 'low', profiles: { low: { shelterMaskSize: 100000 }, medium: { shelterMaskSize: 'big' } } });expect(q.profiles?.low?.shelterMaskSize).toBe(2048);expect(q.profiles?.medium?.shelterMaskSize).toBe(512);diff --git a/sdk/tests/quality-runtime.test.ts b/sdk/tests/quality-runtime.test.tsindex 0805a280b..68555427f 100644--- a/sdk/tests/quality-runtime.test.ts+++ b/sdk/tests/quality-runtime.test.ts@@ -12,10 +12,10 @@ vi.mock('../src/platform', () => ({platformOnAppHide: () => () => {}, platformOnAppShow: () => () => {},}));vi.mock('../src/ecs/bridge/engineApi', () => ({- engineApi: () => ({ renderer_setQualityBudgets: vi.fn(), renderer_setShadowDistance: distanceBudget, renderer_setPlanarReflectionQuality: reflectionBudget, renderer_setDepthPrepass: prepass, renderer_setAsyncShaderCompile: asyncCompile }),+ engineApi: () => ({ renderer_setQualityBudgets: vi.fn(), renderer_setShadowDistance: distanceBudget, renderer_setShadow2DSoftSamples: softSamples, renderer_setPlanarReflectionQuality: reflectionBudget, renderer_setDepthPrepass: prepass, renderer_setAsyncShaderCompile: asyncCompile }),}));-const { distanceBudget, reflectionBudget, prepass, asyncCompile } = vi.hoisted(() => ({ distanceBudget: vi.fn(), reflectionBudget: vi.fn(), prepass: vi.fn(), asyncCompile: vi.fn() }));+const { distanceBudget, softSamples, reflectionBudget, prepass, asyncCompile } = vi.hoisted(() => ({ distanceBudget: vi.fn(), softSamples: vi.fn(), reflectionBudget: vi.fn(), prepass: vi.fn(), asyncCompile: vi.fn() }));describe('quality runtime device selection', () => {it('applies the tier shadow range and restores camera coverage when disabled', () => {@@ -32,6 +32,18 @@ describe('quality runtime device selection', () => {expect(distanceBudget).toHaveBeenLastCalledWith(0);expect(reflectionBudget).toHaveBeenLastCalledWith(0.5,1024,0);});+ it('draws a soft 2D shadow with the samples of its level, and with the sixteen it always had when the quality system is off', () => {+ let apply: (() => void) | undefined;+ let controller: import('../src/render/quality').QualityController;+ const app = { wasmModule: null, insertResource: (_: unknown, value: typeof controller) => { controller = value; },+ pipeline: { setQuality: (_: unknown, callback: () => void) => { apply = callback; } },+ addPlugin: vi.fn(), onFrameEnd: () => () => {},+ } as unknown as App;+ installQuality(app, { mode: 'low', profiles: { low: { shadowSoftSamples: 6 } } }, 4);+ expect(softSamples).toHaveBeenLastCalledWith(6);+ controller!.setMode('off'); apply!();+ expect(softSamples).toHaveBeenLastCalledWith(16);+ });it('turns the depth prepass on for a level that asks for it and off with the quality system, or for a level that does not', () => {let apply: (() => void) | undefined;let controller: import('../src/render/quality').QualityController;diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cppindex a04f96d73..e7758d3bf 100644--- a/src/esengine/bindings/RendererBindings.cpp+++ b/src/esengine/bindings/RendererBindings.cpp@@ -1274,6 +1274,10 @@ void renderer_setShadowDistance(f32 distance) {if (g_renderFrame) g_renderFrame->setShadowDistance(distance);}+void renderer_setShadow2DSoftSamples(u32 samples) {+ if (g_renderFrame) g_renderFrame->setShadow2DSoftSamples(samples);+}+void renderer_setDepthPrepass(bool on) {if (g_renderFrame) g_renderFrame->setDepthPrepass(on);}diff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hppindex 3636ddfd2..90ca21806 100644--- a/src/esengine/bindings/RendererBindings.hpp+++ b/src/esengine/bindings/RendererBindings.hpp@@ -26,6 +26,7 @@ void renderer_init(u32 width, u32 height);void renderer_resize(u32 width, u32 height);void renderer_setQualityBudgets(u32 atlasSize, u32 cellSize, u32 cascades, u32 particleLimit);void renderer_setShadowDistance(f32 distance);+void renderer_setShadow2DSoftSamples(u32 samples);void renderer_setDepthPrepass(bool on);/*** Draws whose shader the browser is still compiling are left out, not waited for: a frame never stops for a compile, and what needs the shaderdiff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cppindex 6907017db..f3517d3ee 100644--- a/src/esengine/bindings/WebSDKEntry.cpp+++ b/src/esengine/bindings/WebSDKEntry.cpp@@ -792,6 +792,7 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {emscripten::function("renderer_setDepthLayers", &esengine::renderer_setDepthLayers);emscripten::function("renderer_setQualityBudgets", &esengine::renderer_setQualityBudgets);emscripten::function("renderer_setShadowDistance", &esengine::renderer_setShadowDistance);+ emscripten::function("renderer_setShadow2DSoftSamples", &esengine::renderer_setShadow2DSoftSamples);emscripten::function("renderer_setDepthPrepass", &esengine::renderer_setDepthPrepass);emscripten::function("renderer_setAsyncShaderCompile", &esengine::renderer_setAsyncShaderCompile);emscripten::function("renderer_getPendingShaders", &esengine::renderer_getPendingShaders);diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cppindex f0022e683..e5b98835c 100644--- a/src/esengine/renderer/frame/RenderFrame.cpp+++ b/src/esengine/renderer/frame/RenderFrame.cpp@@ -1998,6 +1998,10 @@ void RenderFrame::setShadowDistance(f32 distance) {shadow_distance_ = std::isfinite(distance) ? std::max(distance, 0.0f) : 0.0f;}+void RenderFrame::setShadow2DSoftSamples(u32 samples) {+ shadow_2d_soft_samples_ = std::clamp(samples, 1u, 32u);+}+void RenderFrame::buildShadowPlan(ecs::Registry& registry) {shadow_texture_id_ = 0;shadow_resource_ = rg::kNoResource;diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hppindex 92e0f2f03..382333b77 100644--- a/src/esengine/renderer/frame/RenderFrame.hpp+++ b/src/esengine/renderer/frame/RenderFrame.hpp@@ -112,6 +112,8 @@ public:void resize(u32 width, u32 height);void setShadowBudget(u32 atlasSize, u32 cellSize, u32 cascades);void setShadowDistance(f32 distance);+ /// How many samples across a light source a soft 2D shadow is drawn with: the quality level's say on the penumbra's smoothness and cost.+ void setShadow2DSoftSamples(u32 samples);/// Draws the opaque scene twice, depth alone first (see DrawList::DrawPass). Off unless asked: where a GPU already shades each pixel once/// (a tiled one), the second pass is geometry paid for twice.void setDepthPrepass(bool on) { depth_prepass_ = on; }@@ -1041,6 +1043,7 @@ private:u32 shadow_cell_size_ = kShadowCellSize;u32 shadow_cascades_ = MAX_SHADOW_CASCADES;f32 shadow_distance_ = 0.0f;+ u32 shadow_2d_soft_samples_ = 16;ShadowPlanReport shadow_plan_;LightCapReport light_cap_;ViewLighting view_lighting_;diff --git a/src/esengine/renderer/frame/RenderFrameShadow2D.cpp b/src/esengine/renderer/frame/RenderFrameShadow2D.cppindex 8b6cdbf9d..6db3e32a0 100644--- a/src/esengine/renderer/frame/RenderFrameShadow2D.cpp+++ b/src/esengine/renderer/frame/RenderFrameShadow2D.cpp@@ -34,10 +34,6 @@ constexpr u32 kShadow2DFloats = 7;/// channel of the light it belongs to.constexpr u32 kShape2DFloats = 8;-/// Samples across a source that has width. A penumbra made of samples IS banded,-/// and sixteen is where the bands stop reading as rays from the corner that threw-/// them — one silhouette each, over a scene with tens of occluders.-constexpr u32 kSoftSamples = 16;/// How far past a light's own reach a shadow is extruded. A shadow that stopped/// exactly at the reach would end in a visible edge where the light already@@ -250,7 +246,7 @@ void RenderFrame::buildShadow2DGeometry() {// One silhouette is two triangles, and the worst case is every ring seen by every// sample of every light. Reserved once so the frame's growth is not a re-alloc.shadow_2d_vertices_.reserve(shadow_rings_2d_.size() * shadow_2d_lights_.size()- * kSoftSamples * 6 * kShadow2DFloats);+ * shadow_2d_soft_samples_ * 6 * kShadow2DFloats);auto vertex = [this](const glm::vec2& p, f32 shadow, u32 channel) {shadow_2d_vertices_.push_back(p.x);@@ -269,10 +265,9 @@ void RenderFrame::buildShadow2DGeometry() {for (const Shadow2DLight& light : shadow_2d_lights_) {const u32 channel = light.channel;- // A source with width is sampled across, each sample throwing the silhouette- // it sees at its own share. The shares add, which is the soft edge: hidden from- // every sample collects all of them, from half collects half.- const u32 samples = light.softness > 1e-4f ? kSoftSamples : 1u;+ // A source with width is sampled across, each sample throwing its silhouette at its own share; the shares add, which is the+ // soft edge. A penumbra made of samples IS banded: sixteen is where the bands stop reading as rays from the corner that threw them.+ const u32 samples = light.softness > 1e-4f ? shadow_2d_soft_samples_ : 1u;const f32 share = 1.0f / static_cast<f32>(samples);// How far a sample sits from the middle of the source, in -1..1.const auto offsetOf = [samples](u32 s) {diff --git a/tools/check-project-settings.mjs b/tools/check-project-settings.mjsindex dfc788ed4..a305259be 100644--- a/tools/check-project-settings.mjs+++ b/tools/check-project-settings.mjs@@ -297,6 +297,7 @@ const BLOCKS = [waterMirror: { ui: 'project.rendering.quality.waterMirror' },waterCaustics: { ui: 'project.rendering.quality.waterCaustics' },shelterMaskSize: { ui: 'project.rendering.quality.shelterMaskSize' },+ shadowSoftSamples: { ui: 'project.rendering.quality.shadowSoftSamples' },skipEffects: { ui: 'project.rendering.quality.effects' },},},