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(2d): the rain shelter mask size is the effect's own field, and a quality level holds it lower

yhhdf3a0ebdceed
diff --git a/desktop b/desktop
index 4b4e9b303..cd4357743 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 4b4e9b30371aa6977153a2cf4bdb3e8d12ea88de
+Subproject commit cd4357743af9b0f4b7f2b27d2bd5ab1a80777d6d
diff --git a/docs/astro/src/content/docs/graphics/sprites.mdx b/docs/astro/src/content/docs/graphics/sprites.mdx
index 3f5ad1406..5e85608b5 100644
--- a/docs/astro/src/content/docs/graphics/sprites.mdx
+++ b/docs/astro/src/content/docs/graphics/sprites.mdx
@@ -262,8 +262,9 @@ has a room that is dry. So one roof carries both components, and the rain stops
| `margin` | Ground around the sprite's edge that stays dry too, in world units: eaves. |
There is no limit on how many shelters a scene has. Each frame the shelters in view are painted into a small mask over the view (one rectangle each, an ellipse as a few strips),
-and the rain reads one texel of it per pixel; a village of roofs costs what a hut does. The mask is 512 texels across, so a shelter's edge is soft by about the view's size over
-that. The rings and the darkening of a wet floor are drawn over everything, characters included, because a
+and the rain reads one texel of it per pixel; a village of roofs costs what a hut does. The mask is 512 texels across by default, so a shelter's edge is soft by about the view's size over
+that. Set the effect's **Shelter Mask Size** (`maskSize`, 64 to 2048) for finer edges or a cheaper mask, and a quality level holds it lower still: the profile's
+`shelterMaskSize` is the most a level allows (256 low, 512 medium, 1024 high; **Project Settings → Rendering → Quality**). The rings and the darkening of a wet floor are drawn over everything, characters included, because a
2D picture has no way to tell a character from the ground under it; they are small and low, which is why it reads as rain on the picture.
### Depth layers (2.5D)
diff --git a/docs/astro/src/content/docs/zh-cn/graphics/sprites.mdx b/docs/astro/src/content/docs/zh-cn/graphics/sprites.mdx
index d36ffa742..0d7a2d5c4 100644
--- a/docs/astro/src/content/docs/zh-cn/graphics/sprites.mdx
+++ b/docs/astro/src/content/docs/zh-cn/graphics/sprites.mdx
@@ -229,7 +229,7 @@ world.applyEntityOrder([other, another, card]);
| `round` | 覆盖范围取矩形内接的椭圆(树冠),而不是整个矩形(屋顶)。 |
| `margin` | 精灵边缘外多少世界单位也保持干燥(屋檐)。 |
-遮雨区的数量没有上限。每一帧,视野里的遮雨区会被画进一张覆盖视野的小遮罩(每个一个矩形,椭圆用几条横带),雨每个像素只读遮罩里的一个纹素,所以一整个村子的屋顶和一间小屋的开销差不多。遮罩宽 512 个纹素,遮雨区的边缘大约有"视野尺寸除以 512"那么软。涟漪和湿地的变暗是画在所有东西上面的,包括角色,因为 2D 画面分不出角色和脚下的地面;它们小而低,看起来就是画面上的雨。
+遮雨区的数量没有上限。每一帧,视野里的遮雨区会被画进一张覆盖视野的小遮罩(每个一个矩形,椭圆用几条横带),雨每个像素只读遮罩里的一个纹素,所以一整个村子的屋顶和一间小屋的开销差不多。遮罩默认宽 512 个纹素,遮雨区的边缘大约有"视野尺寸除以 512"那么软。在效果上设置 **Shelter Mask Size**(`maskSize`,64 到 2048)可以换更细的边缘或更便宜的遮罩;画质档位还会把它压得更低:档位的 `shelterMaskSize` 是该档位允许的最大值(低 256、中 512、高 1024,在**项目设置 → 渲染 → 画质**里改)。涟漪和湿地的变暗是画在所有东西上面的,包括角色,因为 2D 画面分不出角色和脚下的地面;它们小而低,看起来就是画面上的雨。
### 深度层(2.5D)
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index a33918032..371ad1a8d 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -3,10 +3,10 @@
"counts": {
"public": 115,
"beta": 171,
- "experimental": 2662,
+ "experimental": 2664,
"deprecated": 3
},
- "total": 2948,
+ "total": 2950,
"subsystems": [
{
"id": "mobile-controls",
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index a341ee17d..09820ee21 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 159 beta · 1918 experimental · 3 deprecated
+Symbols: 115 public · 159 beta · 1920 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -7799,6 +7799,7 @@ shadowAtlasSize: number
shadowCascades: number
shadowCellSize: number
shadowDistance: number
+shelterMaskSize: number
skipEffects: readonly string[]
ssao: boolean
waterCaustics: boolean
@@ -14016,6 +14017,11 @@ DragPlugin
(view: EditorViewData, heightPx: number, at?: Vec3): number
```
+## ellipseStripsOf — function @experimental
+```
+(size: number): number
+```
+
## emptyAnimatorController — function @experimental
```
(): AnimatorControllerDef
@@ -14833,7 +14839,7 @@ Logger
## maskRects — function @experimental
```
-(shelters: readonly Shelter[], view: { left: number; bottom: number; right: number; top: number; }): MaskRect[]
+(shelters: readonly Shelter[], view: { left: number; bottom: number; right: number; top: number; }, strips?: number): MaskRect[]
```
## matchLocale — function @experimental
@@ -16091,6 +16097,11 @@ ServicesPlugin
(grid: SheetGrid): number
```
+## shelterMaskSizeOf — function @experimental
+```
+(asked: number, allowed: number | null): number
+```
+
## shippedOptionalSubsystems — function @experimental
```
(): string[]
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 9de311943..185074806 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.native
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 164 beta · 1937 experimental · 3 deprecated
+Symbols: 115 public · 164 beta · 1939 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -8002,6 +8002,7 @@ shadowAtlasSize: number
shadowCascades: number
shadowCellSize: number
shadowDistance: number
+shelterMaskSize: number
skipEffects: readonly string[]
ssao: boolean
waterCaustics: boolean
@@ -14269,6 +14270,11 @@ DragPlugin
(view: EditorViewData, heightPx: number, at?: Vec3): number
```
+## ellipseStripsOf — function @experimental
+```
+(size: number): number
+```
+
## emptyAnimatorController — function @experimental
```
(): AnimatorControllerDef
@@ -15096,7 +15102,7 @@ Logger
## maskRects — function @experimental
```
-(shelters: readonly Shelter[], view: { left: number; bottom: number; right: number; top: number; }): MaskRect[]
+(shelters: readonly Shelter[], view: { left: number; bottom: number; right: number; top: number; }, strips?: number): MaskRect[]
```
## matchLocale — function @experimental
@@ -16354,6 +16360,11 @@ ServicesPlugin
(grid: SheetGrid): number
```
+## shelterMaskSizeOf — function @experimental
+```
+(asked: number, allowed: number | null): number
+```
+
## shippedOptionalSubsystems — function @experimental
```
(): string[]
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 3231d059a..57ab91aa7 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 161 beta · 1917 experimental · 3 deprecated
+Symbols: 115 public · 161 beta · 1919 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -7794,6 +7794,7 @@ shadowAtlasSize: number
shadowCascades: number
shadowCellSize: number
shadowDistance: number
+shelterMaskSize: number
skipEffects: readonly string[]
ssao: boolean
waterCaustics: boolean
@@ -14011,6 +14012,11 @@ DragPlugin
(view: EditorViewData, heightPx: number, at?: Vec3): number
```
+## ellipseStripsOf — function @experimental
+```
+(size: number): number
+```
+
## emptyAnimatorController — function @experimental
```
(): AnimatorControllerDef
@@ -14833,7 +14839,7 @@ Logger
## maskRects — function @experimental
```
-(shelters: readonly Shelter[], view: { left: number; bottom: number; right: number; top: number; }): MaskRect[]
+(shelters: readonly Shelter[], view: { left: number; bottom: number; right: number; top: number; }, strips?: number): MaskRect[]
```
## matchLocale — function @experimental
@@ -16096,6 +16102,11 @@ ServicesPlugin
(grid: SheetGrid): number
```
+## shelterMaskSizeOf — function @experimental
+```
+(asked: number, allowed: number | null): number
+```
+
## shippedOptionalSubsystems — function @experimental
```
(): string[]
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index f5ee44be9..73c680d22 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/minigame
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 159 beta · 1939 experimental · 3 deprecated
+Symbols: 115 public · 159 beta · 1941 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -8088,6 +8088,7 @@ shadowAtlasSize: number
shadowCascades: number
shadowCellSize: number
shadowDistance: number
+shelterMaskSize: number
skipEffects: readonly string[]
ssao: boolean
waterCaustics: boolean
@@ -14316,6 +14317,11 @@ DragPlugin
(view: EditorViewData, heightPx: number, at?: Vec3): number
```
+## ellipseStripsOf — function @experimental
+```
+(size: number): number
+```
+
## emptyAnimatorController — function @experimental
```
(): AnimatorControllerDef
@@ -15143,7 +15149,7 @@ Logger
## maskRects — function @experimental
```
-(shelters: readonly Shelter[], view: { left: number; bottom: number; right: number; top: number; }): MaskRect[]
+(shelters: readonly Shelter[], view: { left: number; bottom: number; right: number; top: number; }, strips?: number): MaskRect[]
```
## matchLocale — function @experimental
@@ -16401,6 +16407,11 @@ ServicesPlugin
(grid: SheetGrid): number
```
+## shelterMaskSizeOf — function @experimental
+```
+(asked: number, allowed: number | null): number
+```
+
## shippedOptionalSubsystems — function @experimental
```
(): string[]
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 8e04b07d9..f7a7430de 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/wechat
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 159 beta · 1930 experimental · 3 deprecated
+Symbols: 115 public · 159 beta · 1932 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -7801,6 +7801,7 @@ shadowAtlasSize: number
shadowCascades: number
shadowCellSize: number
shadowDistance: number
+shelterMaskSize: number
skipEffects: readonly string[]
ssao: boolean
waterCaustics: boolean
@@ -14043,6 +14044,11 @@ DragPlugin
(view: EditorViewData, heightPx: number, at?: Vec3): number
```
+## ellipseStripsOf — function @experimental
+```
+(size: number): number
+```
+
## emptyAnimatorController — function @experimental
```
(): AnimatorControllerDef
@@ -14870,7 +14876,7 @@ Logger
## maskRects — function @experimental
```
-(shelters: readonly Shelter[], view: { left: number; bottom: number; right: number; top: number; }): MaskRect[]
+(shelters: readonly Shelter[], view: { left: number; bottom: number; right: number; top: number; }, strips?: number): MaskRect[]
```
## matchLocale — function @experimental
@@ -16128,6 +16134,11 @@ ServicesPlugin
(grid: SheetGrid): number
```
+## shelterMaskSizeOf — function @experimental
+```
+(asked: number, allowed: number | null): number
+```
+
## shippedOptionalSubsystems — function @experimental
```
(): string[]
diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.ts
index 09ef58fd2..28e94c438 100644
--- a/sdk/src/core-render.ts
+++ b/sdk/src/core-render.ts
@@ -346,7 +346,7 @@ export { RenderDemand } from './render/renderDemand';
export { buildPathGeometry, mergeGeometry, cubicBezier, quadraticBezier, circlePoints } from './render/vectorPath';
export type { PathStyle, PathFill, PathStroke, PathColor, LineJoin, LineCap } from './render/vectorPath';
export { setPath, clearPath } from './render/pathRenderer';
-export { RainShelter, drynessOf, maskRects, type RainShelterData, type Shelter, type MaskRect } from './render/rainShelter';
+export { RainShelter, drynessOf, maskRects, shelterMaskSizeOf, ellipseStripsOf, type RainShelterData, type Shelter, type MaskRect } from './render/rainShelter';
export { CoverFade, CoverFadeTarget, coveredGround, coversPoint, stepFade, type CoverFadeData } from './render/coverFade';
export { BlobShadow, setBlobShadowGround, buildBlobMesh, blobAlpha, type BlobShadowData, type BlobShadowGround } from './render/blobShadow';
export type { RenderOnDemandOptions } from './render/renderDemand';
diff --git a/sdk/src/postprocess/effects.ts b/sdk/src/postprocess/effects.ts
index 81bd7d59c..1921d7ecc 100644
--- a/sdk/src/postprocess/effects.ts
+++ b/sdk/src/postprocess/effects.ts
@@ -1,7 +1,7 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import type { ShaderHandle } from '../render/material';
-import { RAIN_SHELTER_UNIFORMS, RAIN_SHELTER_MASK_TEXTURE } from './rainShelterMask';
+import { RAIN_SHELTER_UNIFORMS, RAIN_SHELTER_MASK_TEXTURE, RAIN_SHELTER_MASK_SIZE, RAIN_SHELTER_MASK_MIN, RAIN_SHELTER_MASK_MAX } from './rainShelterMask';
import { effectSourcesOf, computeSourceOf } from './effectSources';
import type { basicEffects } from './sources/basic';
import type { atmosphereEffects } from './sources/atmosphere';
@@ -335,6 +335,9 @@ registerEffect({
{ name: 'u_wind', label: 'Wind', min: -1, max: 1, step: 0.01, defaultValue: 0.15 },
{ name: 'u_speed', label: 'Speed', min: 0.2, max: 6, step: 0.1, defaultValue: 1.6 },
{ name: 'u_streakLength', label: 'Streak Length', min: 0.05, max: 0.9, step: 0.01, defaultValue: 0.3 },
+ // How many texels a side the shelter mask is: the picture of where the rain is dry is painted this big every frame, so a bigger mask has finer
+ // edges and costs more, and a quality level can hold it lower.
+ { name: 'u_maskSize', label: 'Shelter Mask Size', min: RAIN_SHELTER_MASK_MIN, max: RAIN_SHELTER_MASK_MAX, step: 64, defaultValue: RAIN_SHELTER_MASK_SIZE },
// Where the mask sits in the world, written each frame by the rain-shelter system with the mask itself.
...RAIN_SHELTER_UNIFORMS,
],
diff --git a/sdk/src/postprocess/rainShelterMask.ts b/sdk/src/postprocess/rainShelterMask.ts
index 7c9b8909a..032a55c35 100644
--- a/sdk/src/postprocess/rainShelterMask.ts
+++ b/sdk/src/postprocess/rainShelterMask.ts
@@ -9,8 +9,13 @@ import type { EffectUniformDef } from './effects';
/** The sampler the mask is bound to. */
export const RAIN_SHELTER_MASK_TEXTURE = 'u_shelterMask';
-/** How many texels a side the mask is. The view is stretched over it, so a shelter's edge is soft by about the view's size over this. */
+/**
+ * How many texels a side the mask is unless the effect says otherwise (its `maskSize`), and the least and most it may be. The view is stretched
+ * over it, so a shelter's edge is soft by about the view's size over this.
+ */
export const RAIN_SHELTER_MASK_SIZE = 512;
+export const RAIN_SHELTER_MASK_MIN = 64;
+export const RAIN_SHELTER_MASK_MAX = 2048;
/** The world rectangle the mask covers: its low corner and its size. Written with the mask each frame, so nobody authors them. */
export const RAIN_SHELTER_UNIFORMS: EffectUniformDef[] = ['L', 'B', 'W', 'H'].map((edge): EffectUniformDef => ({
diff --git a/sdk/src/postprocess/sources/rain2d.ts b/sdk/src/postprocess/sources/rain2d.ts
index e2f892100..3c8c61518 100644
--- a/sdk/src/postprocess/sources/rain2d.ts
+++ b/sdk/src/postprocess/sources/rain2d.ts
@@ -104,6 +104,7 @@ const SOURCE = `#pragma shader "PP Rain 2D"
#pragma param u_speed float default(1.6) range(0.2,6)
#pragma param u_streakLength float default(0.3) range(0.05,0.9)
#pragma param u_streakColor color default(0.78,0.82,0.9,1)
+#pragma param u_maskSize float default(512) range(64,2048)
#pragma param u_maskL float default(0) range(-1000000000,1000000000)
#pragma param u_maskB float default(0) range(-1000000000,1000000000)
#pragma param u_maskW float default(0) range(0,1000000000)
diff --git a/sdk/src/render/quality.ts b/sdk/src/render/quality.ts
index 30274c8d8..2d1f23525 100644
--- a/sdk/src/render/quality.ts
+++ b/sdk/src/render/quality.ts
@@ -67,6 +67,11 @@ export interface QualityProfile {
* skips follows from what a frame on that device can afford.
*/
skipEffects: readonly string[];
+ /**
+ * The most texels a side the 2D rain's shelter mask has: the largest a `rain2d` effect is let draw its own `maskSize` at. The mask is painted every frame, so
+ * a weak device spends less on a smaller one and gets rain whose dry edges are softer.
+ */
+ shelterMaskSize: number;
}
export interface DeviceQualityRule {
@@ -115,6 +120,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,
},
medium: {
renderScale: 1, minRenderScale: 0.65, msaaSamples: 2, antialiasing: 'temporal',
@@ -123,6 +129,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,
},
high: {
renderScale: 1, minRenderScale: 0.75, msaaSamples: 4, antialiasing: 'msaa',
@@ -133,6 +140,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,
},
};
@@ -222,6 +230,7 @@ function resolveProfile(level: QualityLevel, value: unknown): QualityProfile {
? r.skipEffects.filter((e): e is string => typeof e === 'string' && e.trim() !== '')
.map((e) => e.trim()).slice(0, 32)
: base.skipEffects,
+ shelterMaskSize: Math.round(finite(r.shelterMaskSize, base.shelterMaskSize, 64, 2048)),
};
}
diff --git a/sdk/src/render/rainShelter.ts b/sdk/src/render/rainShelter.ts
index 9268f952a..6108cc864 100644
--- a/sdk/src/render/rainShelter.ts
+++ b/sdk/src/render/rainShelter.ts
@@ -25,7 +25,8 @@ import { BlendMode } from './blend';
import { Renderer } from './renderer';
import { RenderTexture, type RenderTextureHandle } from './renderTexture';
import { log } from '../util/logger';
-import { RAIN_SHELTER_MASK_SIZE, RAIN_SHELTER_MASK_TEXTURE } from '../postprocess/rainShelterMask';
+import { RAIN_SHELTER_MASK_SIZE, RAIN_SHELTER_MASK_MIN, RAIN_SHELTER_MASK_MAX, RAIN_SHELTER_MASK_TEXTURE } from '../postprocess/rainShelterMask';
+import { Quality } from './qualityRuntime';
import { runtimeTextureRef } from '../postprocess/runtimeTextures';
import type { BlendedEffect } from '../postprocess/volumeBlending';
@@ -98,16 +99,30 @@ export function shelterOf(sprite: SpriteData, transform: TransformData, data: Ra
return { x: centre.x, y: centre.y, hx, hy: data.round ? -hy : hy, dry };
}
-/** How many strips an ellipse is cut into: the mask is a few hundred texels across, so more would draw what it cannot show. */
+/** How many strips an ellipse is cut into at the default mask size. */
export const ELLIPSE_STRIPS = 32;
+/** The size a mask is painted at: what the effect asks for, held to what the quality level allows (none: as asked), in whole sixteens of texels. */
+export function shelterMaskSizeOf(asked: number, allowed: number | null): number {
+ const wanted = Number.isFinite(asked) ? asked : RAIN_SHELTER_MASK_SIZE;
+ const size = Math.round(Math.min(wanted, allowed ?? wanted) / 16) * 16;
+ return Math.min(Math.max(size, RAIN_SHELTER_MASK_MIN), RAIN_SHELTER_MASK_MAX);
+}
+
+/** How many strips an ellipse is cut into for a mask this big: one per sixteen texels, since more would draw what the mask cannot show. */
+export function ellipseStripsOf(size: number): number {
+ return Math.min(Math.max(Math.round(size / 16), 8), 64);
+}
+
/**
* What to draw for the shelters: a rectangle each, an ellipse as strips of one, the driest last so where two overlap the drier wins (a draw
* overwrites, and a max is what overlapping shelters want). The mask is not drawn for shelters the view cannot see.
*
* @param view The world rectangle the mask covers.
*/
-export function maskRects(shelters: readonly Shelter[], view: { left: number; bottom: number; right: number; top: number }): MaskRect[] {
+export function maskRects(
+ shelters: readonly Shelter[], view: { left: number; bottom: number; right: number; top: number }, strips: number = ELLIPSE_STRIPS,
+): MaskRect[] {
const rects: MaskRect[] = [];
const ordered = [...shelters].sort((a, b) => a.dry - b.dry);
for (const s of ordered) {
@@ -117,9 +132,9 @@ export function maskRects(shelters: readonly Shelter[], view: { left: number; bo
rects.push({ x: s.x, y: s.y, w: s.hx * 2, h: h * 2, dry: s.dry });
continue;
}
- const strip = (h * 2) / ELLIPSE_STRIPS;
- for (let i = 0; i < ELLIPSE_STRIPS; i++) {
- const t = ((i + 0.5) / ELLIPSE_STRIPS) * 2 - 1;
+ const strip = (h * 2) / strips;
+ for (let i = 0; i < strips; i++) {
+ const t = ((i + 0.5) / strips) * 2 - 1;
const width = s.hx * 2 * Math.sqrt(Math.max(1 - t * t, 0));
if (width <= 0) continue;
rects.push({ x: s.x, y: s.y + t * h, w: width, h: strip, dry: s.dry });
@@ -138,6 +153,8 @@ interface MaskState {
}
let maskNow: MaskState | null = null;
+/** The mask size the last resolved `rain2d` asked for. */
+let askedSize = RAIN_SHELTER_MASK_SIZE;
/** Column-major orthographic projection over a rectangle: what RenderTexture.begin wants. */
function ortho(l: number, r: number, b: number, t: number): Float32Array {
@@ -159,6 +176,7 @@ export function applyRainSheltersToRain(effects: Map<string, BlendedEffect>): vo
const rain = effects.get('rain2d');
if (!rain || !rain.enabled) return;
const mask = maskNow;
+ askedSize = rain.uniforms.get('u_maskSize') ?? RAIN_SHELTER_MASK_SIZE;
rain.uniforms.set('u_maskL', mask ? mask.left : 0);
rain.uniforms.set('u_maskB', mask ? mask.bottom : 0);
rain.uniforms.set('u_maskW', mask ? mask.width : 0);
@@ -171,6 +189,12 @@ export function installRainShelter(app: App): () => void {
let target: RenderTextureHandle | null = null;
let failed = false;
+ /** The size the quality level lets the mask be, or null with no quality policy running. */
+ const allowedSize = (): number | null => {
+ const policy = app.hasResource(Quality) ? app.getResource(Quality) : null;
+ return policy && policy.enabled ? policy.profile.shelterMaskSize : null;
+ };
+
/** The world rectangle the camera shows, or null where there is none to cover. */
const viewOf = (): { left: number; right: number; bottom: number; top: number } | null => {
const view = app.hasResource(CameraView) ? app.getResource(CameraView).getWorldBounds() : null;
@@ -180,8 +204,11 @@ export function installRainShelter(app: App): () => void {
const paint = (rects: readonly MaskRect[], view: { left: number; right: number; bottom: number; top: number }): boolean => {
if (failed) return false;
try {
+ const size = shelterMaskSizeOf(askedSize, allowedSize());
+ // Asked for another size (the effect's field, or the level changed): the old one goes and a new one is made.
+ if (target && target.width !== size) { RenderTexture.release(target); target = null; }
if (!target) {
- const created = RenderTexture.create({ width: RAIN_SHELTER_MASK_SIZE, height: RAIN_SHELTER_MASK_SIZE, depth: false, filter: 'linear' });
+ const created = RenderTexture.create({ width: size, height: size, depth: false, filter: 'linear' });
// The renderer may not be up yet: try again next frame.
if (created.textureId === 0 || created.texture === 0) { RenderTexture.release(created); return false; }
target = created;
@@ -224,7 +251,7 @@ export function installRainShelter(app: App): () => void {
maskNow = null;
if (found.length === 0) return;
const view = viewOf();
- if (view) paint(maskRects(found, view), view);
+ if (view) paint(maskRects(found, view, ellipseStripsOf(shelterMaskSizeOf(askedSize, allowedSize()))), view);
},
{ name: 'RainShelterSystem' },
);
diff --git a/sdk/tests/atmosphere-2d.test.ts b/sdk/tests/atmosphere-2d.test.ts
index d8cf3c2e0..099d58191 100644
--- a/sdk/tests/atmosphere-2d.test.ts
+++ b/sdk/tests/atmosphere-2d.test.ts
@@ -2,7 +2,8 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { describe, expect, it } from 'vitest';
import { coversPoint, stepFade } from '../src/render/coverFade';
-import { applyRainSheltersToRain, drynessOf, maskRects, shelterOf, ELLIPSE_STRIPS, type Shelter } from '../src/render/rainShelter';
+import { applyRainSheltersToRain, drynessOf, maskRects, shelterOf, shelterMaskSizeOf, ellipseStripsOf, ELLIPSE_STRIPS, type Shelter } from '../src/render/rainShelter';
+import { defaultQualityProfile, parseQualityConfig } from '../src/render/quality';
import { RAIN_SHELTER_MASK_TEXTURE } from '../src/postprocess/rainShelterMask';
import { runtimeTextureHandle, runtimeTextureRef } from '../src/postprocess/runtimeTextures';
import { Light } from '../src/ecs/component';
@@ -199,6 +200,38 @@ describe('the 2D rain', () => {
expect(off.get('rain2d')!.uniforms.size).toBe(0);
});
+ it('has a mask size of its own, authored on the effect, that a quality level can only hold lower', () => {
+ const size = getEffectDef('rain2d')!.uniforms.find((u) => u.name === 'u_maskSize')!;
+ expect(size.defaultValue).toBe(512);
+ expect(size.internal).toBeUndefined();
+ expect(shelterMaskSizeOf(1024, 256)).toBe(256);
+ expect(shelterMaskSizeOf(128, 256)).toBe(128);
+ expect(shelterMaskSizeOf(1024, null)).toBe(1024);
+ expect(shelterMaskSizeOf(Number.NaN, null)).toBe(512);
+ expect(shelterMaskSizeOf(1, null)).toBe(64);
+ expect(shelterMaskSizeOf(99999, null)).toBe(2048);
+ expect(shelterMaskSizeOf(500, null) % 16).toBe(0);
+ });
+
+ it('cuts an ellipse into as many strips as its mask can show', () => {
+ expect(ellipseStripsOf(512)).toBe(ELLIPSE_STRIPS);
+ expect(ellipseStripsOf(64)).toBe(8);
+ expect(ellipseStripsOf(4096)).toBe(64);
+ const round: Shelter[] = [{ x: 0, y: 0, hx: 100, hy: -50, dry: 1 }];
+ const view = { left: -500, bottom: -500, right: 500, top: 500 };
+ expect(maskRects(round, view, 8)).toHaveLength(8);
+ expect(maskRects(round, view, 64)).toHaveLength(64);
+ });
+
+ it('is held lower by each quality level, and a project can say its own', () => {
+ expect(defaultQualityProfile('low').shelterMaskSize).toBe(256);
+ expect(defaultQualityProfile('medium').shelterMaskSize).toBe(512);
+ expect(defaultQualityProfile('high').shelterMaskSize).toBe(1024);
+ 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);
+ });
+
it('names its mask by a ref that carries the handle, so a texture made again is a new ref', () => {
const ref = runtimeTextureRef(RAIN_SHELTER_MASK_TEXTURE, 42);
expect(runtimeTextureHandle(ref)).toBe(42);
diff --git a/tools/check-project-settings.mjs b/tools/check-project-settings.mjs
index 1678cbdaa..dfc788ed4 100644
--- a/tools/check-project-settings.mjs
+++ b/tools/check-project-settings.mjs
@@ -296,6 +296,7 @@ const BLOCKS = [
waterDisplacement: { ui: 'project.rendering.quality.waterDisplacement' },
waterMirror: { ui: 'project.rendering.quality.waterMirror' },
waterCaustics: { ui: 'project.rendering.quality.waterCaustics' },
+ shelterMaskSize: { ui: 'project.rendering.quality.shelterMaskSize' },
skipEffects: { ui: 'project.rendering.quality.effects' },
},
},