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 rain shelter mask size is the effect's own field, and a quality level holds it lower
yhhdf3a0ebdceed
diff --git a/desktop b/desktopindex 4b4e9b303..cd4357743 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 4b4e9b30371aa6977153a2cf4bdb3e8d12ea88de+Subproject commit cd4357743af9b0f4b7f2b27d2bd5ab1a80777d6ddiff --git a/docs/astro/src/content/docs/graphics/sprites.mdx b/docs/astro/src/content/docs/graphics/sprites.mdxindex 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 a2D 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.mdxindex 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.jsonindex 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.mdindex 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: numbershadowCascades: numbershadowCellSize: numbershadowDistance: number+shelterMaskSize: numberskipEffects: readonly string[]ssao: booleanwaterCaustics: 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.mdindex 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: numbershadowCascades: numbershadowCellSize: numbershadowDistance: number+shelterMaskSize: numberskipEffects: readonly string[]ssao: booleanwaterCaustics: 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.mdindex 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: numbershadowCascades: numbershadowCellSize: numbershadowDistance: number+shelterMaskSize: numberskipEffects: readonly string[]ssao: booleanwaterCaustics: 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.mdindex 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: numbershadowCascades: numbershadowCellSize: numbershadowDistance: number+shelterMaskSize: numberskipEffects: readonly string[]ssao: booleanwaterCaustics: 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.mdindex 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: numbershadowCascades: numbershadowCellSize: numbershadowDistance: number+shelterMaskSize: numberskipEffects: readonly string[]ssao: booleanwaterCaustics: 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.tsindex 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.tsindex 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 Teamimport 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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: Rareturn { 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; borects.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>): voconst 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.tsindex 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 Teamimport { 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.mjsindex 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' },},},