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): a sprite that stands on the ground keeps the rain's rings and wet darkening off it

yhh540d2b100c09
diff --git a/desktop b/desktop
index 8182250ad..10abc04d4 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 8182250ad857b8bf8063539b01a0a477b7aa5015
+Subproject commit 10abc04d4d1206b8f92035b1bee9f9ff3f6d1b8f
diff --git a/docs/astro/src/content/docs/graphics/sprites.mdx b/docs/astro/src/content/docs/graphics/sprites.mdx
index 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 stops
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 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.
+`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.mdx
index 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.json
index 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.ts
index 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.json
index 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.md
index 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: number
round: 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; } | null
CompressedTextureFormat | '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.md
index 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: number
round: 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; } | null
CompressedTextureFormat | '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.md
index 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: number
round: 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; } | null
CompressedTextureFormat | '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.md
index 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: number
round: 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; } | null
CompressedTextureFormat | '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.md
index 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: number
round: 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; } | null
CompressedTextureFormat | '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.ts
index 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.ts
index 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_LINEAR
tint = 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.ts
index 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.ts
index 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.mjs
index 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'],
};