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(quality): low and medium light 3D surfaces directly, so a phone pays about half for a lit scene

yhh368f509640f6
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6cf1e1452..0b7bd3196 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,14 @@ published separately; it ships inside the editor.
## [Unreleased]
+### Added
+
+- **On a phone, a lit 3D scene costs about half as much.** The quality level gains `lighting`. At `low` and `medium`, which a phone takes when the project names no level, every lit mesh and material is compiled as `#pragma lighting direct` asks: the same lighting model with the sixteen lights of the light block and hard shadows, without the lights past them, soft shadows or hair shadows. On a Snapdragon 8 Elite a full-screen lit floor drawn fifteen times over went from 57 to 24 ms a frame under the default soft-shadowed sun, and from 33 to 25 ms under a hard-shadowed one. `high`, and a project with quality off, keep everything. **Project Settings → Rendering → Quality → 3D lighting** changes it per level. Sprites keep their 2D lighting at every level.
+
+### Fixed
+
+- **A `#pragma lighting direct` surface takes a sun's shadow.** Under a directional light with a size (any `sourceAngle` above 0, the default 0.53 included) such a shader drew no shadow at all; it now draws the hard shadow the directive promises.
+
## [0.99.1] - 2026-11-07
### Fixed
diff --git a/desktop b/desktop
index 6b69b1b29..20c2a139f 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 6b69b1b298968d99498933ac9245136bb21d0f08
+Subproject commit 20c2a139f9a75cbe00a0d581a3379b045a7ce21b
diff --git a/docs/astro/src/content/docs/graphics/lighting.mdx b/docs/astro/src/content/docs/graphics/lighting.mdx
index 8437da9ee..4e829ed1e 100644
--- a/docs/astro/src/content/docs/graphics/lighting.mdx
+++ b/docs/astro/src/content/docs/graphics/lighting.mdx
@@ -435,6 +435,35 @@ The disc is hidden by what stands in front of it and draws no depth of its own.
steps or land on a wall, so use it where a grounding cue is enough, and a real shadow where the shape of the shadow matters. The disc is an entity of its
own that is never saved with the scene.
+## Lighting on a phone
+
+There is one lighting model: a lit 3D surface, a lit sprite and a material's `applyLightingPBR` all go through the same BRDF. What changes with the
+device is how much of the engine's lighting a shader is compiled with. The quality level's **`lighting`** says it: at `full` a lit mesh takes the lights
+past the sixteen of the light block, soft shadows from a source with size, hair shadows and the 2D light masks; at `direct` it is compiled as
+`#pragma lighting direct` asks, with the sixteen lights and hard shadows only. `low` and `medium` are `direct` (a phone takes `medium` when the project
+names no level), `high` is `full`, and with the quality system off everything is `full`. Change it per level under **Project Settings → Rendering →
+Quality → 3D lighting**, or in code:
+
+```typescript
+quality: { profiles: { medium: { lighting: 'full' } } }
+```
+
+Most of what `direct` saves is not the work it skips but the size of the shader: a program carrying the tiled lights and the soft-shadow search keeps
+more registers in use and runs fewer pixels at once even where none of it executes. On a Snapdragon 8 Elite, a full-screen lit floor drawn fifteen
+times over under a sun at the default `sourceAngle`, with the same settings otherwise:
+
+| | `full` | `direct` |
+|---|---|---|
+| Built-in mesh shader, soft-shadowed sun | 57 ms | 24 ms |
+| Built-in mesh shader, hard-shadowed sun (`sourceAngle: 0`) | 33 ms | 25 ms |
+| A material with `specular` 0, soft-shadowed sun | 41 ms | under 17 ms (the 60 fps cap) |
+
+Sprites keep their 2D lighting at every level: the 2D shadow and shape masks are how a 2D scene draws its shadows.
+
+What the level does not decide is what a surface is. A highlight belongs to the material: a material whose `specular` is 0 skips the lobe for every
+light (the measurement above), and a whole scene of matte surfaces is cheaper for it. Past that, the cheapest shadows are a
+[blob shadow](#blob-shadows-a-disc-instead-of-a-shadow-map) under each moving thing and [baked light](#baked-light) for what stands still.
+
## Baked light
A frame carries 112 lights: sixteen read for every pixel and 96 tiled (see
diff --git a/docs/astro/src/content/docs/graphics/materials.mdx b/docs/astro/src/content/docs/graphics/materials.mdx
index 6ae526902..db87e5619 100644
--- a/docs/astro/src/content/docs/graphics/materials.mdx
+++ b/docs/astro/src/content/docs/graphics/materials.mdx
@@ -172,7 +172,7 @@ One file holds every stage plus its metadata, separated by pragmas:
| `#pragma param …` | A reflected material parameter (table below). |
| `#pragma switch NAME [default(on)]` | Material-facing static permutation toggle (a `#define`). |
| `#pragma feature NAME` | Engine-chosen compile-time variant keyword. |
-| `#pragma lighting direct` | A `Lit` shader lit by the sixteen lights of the block and hard-edged shadows only. It compiles without the tiled lights past those sixteen, the 2D light masks, and soft and hair shadows, which every pixel pays for on a phone whether a scene uses them or not. The Water shader declares it. |
+| `#pragma lighting direct` | A `Lit` shader lit by the sixteen lights of the block and hard-edged shadows only. It compiles without the tiled lights past those sixteen, the 2D light masks, and soft and hair shadows, which every pixel pays for on a phone whether a scene uses them or not. A light with a size (a sun's `sourceAngle`) casts a hard shadow here. The Water shader declares it, and the `low` and `medium` quality levels compile every lit mesh this way (see [Lighting on a phone](/docs/graphics/lighting/#lighting-on-a-phone)). |
| `#pragma coverage PARAM` | While the float param `PARAM` is above zero, the shader's output alpha is coverage — a cutout's alpha sharpened to about a pixel around the cutoff (`cutoutCoverage(alpha, cutoff, fwidth(alpha))`). An opaque draw into a multisampled target then turns it into multisample coverage, so the cutout's edge is antialiased instead of stair-stepped; without multisampling it is the hard cut. The cut is at the cutoff at every distance, as glTF's MASK is: a cutout seen small keeps its area because the cook rescales its mips' alpha to the coverage the full image has at the cutoff. The built-in Model shader declares `u_alphaCutoff`. |
| `#pragma hairshadow PARAM` | While the float param `PARAM` is above zero, meshes drawn with the material are hair for shadows: the sun's cascades gain one fitted to them alone, and a shader that sets `g_hairShadow` before it lights reads the shadow as a density along the light instead of a hard compare. The value is the density. The built-in Hair shader declares `u_hairShadow`. |
| `#pragma gbuffer` | A `PostProcess` shader reads the scene's surface record (see [the G-buffer](/docs/graphics/post-processing/#the-g-buffer)) at `u_gbuffer`. Declaring it is what makes the frame draw one; a chain whose shaders do not never pays for it. |
diff --git a/docs/astro/src/content/docs/performance/quality-levels.mdx b/docs/astro/src/content/docs/performance/quality-levels.mdx
index b28514ebf..4d3545b2d 100644
--- a/docs/astro/src/content/docs/performance/quality-levels.mdx
+++ b/docs/astro/src/content/docs/performance/quality-levels.mdx
@@ -31,7 +31,7 @@ to.
| Group | Settings |
|---|---|
| Rendering | Render scale, Min render scale, Anti-aliasing (MSAA or Temporal), MSAA, Depth pre-pass, Detail distance, Draw call budget, Texture streaming and its budget, 2D rain shelter mask |
-| Shadows | Atlas size, Cell size, Cascades, Distance, 2D soft-shadow samples |
+| Shadows | 3D lighting (Full or Direct), Atlas size, Cell size, Cascades, Distance, 2D soft-shadow samples |
| Reflections and particles | Planar reflection scale, max size and updates per second, Particle limit |
| Water | Water waves (1 to 4), Water ripple cells, and the Displacement, Mirror and Caustics switches. Shown once the level is not Off and the water module is in the build |
| Post-processing | A master switch, and a tick for each effect that runs at this level |
@@ -46,6 +46,10 @@ is chosen. **Depth pre-pass** draws the opaque scene twice, depth alone first, s
front. It pays where surfaces overlap (a wood, a crowd of foliage) on a GPU that shades what it rasterises; on one that defers
shading to the end of a tile it is geometry paid for twice. It is off at Low and on at Medium and High. The default anti-aliasing is MSAA at Low (one sample) and High (4), and Temporal at Medium. The pre-pass and the colour pass declare the vertex position invariant on both WebGL2 and WebGPU, so a surface's colour always passes the equal-depth test against its own depth, including on Metal; a Mac that showed dark triangles on terrain with the pre-pass on needs nothing but an up-to-date build.
+**3D lighting** is Full or Direct. Direct compiles every lit mesh as `#pragma lighting direct` does: the same lighting model with the sixteen lights of
+the light block and hard shadows, without the lights past them, soft shadows or hair shadows. A full-screen lit floor on a phone costs about half as much
+(see [Lighting on a phone](/docs/graphics/lighting/#lighting-on-a-phone)). Low and Medium are Direct, High is Full; sprites keep their 2D lighting either way.
+
<Aside type="note">
A row's "default" is the default of the level it is showing, so the same number can be a change at Low and the default
at Medium.
diff --git a/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx b/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx
index 17fb259c6..2acb370b4 100644
--- a/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx
+++ b/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx
@@ -390,6 +390,26 @@ cmds.spawn()
圆片会被挡在它前面的东西遮住,自己不写深度。它不是光源的阴影:不会随太阳拉长,不会落在台阶或墙上,所以只需要"落地感"时用它,阴影形状要紧的地方还是用真阴影。圆片是自己的一个实体,不会随场景保存。
+## 手机上的光照
+
+光照模型只有一套:受光的 3D 表面、受光的精灵、材质里的 `applyLightingPBR`,用的都是同一个 BRDF。随设备变化的,是着色器编译时带上引擎光照的多少。这由画质档的 **`lighting`** 决定:`full` 时受光网格带上光源块十六盏之外的灯、有尺寸光源的软阴影、头发阴影和 2D 光遮罩;`direct` 时按 `#pragma lighting direct` 编译,只有十六盏灯和硬阴影。`low` 和 `medium` 是 `direct`(项目没指定档位时手机用 `medium`),`high` 是 `full`,关掉画质系统时一律 `full`。可以在 **项目设置 → 渲染 → 画质 → 3D 光照** 里按档位改,或者在代码里:
+
+```typescript
+quality: { profiles: { medium: { lighting: 'full' } } }
+```
+
+`direct` 省下的大头不是它跳过的计算,而是着色器的体积:带着分块灯和软阴影搜索的程序,哪怕这些分支一行都不执行,也会占用更多寄存器,同时能跑的像素更少。在骁龙 8 Elite 上,一块铺满全屏的受光地板叠画十五层、太阳为默认的 `sourceAngle`,其余设置相同:
+
+| | `full` | `direct` |
+|---|---|---|
+| 内置网格着色器,软阴影太阳 | 57 ms | 24 ms |
+| 内置网格着色器,硬阴影太阳(`sourceAngle: 0`) | 33 ms | 25 ms |
+| `specular` 为 0 的材质,软阴影太阳 | 41 ms | 低于 17 ms(60 帧封顶) |
+
+精灵在任何档位都保留 2D 光照:2D 阴影和形状遮罩就是 2D 场景画影子的方式。
+
+档位不决定表面是什么。高光属于材质:`specular` 为 0 的材质对每盏灯都跳过高光项(上表最后一行),整个场景都是哑光表面时会更省。再往下,最省的影子是给移动物体用[假阴影](#假阴影用一个圆片代替阴影图),不动的部分用[烘焙光照](#烘焙光照)。
+
## 烘焙光照
一帧最多携带 112 盏灯:16 盏对每个像素都读取,96 盏分块(见「多盏光」)。超出的会被丢掉——按亮度取舍,
diff --git a/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx b/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx
index bc2885437..06b1aec0c 100644
--- a/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx
+++ b/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx
@@ -142,7 +142,7 @@ Terrain、Foliage、Water、Hair、Skin、Eye 这几个模板属于各自的模
| `#pragma switch NAME [default(on)]` | 材质可控的静态排列开关(一个 `#define`)。 |
| `#pragma coverage PARAM` | 浮点参数 `PARAM` 大于零时,着色器输出的 alpha 就是覆盖率——镂空的 alpha 在阈值附近锐化到约一个像素宽(`cutoutCoverage(alpha, cutoff, fwidth(alpha))`)。不透明物体画进多重采样目标时,它会转成多重采样覆盖率,镂空边缘就有抗锯齿而不是台阶;没有多重采样时就是硬切。任何距离都在阈值处切,与 glTF 的 MASK 定义一致:镂空缩小显示时之所以还保持原来的面积,是因为烘焙时把每级 mip 的 alpha 缩放到与原图在阈值处相同的覆盖率。内置 Model 着色器声明了 `u_alphaCutoff`。 |
| `#pragma feature NAME` | 引擎选择的编译期变体关键字。 |
-| `#pragma lighting direct` | `Lit` 着色器只接受光源块里的十六盏灯和硬边阴影。编译时去掉十六盏之外的分块光源、2D 光遮罩、软阴影和头发阴影;这些分支无论场景用不用,手机上每个像素都要付出代价。Water 着色器声明了它。 |
+| `#pragma lighting direct` | `Lit` 着色器只接受光源块里的十六盏灯和硬边阴影。编译时去掉十六盏之外的分块光源、2D 光遮罩、软阴影和头发阴影;这些分支无论场景用不用,手机上每个像素都要付出代价。有尺寸的光源(太阳的 `sourceAngle`)在这里投硬阴影。Water 着色器声明了它;画质的 `low`、`medium` 档会把所有受光网格都这样编译(见[手机上的光照](/docs/zh-cn/graphics/lighting/#手机上的光照))。 |
| `#pragma hairshadow PARAM` | 浮点参数 `PARAM` 大于零时,用这个材质画的网格就是阴影意义上的头发:太阳的级联多出一个只拟合它们的级联,并且着色器在打光前设置 `g_hairShadow` 的话,阴影就按沿光线的密度读,而不是硬比较。参数值就是密度。内置 Hair 着色器声明了 `u_hairShadow`。 |
| `#pragma gbuffer` | `PostProcess` 着色器要读取场景的表面记录(见[G-buffer](/docs/zh-cn/graphics/post-processing/#g-buffer)),在 `u_gbuffer` 处。声明它才会让这一帧画出一份;着色器里没有它的链路永远不付这笔钱。 |
| `#pragma vertex` / `#pragma fragment` … `#pragma end` | Stage 代码体。**2D 域的顶点段可省略**——引擎注入规范顶点段。 |
diff --git a/docs/astro/src/content/docs/zh-cn/performance/quality-levels.mdx b/docs/astro/src/content/docs/zh-cn/performance/quality-levels.mdx
index 6f1eb5f70..c0120f047 100644
--- a/docs/astro/src/content/docs/zh-cn/performance/quality-levels.mdx
+++ b/docs/astro/src/content/docs/zh-cn/performance/quality-levels.mdx
@@ -29,7 +29,7 @@ import { Aside } from '@astrojs/starlight/components';
| 分组 | 设置 |
|---|---|
| 渲染 | 渲染比例、最小渲染比例、抗锯齿方式(MSAA 或时间性)、MSAA、深度预通道、细节距离、Draw call 预算、贴图流式加载及其预算、2D 雨遮罩尺寸 |
-| 阴影 | 图集尺寸、单元尺寸、级联数、距离、2D 软阴影采样数 |
+| 阴影 | 3D 光照(完整或直接)、图集尺寸、单元尺寸、级联数、距离、2D 软阴影采样数 |
| 反射与粒子 | 平面反射的比例、最大尺寸和每秒更新次数,粒子上限 |
| 水体 | 水体波数(1 到 4)、水体涟漪格数,以及位移、镜面、焦散三个开关。档位不是关闭、且构建里带水体模块时才显示 |
| 后处理 | 总开关,以及在这个档位运行的每个效果的勾选框 |
@@ -39,6 +39,8 @@ import { Aside } from '@astrojs/starlight/components';
**抗锯齿方式**可选 MSAA 或时间性(TAA)。时间性按 1 个采样绘制,由 TAA 通道用之前的帧来平滑:1080p 下便宜得多,画面略软,需要相机上有后处理体积;选它时 MSAA 一行会隐藏。**深度预通道**把不透明场景画两遍,先只画深度,让每个像素只为最前面的表面着色一次。表面大量重叠(树林、成片植被)且 GPU 对光栅化出的像素立即着色时划算;对把着色推迟到分块末尾的 GPU,等于几何多付一遍。低档默认关,中、高档默认开。默认抗锯齿方式:低档 MSAA(1 个采样)、高档 MSAA(4 个采样)、中档时间性。预通道和颜色通道在 WebGL2 与 WebGPU 上都把顶点位置声明为 invariant,所以表面的颜色总能通过与自己深度的等深测试,Metal 上也一样;Mac 上开着预通道时地形出现暗色三角形,只需更新到新的构建。
+**3D 光照**可选完整或直接。直接按 `#pragma lighting direct` 编译所有受光网格:同一套光照模型,只有光源块里的十六盏灯和硬阴影,没有十六盏之外的灯、软阴影和头发阴影。手机上铺满全屏的受光地板成本约减半(见[手机上的光照](/docs/zh-cn/graphics/lighting/#手机上的光照))。低档和中档是直接,高档是完整;精灵的 2D 光照两种都不变。
+
<Aside type="note">
一行的"默认值"是它正显示的那个档位的默认值,所以同一个数字在低档可能是改动,在中档却是默认。
</Aside>
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index d785a73f7..508768047 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -8238,6 +8238,7 @@ antialiasing: "msaa" | "temporal"
depthPrepass: boolean
detailScale: number
drawCallBudget: number
+lighting: "full" | "direct"
minRenderScale: number
msaaSamples: 2 | 1 | 4 | 8
particleLimit: number
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 7d6525301..5bcbe2203 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -8444,6 +8444,7 @@ antialiasing: "msaa" | "temporal"
depthPrepass: boolean
detailScale: number
drawCallBudget: number
+lighting: "full" | "direct"
minRenderScale: number
msaaSamples: 2 | 1 | 4 | 8
particleLimit: number
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index d22b5007b..01054e220 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -8233,6 +8233,7 @@ antialiasing: "msaa" | "temporal"
depthPrepass: boolean
detailScale: number
drawCallBudget: number
+lighting: "full" | "direct"
minRenderScale: number
msaaSamples: 2 | 1 | 4 | 8
particleLimit: number
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 040f1645a..0d3a14649 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -8529,6 +8529,7 @@ antialiasing: "msaa" | "temporal"
depthPrepass: boolean
detailScale: number
drawCallBudget: number
+lighting: "full" | "direct"
minRenderScale: number
msaaSamples: 2 | 1 | 4 | 8
particleLimit: number
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index ab33de0e4..f1ff37bd9 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -543,6 +543,7 @@ renderer_setDepthLayers: ((mask: number) => void) | undefined
renderer_setDepthPrepass: ((on: boolean) => void) | undefined
renderer_setEntityDrawOrder: ((registry: CppRegistry, entitiesPtr: number, count: number) => void) | undefined
renderer_setImpostorAtlas: ((entity: number, texture: number, frames: number) => void) | undefined
+renderer_setLightingDirect: ((on: boolean) => void) | undefined
renderer_setLodPreview: ((view: number, entity: number, level: number) => void) | undefined
renderer_setMeshEdgeBuffers: ((enabled: boolean) => void) | undefined
renderer_setOrigin: ((x: number, y: number, z: number) => void) | undefined
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 62941351b..89b72b18f 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -8240,6 +8240,7 @@ antialiasing: "msaa" | "temporal"
depthPrepass: boolean
detailScale: number
drawCallBudget: number
+lighting: "full" | "direct"
minRenderScale: number
msaaSamples: 2 | 1 | 4 | 8
particleLimit: number
diff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
index 89e0e2b83..8c010c449 100644
--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
@@ -222,6 +222,7 @@ export interface NativeEngineApi {
renderer_setDepthPrepass?(on: boolean): void;
renderer_setEntityDrawOrder?(registry: unknown, entitiesPtr: number, count: number): void;
renderer_setImpostorAtlas?(entity: number, texture: number, frames: number): void;
+ renderer_setLightingDirect?(on: boolean): void;
renderer_setLodPreview?(view: number, entity: number, level: number): void;
renderer_setMeshEdgeBuffers?(enabled: boolean): void;
renderer_setOrigin?(x: number, y: number, z: number): void;
@@ -563,6 +564,7 @@ export function createNativeEngineApi(
bind('renderer_setDepthPrepass', 'es_renderer_setDepthPrepass', false);
bind('renderer_setEntityDrawOrder', 'es_renderer_setEntityDrawOrder', true);
bind('renderer_setImpostorAtlas', 'es_renderer_setImpostorAtlas', false);
+ bind('renderer_setLightingDirect', 'es_renderer_setLightingDirect', false);
bind('renderer_setLodPreview', 'es_renderer_setLodPreview', false);
bind('renderer_setMeshEdgeBuffers', 'es_renderer_setMeshEdgeBuffers', false);
bind('renderer_setOrigin', 'es_renderer_setOrigin', false);
diff --git a/sdk/src/render/quality.ts b/sdk/src/render/quality.ts
index 4e8e986f8..47f9ada45 100644
--- a/sdk/src/render/quality.ts
+++ b/sdk/src/render/quality.ts
@@ -81,6 +81,7 @@ export interface QualityProfile {
* 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;
+ lighting: 'full' | 'direct';
/**
* The most draws a frame at this level should ask of the GPU, every pass counted (shadows, prepass, reflections and post-processing with the
* scene). Nothing is held back to meet it: the profiler and the stats overlay show a frame over it, and the frame debugger says where the draws
@@ -148,7 +149,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, shadowSoftSamples: 8, drawCallBudget: 150, textureStreaming: true, textureStreamingBudget: 128,
+ shelterMaskSize: 256, shadowSoftSamples: 8, lighting: 'direct', drawCallBudget: 150, textureStreaming: true, textureStreamingBudget: 128,
},
medium: {
renderScale: 1, minRenderScale: 0.65, msaaSamples: 2, antialiasing: 'temporal',
@@ -157,7 +158,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, shadowSoftSamples: 12, drawCallBudget: 400, textureStreaming: true, textureStreamingBudget: 256,
+ shelterMaskSize: 512, shadowSoftSamples: 12, lighting: 'direct', drawCallBudget: 400, textureStreaming: true, textureStreamingBudget: 256,
},
high: {
renderScale: 1, minRenderScale: 0.75, msaaSamples: 4, antialiasing: 'msaa',
@@ -168,7 +169,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, shadowSoftSamples: 16, drawCallBudget: 1500, textureStreaming: false, textureStreamingBudget: 0,
+ shelterMaskSize: 1024, shadowSoftSamples: 16, lighting: 'full', drawCallBudget: 1500, textureStreaming: false, textureStreamingBudget: 0,
},
};
@@ -282,6 +283,7 @@ function resolveProfile(level: QualityLevel, value: unknown): QualityProfile {
: base.skipEffects,
shelterMaskSize: Math.round(finite(r.shelterMaskSize, base.shelterMaskSize, 64, 2048)),
shadowSoftSamples: Math.round(finite(r.shadowSoftSamples, base.shadowSoftSamples, 1, 32)),
+ lighting: r.lighting === 'full' || r.lighting === 'direct' ? r.lighting : base.lighting,
drawCallBudget: Math.round(finite(r.drawCallBudget, base.drawCallBudget, 1, 100000)),
textureStreaming: typeof r.textureStreaming === 'boolean' ? r.textureStreaming : base.textureStreaming,
textureStreamingBudget: Math.round(finite(r.textureStreamingBudget, base.textureStreamingBudget, 0, 65536)),
diff --git a/sdk/src/render/qualityRuntime.ts b/sdk/src/render/qualityRuntime.ts
index 9d7691621..beba2c32b 100644
--- a/sdk/src/render/qualityRuntime.ts
+++ b/sdk/src/render/qualityRuntime.ts
@@ -47,6 +47,7 @@ export function installQuality(app: App, config: QualityConfig, authoredMsaa: nu
// 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_setLightingDirect?.(enabled && applied.lighting === 'direct');
api?.renderer_setPlanarReflectionQuality?.(enabled ? applied.planarReflectionScale : 0.5,
enabled ? applied.planarReflectionMaxSize : 1024,
enabled ? applied.planarReflectionUpdatesPerSecond : 0);
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index 0edb72a7f..660aee613 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -730,6 +730,7 @@ export interface ESEngineModule {
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_setLightingDirect?(on: boolean): void;
renderer_setAsyncShaderCompile?(on: boolean): void;
renderer_getPendingShaders?(): number;
renderer_setPlanarReflectionQuality?(scale: number, maxSize: number, updatesPerSecond: number): void;
diff --git a/sdk/tests/quality-runtime.test.ts b/sdk/tests/quality-runtime.test.ts
index 68555427f..0c7e6b058 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_setShadow2DSoftSamples: softSamples, 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_setLightingDirect: lightingDirect, renderer_setAsyncShaderCompile: asyncCompile }),
}));
-const { distanceBudget, softSamples, reflectionBudget, prepass, asyncCompile } = vi.hoisted(() => ({ distanceBudget: vi.fn(), softSamples: vi.fn(), reflectionBudget: vi.fn(), prepass: vi.fn(), asyncCompile: vi.fn() }));
+const { distanceBudget, softSamples, reflectionBudget, prepass, lightingDirect, asyncCompile } = vi.hoisted(() => ({ distanceBudget: vi.fn(), softSamples: vi.fn(), reflectionBudget: vi.fn(), prepass: vi.fn(), lightingDirect: vi.fn(), asyncCompile: vi.fn() }));
describe('quality runtime device selection', () => {
it('applies the tier shadow range and restores camera coverage when disabled', () => {
@@ -60,6 +60,26 @@ describe('quality runtime device selection', () => {
controller!.setMode('off'); apply!();
expect(prepass).toHaveBeenLastCalledWith(false);
});
+ it('lights 3D surfaces directly at the levels a phone runs, fully at high, and fully with the quality system 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: 'medium' }, 4);
+ expect(lightingDirect).toHaveBeenLastCalledWith(true);
+ controller!.setMode('low'); apply!();
+ expect(lightingDirect).toHaveBeenLastCalledWith(true);
+ controller!.setMode('high'); apply!();
+ expect(lightingDirect).toHaveBeenLastCalledWith(false);
+ controller!.setMode('off'); apply!();
+ expect(lightingDirect).toHaveBeenLastCalledWith(false);
+ installQuality(app, { mode: 'medium', profiles: { medium: { lighting: 'full' } } }, 4);
+ expect(lightingDirect).toHaveBeenLastCalledWith(false);
+ installQuality(app, { mode: 'high', profiles: { high: { lighting: 'bogus' as never } } }, 4);
+ expect(lightingDirect).toHaveBeenLastCalledWith(false);
+ });
it('leaves shader compiles waited for unless the config asks for them not to be, whatever the level', () => {
const app = { wasmModule: null, insertResource: vi.fn(), addPlugin: vi.fn(), onFrameEnd: () => () => {} } as unknown as App;
installQuality(app, { mode: 'high' }, 4);
diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cpp
index b343c3a75..a444682f9 100644
--- a/src/esengine/bindings/RendererBindings.cpp
+++ b/src/esengine/bindings/RendererBindings.cpp
@@ -1295,6 +1295,10 @@ void renderer_setShadow2DSoftSamples(u32 samples) {
if (g_renderFrame) g_renderFrame->setShadow2DSoftSamples(samples);
}
+void renderer_setLightingDirect(bool on) {
+ if (g_renderFrame) g_renderFrame->setLightingDirect(on);
+}
+
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.hpp
index 923177c06..82645546f 100644
--- a/src/esengine/bindings/RendererBindings.hpp
+++ b/src/esengine/bindings/RendererBindings.hpp
@@ -28,6 +28,7 @@ void renderer_setQualityBudgets(u32 atlasSize, u32 cellSize, u32 cascades, u32 p
void renderer_setShadowDistance(f32 distance);
void renderer_setShadow2DSoftSamples(u32 samples);
void renderer_setDepthPrepass(bool on);
+void renderer_setLightingDirect(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 shader
* appears when it is done (several at once compile side by side, which the waiting form never gives them). Off (the default) is a frame that waits.
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index 84cdd86fe..deeb3ff0a 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -798,6 +798,7 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {
emscripten::function("renderer_setShadowDistance", &esengine::renderer_setShadowDistance);
emscripten::function("renderer_setShadow2DSoftSamples", &esengine::renderer_setShadow2DSoftSamples);
emscripten::function("renderer_setDepthPrepass", &esengine::renderer_setDepthPrepass);
+ emscripten::function("renderer_setLightingDirect", &esengine::renderer_setLightingDirect);
emscripten::function("renderer_setAsyncShaderCompile", &esengine::renderer_setAsyncShaderCompile);
emscripten::function("renderer_getPendingShaders", &esengine::renderer_getPendingShaders);
emscripten::function("renderer_setPlanarReflectionQuality", &esengine::renderer_setPlanarReflectionQuality);
diff --git a/src/esengine/renderer/RenderTypePlugin.hpp b/src/esengine/renderer/RenderTypePlugin.hpp
index 52d1094fe..bb6f866a7 100644
--- a/src/esengine/renderer/RenderTypePlugin.hpp
+++ b/src/esengine/renderer/RenderTypePlugin.hpp
@@ -90,6 +90,7 @@ struct RenderFrameContext {
/// Absent for an orthographic camera, which has no position to be far from.
glm::vec3 view_eye{0.0f};
bool has_view_eye = false;
+ bool lighting_direct = false;
};
/** @brief What every plugin needs to know about the camera, derived once per collect
diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cpp
index 7687922a3..9842dc183 100644
--- a/src/esengine/renderer/frame/RenderFrame.cpp
+++ b/src/esengine/renderer/frame/RenderFrame.cpp
@@ -1466,6 +1466,7 @@ RenderFrameContext RenderFrame::makeContext() {
shadow_texture_id_,
environment_texture_id_
};
+ ctx.lighting_direct = lighting_direct_;
const glm::vec4 eye = cameraFromViewProjection(view_projection_);
ctx.has_view_eye = eye.w > 0.5f;
if (ctx.has_view_eye) ctx.view_eye = glm::vec3(eye);
@@ -2068,6 +2069,11 @@ void RenderFrame::setShadowDistance(f32 distance) {
shadow_distance_ = std::isfinite(distance) ? std::max(distance, 0.0f) : 0.0f;
}
+void RenderFrame::setLightingDirect(bool on) {
+ lighting_direct_ = on;
+ context_.materials().setLightingDirect(on);
+}
+
void RenderFrame::setShadow2DSoftSamples(u32 samples) {
shadow_2d_soft_samples_ = std::clamp(samples, 1u, 32u);
}
diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hpp
index 28f87a43b..caf6f5280 100644
--- a/src/esengine/renderer/frame/RenderFrame.hpp
+++ b/src/esengine/renderer/frame/RenderFrame.hpp
@@ -119,6 +119,8 @@ public:
/// 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; }
+ void setLightingDirect(bool on);
+ bool lightingDirect() const { return lighting_direct_; }
void setPlanarQuality(f32 scale, u32 maxSize, f32 updatesPerSecond);
/**
* @brief Note that a view drew a mesh with texture @p texture (a resource handle) where it needs @p side texels across for a texel to
@@ -1081,6 +1083,7 @@ private:
glm::vec2 scene_jitter_{0.0f};
/// Whether the opaque scene is drawn twice, depth alone first. See DrawList::DrawPass.
bool depth_prepass_ = false;
+ bool lighting_direct_ = false;
/// One per view, kept across frames for the capacity. The whole pass is collected
/// before any of it is drawn, so a view's commands have to outlive its collect.
std::vector<DrawList> shadow_view_lists_;
diff --git a/src/esengine/renderer/plugins/MeshPlugin.cpp b/src/esengine/renderer/plugins/MeshPlugin.cpp
index bf29ecc46..5837c83fd 100644
--- a/src/esengine/renderer/plugins/MeshPlugin.cpp
+++ b/src/esengine/renderer/plugins/MeshPlugin.cpp
@@ -259,11 +259,11 @@ void reportLodAuthoring(const LodLevels& levels, bool& warned) {
u32 meshVariant(bool normals, bool lit, bool normalMapped, bool skinned, bool depthOnly,
bool envMapped, bool lightmapped, bool weightHeat = false, bool gbuffer = false,
- bool motion = false, bool tangents = false) {
+ bool motion = false, bool tangents = false, bool direct = false) {
return (normals ? 1u : 0u) | (lit ? 2u : 0u) | (normalMapped ? 4u : 0u)
| (skinned ? 8u : 0u) | (depthOnly ? 16u : 0u) | (envMapped ? 32u : 0u)
| (lightmapped ? 64u : 0u) | (weightHeat ? 128u : 0u) | (gbuffer ? 256u : 0u)
- | (motion ? 512u : 0u) | (tangents ? 1024u : 0u);
+ | (motion ? 512u : 0u) | (tangents ? 1024u : 0u) | (direct ? 2048u : 0u);
}
/**
@@ -312,7 +312,7 @@ struct MeshDrawKeys {
u32 normalTextureId = 0;
};
-u32 meshVariantFrom(const MeshProgramFacts& facts, bool envMapped, bool shadowDepth, bool weightHeat = false,
+u32 meshVariantFrom(const MeshProgramFacts& facts, bool envMapped, bool shadowDepth, bool direct, bool weightHeat = false,
bool gbuffer = false) {
// `lightmapped` and `tangents` survive the shadow pass, unlike the three describing shading: each declares a vertex attribute.
// Weights are read off the surface of a skinned draw and nothing else's: the colour is
@@ -322,7 +322,7 @@ u32 meshVariantFrom(const MeshProgramFacts& facts, bool envMapped, bool shadowDe
// The surface record is for what takes light: an unlit surface has no normal worth recording.
return meshVariant(facts.hasNormals, lit,
facts.normalTextureId != 0 && !shadowDepth && !heat, facts.skinned, shadowDepth,
- envMapped, facts.lightmapped, heat, gbuffer && lit, false, facts.tangents);
+ envMapped, facts.lightmapped, heat, gbuffer && lit, false, facts.tangents, direct && lit);
}
/** @brief The facts a LIVE entity answers with: its components and its mesh. */
@@ -351,7 +351,7 @@ MeshDrawKeys meshDrawFor(RenderFrameContext& ctx, ecs::Registry& registry, Entit
const MeshProgramFacts facts =
meshFactsFromEntity(ctx, registry, entity, mesh, resident, warnedBones);
return { meshVariantFrom(facts, ctx.environment_texture_id != 0
- || (!shadowDepth && ctx.frame && ctx.frame->planarTextureFor(entity) != 0), shadowDepth, weightHeat,
+ || (!shadowDepth && ctx.frame && ctx.frame->planarTextureFor(entity) != 0), shadowDepth, ctx.lighting_direct, weightHeat,
ctx.gbuffer && !shadowDepth),
facts.normalTextureId };
}
@@ -391,7 +391,7 @@ u32 MeshPlugin::meshProgram(RenderFrameContext& ctx, u32 variant) {
const bool depthOnly = (variant & 16u) != 0, envMapped = (variant & 32u) != 0;
const bool lightmapped = (variant & 64u) != 0, weightHeat = (variant & 128u) != 0;
const bool gbuffer = (variant & 256u) != 0, motion = (variant & 512u) != 0;
- const bool tangents = (variant & 1024u) != 0;
+ const bool tangents = (variant & 1024u) != 0, direct = (variant & 2048u) != 0;
if (mesh_compiled_[variant]) return mesh_programs_[variant];
mesh_compiled_[variant] = true;
// Counted because the cost of this function is entirely the times it does
@@ -426,6 +426,7 @@ u32 MeshPlugin::meshProgram(RenderFrameContext& ctx, u32 variant) {
// After the receiving features, not between them and the `else` they hang from: a lit draw that writes the
// surface record still receives shadows and reflections.
if (gbuffer) features.emplace_back("ES_GBUFFER");
+ if (direct) features.emplace_back("ES_LIGHT_DIRECT");
// Authored as mesh.esshader, WGSL twin included. Its vertex stage is the one
// that reads a model matrix, which is what lets the vertices stay local.
@@ -473,7 +474,7 @@ RenderPrewarmResult MeshPlugin::prewarmFacts(RenderFrameContext& ctx,
for (u32 pass = 0; pass < 2; ++pass) {
const bool shadowDepth = pass == 1;
if (shadowDepth && (!shadowPasses || !residentGeometry)) continue;
- const u32 variant = meshVariantFrom(facts[i], envMapped, shadowDepth);
+ const u32 variant = meshVariantFrom(facts[i], envMapped, shadowDepth, ctx.lighting_direct);
++out.asks;
if (out.addKey(variant)) ++out.uniqueKeys;
if (!mesh_compiled_[variant]) ++out.compiles;
diff --git a/src/esengine/renderer/rhi/GfxEnums.hpp b/src/esengine/renderer/rhi/GfxEnums.hpp
index 2f0763452..a361ebc9e 100644
--- a/src/esengine/renderer/rhi/GfxEnums.hpp
+++ b/src/esengine/renderer/rhi/GfxEnums.hpp
@@ -141,10 +141,7 @@ static constexpr u32 MORPH_TEXTURE_WIDTH = 2048;
/// Beyond it the geometry draws unmorphed — a texture the device refuses is a
/// mesh that does not draw at all.
static constexpr u32 MORPH_MAX_TEXELS = MORPH_TEXTURE_WIDTH * MORPH_TEXTURE_WIDTH;
-/// Programs the resident-mesh shader has: one per combination of {normals, lit, normal-mapped, skinned, depth-only,
-/// env-mapped, lightmapped, weight-heat, writes-the-surface-record, writes-the-motion, tangents}: eleven bits, because
-/// the geometry, the draw, the frame and the pass each answer a different one.
-static constexpr u32 MESH_VARIANTS = 2048;
+static constexpr u32 MESH_VARIANTS = 4096;
/**
* @brief What a mesh vertex channel MEANS, and the attribute location it binds to.
* @details One vocabulary for the file format, the layout and the shaders: a
diff --git a/src/esengine/renderer/store/MaterialStore.cpp b/src/esengine/renderer/store/MaterialStore.cpp
index f4a37c322..43d3c105f 100644
--- a/src/esengine/renderer/store/MaterialStore.cpp
+++ b/src/esengine/renderer/store/MaterialStore.cpp
@@ -73,11 +73,13 @@ u32 MaterialStore::meshProgram(u32 materialId, resource::ResourceManager& resour
// Only for a shader that has something to write: one that never mentions the feature would
// compile the same program twice and then be declared to write an output it does not have.
bool albedo = false;
- if (gbuffer) {
+ bool direct = false;
+ if (gbuffer || lighting_direct_) {
const MaterialRecord* rec = find(materialId);
const auto src = rec && rec->shaderRef.isValid() ? sources_.find(rec->shaderRef.id()) : sources_.end();
- gbuffer = src != sources_.end() && src->second.mentionsGbuffer;
+ gbuffer = gbuffer && src != sources_.end() && src->second.mentionsGbuffer;
albedo = gbuffer && src->second.writesAlbedo;
+ direct = lighting_direct_ && src != sources_.end() && src->second.takesLight;
}
// Keyed by shader AND vertex shape: a layout may not declare an attribute its
// shader ignores, so geometry with normals — or posed by bones — needs its own.
@@ -87,7 +89,8 @@ u32 MaterialStore::meshProgram(u32 materialId, resource::ResourceManager& resour
| (lightmapped ? (1ull << 36) : 0ull)
| (gbuffer ? (1ull << 38) : 0ull)
| (tangents && withNormals ? (1ull << 39) : 0ull)
- | (tipPass ? (1ull << 40) : 0ull);
+ | (tipPass ? (1ull << 40) : 0ull)
+ | (direct ? (1ull << 42) : 0ull);
// A program already made for this shader and vertex shape is the answer, and almost every draw of a frame asks for one: it is looked up before
// the feature list is built, since building it (nine strings and the vector that holds them) was most of what a cached answer cost.
if (const MaterialRecord* rec = find(materialId); rec && rec->shaderRef.isValid()) {
@@ -115,6 +118,7 @@ u32 MaterialStore::meshProgram(u32 materialId, resource::ResourceManager& resour
features.push_back("ES_SURFACE_3D");
if (gbuffer) features.push_back("ES_GBUFFER");
if (tipPass) features.push_back("ES_TIP_PASS");
+ if (direct) features.push_back("ES_LIGHT_DIRECT");
const u32 program = variantProgram(materialId, resources, shape, features, "resident geometry");
if (gbuffer && program != 0) markGBufferProgram(program, albedo);
return program;
diff --git a/src/esengine/renderer/store/MaterialStore.hpp b/src/esengine/renderer/store/MaterialStore.hpp
index f0d47ddb8..cb16be430 100644
--- a/src/esengine/renderer/store/MaterialStore.hpp
+++ b/src/esengine/renderer/store/MaterialStore.hpp
@@ -201,7 +201,8 @@ public:
if (shader.isValid()) {
const bool mentionsGbuffer = source.find("ES_GBUFFER") != std::string::npos;
const bool writesAlbedo = mentionsGbuffer && source.find("fragAlbedo") != std::string::npos;
- sources_[shader.id()] = { std::move(source), std::move(features), mentionsGbuffer, writesAlbedo };
+ const bool takesLight = source.find("applyLighting") != std::string::npos;
+ sources_[shader.id()] = { std::move(source), std::move(features), mentionsGbuffer, writesAlbedo, takesLight };
}
}
@@ -213,6 +214,9 @@ public:
bool envMapped = false, bool lightmapped = false, bool gbuffer = false,
bool tangents = false, bool tipPass = false) const;
+ void setLightingDirect(bool on) { lighting_direct_ = on; }
+ bool lightingDirect() const { return lighting_direct_; }
+
/// Whether @p programId is a variant that writes the surface record's second output — set when
/// it was compiled for a pass that has one AND the material's shader has something to write
/// (it mentions ES_GBUFFER). The draw list asks per command, so a pipeline says what its shader does.
@@ -463,8 +467,10 @@ private:
/// Whether its gbuffer variant also writes `fragAlbedo` (location 2): a shader written before the
/// attachment existed writes two outputs, and its pipeline must leave the third alone.
bool writesAlbedo = false;
+ bool takesLight = false;
};
std::unordered_map<u32, ShaderSource> sources_;
+ bool lighting_direct_ = false;
/// (Handle, vertex source) → the program compiled for it (0 = tried and
/// failed). Mutable because compiling it is memoization: the collect path
/// asks a read-only store, and the answer is the same every time.
diff --git a/tests/renderer/test_shader_variant.cpp b/tests/renderer/test_shader_variant.cpp
index 1278c43aa..e627b5b4f 100644
--- a/tests/renderer/test_shader_variant.cpp
+++ b/tests/renderer/test_shader_variant.cpp
@@ -825,6 +825,14 @@ static void testLightingDirect() {
&& on.find("if (src <= 0.0 || g_shadowHard > 0.5) {") == std::string::npos,
"a source with size is shadowed hard, not left unshadowed, when the soft path is compiled out");
+ std::vector<std::string> asked = mesh;
+ asked.push_back("ES_LIGHT_DIRECT");
+ const std::string byQuality = ShaderParser::assembleStage(full, ShaderStage::Fragment, "", asked, ShaderTargetLanguage::WGSL);
+ CHECK(byQuality == on, "a renderer that asks for direct lighting compiles what the directive does");
+ const std::string both = ShaderParser::assembleStage(direct, ShaderStage::Fragment, "", asked, ShaderTargetLanguage::GLSL_ES300);
+ const size_t first = both.find("#define ES_LIGHT_DIRECT");
+ CHECK(first != std::string::npos && both.find("#define ES_LIGHT_DIRECT", first + 1) == std::string::npos,
+ "asked by the shader and the renderer, the define is written once");
}
int main() {
diff --git a/tools/check-project-settings.mjs b/tools/check-project-settings.mjs
index 178ff660a..71c284f35 100644
--- a/tools/check-project-settings.mjs
+++ b/tools/check-project-settings.mjs
@@ -310,6 +310,7 @@ const BLOCKS = [
waterCaustics: { ui: 'project.rendering.quality.waterCaustics' },
shelterMaskSize: { ui: 'project.rendering.quality.shelterMaskSize' },
shadowSoftSamples: { ui: 'project.rendering.quality.shadowSoftSamples' },
+ lighting: { ui: 'project.rendering.quality.lighting' },
drawCallBudget: { ui: 'project.rendering.quality.drawCallBudget' },
textureStreaming: { ui: 'project.rendering.quality.textureStreaming' },
textureStreamingBudget: { ui: 'project.rendering.quality.textureStreamingBudget' },
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 89f923302..2582d7acb 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -4112,4 +4112,10 @@ export const NOTED = {
{"note": "A WeChat mini-game no longer takes WeChat down with it on iOS."},
"fix(timeline): importing esengine/timeline installs timelines again, so a mini-game's animated characters leave the bind pose":
{"note": "Animated characters move in a WeChat mini-game."},
+ "fix(render): a lighting-direct surface takes a hard shadow from a sun with a size, where it took none":
+ {"note": "A `#pragma lighting direct` surface takes a sun's shadow."},
+ "feat(quality): low and medium light 3D surfaces directly, so a phone pays about half for a lit scene":
+ {"note": "On a phone, a lit 3D scene costs about half as much."},
+ "feat(quality): the quality levels have a 3D lighting row":
+ {"note": "On a phone, a lit 3D scene costs about half as much."},
};