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): what walks leaves rings on water and prints on soft ground

yhhaf662b801a36
diff --git a/desktop b/desktop
index 2a76f952a..a0e29f128 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 2a76f952aef8adbb947279d9627649600f074f2f
+Subproject commit a0e29f12827d4e7dfafa38cb05eadd72479a0f99
diff --git a/docs/astro/src/content/docs/graphics/sprites.mdx b/docs/astro/src/content/docs/graphics/sprites.mdx
index 9b85d61a9..5034f9d8c 100644
--- a/docs/astro/src/content/docs/graphics/sprites.mdx
+++ b/docs/astro/src/content/docs/graphics/sprites.mdx
@@ -302,6 +302,24 @@ The effect's **Remembered Brightness** and **Remembered Desaturation** say how t
`exploredToString()` gives a string and `exploredFromString(text)` puts it back (false for one that does not fit the fog's `texels`), and the fog repaints from it. The same grid is
what repaints the map after a lost graphics device. A scene with no `FogOfWar` has its `fog2d` effect turned off, not black.
+### Footsteps and ripples
+
+Put `Footsteps` on what walks, and `StepSurface` on the sprites that are ground worth marking: a pond (`kind` Water), a mud flat or snow (`kind` Print). Every `stride` world units
+the walker travels it takes a step, alternating left and right of the way it is heading. A step on a Water surface is a **ring** that spreads from a third of its size and fades;
+on a Print surface it is a **footprint** that stays full size and fades over `printLife` seconds; anywhere else it is nothing, unless the walker sets `onBareGround`. A surface's covered
+ground is its sprite's rectangle, or the ellipse inside it with `round`, and where two cover a point the one on the higher sprite layer wins.
+
+| Field | On | What it does |
+|---|---|---|
+| `stride`, `width` | `Footsteps` | How far between two steps, and how far apart the left and right feet are. |
+| `printSize`, `printLife`, `printColor` | `Footsteps` | A footprint's length, how long it lasts, and its colour (alpha is its strongest). |
+| `rippleSize`, `rippleLife`, `rippleColor` | `Footsteps` | A ring's final width, how long it takes to spread and fade, and its colour. |
+| `layer` | `Footsteps` | The sprite layer the steps are drawn on: above the ground, below whatever walks. |
+| `printTexture`, `rippleTexture` | `Footsteps` | A texture handle of your own for either; 0 uses the ones drawn by the engine (a disc cut to an oval, and a ring). |
+| `kind`, `round`, `margin` | `StepSurface` | Water or Print; the ellipse inside the rectangle; ground round the edge that counts. |
+
+Each step is a sprite of its own that the engine spawns and puts away, never saved, and at most 256 are alive at once over every walker. A walker that jumps across the world (a teleport) takes no steps for the jump.
+
### Depth layers (2.5D)
Check a layer under **Settings → Project → Rendering → Advanced → Depth-sorted layers** and it
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 0d47453bd..f98c605e8 100644
--- a/docs/astro/src/content/docs/zh-cn/graphics/sprites.mdx
+++ b/docs/astro/src/content/docs/zh-cn/graphics/sprites.mdx
@@ -256,6 +256,21 @@ world.applyEntityOrder([other, another, card]);
效果上的 **Remembered Brightness** 与 **Remembered Desaturation** 决定被记住的地面长什么样,**Unexplored Colour** 是没见过的地方的颜色。存档能保存玩家已经发现的地方:`exploredToString()` 返回一个字符串,`exploredFromString(text)` 把它放回去(与迷雾的 `texels` 不符时返回 false),迷雾随后据此重绘。显卡设备丢失后,也是靠这张网格重绘。场景里没有 `FogOfWar` 时,`fog2d` 效果会被关掉,而不是整屏变黑。
+### 脚印与涟漪
+
+给会走动的东西加 `Footsteps`,给值得留下痕迹的地面精灵加 `StepSurface`:池塘(`kind` 选 Water)、泥地或雪地(`kind` 选 Print)。走动者每走 `stride` 个世界单位就迈一步,左右脚沿前进方向交替。踩在 Water 表面上留下一个从三分之一大小扩散并淡出的**涟漪**;踩在 Print 表面上留下一个保持原大小、在 `printLife` 秒内淡去的**脚印**;其它地方什么也不留,除非走动者勾选 `onBareGround`。表面覆盖的地面是它精灵的矩形,勾 `round` 则取矩形内接的椭圆;两个表面都盖住同一点时,精灵层更高的那个生效。
+
+| 字段 | 所在组件 | 作用 |
+|---|---|---|
+| `stride`、`width` | `Footsteps` | 两步之间的距离,以及左右脚相距多远。 |
+| `printSize`、`printLife`、`printColor` | `Footsteps` | 脚印的长度、持续多久、颜色(alpha 是最浓时的透明度)。 |
+| `rippleSize`、`rippleLife`、`rippleColor` | `Footsteps` | 涟漪最终的宽度、扩散并淡出要多久、颜色。 |
+| `layer` | `Footsteps` | 痕迹画在哪个精灵层:在地面之上、走动者之下。 |
+| `printTexture`、`rippleTexture` | `Footsteps` | 自己的纹理句柄;0 表示用引擎画出来的那两张(切成椭圆的圆盘,和一个圆环)。 |
+| `kind`、`round`、`margin` | `StepSurface` | Water 或 Print;取矩形内接椭圆;边缘外多远仍算在表面上。 |
+
+每一步都是引擎自己生成、自己收走的精灵,不会被保存,所有走动者加起来最多同时存在 256 个。走动者瞬移越过半个世界时,那一跳不算步数。
+
### 深度层(2.5D)
在 **设置 → 项目 → 渲染 → 高级 → 深度排序层** 勾选某个层后,该层完全不再依赖
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 40a3a7e3a..356a15ae1 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": 2702,
+ "experimental": 2710,
"deprecated": 3
},
- "total": 2988,
+ "total": 2996,
"subsystems": [
{
"id": "mobile-controls",
diff --git a/docs/astro/src/data/componentDocs.ts b/docs/astro/src/data/componentDocs.ts
index bc1c179eb..9463ad35d 100644
--- a/docs/astro/src/data/componentDocs.ts
+++ b/docs/astro/src/data/componentDocs.ts
@@ -82,6 +82,8 @@ export const COMPONENT_DOCS: Record<string, ComponentDoc> = {
BakedLighting: { category: 'graphics', summary: 'How this scene is baked — atlas size, density, bounces — and a record of what the last bake read.', doc: 'graphics/lighting', anchor: 'baked-light', anchorZh: '烘焙光照' },
DecalProjector: { category: 'graphics', summary: 'Prints this entity\'s material onto what its box covers — the surface is cut to the box and drawn again, so a decal is lit and shadowed as the surface under it.', doc: 'graphics/lighting', anchor: 'baked-light', anchorZh: '烘焙光照' },
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: '假阴影用一个圆片代替阴影图' },
+ Footsteps: { category: 'graphics', summary: 'Makes what walks leave rings on water and prints on soft ground, by the StepSurface under each step.', doc: 'graphics/sprites', anchor: 'footsteps-and-ripples', anchorZh: '脚印与涟漪' },
+ StepSurface: { category: 'graphics', summary: 'Makes the ground this sprite covers a surface that steps leave water rings or footprints on.', doc: 'graphics/sprites', anchor: 'footsteps-and-ripples', anchorZh: '脚印与涟漪' },
SwayPusher: { category: 'graphics', summary: 'A body the plants of a sprite-sway material lean away from as it walks through them: the eight nearest the camera are told to the shader.', doc: 'graphics/materials', anchor: 'built-in-shader-templates', anchorZh: '内置着色器模板' },
FogOfWar: { category: 'graphics', summary: 'Names the world rectangle a 2D fog of war covers: ground no SightViewer has seen is dark, ground seen and left is remembered, ground in view is clear.', doc: 'graphics/sprites', anchor: 'fog-of-war', anchorZh: '战争迷雾' },
SightViewer: { category: 'graphics', summary: 'An eye: sprites with a SightTarget are seen while some viewer has a clear line to them past the ShadowCaster2D walls.', doc: 'graphics/sprites', anchor: 'what-the-player-can-see', anchorZh: '玩家能看见什么' },
diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.json
index 2716afe2d..54a177fa9 100644
--- a/docs/astro/src/data/components.generated.json
+++ b/docs/astro/src/data/components.generated.json
@@ -2047,6 +2047,111 @@
"damping"
]
},
+ {
+ "name": "Footsteps",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "stride",
+ "type": "number",
+ "default": "28",
+ "doc": "How far it travels between two steps.",
+ "range": "≥ 1, step 1"
+ },
+ {
+ "key": "width",
+ "type": "number",
+ "default": "10",
+ "doc": "How far apart the left and right feet are.",
+ "range": "≥ 0, step 1"
+ },
+ {
+ "key": "printSize",
+ "type": "number",
+ "default": "14",
+ "doc": "A footprint's length.",
+ "range": "≥ 1, step 1"
+ },
+ {
+ "key": "printLife",
+ "type": "number",
+ "default": "6",
+ "doc": "How long a footprint lasts before it has faded.",
+ "range": "≥ 0.1, step 0.1"
+ },
+ {
+ "key": "printColor",
+ "type": "Color",
+ "default": "#00000066"
+ },
+ {
+ "key": "rippleSize",
+ "type": "number",
+ "default": "64",
+ "doc": "A ring's width when it has spread.",
+ "range": "≥ 1, step 1"
+ },
+ {
+ "key": "rippleLife",
+ "type": "number",
+ "default": "1.4",
+ "doc": "How long a ring takes to spread and fade.",
+ "range": "≥ 0.1, step 0.1"
+ },
+ {
+ "key": "rippleColor",
+ "type": "Color",
+ "default": "#ffffffb3"
+ },
+ {
+ "key": "layer",
+ "type": "number",
+ "default": "1",
+ "doc": "The sprite layer the steps are drawn on: above the ground, below whatever walks.",
+ "range": "step 1"
+ },
+ {
+ "key": "onBareGround",
+ "type": "boolean",
+ "default": "false",
+ "doc": "Also leave a print where there is no StepSurface."
+ },
+ {
+ "key": "printTexture",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "rippleTexture",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ }
+ ],
+ "animatable": [
+ "stride",
+ "width",
+ "printSize",
+ "printLife",
+ "printColor.r",
+ "printColor.g",
+ "printColor.b",
+ "printColor.a",
+ "rippleSize",
+ "rippleLife",
+ "rippleColor.r",
+ "rippleColor.g",
+ "rippleColor.b",
+ "rippleColor.a",
+ "layer",
+ "printTexture",
+ "rippleTexture"
+ ]
+ },
{
"name": "Health",
"source": "ts",
@@ -5688,6 +5793,44 @@
"batched"
]
},
+ {
+ "name": "StepSurface",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "kind",
+ "type": "enum",
+ "default": "Water (a ring)",
+ "doc": "What a step on this ground leaves: a ring that spreads, or a footprint.",
+ "values": [
+ "Water (a ring)",
+ "Print (a footprint)"
+ ]
+ },
+ {
+ "key": "round",
+ "type": "boolean",
+ "default": "false",
+ "doc": "The covered ground is the ellipse inside the sprite's rectangle and not the whole of it."
+ },
+ {
+ "key": "margin",
+ "type": "number",
+ "default": "0",
+ "doc": "Ground around the sprite's edge that counts as on it, in world units.",
+ "range": "≥ 0, step 1"
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ }
+ ],
+ "animatable": [
+ "kind",
+ "margin"
+ ]
+ },
{
"name": "StreamedWorld",
"source": "ts",
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index e7839cbcc..e3e5354b8 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 · 1950 experimental · 3 deprecated
+Symbols: 115 public · 159 beta · 1958 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -4397,6 +4397,28 @@ target: number
number
```
+## Footsteps — const @experimental
+```
+ComponentDef<FootstepsData>
+```
+
+## FootstepsData — interface @experimental
+```
+enabled: boolean
+layer: number
+onBareGround: boolean
+printColor: { r: number; g: number; b: number; a: number; }
+printLife: number
+printSize: number
+printTexture: number
+rippleColor: { r: number; g: number; b: number; a: number; }
+rippleLife: number
+rippleSize: number
+rippleTexture: number
+stride: number
+width: number
+```
+
## ForceFieldType — enum @experimental
```
Directional = 0
@@ -10137,6 +10159,25 @@ position: StatsPosition | undefined
'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
```
+## StepKind — enum @experimental
+```
+Print = 1
+Water = 0
+```
+
+## StepSurface — const @experimental
+```
+ComponentDef<StepSurfaceData>
+```
+
+## StepSurfaceData — interface @experimental
+```
+enabled: boolean
+kind: StepKind
+margin: number
+round: boolean
+```
+
## Stick — const @public
```
(stick: "left" | "right", pad?: number) => Binding
@@ -14396,6 +14437,11 @@ FocusPlugin
Plugin
```
+## footAt — function @experimental
+```
+(x: number, y: number, heading: number, width: number, left: boolean): { x: number; y: number; }
+```
+
## formatActionArg — function @experimental
```
(params: Readonly<Record<string, AiParamValue>> | undefined, defs: readonly AiParamDef[], separator?: string): string | undefined
@@ -16396,6 +16442,11 @@ MotionDriver<AnimatorClipMotion>
(error: unknown): string | undefined
```
+## stampLook — function @experimental
+```
+(kind: StepKind, age: number, life: number): { scale: number; alpha: number; }
+```
+
## startDebugChannel — function @experimental
```
(config: DebugChannelConfig): void
@@ -16461,6 +16512,11 @@ StatsPlugin
(hour: number, latitude: number, declination: number, north: number): { elevation: number; azimuth: number; }
```
+## surfaceAt — function @experimental
+```
+(x: number, y: number, surfaces: readonly { kind: StepKind; layer: number; centre: { x: number; y: number; }; half: { x: number; y: number; }; margin: number; round: boolean; }[]): StepKind | null
+```
+
## switchTheme — function @experimental
```
(world: World, tokens: ThemeTokens): void
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 8874900c2..d68d303ec 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 · 1969 experimental · 3 deprecated
+Symbols: 115 public · 164 beta · 1977 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -4405,6 +4405,28 @@ target: number
number
```
+## Footsteps — const @experimental
+```
+ComponentDef<FootstepsData>
+```
+
+## FootstepsData — interface @experimental
+```
+enabled: boolean
+layer: number
+onBareGround: boolean
+printColor: { r: number; g: number; b: number; a: number; }
+printLife: number
+printSize: number
+printTexture: number
+rippleColor: { r: number; g: number; b: number; a: number; }
+rippleLife: number
+rippleSize: number
+rippleTexture: number
+stride: number
+width: number
+```
+
## ForceFieldType — enum @experimental
```
Directional = 0
@@ -10350,6 +10372,25 @@ position: StatsPosition | undefined
'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
```
+## StepKind — enum @experimental
+```
+Print = 1
+Water = 0
+```
+
+## StepSurface — const @experimental
+```
+ComponentDef<StepSurfaceData>
+```
+
+## StepSurfaceData — interface @experimental
+```
+enabled: boolean
+kind: StepKind
+margin: number
+round: boolean
+```
+
## Stick — const @public
```
(stick: "left" | "right", pad?: number) => Binding
@@ -14649,6 +14690,11 @@ FocusPlugin
Plugin
```
+## footAt — function @experimental
+```
+(x: number, y: number, heading: number, width: number, left: boolean): { x: number; y: number; }
+```
+
## formatActionArg — function @experimental
```
(params: Readonly<Record<string, AiParamValue>> | undefined, defs: readonly AiParamDef[], separator?: string): string | undefined
@@ -16659,6 +16705,11 @@ MotionDriver<AnimatorClipMotion>
(error: unknown): string | undefined
```
+## stampLook — function @experimental
+```
+(kind: StepKind, age: number, life: number): { scale: number; alpha: number; }
+```
+
## startDebugChannel — function @experimental
```
(config: DebugChannelConfig): void
@@ -16724,6 +16775,11 @@ StatsPlugin
(hour: number, latitude: number, declination: number, north: number): { elevation: number; azimuth: number; }
```
+## surfaceAt — function @experimental
+```
+(x: number, y: number, surfaces: readonly { kind: StepKind; layer: number; centre: { x: number; y: number; }; half: { x: number; y: number; }; margin: number; round: boolean; }[]): StepKind | null
+```
+
## switchTheme — function @experimental
```
(world: World, tokens: ThemeTokens): void
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 921affc6f..b84796d42 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 · 1949 experimental · 3 deprecated
+Symbols: 115 public · 161 beta · 1957 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -4392,6 +4392,28 @@ target: number
number
```
+## Footsteps — const @experimental
+```
+ComponentDef<FootstepsData>
+```
+
+## FootstepsData — interface @experimental
+```
+enabled: boolean
+layer: number
+onBareGround: boolean
+printColor: { r: number; g: number; b: number; a: number; }
+printLife: number
+printSize: number
+printTexture: number
+rippleColor: { r: number; g: number; b: number; a: number; }
+rippleLife: number
+rippleSize: number
+rippleTexture: number
+stride: number
+width: number
+```
+
## ForceFieldType — enum @experimental
```
Directional = 0
@@ -10132,6 +10154,25 @@ position: StatsPosition | undefined
'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
```
+## StepKind — enum @experimental
+```
+Print = 1
+Water = 0
+```
+
+## StepSurface — const @experimental
+```
+ComponentDef<StepSurfaceData>
+```
+
+## StepSurfaceData — interface @experimental
+```
+enabled: boolean
+kind: StepKind
+margin: number
+round: boolean
+```
+
## Stick — const @public
```
(stick: "left" | "right", pad?: number) => Binding
@@ -14391,6 +14432,11 @@ FocusPlugin
Plugin
```
+## footAt — function @experimental
+```
+(x: number, y: number, heading: number, width: number, left: boolean): { x: number; y: number; }
+```
+
## formatActionArg — function @experimental
```
(params: Readonly<Record<string, AiParamValue>> | undefined, defs: readonly AiParamDef[], separator?: string): string | undefined
@@ -16401,6 +16447,11 @@ MotionDriver<AnimatorClipMotion>
(error: unknown): string | undefined
```
+## stampLook — function @experimental
+```
+(kind: StepKind, age: number, life: number): { scale: number; alpha: number; }
+```
+
## startDebugChannel — function @experimental
```
(config: DebugChannelConfig): void
@@ -16466,6 +16517,11 @@ StatsPlugin
(hour: number, latitude: number, declination: number, north: number): { elevation: number; azimuth: number; }
```
+## surfaceAt — function @experimental
+```
+(x: number, y: number, surfaces: readonly { kind: StepKind; layer: number; centre: { x: number; y: number; }; half: { x: number; y: number; }; margin: number; round: boolean; }[]): StepKind | null
+```
+
## switchTheme — function @experimental
```
(world: World, tokens: ThemeTokens): void
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 36506e13a..d7f121fa3 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 · 1971 experimental · 3 deprecated
+Symbols: 115 public · 159 beta · 1979 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -4392,6 +4392,28 @@ target: number
number
```
+## Footsteps — const @experimental
+```
+ComponentDef<FootstepsData>
+```
+
+## FootstepsData — interface @experimental
+```
+enabled: boolean
+layer: number
+onBareGround: boolean
+printColor: { r: number; g: number; b: number; a: number; }
+printLife: number
+printSize: number
+printTexture: number
+rippleColor: { r: number; g: number; b: number; a: number; }
+rippleLife: number
+rippleSize: number
+rippleTexture: number
+stride: number
+width: number
+```
+
## ForceFieldType — enum @experimental
```
Directional = 0
@@ -10426,6 +10448,25 @@ position: StatsPosition | undefined
'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
```
+## StepKind — enum @experimental
+```
+Print = 1
+Water = 0
+```
+
+## StepSurface — const @experimental
+```
+ComponentDef<StepSurfaceData>
+```
+
+## StepSurfaceData — interface @experimental
+```
+enabled: boolean
+kind: StepKind
+margin: number
+round: boolean
+```
+
## Stick — const @public
```
(stick: "left" | "right", pad?: number) => Binding
@@ -14696,6 +14737,11 @@ FocusPlugin
Plugin
```
+## footAt — function @experimental
+```
+(x: number, y: number, heading: number, width: number, left: boolean): { x: number; y: number; }
+```
+
## formatActionArg — function @experimental
```
(params: Readonly<Record<string, AiParamValue>> | undefined, defs: readonly AiParamDef[], separator?: string): string | undefined
@@ -16706,6 +16752,11 @@ MotionDriver<AnimatorClipMotion>
(error: unknown): string | undefined
```
+## stampLook — function @experimental
+```
+(kind: StepKind, age: number, life: number): { scale: number; alpha: number; }
+```
+
## startDebugChannel — function @experimental
```
(config: DebugChannelConfig): void
@@ -16771,6 +16822,11 @@ StatsPlugin
(hour: number, latitude: number, declination: number, north: number): { elevation: number; azimuth: number; }
```
+## surfaceAt — function @experimental
+```
+(x: number, y: number, surfaces: readonly { kind: StepKind; layer: number; centre: { x: number; y: number; }; half: { x: number; y: number; }; margin: number; round: boolean; }[]): StepKind | null
+```
+
## switchTheme — function @experimental
```
(world: World, tokens: ThemeTokens): void
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 0fd8bda5e..b58fe14bc 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 · 1962 experimental · 3 deprecated
+Symbols: 115 public · 159 beta · 1970 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -4392,6 +4392,28 @@ target: number
number
```
+## Footsteps — const @experimental
+```
+ComponentDef<FootstepsData>
+```
+
+## FootstepsData — interface @experimental
+```
+enabled: boolean
+layer: number
+onBareGround: boolean
+printColor: { r: number; g: number; b: number; a: number; }
+printLife: number
+printSize: number
+printTexture: number
+rippleColor: { r: number; g: number; b: number; a: number; }
+rippleLife: number
+rippleSize: number
+rippleTexture: number
+stride: number
+width: number
+```
+
## ForceFieldType — enum @experimental
```
Directional = 0
@@ -10139,6 +10161,25 @@ position: StatsPosition | undefined
'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
```
+## StepKind — enum @experimental
+```
+Print = 1
+Water = 0
+```
+
+## StepSurface — const @experimental
+```
+ComponentDef<StepSurfaceData>
+```
+
+## StepSurfaceData — interface @experimental
+```
+enabled: boolean
+kind: StepKind
+margin: number
+round: boolean
+```
+
## Stick — const @public
```
(stick: "left" | "right", pad?: number) => Binding
@@ -14423,6 +14464,11 @@ FocusPlugin
Plugin
```
+## footAt — function @experimental
+```
+(x: number, y: number, heading: number, width: number, left: boolean): { x: number; y: number; }
+```
+
## formatActionArg — function @experimental
```
(params: Readonly<Record<string, AiParamValue>> | undefined, defs: readonly AiParamDef[], separator?: string): string | undefined
@@ -16433,6 +16479,11 @@ MotionDriver<AnimatorClipMotion>
(error: unknown): string | undefined
```
+## stampLook — function @experimental
+```
+(kind: StepKind, age: number, life: number): { scale: number; alpha: number; }
+```
+
## startDebugChannel — function @experimental
```
(config: DebugChannelConfig): void
@@ -16498,6 +16549,11 @@ StatsPlugin
(hour: number, latitude: number, declination: number, north: number): { elevation: number; azimuth: number; }
```
+## surfaceAt — function @experimental
+```
+(x: number, y: number, surfaces: readonly { kind: StepKind; layer: number; centre: { x: number; y: number; }; half: { x: number; y: number; }; margin: number; round: boolean; }[]): StepKind | null
+```
+
## switchTheme — function @experimental
```
(world: World, tokens: ThemeTokens): void
diff --git a/sdk/src/animation/AnimationPlugin.ts b/sdk/src/animation/AnimationPlugin.ts
index 0d740cf5b..4a716070e 100644
--- a/sdk/src/animation/AnimationPlugin.ts
+++ b/sdk/src/animation/AnimationPlugin.ts
@@ -27,6 +27,7 @@ import { installRainShelter } from '../render/rainShelter';
import { installSight } from '../render/sight';
import { installFogOfWar } from '../render/fogOfWar';
import { installSwayPush } from '../render/swayPush';
+import { installFootsteps } from '../render/footsteps';
import { SystemLabel } from '../ecs/systemLabels';
export class AnimationPlugin implements Plugin {
@@ -64,7 +65,8 @@ export class AnimationPlugin implements Plugin {
// After the sight system, whose walls it casts rays against.
const offFog = installFogOfWar(app);
const offSwayPush = installSwayPush(app);
- const release = (): void => { offDespawn(); offCoverFade(); offRainShelter(); offSight(); offFog(); offSwayPush(); };
+ const offFootsteps = installFootsteps(app);
+ const release = (): void => { offDespawn(); offCoverFade(); offRainShelter(); offSight(); offFog(); offSwayPush(); offFootsteps(); };
this.despawnCleanups_.set(app, release);
this.latestDespawnCleanup_ = release;
diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.ts
index 34a1410e3..10e0bbc63 100644
--- a/sdk/src/core-render.ts
+++ b/sdk/src/core-render.ts
@@ -347,6 +347,7 @@ export { buildPathGeometry, mergeGeometry, cubicBezier, quadraticBezier, circleP
export type { PathStyle, PathFill, PathStroke, PathColor, LineJoin, LineCap } from './render/vectorPath';
export { setPath, clearPath } from './render/pathRenderer';
export { RainShelter, RainUpright, uprightOf, uprightRects, drynessOf, maskRects, shelterMaskSizeOf, ellipseStripsOf, type RainShelterData, type RainUprightData, type Upright, type Shelter, type MaskRect } from './render/rainShelter';
+export { Footsteps, StepSurface, StepKind, surfaceAt, footAt, stampLook, type FootstepsData, type StepSurfaceData } from './render/footsteps';
export { SwayPusher, nearestPushers, SWAY_PUSHERS, type SwayPusherData, type PushValue } from './render/swayPush';
export { FogOfWar, ExploredGrid, fanDistances, exploredToString, exploredFromString, type FogOfWarData } from './render/fogOfWar';
export { SightViewer, SightTarget, segmentBlocked, seesPoint, sightRingOf, ringContains, currentSightRings, type SightViewerData, type SightTargetData, type SightRing, type SightPoint } from './render/sight';
diff --git a/sdk/src/render/footsteps.ts b/sdk/src/render/footsteps.ts
new file mode 100644
index 000000000..47222af07
--- /dev/null
+++ b/sdk/src/render/footsteps.ts
@@ -0,0 +1,331 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file footsteps.ts
+ * @brief What a body leaves behind it as it walks: a ring spreading on water, a print in mud, each fading as it ages.
+ *
+ * @details `Footsteps` goes on what walks. Every `stride` world units it travels it takes a step, alternating left and right of its heading, and what
+ * the step makes depends on what it stands on: `StepSurface` goes on a sprite (the pond, the mud flat, the snow) and its covered ground, the
+ * rectangle of the sprite or the ellipse inside it, is that surface. On water a step is a ring that grows and fades; on a print surface it is
+ * a footprint that stays a while and fades; anywhere else it is nothing, unless the walker says `onBareGround`.
+ *
+ * A step is a sprite of its own, spawned and despawned by this system and never saved. With no texture named, the rings and the prints are drawn
+ * once into two small textures: a ring, and a disc that the print's oval is cut from. Name a texture for either and that is used instead.
+ * Prints are a sprite below the walker (`layer`), so they need a layer between the ground and the characters. It runs in play only.
+ */
+import type { App } from '../app/app';
+import type { Entity } from '../types';
+import { defineComponent, RuntimeOnly, Sprite, Transform, type SpriteData, type TransformData } from '../ecs/component';
+import { defineSystem, Schedule, GetWorld } from '../ecs/system';
+import { Res, Time, type TimeData } from '../ecs/resource';
+import { Query } from '../ecs/query';
+import type { World } from '../ecs/world';
+import { isEditor, isPlayMode } from '../ecs/env';
+import { coveredGround, coversPoint } from './coverFade';
+import { Draw } from './draw';
+import { BlendMode } from './blend';
+import { Renderer } from './renderer';
+import { RenderTexture, type RenderTextureHandle } from './renderTexture';
+import { log } from '../util/logger';
+
+/** What a surface makes of a step. */
+export enum StepKind {
+ /** A ring that spreads and fades. */
+ Water = 0,
+ /** A footprint that stays a while and fades. */
+ Print = 1,
+}
+
+/** The fields of the `StepSurface` component. @experimental */
+export interface StepSurfaceData {
+ kind: StepKind;
+ /** The covered ground is the ellipse inside the sprite's rectangle, not the whole of it. */
+ round: boolean;
+ /** Ground around the sprite's edge that counts as on it, in world units. */
+ margin: number;
+ enabled: boolean;
+}
+
+/**
+ * Makes the ground this sprite covers a surface that steps leave water rings or footprints on.
+ *
+ * @experimental
+ */
+export const StepSurface = defineComponent<StepSurfaceData>('StepSurface',
+ { kind: StepKind.Water, round: false, margin: 0, enabled: true },
+ {
+ fields: {
+ kind: { enum: [{ label: 'Water (a ring)', value: StepKind.Water }, { label: 'Print (a footprint)', value: StepKind.Print }], tooltip: 'What a step on this ground leaves: a ring that spreads, or a footprint.' },
+ round: { tooltip: "The covered ground is the ellipse inside the sprite's rectangle and not the whole of it." },
+ margin: { min: 0, step: 1, tooltip: "Ground around the sprite's edge that counts as on it, in world units." },
+ },
+ },
+);
+
+/** The fields of the `Footsteps` component. @experimental */
+export interface FootstepsData {
+ /** How far it travels between two steps, in world units. */
+ stride: number;
+ /** How far apart the left and right feet are, in world units. */
+ width: number;
+ /** A footprint's length, in world units, and how long it lasts, in seconds. */
+ printSize: number;
+ printLife: number;
+ printColor: { r: number; g: number; b: number; a: number };
+ /** A ring's final size (its width), in world units, and how long it takes to spread and fade, in seconds. */
+ rippleSize: number;
+ rippleLife: number;
+ rippleColor: { r: number; g: number; b: number; a: number };
+ /** The sprite layer the steps are drawn on: above the ground, below whatever walks. */
+ layer: number;
+ /** Also leave a print where there is no surface at all. */
+ onBareGround: boolean;
+ /** Optional textures for a print and a ring (a texture handle); 0 uses the ones drawn here. */
+ printTexture: number;
+ rippleTexture: number;
+ enabled: boolean;
+}
+
+/**
+ * Makes what walks leave rings on water and prints on soft ground, by what it stands on (see `StepSurface`).
+ *
+ * @experimental
+ */
+export const Footsteps = defineComponent<FootstepsData>('Footsteps',
+ {
+ stride: 28, width: 10, printSize: 14, printLife: 6, printColor: { r: 0, g: 0, b: 0, a: 0.4 },
+ rippleSize: 64, rippleLife: 1.4, rippleColor: { r: 1, g: 1, b: 1, a: 0.7 },
+ layer: 1, onBareGround: false, printTexture: 0, rippleTexture: 0, enabled: true,
+ },
+ {
+ fields: {
+ stride: { min: 1, step: 1, unit: 'wu', tooltip: 'How far it travels between two steps.' },
+ width: { min: 0, step: 1, unit: 'wu', tooltip: 'How far apart the left and right feet are.' },
+ printSize: { min: 1, step: 1, unit: 'wu', tooltip: "A footprint's length." },
+ printLife: { min: 0.1, step: 0.1, unit: 's', tooltip: 'How long a footprint lasts before it has faded.' },
+ rippleSize: { min: 1, step: 1, unit: 'wu', tooltip: "A ring's width when it has spread." },
+ rippleLife: { min: 0.1, step: 0.1, unit: 's', tooltip: 'How long a ring takes to spread and fade.' },
+ layer: { step: 1, tooltip: 'The sprite layer the steps are drawn on: above the ground, below whatever walks.' },
+ onBareGround: { tooltip: 'Also leave a print where there is no StepSurface.' },
+ },
+ },
+);
+
+/** The surface a step lands on: the highest sprite layer of the surfaces that cover the point, or null. */
+export function surfaceAt(
+ x: number, y: number,
+ surfaces: readonly { kind: StepKind; layer: number; centre: { x: number; y: number }; half: { x: number; y: number }; margin: number; round: boolean }[],
+): StepKind | null {
+ let best: { kind: StepKind; layer: number } | null = null;
+ for (const s of surfaces) {
+ if (!coversPoint(x, y, s.centre, s.half, s.margin, s.round)) continue;
+ if (!best || s.layer >= best.layer) best = { kind: s.kind, layer: s.layer };
+ }
+ return best ? best.kind : null;
+}
+
+/** Where one foot lands: `stride` along from the last step is not asked here; this is the foot's side of a body heading `heading` (radians). */
+export function footAt(x: number, y: number, heading: number, width: number, left: boolean): { x: number; y: number } {
+ const side = left ? 1 : -1;
+ return { x: x - Math.sin(heading) * width * 0.5 * side, y: y + Math.cos(heading) * width * 0.5 * side };
+}
+
+/** A step's look at `age` of `life` seconds: how big and how clear. A ring spreads from a third of its size and fades; a print stays full size and fades. */
+export function stampLook(kind: StepKind, age: number, life: number): { scale: number; alpha: number } {
+ const t = Math.min(Math.max(age / Math.max(life, 1e-3), 0), 1);
+ if (kind === StepKind.Water) return { scale: 0.33 + 0.67 * (1 - (1 - t) * (1 - t)), alpha: (1 - t) * (1 - t) };
+ return { scale: 1, alpha: 1 - t * t };
+}
+
+/** The most steps alive at once, over every walker: a crowd that walks for ever holds a bounded number of sprites. */
+const MAX_STEPS = 256;
+
+interface Stamp {
+ entity: Entity;
+ kind: StepKind;
+ age: number;
+ life: number;
+ width: number;
+ length: number;
+ color: { r: number; g: number; b: number; a: number };
+}
+
+interface Walker {
+ x: number;
+ y: number;
+ carried: number;
+ left: boolean;
+}
+
+interface DefaultTextures {
+ ring: RenderTextureHandle;
+ disc: RenderTextureHandle;
+}
+
+/** Column-major orthographic projection over a rectangle: what RenderTexture.begin wants. */
+function ortho(l: number, r: number, b: number, t: number): Float32Array {
+ const m = new Float32Array(16);
+ m[0] = 2 / (r - l);
+ m[5] = 2 / (t - b);
+ m[10] = -1;
+ m[12] = -(r + l) / (r - l);
+ m[13] = -(t + b) / (t - b);
+ m[15] = 1;
+ return m;
+}
+
+/** Installs the system that takes steps and ages them. Returns the function that puts every step away. */
+export function installFootsteps(app: App): () => void {
+ const stamps: Stamp[] = [];
+ const walkers = new Map<Entity, Walker>();
+ let textures: DefaultTextures | null = null;
+ let failed = false;
+
+ /** The ring and the disc, drawn once; drawn again where the device was lost. */
+ const defaults = (): DefaultTextures | null => {
+ if (failed) return null;
+ try {
+ if (textures && !RenderTexture.contentLost(textures.ring) && !RenderTexture.contentLost(textures.disc)) return textures;
+ if (!textures) {
+ const ring = RenderTexture.create({ width: 64, height: 64, depth: false, filter: 'linear' });
+ const disc = RenderTexture.create({ width: 64, height: 64, depth: false, filter: 'linear' });
+ // The renderer may not be up yet: try again next frame.
+ if (ring.texture === 0 || disc.texture === 0) { RenderTexture.release(ring); RenderTexture.release(disc); return null; }
+ textures = { ring, disc };
+ }
+ const vp = ortho(-1, 1, -1, 1);
+ const paint = (target: RenderTextureHandle, body: () => void): void => {
+ RenderTexture.begin(target, vp);
+ Draw.begin(vp);
+ Renderer.setViewport(0, 0, target.width, target.height);
+ Draw.setBlendMode(BlendMode.None);
+ Draw.rect({ x: 0, y: 0 }, { x: 2, y: 2 }, { r: 1, g: 1, b: 1, a: 0 });
+ body();
+ Draw.end();
+ RenderTexture.end();
+ RenderTexture.contentDrawn(target);
+ };
+ paint(textures.ring, () => Draw.circleOutline({ x: 0, y: 0 }, 0.86, { r: 1, g: 1, b: 1, a: 1 }, 0.1, 48));
+ paint(textures.disc, () => Draw.circle({ x: 0, y: 0 }, 0.95, { r: 1, g: 1, b: 1, a: 1 }, true, 32));
+ return textures;
+ } catch (error) {
+ failed = true;
+ log.warn('footsteps', `the footstep textures cannot be drawn on this device: ${String(error)}`);
+ return null;
+ }
+ };
+
+ const away = (world: World, stamp: Stamp): void => {
+ if (world.valid(stamp.entity)) world.despawn(stamp.entity);
+ };
+
+ interface Request { kind: StepKind; foot: { x: number; y: number }; heading: number; step: FootstepsData }
+ const pending: Request[] = [];
+
+ const spawnStep = (world: World, { kind, foot, heading, step }: Request): void => {
+ const made = defaults();
+ const texture = kind === StepKind.Water ? (step.rippleTexture || made?.ring.texture || 0) : (step.printTexture || made?.disc.texture || 0);
+ if (texture === 0) return;
+ while (stamps.length >= MAX_STEPS) { away(world, stamps[0]!); stamps.shift(); }
+ const entity = world.spawn();
+ const half = heading / 2;
+ const water = kind === StepKind.Water;
+ const color = water ? step.rippleColor : step.printColor;
+ // A print is an oval with its length along the heading; a ring is round.
+ const length = water ? step.rippleSize : step.printSize;
+ const width = water ? step.rippleSize : step.printSize * 0.55;
+ world.insert(entity, RuntimeOnly);
+ world.insert(entity, Transform, {
+ position: { x: foot.x, y: foot.y, z: 0 },
+ rotation: water ? { w: 1, x: 0, y: 0, z: 0 } : { w: Math.cos(half), x: 0, y: 0, z: Math.sin(half) },
+ });
+ world.insert(entity, Sprite, {
+ texture, size: { x: length * (water ? 0.33 : 1), y: width * (water ? 0.33 : 1) },
+ color: { r: color.r, g: color.g, b: color.b, a: color.a }, layer: step.layer,
+ });
+ stamps.push({ entity, kind, age: 0, life: water ? step.rippleLife : step.printLife, width: width, length, color });
+ };
+
+ // system-access: steps are spawned, written and despawned through the world, one sprite each, because they are not authored.
+ const system = defineSystem(
+ [Query(Footsteps, Transform), Query(StepSurface, Sprite, Transform), Res(Time), GetWorld()],
+ (
+ movers: Iterable<[Entity, FootstepsData, TransformData]>,
+ surfaces: Iterable<[Entity, StepSurfaceData, SpriteData, TransformData]>,
+ time: TimeData, world: World,
+ ) => {
+ if (isEditor() && !isPlayMode()) {
+ if (stamps.length > 0) { for (const s of stamps) away(world, s); stamps.length = 0; }
+ walkers.clear();
+ return;
+ }
+ // Age what is there, and put away what has run out.
+ for (let i = stamps.length - 1; i >= 0; i--) {
+ const stamp = stamps[i]!;
+ stamp.age += time.delta;
+ if (stamp.age >= stamp.life || !world.valid(stamp.entity)) {
+ away(world, stamp);
+ stamps.splice(i, 1);
+ continue;
+ }
+ const look = stampLook(stamp.kind, stamp.age, stamp.life);
+ const sprite = world.get(stamp.entity, Sprite) as SpriteData;
+ world.set(stamp.entity, Sprite, {
+ ...sprite,
+ size: { x: stamp.length * look.scale, y: stamp.width * look.scale },
+ color: { r: stamp.color.r, g: stamp.color.g, b: stamp.color.b, a: stamp.color.a * look.alpha },
+ });
+ }
+
+ const covers: Array<Parameters<typeof surfaceAt>[2][number]> = [];
+ const walking = new Set<Entity>();
+ let surfacesRead = false;
+ for (const [entity, step, transform] of movers) {
+ walking.add(entity);
+ const here = { x: transform.worldPosition.x, y: transform.worldPosition.y };
+ const known = walkers.get(entity);
+ if (!known || !step.enabled) { walkers.set(entity, { ...here, carried: 0, left: true }); continue; }
+ const dx = here.x - known.x, dy = here.y - known.y;
+ const moved = Math.hypot(dx, dy);
+ known.x = here.x;
+ known.y = here.y;
+ if (moved <= 1e-4) continue;
+ // A jump across the world (a teleport) is not a walk.
+ if (moved > step.stride * 20) { known.carried = 0; continue; }
+ known.carried += moved;
+ if (known.carried < step.stride) continue;
+ const heading = Math.atan2(dy, dx);
+
+ if (!surfacesRead) {
+ surfacesRead = true;
+ for (const [, surface, sprite, st] of surfaces) {
+ if (!surface.enabled) continue;
+ const ground = coveredGround(sprite, st);
+ covers.push({ kind: surface.kind, layer: sprite.layer, centre: ground.centre, half: ground.half, margin: surface.margin, round: surface.round });
+ }
+ }
+ while (known.carried >= step.stride) {
+ known.carried -= step.stride;
+ known.left = !known.left;
+ const foot = footAt(here.x, here.y, heading, step.width, known.left);
+ const kind = surfaceAt(foot.x, foot.y, covers) ?? (step.onBareGround ? StepKind.Print : null);
+ if (kind === null) continue;
+ // Spawned after the queries are done: an entity cannot be made while they are walked.
+ pending.push({ kind, foot, heading, step });
+ }
+ }
+ for (const entity of [...walkers.keys()]) if (!walking.has(entity)) walkers.delete(entity);
+ for (const request of pending.splice(0)) spawnStep(world, request);
+ },
+ { name: 'FootstepsSystem' },
+ );
+ app.addSystemToSchedule(Schedule.PostUpdate, system);
+
+ return () => {
+ const world = app.world;
+ for (const s of stamps) away(world, s);
+ stamps.length = 0;
+ walkers.clear();
+ if (textures) { RenderTexture.release(textures.ring); RenderTexture.release(textures.disc); textures = null; }
+ };
+}
diff --git a/sdk/tests/footsteps.test.ts b/sdk/tests/footsteps.test.ts
new file mode 100644
index 000000000..a3ddb07a5
--- /dev/null
+++ b/sdk/tests/footsteps.test.ts
@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file What a walker leaves behind: which surface a step lands on, where each foot goes, and how a ring and a print age.
+ */
+import { describe, expect, it } from 'vitest';
+import { StepKind, footAt, stampLook, surfaceAt } from '../src/render/footsteps';
+
+const cover = (kind: StepKind, x: number, y: number, hx: number, hy: number, layer = 0, round = false) =>
+ ({ kind, layer, centre: { x, y }, half: { x: hx, y: hy }, margin: 0, round });
+
+describe('the surface a step lands on', () => {
+ const pond = cover(StepKind.Water, 0, 0, 100, 100, 0);
+ const mud = cover(StepKind.Print, 300, 0, 50, 50, 0);
+
+ it('is the one that covers the point, or none', () => {
+ expect(surfaceAt(10, 10, [pond, mud])).toBe(StepKind.Water);
+ expect(surfaceAt(310, 0, [pond, mud])).toBe(StepKind.Print);
+ expect(surfaceAt(200, 0, [pond, mud])).toBeNull();
+ });
+
+ it('is the highest layer where two cover it, and the later one on a tie', () => {
+ const dock = cover(StepKind.Print, 0, 0, 20, 20, 5);
+ expect(surfaceAt(0, 0, [pond, dock])).toBe(StepKind.Print);
+ expect(surfaceAt(60, 0, [pond, dock])).toBe(StepKind.Water);
+ expect(surfaceAt(0, 0, [pond, cover(StepKind.Print, 0, 0, 20, 20, 0)])).toBe(StepKind.Print);
+ });
+
+ it('takes a round surface as the ellipse inside its rectangle', () => {
+ const round = cover(StepKind.Water, 0, 0, 100, 100, 0, true);
+ expect(surfaceAt(90, 90, [round])).toBeNull();
+ expect(surfaceAt(60, 60, [round])).toBe(StepKind.Water);
+ });
+});
+
+describe('the feet', () => {
+ it('stand either side of the way the walker heads, a width apart', () => {
+ const l = footAt(0, 0, 0, 10, true), r = footAt(0, 0, 0, 10, false);
+ expect(l.x).toBeCloseTo(0, 6);
+ expect(l.y).toBeCloseTo(5, 6);
+ expect(r.y).toBeCloseTo(-5, 6);
+ // Heading up the screen, the left foot is on the -x side.
+ const up = footAt(0, 0, Math.PI / 2, 10, true);
+ expect(up.x).toBeCloseTo(-5, 6);
+ expect(up.y).toBeCloseTo(0, 6);
+ });
+});
+
+describe('a step ageing', () => {
+ it('spreads and fades a ring, from a third of its size to all of it and from clear to none', () => {
+ const born = stampLook(StepKind.Water, 0, 2), done = stampLook(StepKind.Water, 2, 2);
+ expect(born.scale).toBeCloseTo(0.33, 6);
+ expect(born.alpha).toBe(1);
+ expect(done.scale).toBeCloseTo(1, 6);
+ expect(done.alpha).toBe(0);
+ expect(stampLook(StepKind.Water, 1, 2).scale).toBeGreaterThan(0.6);
+ });
+
+ it('keeps a print its size and fades it', () => {
+ expect(stampLook(StepKind.Print, 0, 6)).toEqual({ scale: 1, alpha: 1 });
+ const half = stampLook(StepKind.Print, 3, 6);
+ expect(half.scale).toBe(1);
+ expect(half.alpha).toBeCloseTo(0.75, 6);
+ expect(stampLook(StepKind.Print, 99, 6).alpha).toBe(0);
+ });
+});
diff --git a/tools/check-corpus-authoring.mjs b/tools/check-corpus-authoring.mjs
index cb417395c..bca31ac21 100644
--- a/tools/check-corpus-authoring.mjs
+++ b/tools/check-corpus-authoring.mjs
@@ -136,6 +136,8 @@ const DISPOSITION = {
// — owed: a creator-facing component nothing in the shipped corpus authors.
// Each reason names where the coverage belongs. —
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'],
+ Footsteps: ['owed', 'only the rainforest-2d probe, kept out of the examples, places one; it arrives with the top-down example CoverFade is owed'],
+ StepSurface: ['owed', 'only the rainforest-2d probe, kept out of the examples, places one; it arrives with the top-down example CoverFade is owed'],
SwayPusher: ['owed', 'only the rainforest-2d probe, kept out of the examples, places one; it arrives with the top-down example CoverFade is owed'],
FogOfWar: ['owed', 'only the rainforest-2d probe, kept out of the examples, places one; it arrives with the top-down example CoverFade is owed'],
SightViewer: ['owed', 'only the rainforest-2d probe, kept out of the examples, places one; it arrives with the top-down example CoverFade is owed'],
diff --git a/tools/check-gizmo-coverage.mjs b/tools/check-gizmo-coverage.mjs
index 8e221d290..20aa23477 100644
--- a/tools/check-gizmo-coverage.mjs
+++ b/tools/check-gizmo-coverage.mjs
@@ -128,6 +128,9 @@ const DISPOSITION = {
'Terrain.height': ['renders', 'the ground drawn at it is the outline'],
'Terrain.dirtHeight': ['not-world', 'a share of the height of the terrain, 0 to 1'],
'Terrain.snowHeight': ['not-world', 'a share of the height of the terrain, 0 to 1'],
+ 'Footsteps.width': ['no-place', 'how far apart the left and right feet land, a spacing between steps and not a region of the walker'],
+ 'Footsteps.printSize': ['no-place', 'the size of a footprint sprite the engine spawns, not a region of the walker that carries the component'],
+ 'Footsteps.rippleSize': ['no-place', 'the final size of a ring sprite the engine spawns, not a region of the walker that carries the component'],
'SwayPusher.radius': ['owed', 'how far from the entity plants lean away is not outlined in the viewport yet'],
'Text.boxWidth': ['owed', 'the rectangle a world label wraps and aligns in is not outlined in the viewport yet'],
'Text.boxHeight': ['owed', 'the rectangle a world label wraps and aligns in is not outlined in the viewport yet'],