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): a sprite that stands on the ground keeps the rain's rings and wet darkening off it
yhh540d2b100c09
diff --git a/desktop b/desktopindex 8182250ad..10abc04d4 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 8182250ad857b8bf8063539b01a0a477b7aa5015+Subproject commit 10abc04d4d1206b8f92035b1bee9f9ff3f6d1b8fdiff --git a/docs/astro/src/content/docs/graphics/sprites.mdx b/docs/astro/src/content/docs/graphics/sprites.mdxindex 5e85608b5..2b44d0023 100644--- a/docs/astro/src/content/docs/graphics/sprites.mdx+++ b/docs/astro/src/content/docs/graphics/sprites.mdx@@ -264,8 +264,10 @@ has a room that is dry. So one roof carries both components, and the rain stopsThere 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 by default, so a shelter's edge is soft by about the view's size overthat. 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.+`shelterMaskSize` is the most a level allows (256 low, 512 medium, 1024 high; **Project Settings → Rendering → Quality**). The rain is laid over the finished picture, so it cannot tell a character from the floor under them. Put `RainUpright` on a sprite that stands on the ground+(a character, a trunk, a crate) and the rings, splashes, puddles and wet darkening are left off it; the falling streaks still cross it, since rain falls on people.+The sprite's rectangle is what is kept clear, so `inset` (world units) shrinks it by that much on every side, to leave the ground at the feet wet. A sprite faded by a+`CoverFade` keeps the rain off it only as much as it shows.### 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 0d7a2d5c4..a2b240bb9 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"那么软。在效果上设置 **Shelter Mask Size**(`maskSize`,64 到 2048)可以换更细的边缘或更便宜的遮罩;画质档位还会把它压得更低:档位的 `shelterMaskSize` 是该档位允许的最大值(低 256、中 512、高 1024,在**项目设置 → 渲染 → 画质**里改)。涟漪和湿地的变暗是画在所有东西上面的,包括角色,因为 2D 画面分不出角色和脚下的地面;它们小而低,看起来就是画面上的雨。+遮雨区的数量没有上限。每一帧,视野里的遮雨区会被画进一张覆盖视野的小遮罩(每个一个矩形,椭圆用几条横带),雨每个像素只读遮罩里的一个纹素,所以一整个村子的屋顶和一间小屋的开销差不多。遮罩默认宽 512 个纹素,遮雨区的边缘大约有"视野尺寸除以 512"那么软。在效果上设置 **Shelter Mask Size**(`maskSize`,64 到 2048)可以换更细的边缘或更便宜的遮罩;画质档位还会把它压得更低:档位的 `shelterMaskSize` 是该档位允许的最大值(低 256、中 512、高 1024,在**项目设置 → 渲染 → 画质**里改)。雨是盖在画好的画面上的,分不出角色和脚下的地面。给站在地上的精灵(角色、树干、箱子)加 `RainUpright`,涟漪、溅花、积水和湿地变暗就不会画在它身上;雨线仍会穿过它,因为雨本来就会落在人身上。被保持干净的是精灵的矩形,`inset`(世界单位)把它四周各缩进这么多,让脚边的地面仍然是湿的。被 `CoverFade` 淡出的精灵,露出多少,雨就让开多少。### 深度层(2.5D)diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex 371ad1a8d..2449d0609 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": 2664,+ "experimental": 2669,"deprecated": 3},- "total": 2950,+ "total": 2955,"subsystems": [{"id": "mobile-controls",diff --git a/docs/astro/src/data/componentDocs.ts b/docs/astro/src/data/componentDocs.tsindex 62f1288f7..707e9993f 100644--- a/docs/astro/src/data/componentDocs.ts+++ b/docs/astro/src/data/componentDocs.ts@@ -84,6 +84,7 @@ export const COMPONENT_DOCS: Record<string, ComponentDoc> = {BlobShadow: { category: 'graphics', summary: 'A soft dark disc on the ground under an entity — no shadow map, no light, no extra pass — that fades and shrinks as the entity leaves the ground.', doc: 'graphics/lighting', anchor: 'blob-shadows-a-disc-instead-of-a-shadow-map', anchorZh: '假阴影用一个圆片代替阴影图' },CoverFade: { category: 'graphics', summary: 'A roof or a tree crown that thins out while a CoverFadeTarget stands under it, so the player is never hidden by what they walked into.', doc: 'graphics/sprites', anchor: 'fading-a-roof-or-a-crown-over-the-player', anchorZh: '屋顶与树冠遮挡淡出' },CoverFadeTarget: { category: 'graphics', summary: 'Marks what a CoverFade keeps visible — the player, and anything else that must not be hidden by a roof or a crown.', doc: 'graphics/sprites', anchor: 'fading-a-roof-or-a-crown-over-the-player', anchorZh: '屋顶与树冠遮挡淡出' },+ RainUpright: { category: 'graphics', summary: 'Marks a sprite that stands on the ground (a character, a trunk), so the 2D rain draws no rings, splashes or wet darkening over it.', doc: 'graphics/sprites', anchor: 'keeping-the-ground-under-a-roof-dry', anchorZh: '让屋顶下的地面保持干燥' },RainShelter: { category: 'graphics', summary: 'A roof, awning or crown that keeps the ground under it dry in the 2D rain, as far as the sprite lets that ground be seen.', doc: 'graphics/sprites', anchor: 'keeping-the-ground-under-a-roof-dry', anchorZh: '让屋顶下的地面保持干燥' },StreamedWorld: { category: 'world', summary: 'Declares the scene a streamed world and how big the cook cuts its cells.', doc: 'world/streaming', anchor: 'declaring-a-streamed-world', anchorZh: '声明一个流送世界' },WorldPersistent: { category: 'world', summary: 'Keeps an entity\'s whole subtree out of the partition — it belongs to the persistent world.', doc: 'world/streaming', anchor: 'declaring-a-streamed-world', anchorZh: '声明一个流送世界' },diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.jsonindex 463bff83c..d8586f0e7 100644--- a/docs/astro/src/data/components.generated.json+++ b/docs/astro/src/data/components.generated.json@@ -4297,6 +4297,27 @@"margin"]},+ {+ "name": "RainUpright",+ "source": "ts",+ "fields": [+ {+ "key": "inset",+ "type": "number",+ "default": "0",+ "doc": "Ground around the sprite's edge that the rain still draws on, in world units: the feet, or a trunk's base.",+ "range": "≥ 0, step 1"+ },+ {+ "key": "enabled",+ "type": "boolean",+ "default": "true"+ }+ ],+ "animatable": [+ "inset"+ ]+ },{"name": "ReflectionProbe","source": "cpp",diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 439df9abc..1edbfc923 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 · 1920 experimental · 3 deprecated+Symbols: 115 public · 159 beta · 1925 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -7928,6 +7928,17 @@ margin: numberround: boolean```+## RainUpright — const @experimental+```+ComponentDef<RainUprightData>+```++## RainUprightData — interface @experimental+```+enabled: boolean+inset: number+```+## ReadableWorld — type @experimental```Pick<World, 'valid' | 'has' | 'get'>@@ -11882,6 +11893,15 @@ staged: { revision: string | null; assets: number; bytes: number; } | nullCompressedTextureFormat | 'rgba8'```+## Upright — interface @experimental+```+amount: number+hx: number+hy: number+x: number+y: number+```+## ValidatePrefabOptions — interface @experimental```instanceOverrides: readonly PrefabOverride[] | undefined@@ -16503,6 +16523,16 @@ UIVisibilityPlugin(world: World, aspectRatio: number): void```+## uprightOf — function @experimental+```+(sprite: SpriteData, transform: TransformData, data: RainUprightData): Upright | null+```++## uprightRects — function @experimental+```+(uprights: readonly Upright[], view: { left: number; bottom: number; right: number; top: number; }): MaskRect[]+```+## v2 — const @experimental```{ readonly create: (x?: number, y?: number) => Vec2; readonly clone: (a: Vec2) => Vec2; readonly add: (a: Vec2, b: Vec2) => Vec2; readonly sub: (a: Vec2, b: Vec2) => Vec2; readonly scale: (a: Vec2, s: number) => Vec2; readonly mul: (a: Vec2, b: Vec2) => Vec2; readonly neg: (a: Vec2) => Vec2; readonly dot: (a: Vec2, b: Vec2) => number; readonly cross: (a: Vec2, b: Vec2) => number; readonly len: (a: Vec2) => number; readonly len2: (a: Vec2) => number; readonly dist: (a: Vec2, b: Vec2) => number; readonly dist2: (a: Vec2, b: Vec2) => number; readonly normalize: (a: Vec2) => Vec2; readonly lerp: (a: Vec2, b: Vec2, t: number) => Vec2; readonly angle: (a: Vec2) => number; readonly fromAngle: (radians: number, length?: number) => Vec2; readonly rotate: (a: Vec2, radians: number) => Vec2; readonly perp: (a: Vec2) => Vec2; readonly equals: (a: Vec2, b: Vec2, epsilon?: number) => boolean; }diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 1f2a9bf10..3b32f69d8 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 · 1939 experimental · 3 deprecated+Symbols: 115 public · 164 beta · 1944 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -8141,6 +8141,17 @@ margin: numberround: boolean```+## RainUpright — const @experimental+```+ComponentDef<RainUprightData>+```++## RainUprightData — interface @experimental+```+enabled: boolean+inset: number+```+## ReadableWorld — type @experimental```Pick<World, 'valid' | 'has' | 'get'>@@ -12095,6 +12106,15 @@ staged: { revision: string | null; assets: number; bytes: number; } | nullCompressedTextureFormat | 'rgba8'```+## Upright — interface @experimental+```+amount: number+hx: number+hy: number+x: number+y: number+```+## ValidatePrefabOptions — interface @experimental```instanceOverrides: readonly PrefabOverride[] | undefined@@ -16766,6 +16786,16 @@ UIVisibilityPlugin(world: World, aspectRatio: number): void```+## uprightOf — function @experimental+```+(sprite: SpriteData, transform: TransformData, data: RainUprightData): Upright | null+```++## uprightRects — function @experimental+```+(uprights: readonly Upright[], view: { left: number; bottom: number; right: number; top: number; }): MaskRect[]+```+## v2 — const @experimental```{ readonly create: (x?: number, y?: number) => Vec2; readonly clone: (a: Vec2) => Vec2; readonly add: (a: Vec2, b: Vec2) => Vec2; readonly sub: (a: Vec2, b: Vec2) => Vec2; readonly scale: (a: Vec2, s: number) => Vec2; readonly mul: (a: Vec2, b: Vec2) => Vec2; readonly neg: (a: Vec2) => Vec2; readonly dot: (a: Vec2, b: Vec2) => number; readonly cross: (a: Vec2, b: Vec2) => number; readonly len: (a: Vec2) => number; readonly len2: (a: Vec2) => number; readonly dist: (a: Vec2, b: Vec2) => number; readonly dist2: (a: Vec2, b: Vec2) => number; readonly normalize: (a: Vec2) => Vec2; readonly lerp: (a: Vec2, b: Vec2, t: number) => Vec2; readonly angle: (a: Vec2) => number; readonly fromAngle: (radians: number, length?: number) => Vec2; readonly rotate: (a: Vec2, radians: number) => Vec2; readonly perp: (a: Vec2) => Vec2; readonly equals: (a: Vec2, b: Vec2, epsilon?: number) => boolean; }diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex ca89d3c2e..53c4e5b6d 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 · 1919 experimental · 3 deprecated+Symbols: 115 public · 161 beta · 1924 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -7923,6 +7923,17 @@ margin: numberround: boolean```+## RainUpright — const @experimental+```+ComponentDef<RainUprightData>+```++## RainUprightData — interface @experimental+```+enabled: boolean+inset: number+```+## ReadableWorld — type @experimental```Pick<World, 'valid' | 'has' | 'get'>@@ -11877,6 +11888,15 @@ staged: { revision: string | null; assets: number; bytes: number; } | nullCompressedTextureFormat | 'rgba8'```+## Upright — interface @experimental+```+amount: number+hx: number+hy: number+x: number+y: number+```+## ValidatePrefabOptions — interface @experimental```instanceOverrides: readonly PrefabOverride[] | undefined@@ -16508,6 +16528,16 @@ UIVisibilityPlugin(world: World, aspectRatio: number): void```+## uprightOf — function @experimental+```+(sprite: SpriteData, transform: TransformData, data: RainUprightData): Upright | null+```++## uprightRects — function @experimental+```+(uprights: readonly Upright[], view: { left: number; bottom: number; right: number; top: number; }): MaskRect[]+```+## v2 — const @experimental```{ readonly create: (x?: number, y?: number) => Vec2; readonly clone: (a: Vec2) => Vec2; readonly add: (a: Vec2, b: Vec2) => Vec2; readonly sub: (a: Vec2, b: Vec2) => Vec2; readonly scale: (a: Vec2, s: number) => Vec2; readonly mul: (a: Vec2, b: Vec2) => Vec2; readonly neg: (a: Vec2) => Vec2; readonly dot: (a: Vec2, b: Vec2) => number; readonly cross: (a: Vec2, b: Vec2) => number; readonly len: (a: Vec2) => number; readonly len2: (a: Vec2) => number; readonly dist: (a: Vec2, b: Vec2) => number; readonly dist2: (a: Vec2, b: Vec2) => number; readonly normalize: (a: Vec2) => Vec2; readonly lerp: (a: Vec2, b: Vec2, t: number) => Vec2; readonly angle: (a: Vec2) => number; readonly fromAngle: (radians: number, length?: number) => Vec2; readonly rotate: (a: Vec2, radians: number) => Vec2; readonly perp: (a: Vec2) => Vec2; readonly equals: (a: Vec2, b: Vec2, epsilon?: number) => boolean; }diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex ed618c28d..8bcc6295f 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 · 1941 experimental · 3 deprecated+Symbols: 115 public · 159 beta · 1946 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -8217,6 +8217,17 @@ margin: numberround: boolean```+## RainUpright — const @experimental+```+ComponentDef<RainUprightData>+```++## RainUprightData — interface @experimental+```+enabled: boolean+inset: number+```+## ReadableWorld — type @experimental```Pick<World, 'valid' | 'has' | 'get'>@@ -12171,6 +12182,15 @@ staged: { revision: string | null; assets: number; bytes: number; } | nullCompressedTextureFormat | 'rgba8'```+## Upright — interface @experimental+```+amount: number+hx: number+hy: number+x: number+y: number+```+## ValidatePrefabOptions — interface @experimental```instanceOverrides: readonly PrefabOverride[] | undefined@@ -16813,6 +16833,16 @@ UIVisibilityPlugin(world: World, aspectRatio: number): void```+## uprightOf — function @experimental+```+(sprite: SpriteData, transform: TransformData, data: RainUprightData): Upright | null+```++## uprightRects — function @experimental+```+(uprights: readonly Upright[], view: { left: number; bottom: number; right: number; top: number; }): MaskRect[]+```+## v2 — const @experimental```{ readonly create: (x?: number, y?: number) => Vec2; readonly clone: (a: Vec2) => Vec2; readonly add: (a: Vec2, b: Vec2) => Vec2; readonly sub: (a: Vec2, b: Vec2) => Vec2; readonly scale: (a: Vec2, s: number) => Vec2; readonly mul: (a: Vec2, b: Vec2) => Vec2; readonly neg: (a: Vec2) => Vec2; readonly dot: (a: Vec2, b: Vec2) => number; readonly cross: (a: Vec2, b: Vec2) => number; readonly len: (a: Vec2) => number; readonly len2: (a: Vec2) => number; readonly dist: (a: Vec2, b: Vec2) => number; readonly dist2: (a: Vec2, b: Vec2) => number; readonly normalize: (a: Vec2) => Vec2; readonly lerp: (a: Vec2, b: Vec2, t: number) => Vec2; readonly angle: (a: Vec2) => number; readonly fromAngle: (radians: number, length?: number) => Vec2; readonly rotate: (a: Vec2, radians: number) => Vec2; readonly perp: (a: Vec2) => Vec2; readonly equals: (a: Vec2, b: Vec2, epsilon?: number) => boolean; }diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex c8d84e515..915b514fb 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 · 1932 experimental · 3 deprecated+Symbols: 115 public · 159 beta · 1937 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -7930,6 +7930,17 @@ margin: numberround: boolean```+## RainUpright — const @experimental+```+ComponentDef<RainUprightData>+```++## RainUprightData — interface @experimental+```+enabled: boolean+inset: number+```+## ReadableWorld — type @experimental```Pick<World, 'valid' | 'has' | 'get'>@@ -11884,6 +11895,15 @@ staged: { revision: string | null; assets: number; bytes: number; } | nullCompressedTextureFormat | 'rgba8'```+## Upright — interface @experimental+```+amount: number+hx: number+hy: number+x: number+y: number+```+## ValidatePrefabOptions — interface @experimental```instanceOverrides: readonly PrefabOverride[] | undefined@@ -16540,6 +16560,16 @@ UIVisibilityPlugin(world: World, aspectRatio: number): void```+## uprightOf — function @experimental+```+(sprite: SpriteData, transform: TransformData, data: RainUprightData): Upright | null+```++## uprightRects — function @experimental+```+(uprights: readonly Upright[], view: { left: number; bottom: number; right: number; top: number; }): MaskRect[]+```+## v2 — const @experimental```{ readonly create: (x?: number, y?: number) => Vec2; readonly clone: (a: Vec2) => Vec2; readonly add: (a: Vec2, b: Vec2) => Vec2; readonly sub: (a: Vec2, b: Vec2) => Vec2; readonly scale: (a: Vec2, s: number) => Vec2; readonly mul: (a: Vec2, b: Vec2) => Vec2; readonly neg: (a: Vec2) => Vec2; readonly dot: (a: Vec2, b: Vec2) => number; readonly cross: (a: Vec2, b: Vec2) => number; readonly len: (a: Vec2) => number; readonly len2: (a: Vec2) => number; readonly dist: (a: Vec2, b: Vec2) => number; readonly dist2: (a: Vec2, b: Vec2) => number; readonly normalize: (a: Vec2) => Vec2; readonly lerp: (a: Vec2, b: Vec2, t: number) => Vec2; readonly angle: (a: Vec2) => number; readonly fromAngle: (radians: number, length?: number) => Vec2; readonly rotate: (a: Vec2, radians: number) => Vec2; readonly perp: (a: Vec2) => Vec2; readonly equals: (a: Vec2, b: Vec2, epsilon?: number) => boolean; }diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.tsindex 28e94c438..2227406f0 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, shelterMaskSizeOf, ellipseStripsOf, type RainShelterData, type Shelter, type MaskRect } from './render/rainShelter';+export { RainShelter, RainUpright, uprightOf, uprightRects, drynessOf, maskRects, shelterMaskSizeOf, ellipseStripsOf, type RainShelterData, type RainUprightData, type Upright, 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/sources/rain2d.ts b/sdk/src/postprocess/sources/rain2d.tsindex 3c8c61518..db2453ae3 100644--- a/sdk/src/postprocess/sources/rain2d.ts+++ b/sdk/src/postprocess/sources/rain2d.ts@@ -11,8 +11,8 @@* much of the ground under it can be seen, so an opaque roof (which shows the roof, and the rain falls on that) is not dry, and one faded* to show the room is.*- * It cannot tell a character from the ground it stands on, so rings and the darkening of a wet floor are drawn over everything. They are- * small and low, which is why that reads as rain on the picture and not as a fault.+ * It cannot tell a character from the ground it stands on by itself, so a sprite marked `RainUpright` is painted into the red channel of the+ * same mask, and the rings, splashes, puddles and wet darkening are left off it. The falling streaks cross it: rain does fall on people.*/import type { ShaderHandle } from '../../render/material';import { Material } from '../../render/material';@@ -30,12 +30,13 @@ float vnoise(vec2 p) {float puddleNoise(vec2 p) {return vnoise(p) * 0.5 + vnoise(p * 2.07 + vec2(11.0, 5.0)) * 0.3 + vnoise(p * 4.3 + vec2(3.0, 17.0)) * 0.2;}-/// How dry the ground is at a point: the alpha of the shelter mask, which covers the view from (u_maskL, u_maskB) by (u_maskW, u_maskH) world units.-float dryAt(vec2 w) {- if (u_maskW <= 0.0 || u_maskH <= 0.0) return 0.0;+/// The mask at a point: its alpha is how dry the ground is, its red how much of the point is something standing on it. The mask covers the view from (u_maskL, u_maskB) by (u_maskW, u_maskH) world units.+vec2 maskAt(vec2 w) {+ if (u_maskW <= 0.0 || u_maskH <= 0.0) return vec2(0.0);vec2 uv = (w - vec2(u_maskL, u_maskB)) / vec2(u_maskW, u_maskH);- if (uv.x < 0.0 || uv.x > 1.0 || uv.y < 0.0 || uv.y > 1.0) return 0.0;- return textureLod(u_shelterMask, uv, 0.0).a;+ if (uv.x < 0.0 || uv.x > 1.0 || uv.y < 0.0 || uv.y > 1.0) return vec2(0.0);+ vec4 m = textureLod(u_shelterMask, uv, 0.0);+ return vec2(m.a, m.r);}/// One layer of streaks: columns across the screen, one streak per cell at most, scrolling down.float streaks(vec2 uv, float aspect, float cols, float speed, float seed, float T) {@@ -67,12 +68,13 @@ fn vnoise(p : vec2f) -> f32 {fn puddleNoise(p : vec2f) -> f32 {return vnoise(p) * 0.5 + vnoise(p * 2.07 + vec2f(11.0, 5.0)) * 0.3 + vnoise(p * 4.3 + vec2f(3.0, 17.0)) * 0.2;}-fn dryAt(w : vec2f) -> f32 {- if (mc.u_maskW <= 0.0 || mc.u_maskH <= 0.0) { return 0.0; }+fn maskAt(w : vec2f) -> vec2f {+ if (mc.u_maskW <= 0.0 || mc.u_maskH <= 0.0) { return vec2f(0.0); }let uv = (w - vec2f(mc.u_maskL, mc.u_maskB)) / vec2f(mc.u_maskW, mc.u_maskH);- if (uv.x < 0.0 || uv.x > 1.0 || uv.y < 0.0 || uv.y > 1.0) { return 0.0; }+ if (uv.x < 0.0 || uv.x > 1.0 || uv.y < 0.0 || uv.y > 1.0) { return vec2f(0.0); }// This device's texture rows run the other way from the clip space the mask was drawn in.- return textureSampleLevel(u_shelterMask, u_shelterMask_s, vec2f(uv.x, 1.0 - uv.y), 0.0).a;+ let m = textureSampleLevel(u_shelterMask, u_shelterMask_s, vec2f(uv.x, 1.0 - uv.y), 0.0);+ return vec2f(m.a, m.r);}fn streaks(uv : vec2f, aspect : f32, cols : f32, speed : f32, seed : f32, T : f32) -> f32 {let q = vec2f(uv.x * aspect - (1.0 - uv.y) * mc.u_wind, 1.0 - uv.y);@@ -130,9 +132,12 @@ void main() {tint = srgbToLinear(tint);#endif// Where a roof or a crown shows the ground under it, that ground is dry and nothing falls on it.- float dry = min(dryAt(w) * 1.15, 1.0);- float wet = u_wetness * (1.0 - dry);- float falling = clamp(u_intensity, 0.0, 1.0) * (1.0 - dry);+ vec2 m = maskAt(w);+ float dry = min(m.x * 1.15, 1.0);+ // Ground only: where a character or a trunk stands, the floor is not what is seen, so no rings, puddles or wet darkening are drawn on it.+ float ground = 1.0 - min(m.y * 1.15, 1.0);+ float wet = u_wetness * (1.0 - dry) * ground;+ float falling = clamp(u_intensity, 0.0, 1.0) * (1.0 - dry) * ground;vec3 col = src.rgb;// Standing water where a slow noise of the ground passes a threshold; the rest of the ground is only darker.@@ -184,9 +189,11 @@ ${WGSL}#ifdef ES_LINEARtint = srgbToLinear(tint);#endif- let dry = min(dryAt(w) * 1.15, 1.0);- let wet = mc.u_wetness * (1.0 - dry);- let falling = clamp(mc.u_intensity, 0.0, 1.0) * (1.0 - dry);+ let m = maskAt(w);+ let dry = min(m.x * 1.15, 1.0);+ let ground = 1.0 - min(m.y * 1.15, 1.0);+ let wet = mc.u_wetness * (1.0 - dry) * ground;+ let falling = clamp(mc.u_intensity, 0.0, 1.0) * (1.0 - dry) * ground;var col = src.rgb;let lo = 1.0 - mc.u_puddles;diff --git a/sdk/src/render/rainShelter.ts b/sdk/src/render/rainShelter.tsindex 6108cc864..5a846ca2d 100644--- a/sdk/src/render/rainShelter.ts+++ b/sdk/src/render/rainShelter.ts@@ -55,6 +55,60 @@ export const RainShelter = defineComponent<RainShelterData>('RainShelter',},);+/** The fields of the `RainUpright` component. @experimental */+export interface RainUprightData {+ /** Ground around the sprite's edge that the rain still draws on, in world units: the feet, or a trunk's base. */+ inset: number;+ /** Off: the sprite is treated as ground like any other. */+ enabled: boolean;+}++/**+ * Marks a sprite that STANDS on the ground (a character, a trunk, a crate), so the 2D rain's rings, splashes and wet darkening are not drawn over+ * it. The rain is laid over the finished picture and cannot tell a character from the floor under them; this tells it. Falling streaks still cross it.+ *+ * @experimental+ */+export const RainUpright = defineComponent<RainUprightData>('RainUpright',+ { inset: 0, enabled: true },+ {+ fields: {+ inset: { min: 0, step: 1, tooltip: 'Ground around the sprite\'s edge that the rain still draws on, in world units: the feet, or a trunk\'s base.' },+ },+ },+);++/** One upright sprite's rectangle, and how much of it shows (a faded one shows the ground behind it). */+export interface Upright {+ x: number;+ y: number;+ hx: number;+ hy: number;+ amount: number;+}++/** The upright a sprite is, or null where it has no body to keep the rain off. */+export function uprightOf(sprite: SpriteData, transform: TransformData, data: RainUprightData): Upright | null {+ if (!data.enabled || !sprite.enabled) return null;+ const amount = Math.min(Math.max(sprite.color.a, 0), 1);+ if (amount <= 0) return null;+ const { centre, half } = coveredGround(sprite, transform);+ const hx = half.x - data.inset;+ const hy = half.y - data.inset;+ if (hx <= 0 || hy <= 0) return null;+ return { x: centre.x, y: centre.y, hx, hy, amount };+}++/** What to draw for the uprights the view can see: a rectangle each, the amount in the red channel. */+export function uprightRects(uprights: readonly Upright[], view: { left: number; bottom: number; right: number; top: number }): MaskRect[] {+ const rects: MaskRect[] = [];+ for (const u of uprights) {+ if (u.x + u.hx < view.left || u.x - u.hx > view.right || u.y + u.hy < view.bottom || u.y - u.hy > view.top) continue;+ rects.push({ x: u.x, y: u.y, w: u.hx * 2, h: u.hy * 2, dry: u.amount });+ }+ return rects;+}+/** One shelter: its ground and how dry it is. A negative half height says round. */export interface Shelter {x: number;@@ -201,7 +255,7 @@ export function installRainShelter(app: App): () => void {return view && view.right > view.left && view.top > view.bottom ? view : null;};- const paint = (rects: readonly MaskRect[], view: { left: number; right: number; bottom: number; top: number }): boolean => {+ const paint = (rects: readonly MaskRect[], stands: readonly MaskRect[], view: { left: number; right: number; bottom: number; top: number }): boolean => {if (failed) return false;try {const size = shelterMaskSizeOf(askedSize, allowedSize());@@ -224,6 +278,9 @@ export function installRainShelter(app: App): () => void {Draw.setBlendMode(BlendMode.None);Draw.rect({ x: cx, y: cy }, { x: view.right - view.left, y: view.top - view.bottom }, { r: 0, g: 0, b: 0, a: 0 });for (const r of rects) Draw.rect({ x: r.x, y: r.y }, { x: r.w, y: r.h }, { r: 0, g: 0, b: 0, a: r.dry });+ // What stands on the ground goes in the red channel, and Lighten keeps the alpha the shelters wrote.+ Draw.setBlendMode(BlendMode.Lighten);+ for (const r of stands) Draw.rect({ x: r.x, y: r.y }, { x: r.w, y: r.h }, { r: r.dry, g: 0, b: 0, a: 0 });Draw.end();RenderTexture.end();RenderTexture.contentDrawn(target);@@ -240,18 +297,23 @@ export function installRainShelter(app: App): () => void {};const system = defineSystem(- [Query(RainShelter, Sprite, Transform)],- (shelters: Iterable<[Entity, RainShelterData, SpriteData, TransformData]>) => {+ [Query(RainShelter, Sprite, Transform), Query(RainUpright, Sprite, Transform)],+ (shelters: Iterable<[Entity, RainShelterData, SpriteData, TransformData]>, uprights: Iterable<[Entity, RainUprightData, SpriteData, TransformData]>) => {const found: Shelter[] = [];for (const [, data, sprite, transform] of shelters) {const shelter = shelterOf(sprite, transform, data);if (shelter) found.push(shelter);}+ const standing: Upright[] = [];+ for (const [, data, sprite, transform] of uprights) {+ const upright = uprightOf(sprite, transform, data);+ if (upright) standing.push(upright);+ }sheltersNow = found;maskNow = null;- if (found.length === 0) return;+ if (found.length === 0 && standing.length === 0) return;const view = viewOf();- if (view) paint(maskRects(found, view, ellipseStripsOf(shelterMaskSizeOf(askedSize, allowedSize()))), view);+ if (view) paint(maskRects(found, view, ellipseStripsOf(shelterMaskSizeOf(askedSize, allowedSize()))), uprightRects(standing, view), view);},{ name: 'RainShelterSystem' },);diff --git a/sdk/tests/atmosphere-2d.test.ts b/sdk/tests/atmosphere-2d.test.tsindex 44895630f..94b0b8421 100644--- a/sdk/tests/atmosphere-2d.test.ts+++ b/sdk/tests/atmosphere-2d.test.ts@@ -1,8 +1,11 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { readFileSync } from 'node:fs';+import { dirname, join } from 'node:path';+import { fileURLToPath } from 'node:url';import { describe, expect, it } from 'vitest';import { coversPoint, stepFade } from '../src/render/coverFade';-import { applyRainSheltersToRain, drynessOf, maskRects, shelterOf, shelterMaskSizeOf, ellipseStripsOf, ELLIPSE_STRIPS, type Shelter } from '../src/render/rainShelter';+import { applyRainSheltersToRain, drynessOf, maskRects, shelterOf, uprightOf, uprightRects, 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';@@ -138,6 +141,28 @@ describe('the 2D rain', () => {expect(s.dry).toBeCloseTo(0.75, 6);});+ it('lists a sprite that stands on the ground as an upright, with how much of it shows', () => {+ const u = uprightOf(sprite(0.5), at(10, 20), { inset: 4, enabled: true })!;+ expect(u).toMatchObject({ x: 10, y: 20, hx: 46, hy: 26 });+ expect(u.amount).toBe(0.5);+ expect(uprightOf(sprite(0), at(0, 0), { inset: 0, enabled: true })).toBeNull();+ expect(uprightOf(sprite(1), at(0, 0), { inset: 0, enabled: false })).toBeNull();+ expect(uprightOf(sprite(1), at(0, 0), { inset: 40, enabled: true })).toBeNull();+ });++ it('paints only the uprights the view can see, one rectangle each, the amount in the colour', () => {+ const view = { left: -100, right: 100, bottom: -100, top: 100 };+ const seen = uprightOf(sprite(1), at(0, 0), { inset: 0, enabled: true })!;+ const far = uprightOf(sprite(1), at(900, 0), { inset: 0, enabled: true })!;+ expect(uprightRects([seen, far], view)).toEqual([{ x: 0, y: 0, w: 100, h: 60, dry: 1 }]);+ });++ it('leaves the rings, splashes and wet darkening off what stands, in both shader languages', () => {+ const rain2dSource = readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'src', 'postprocess', 'sources', 'rain2d.ts'), 'utf8');+ expect(rain2dSource).toContain('float ground = 1.0 - min(m.y * 1.15, 1.0);');+ expect(rain2dSource).toContain('let ground = 1.0 - min(m.y * 1.15, 1.0);');+ });+it('says round by a negative half height', () => {expect(shelterOf(sprite(0), at(0, 0), { ...data, round: true })!.hy).toBeLessThan(0);});diff --git a/tools/check-corpus-authoring.mjs b/tools/check-corpus-authoring.mjsindex 101f52e9f..be2228e29 100644--- a/tools/check-corpus-authoring.mjs+++ b/tools/check-corpus-authoring.mjs@@ -138,6 +138,7 @@ const DISPOSITION = {BlobShadow: ['owed', 'only the blob-shadow render fixture places one; an example for a phone-scale scene that wants a shadow without a shadow map is owed'],CoverFade: ['owed', 'only the rainforest-2d probe, kept out of the examples, places one; an example of a top-down hut whose roof thins as the player walks in is owed'],CoverFadeTarget: ['owed', 'the tag that goes with CoverFade, and owed with it'],+ RainUpright: ['owed', 'only the rainforest-2d probe, kept out of the examples, places one; it arrives with the top-down rain example RainShelter is owed'],RainShelter: ['owed', 'only the rainforest-2d probe, kept out of the examples, places one; it arrives with the top-down rain example CoverFade is owed'],StaticBatch: ['owed', 'no corpus scene marks a mesh yet: a marked mesh is merged while the game runs, which a golden project has no frame to certify — the static-batch-on / static-batch-off render scenes, tests/static-batch.test.ts and the static-batch editor check hold it'],};