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(spline): PathFollower moves an entity along a Spline at a steady speed (once, loop, ping-pong)

yhh57976ea9c5ad
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 3d107b37e..da2079a39 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 · 161 beta · 1978 experimental · 3 deprecated
+Symbols: 115 public · 161 beta · 1983 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -4181,6 +4181,7 @@ swell: number
## FieldSource — class @experimental
```
bounds: readonly [number, number, number, number]
+ensureSplats: (second: boolean) => { a: Splat; b: Splat | null; }
field: Heightfield
height: (x: number, z: number) => number | null
infinite: false
@@ -4188,6 +4189,7 @@ maxHeight: number
minHeight: number
normal: (x: number, z: number) => [number, number, number] | null
paint: (x: number, z: number, h: number, ny: number) => LayerWeights
+splats: () => { a: Splat | null; b: Splat | null; }
toData: () => FieldSourceData
static fromData: (d: FieldSourceData) => FieldSource
static new (field: Heightfield, data: Pick<TerrainData, "sizeX" | "sizeZ" | "height" | "rockSlope" | "dirtHeight" | "snowHeight">, splat: Splat | null, flow: Float32Array | null, range?: readonly [number, number], splat2?: Splat | null): FieldSource
@@ -6631,6 +6633,31 @@ color: PathColor
holes: readonly (readonly Vec2[])[] | undefined
```
+## PathFollower — const @experimental
+```
+ComponentDef<PathFollowerData>
+```
+
+## PathFollowerData — interface @experimental
+```
+distance: number
+mode: number
+orient: number
+playing: boolean
+speed: number
+spline: number
+```
+
+## PathMode — const @experimental
+```
+{ readonly Once: 0; readonly Loop: 1; readonly PingPong: 2; }
+```
+
+## PathOrient — const @experimental
+```
+{ readonly None: 0; readonly FaceXZ: 1; readonly FaceXY: 2; }
+```
+
## PathStroke — interface @experimental
```
cap: LineCap | undefined
@@ -9931,7 +9958,7 @@ side: number
## SplinePlugin — class @experimental
```
-build: (_app: App) => void
+build: (app: App) => void
name: string
static new (): SplinePlugin
static prototype: SplinePlugin
@@ -10813,6 +10840,7 @@ collisionReadyAt: (x: number, z: number) => boolean
deleteModifier: (id: string) => void
findPath: (from: { x: number; z: number; }, to: { x: number; z: number; }, options?: ReachOptions) => ReachResult
groundData: () => GroundData | null
+groundEdit: (entity: Entity) => GroundEdit | null
groundKnownAt: (x: number, z: number) => boolean
heightAt: (x: number, z: number) => number | null
heightBeneathAt: (x: number, z: number) => number | null
@@ -15557,6 +15585,11 @@ ParticlePlugin
(scene: SceneData, sceneName: string, options: PartitionOptions): WorldPartition | null
```
+## pathPlace — function @experimental
+```
+(travelled: number, length: number, mode: number, forward?: boolean): { s: number; done: boolean; }
+```
+
## pendingShaders — function @experimental
```
(source: App | ESEngineModule | null): number
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index ce31b3d15..d5ef1d837 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 · 166 beta · 1997 experimental · 3 deprecated
+Symbols: 115 public · 166 beta · 2002 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -4189,6 +4189,7 @@ swell: number
## FieldSource — class @experimental
```
bounds: readonly [number, number, number, number]
+ensureSplats: (second: boolean) => { a: Splat; b: Splat | null; }
field: Heightfield
height: (x: number, z: number) => number | null
infinite: false
@@ -4196,6 +4197,7 @@ maxHeight: number
minHeight: number
normal: (x: number, z: number) => [number, number, number] | null
paint: (x: number, z: number, h: number, ny: number) => LayerWeights
+splats: () => { a: Splat | null; b: Splat | null; }
toData: () => FieldSourceData
static fromData: (d: FieldSourceData) => FieldSource
static new (field: Heightfield, data: Pick<TerrainData, "sizeX" | "sizeZ" | "height" | "rockSlope" | "dirtHeight" | "snowHeight">, splat: Splat | null, flow: Float32Array | null, range?: readonly [number, number], splat2?: Splat | null): FieldSource
@@ -6834,6 +6836,31 @@ color: PathColor
holes: readonly (readonly Vec2[])[] | undefined
```
+## PathFollower — const @experimental
+```
+ComponentDef<PathFollowerData>
+```
+
+## PathFollowerData — interface @experimental
+```
+distance: number
+mode: number
+orient: number
+playing: boolean
+speed: number
+spline: number
+```
+
+## PathMode — const @experimental
+```
+{ readonly Once: 0; readonly Loop: 1; readonly PingPong: 2; }
+```
+
+## PathOrient — const @experimental
+```
+{ readonly None: 0; readonly FaceXZ: 1; readonly FaceXY: 2; }
+```
+
## PathStroke — interface @experimental
```
cap: LineCap | undefined
@@ -10144,7 +10171,7 @@ side: number
## SplinePlugin — class @experimental
```
-build: (_app: App) => void
+build: (app: App) => void
name: string
static new (): SplinePlugin
static prototype: SplinePlugin
@@ -11026,6 +11053,7 @@ collisionReadyAt: (x: number, z: number) => boolean
deleteModifier: (id: string) => void
findPath: (from: { x: number; z: number; }, to: { x: number; z: number; }, options?: ReachOptions) => ReachResult
groundData: () => GroundData | null
+groundEdit: (entity: Entity) => GroundEdit | null
groundKnownAt: (x: number, z: number) => boolean
heightAt: (x: number, z: number) => number | null
heightBeneathAt: (x: number, z: number) => number | null
@@ -15820,6 +15848,11 @@ ParticlePlugin
(scene: SceneData, sceneName: string, options: PartitionOptions): WorldPartition | null
```
+## pathPlace — function @experimental
+```
+(travelled: number, length: number, mode: number, forward?: boolean): { s: number; done: boolean; }
+```
+
## pendingShaders — function @experimental
```
(source: App | ESEngineModule | null): number
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 188512976..542228784 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 · 163 beta · 1977 experimental · 3 deprecated
+Symbols: 115 public · 163 beta · 1982 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -4176,6 +4176,7 @@ swell: number
## FieldSource — class @experimental
```
bounds: readonly [number, number, number, number]
+ensureSplats: (second: boolean) => { a: Splat; b: Splat | null; }
field: Heightfield
height: (x: number, z: number) => number | null
infinite: false
@@ -4183,6 +4184,7 @@ maxHeight: number
minHeight: number
normal: (x: number, z: number) => [number, number, number] | null
paint: (x: number, z: number, h: number, ny: number) => LayerWeights
+splats: () => { a: Splat | null; b: Splat | null; }
toData: () => FieldSourceData
static fromData: (d: FieldSourceData) => FieldSource
static new (field: Heightfield, data: Pick<TerrainData, "sizeX" | "sizeZ" | "height" | "rockSlope" | "dirtHeight" | "snowHeight">, splat: Splat | null, flow: Float32Array | null, range?: readonly [number, number], splat2?: Splat | null): FieldSource
@@ -6626,6 +6628,31 @@ color: PathColor
holes: readonly (readonly Vec2[])[] | undefined
```
+## PathFollower — const @experimental
+```
+ComponentDef<PathFollowerData>
+```
+
+## PathFollowerData — interface @experimental
+```
+distance: number
+mode: number
+orient: number
+playing: boolean
+speed: number
+spline: number
+```
+
+## PathMode — const @experimental
+```
+{ readonly Once: 0; readonly Loop: 1; readonly PingPong: 2; }
+```
+
+## PathOrient — const @experimental
+```
+{ readonly None: 0; readonly FaceXZ: 1; readonly FaceXY: 2; }
+```
+
## PathStroke — interface @experimental
```
cap: LineCap | undefined
@@ -9926,7 +9953,7 @@ side: number
## SplinePlugin — class @experimental
```
-build: (_app: App) => void
+build: (app: App) => void
name: string
static new (): SplinePlugin
static prototype: SplinePlugin
@@ -10808,6 +10835,7 @@ collisionReadyAt: (x: number, z: number) => boolean
deleteModifier: (id: string) => void
findPath: (from: { x: number; z: number; }, to: { x: number; z: number; }, options?: ReachOptions) => ReachResult
groundData: () => GroundData | null
+groundEdit: (entity: Entity) => GroundEdit | null
groundKnownAt: (x: number, z: number) => boolean
heightAt: (x: number, z: number) => number | null
heightBeneathAt: (x: number, z: number) => number | null
@@ -15562,6 +15590,11 @@ ParticlePlugin
(scene: SceneData, sceneName: string, options: PartitionOptions): WorldPartition | null
```
+## pathPlace — function @experimental
+```
+(travelled: number, length: number, mode: number, forward?: boolean): { s: number; done: boolean; }
+```
+
## pendingShaders — function @experimental
```
(source: App | ESEngineModule | null): number
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 265caa068..8838dca4e 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 · 161 beta · 1999 experimental · 3 deprecated
+Symbols: 115 public · 161 beta · 2004 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -4176,6 +4176,7 @@ swell: number
## FieldSource — class @experimental
```
bounds: readonly [number, number, number, number]
+ensureSplats: (second: boolean) => { a: Splat; b: Splat | null; }
field: Heightfield
height: (x: number, z: number) => number | null
infinite: false
@@ -4183,6 +4184,7 @@ maxHeight: number
minHeight: number
normal: (x: number, z: number) => [number, number, number] | null
paint: (x: number, z: number, h: number, ny: number) => LayerWeights
+splats: () => { a: Splat | null; b: Splat | null; }
toData: () => FieldSourceData
static fromData: (d: FieldSourceData) => FieldSource
static new (field: Heightfield, data: Pick<TerrainData, "sizeX" | "sizeZ" | "height" | "rockSlope" | "dirtHeight" | "snowHeight">, splat: Splat | null, flow: Float32Array | null, range?: readonly [number, number], splat2?: Splat | null): FieldSource
@@ -6921,6 +6923,31 @@ color: PathColor
holes: readonly (readonly Vec2[])[] | undefined
```
+## PathFollower — const @experimental
+```
+ComponentDef<PathFollowerData>
+```
+
+## PathFollowerData — interface @experimental
+```
+distance: number
+mode: number
+orient: number
+playing: boolean
+speed: number
+spline: number
+```
+
+## PathMode — const @experimental
+```
+{ readonly Once: 0; readonly Loop: 1; readonly PingPong: 2; }
+```
+
+## PathOrient — const @experimental
+```
+{ readonly None: 0; readonly FaceXZ: 1; readonly FaceXY: 2; }
+```
+
## PathStroke — interface @experimental
```
cap: LineCap | undefined
@@ -10221,7 +10248,7 @@ side: number
## SplinePlugin — class @experimental
```
-build: (_app: App) => void
+build: (app: App) => void
name: string
static new (): SplinePlugin
static prototype: SplinePlugin
@@ -11103,6 +11130,7 @@ collisionReadyAt: (x: number, z: number) => boolean
deleteModifier: (id: string) => void
findPath: (from: { x: number; z: number; }, to: { x: number; z: number; }, options?: ReachOptions) => ReachResult
groundData: () => GroundData | null
+groundEdit: (entity: Entity) => GroundEdit | null
groundKnownAt: (x: number, z: number) => boolean
heightAt: (x: number, z: number) => number | null
heightBeneathAt: (x: number, z: number) => number | null
@@ -15868,6 +15896,11 @@ ParticlePlugin
(scene: SceneData, sceneName: string, options: PartitionOptions): WorldPartition | null
```
+## pathPlace — function @experimental
+```
+(travelled: number, length: number, mode: number, forward?: boolean): { s: number; done: boolean; }
+```
+
## pendingShaders — function @experimental
```
(source: App | ESEngineModule | null): number
diff --git a/sdk/etc/spline.api.md b/sdk/etc/spline.api.md
index 8ffeb6978..4b9028193 100644
--- a/sdk/etc/spline.api.md
+++ b/sdk/etc/spline.api.md
@@ -1,7 +1,32 @@
# API surface — esengine/spline
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 0 public · 0 beta · 7 experimental · 0 deprecated
+Symbols: 0 public · 0 beta · 12 experimental · 0 deprecated
+
+## PathFollower — const @experimental
+```
+ComponentDef<PathFollowerData>
+```
+
+## PathFollowerData — interface @experimental
+```
+distance: number
+mode: number
+orient: number
+playing: boolean
+speed: number
+spline: number
+```
+
+## PathMode — const @experimental
+```
+{ readonly Once: 0; readonly Loop: 1; readonly PingPong: 2; }
+```
+
+## PathOrient — const @experimental
+```
+{ readonly None: 0; readonly FaceXZ: 1; readonly FaceXY: 2; }
+```
## Spline — const @experimental
```
@@ -36,7 +61,7 @@ side: number
## SplinePlugin — class @experimental
```
-build: (_app: App) => void
+build: (app: App) => void
name: string
static new (): SplinePlugin
static prototype: SplinePlugin
@@ -50,6 +75,11 @@ y: number
z: number
```
+## pathPlace — function @experimental
+```
+(travelled: number, length: number, mode: number, forward?: boolean): { s: number; done: boolean; }
+```
+
## splinePlugin — const @experimental
```
Plugin
diff --git a/sdk/etc/terrain.api.md b/sdk/etc/terrain.api.md
index ddbe6766d..44dd9d09c 100644
--- a/sdk/etc/terrain.api.md
+++ b/sdk/etc/terrain.api.md
@@ -1,7 +1,23 @@
# API surface — esengine/terrain
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 0 public · 0 beta · 98 experimental · 0 deprecated
+Symbols: 0 public · 0 beta · 110 experimental · 0 deprecated
+
+## Brush — interface @experimental
+```
+falloff: number
+radius: number
+x: number
+z: number
+```
+
+## Dirty — interface @experimental
+```
+i0: number
+i1: number
+j0: number
+j1: number
+```
## Eroded — interface @experimental
```
@@ -26,6 +42,7 @@ readonly { normal: readonly [number, number, number]; a: readonly [number, numbe
## FieldSource — class @experimental
```
bounds: readonly [number, number, number, number]
+ensureSplats: (second: boolean) => { a: Splat; b: Splat | null; }
field: Heightfield
height: (x: number, z: number) => number | null
infinite: false
@@ -33,12 +50,39 @@ maxHeight: number
minHeight: number
normal: (x: number, z: number) => [number, number, number] | null
paint: (x: number, z: number, h: number, ny: number) => LayerWeights
+splats: () => { a: Splat | null; b: Splat | null; }
toData: () => FieldSourceData
static fromData: (d: FieldSourceData) => FieldSource
static new (field: Heightfield, data: Pick<TerrainData, "sizeX" | "sizeZ" | "height" | "rockSlope" | "dirtHeight" | "snowHeight">, splat: Splat | null, flow: Float32Array | null, range?: readonly [number, number], splat2?: Splat | null): FieldSource
static prototype: FieldSource
```
+## GroundEdit — class @experimental
+```
+apply: (patch: GroundPatch, side: "before" | "after") => void
+area: { sizeX: number; sizeZ: number; }
+begin: () => void
+end: () => GroundPatch | null
+field: Heightfield
+heightAt: (x: number, z: number) => number | null
+heightmapPixels: () => { width: number; height: number; pixels: Uint8Array; }
+maxHeight: number
+minHeight: number
+origin: { x: number; z: number; }
+paint: (layer: number, x: number, z: number, radius: number, falloff: number, strength: number, erase?: boolean) => void
+sculpt: (mode: number, x: number, z: number, radius: number, falloff: number, amount: number, target?: number) => void
+splatmapPixels: () => { a: Splat | null; b: Splat | null; }
+static new (host: GroundHost, source: FieldSource, modified: ModifiedSource, sizeX: number, sizeZ: number): GroundEdit
+static prototype: GroundEdit
+```
+
+## GroundPatch — interface @experimental
+```
+heights: Piece<Float32Array<ArrayBufferLike>> | null
+splat2: Piece<Uint8Array<ArrayBufferLike>> | null
+splat: Piece<Uint8Array<ArrayBufferLike>> | null
+```
+
## Heightfield — interface @experimental
```
data: Float32Array<ArrayBufferLike>
@@ -174,6 +218,14 @@ static new (atlasSize: number): PageTable
static prototype: PageTable
```
+## PaintDab — interface @experimental
+```
+brush: Brush
+erase: boolean | undefined
+layer: number
+strength: number
+```
+
## Planet — const @experimental
```
ComponentDef<PlanetData>
@@ -365,6 +417,19 @@ path: { x: number; y: number; z: number; }[]
state: "noGround" | "reached" | "unreachable" | "exhausted"
```
+## SculptDab — interface @experimental
+```
+amount: number
+brush: Brush
+mode: number
+target: number | undefined
+```
+
+## SculptMode — const @experimental
+```
+{ readonly Raise: 0; readonly Lower: 1; readonly Smooth: 2; readonly Flatten: 3; }
+```
+
## SphereNode — interface @experimental
```
face: number
@@ -556,6 +621,7 @@ collisionReadyAt: (x: number, z: number) => boolean
deleteModifier: (id: string) => void
findPath: (from: { x: number; z: number; }, to: { x: number; z: number; }, options?: ReachOptions) => ReachResult
groundData: () => GroundData | null
+groundEdit: (entity: Entity) => GroundEdit | null
groundKnownAt: (x: number, z: number) => boolean
heightAt: (x: number, z: number) => number | null
heightBeneathAt: (x: number, z: number) => number | null
@@ -583,6 +649,11 @@ ResourceDef<Terrains>
(x0: number, z0: number, size: number, y0: number, y1: number, ex: number, ey: number, ez: number): number
```
+## brushWeight — function @experimental
+```
+(d: number, radius: number, falloff: number): number
+```
+
## buildPatchMesh — function @experimental
```
(cells: number, flipped?: boolean): MeshData
@@ -593,6 +664,11 @@ ResourceDef<Terrains>
(face: number, u: number, v: number, out?: [number, number, number]): [number, number, number]
```
+## encodeHeightmap — function @experimental
+```
+(field: Heightfield): Uint8Array
+```
+
## erodeHeightfield — function @experimental
```
(field: Heightfield, p: ErosionParams): Eroded
@@ -693,6 +769,11 @@ ResourceDef<Terrains>
(layers: readonly LayerSource[], maxSize?: number): PackedLayers
```
+## paintSplat — function @experimental
+```
+(a: Splat, b: Splat | null, sizeX: number, sizeZ: number, dab: PaintDab): Dirty | null
+```
+
## paintWeights — function @experimental
```
(h: number, ny: number, t: Pick<TerrainData, "rockSlope" | "dirtHeight" | "snowHeight">): [number, number, number, number]
@@ -738,6 +819,11 @@ PlanetPlugin
(field: Heightfield, u: number, v: number): number
```
+## sculptField — function @experimental
+```
+(field: Heightfield, sizeX: number, sizeZ: number, dab: SculptDab): Dirty | null
+```
+
## selectNodes — function @experimental
```
(p: QuadtreeParams, ex: number, ey: number, ez: number): TerrainNode[]
@@ -778,3 +864,8 @@ Plugin
(id: string): TerrainProvider | undefined
```
+## unionDirty — function @experimental
+```
+(a: Dirty | null, b: Dirty | null): Dirty | null
+```
+
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 9e6ac05b4..b94d19126 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 · 161 beta · 1990 experimental · 3 deprecated
+Symbols: 115 public · 161 beta · 1995 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -4176,6 +4176,7 @@ swell: number
## FieldSource — class @experimental
```
bounds: readonly [number, number, number, number]
+ensureSplats: (second: boolean) => { a: Splat; b: Splat | null; }
field: Heightfield
height: (x: number, z: number) => number | null
infinite: false
@@ -4183,6 +4184,7 @@ maxHeight: number
minHeight: number
normal: (x: number, z: number) => [number, number, number] | null
paint: (x: number, z: number, h: number, ny: number) => LayerWeights
+splats: () => { a: Splat | null; b: Splat | null; }
toData: () => FieldSourceData
static fromData: (d: FieldSourceData) => FieldSource
static new (field: Heightfield, data: Pick<TerrainData, "sizeX" | "sizeZ" | "height" | "rockSlope" | "dirtHeight" | "snowHeight">, splat: Splat | null, flow: Float32Array | null, range?: readonly [number, number], splat2?: Splat | null): FieldSource
@@ -6633,6 +6635,31 @@ color: PathColor
holes: readonly (readonly Vec2[])[] | undefined
```
+## PathFollower — const @experimental
+```
+ComponentDef<PathFollowerData>
+```
+
+## PathFollowerData — interface @experimental
+```
+distance: number
+mode: number
+orient: number
+playing: boolean
+speed: number
+spline: number
+```
+
+## PathMode — const @experimental
+```
+{ readonly Once: 0; readonly Loop: 1; readonly PingPong: 2; }
+```
+
+## PathOrient — const @experimental
+```
+{ readonly None: 0; readonly FaceXZ: 1; readonly FaceXY: 2; }
+```
+
## PathStroke — interface @experimental
```
cap: LineCap | undefined
@@ -9933,7 +9960,7 @@ side: number
## SplinePlugin — class @experimental
```
-build: (_app: App) => void
+build: (app: App) => void
name: string
static new (): SplinePlugin
static prototype: SplinePlugin
@@ -10815,6 +10842,7 @@ collisionReadyAt: (x: number, z: number) => boolean
deleteModifier: (id: string) => void
findPath: (from: { x: number; z: number; }, to: { x: number; z: number; }, options?: ReachOptions) => ReachResult
groundData: () => GroundData | null
+groundEdit: (entity: Entity) => GroundEdit | null
groundKnownAt: (x: number, z: number) => boolean
heightAt: (x: number, z: number) => number | null
heightBeneathAt: (x: number, z: number) => number | null
@@ -15594,6 +15622,11 @@ ParticlePlugin
(scene: SceneData, sceneName: string, options: PartitionOptions): WorldPartition | null
```
+## pathPlace — function @experimental
+```
+(travelled: number, length: number, mode: number, forward?: boolean): { s: number; done: boolean; }
+```
+
## pendingShaders — function @experimental
```
(source: App | ESEngineModule | null): number
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index 0c8fc7acb..056d29180 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -825,7 +825,7 @@ export { PlacementDiffs, type PlacementChange, type PlacementDiffsData } from '.
// Splines and water are optional modules too (`esengine/spline`, `esengine/water`).
export { Bakes, BakesRes, bakesOf, finish, type WorkJob, type BakeProgress } from './runtime/bakes';
export { CollisionGeometry, CollisionGeometryRes, collisionGeometryOf, type CollisionPiece } from './runtime/collisionGeometry';
-export { Spline, SplinePlugin, splinePlugin, type SplineData } from './spline/splinePlugin';
+export { Spline, SplinePlugin, splinePlugin, PathFollower, PathMode, PathOrient, pathPlace, type SplineData, type PathFollowerData } from './spline/splinePlugin';
export { SplineCurve, type SplinePoint, type SplineNearest } from './spline/curve';
export {
WaterBody, WaterForm, Waters, WatersRes, WaterPlugin, waterPlugin, type WaterBodyData, type WaterSample,
diff --git a/sdk/src/spline/index.ts b/sdk/src/spline/index.ts
index 307ab6094..4416db67d 100644
--- a/sdk/src/spline/index.ts
+++ b/sdk/src/spline/index.ts
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
-export { Spline, SplinePlugin, splinePlugin, type SplineData } from './splinePlugin';
+export { Spline, SplinePlugin, splinePlugin, PathFollower, PathMode, PathOrient, pathPlace, type SplineData, type PathFollowerData } from './splinePlugin';
export { SplineCurve, type SplinePoint, type SplineNearest } from './curve';
// Importing this subpath INSTALLS splines — see tilemap/index.ts.
diff --git a/sdk/src/spline/splinePlugin.ts b/sdk/src/spline/splinePlugin.ts
index 9df2125bc..3be252a21 100644
--- a/sdk/src/spline/splinePlugin.ts
+++ b/sdk/src/spline/splinePlugin.ts
@@ -6,11 +6,14 @@
*
* @details A `Spline` is data and nothing draws it: a river, a road or a camera rail reads it from the same entity and builds what it needs
* (see {@link SplineCurve}). The points are in the entity's own space, so moving or turning the entity moves the whole curve.
- * There is nothing to run each frame, so the plugin only keeps the component known to a build that carries it.
+ * The one thing that runs each frame is what follows it: a {@link PathFollower} moves its own entity along the curve of another.
*/
import type { App, Plugin } from '../app/app';
-import { defineComponent, type ComponentDef } from '../ecs/component';
-import type { SplinePoint } from './curve';
+import { defineSystem, Schedule } from '../ecs/system';
+import { Res, Time, type TimeData } from '../ecs/resource';
+import { playModeOnly } from '../ecs/env';
+import { defineComponent, Transform, type ComponentDef, type TransformData } from '../ecs/component';
+import { SplineCurve, type SplinePoint } from './curve';
/** The fields of the `Spline` component. @experimental */
export interface SplineData {
@@ -21,7 +24,7 @@ export interface SplineData {
}
/**
- * A curve through points. It is read by what follows it (a river's `WaterBody`, on the same entity).
+ * A curve through points. It is read by what follows it (a river's `WaterBody` on the same entity, a {@link PathFollower} on another).
*
* @experimental
*/
@@ -35,10 +38,143 @@ export const Spline: ComponentDef<SplineData> = defineComponent<SplineData>('Spl
},
});
+/** What a {@link PathFollower} does at the end of the curve. */
+export const PathMode = { Once: 0, Loop: 1, PingPong: 2 } as const;
+
+/** How a {@link PathFollower} turns to the way it is going. */
+export const PathOrient = {
+ /** Keeps the rotation it has. */
+ None: 0,
+ /** Turns about y to face along the curve, +z forward: a 3D walker on the ground. */
+ FaceXZ: 1,
+ /** Turns about z to face along the curve, +x forward: a 2D sprite. */
+ FaceXY: 2,
+} as const;
+
+/** The fields of the `PathFollower` component. @experimental */
+export interface PathFollowerData {
+ /** The entity that holds the `Spline` to follow. */
+ spline: number;
+ /** World units a second along the curve; negative runs it backwards. */
+ speed: number;
+ /** How far along the curve it has gone, in world units. Written each frame; set it to start part-way along. */
+ distance: number;
+ /** {@link PathMode}. */
+ mode: number;
+ /** {@link PathOrient}. */
+ orient: number;
+ /** Whether it is moving. A `Once` follower stops itself at the end. */
+ playing: boolean;
+}
+
+/**
+ * Moves its entity along the `Spline` of another: an enemy on a patrol route, a platform on a rail, a camera on a track. It sets the entity's
+ * own `position` (and `rotation`, when asked), so a follower sits at the top of the hierarchy. The curve is read through its entity's
+ * Transform, so moving, turning or scaling the spline moves the whole route. It advances by the length of the curve, not by its parameter,
+ * so it goes at `speed` everywhere on it.
+ *
+ * @experimental
+ */
+export const PathFollower: ComponentDef<PathFollowerData> = defineComponent<PathFollowerData>('PathFollower', {
+ spline: -1, speed: 4, distance: 0, mode: PathMode.Loop, orient: PathOrient.None, playing: true,
+}, {
+ entityFields: ['spline'],
+ fields: {
+ spline: { category: 'Path', tooltip: 'The entity that holds the Spline to follow.' },
+ speed: { category: 'Path', tooltip: 'World units a second along the curve. Negative runs it backwards.' },
+ distance: { min: 0, category: 'Path', tooltip: 'How far along the curve it has gone, in world units. Set it to start part-way along.' },
+ mode: { enum: [{ label: 'Once', value: PathMode.Once }, { label: 'Loop', value: PathMode.Loop }, { label: 'Ping-pong', value: PathMode.PingPong }], category: 'Path', tooltip: 'What it does at the end of the curve: stop, go round again, or turn back.' },
+ orient: { enum: [{ label: 'None', value: PathOrient.None }, { label: 'Face along (XZ)', value: PathOrient.FaceXZ }, { label: 'Face along (XY)', value: PathOrient.FaceXY }], category: 'Path', tooltip: 'Whether it turns to face the way it is going: about y for a 3D walker, about z for a 2D sprite.' },
+ playing: { category: 'Path', tooltip: 'Whether it is moving. A follower set to Once stops itself at the end.' },
+ },
+});
+
+/**
+ * Where a follower that has gone `travelled` along a curve of `length` stands, and whether a `Once` follower has run out of curve going the way
+ * it was going (`forward`).
+ */
+export function pathPlace(travelled: number, length: number, mode: number, forward = true): { s: number; done: boolean } {
+ if (!(length > 0)) return { s: 0, done: mode === PathMode.Once };
+ if (mode === PathMode.Loop) return { s: ((travelled % length) + length) % length, done: false };
+ if (mode === PathMode.PingPong) {
+ const t = ((travelled % (2 * length)) + 2 * length) % (2 * length);
+ return { s: t <= length ? t : 2 * length - t, done: false };
+ }
+ return { s: Math.min(Math.max(travelled, 0), length), done: forward ? travelled >= length : travelled <= 0 };
+}
+
+type Quat = { x: number; y: number; z: number; w: number };
+
+function turn(q: Quat, vx: number, vy: number, vz: number): [number, number, number] {
+ const tx = 2 * (q.y * vz - q.z * vy), ty = 2 * (q.z * vx - q.x * vz), tz = 2 * (q.x * vy - q.y * vx);
+ return [vx + q.w * tx + (q.y * tz - q.z * ty), vy + q.w * ty + (q.z * tx - q.x * tz), vz + q.w * tz + (q.x * ty - q.y * tx)];
+}
+
export class SplinePlugin implements Plugin {
name = 'spline';
- build(_app: App): void {
- // Data only: nothing runs each frame.
+ private readonly curves_ = new Map<number, { key: string; curve: SplineCurve }>();
+
+ build(app: App): void {
+ app.addSystemToSchedule(Schedule.Update,
+ defineSystem([Res(Time)], (time: TimeData) => this.follow(app, time.delta), { name: 'PathFollowerSystem' }),
+ { runIf: playModeOnly });
+ }
+
+ private curveOf(app: App, entity: number): { curve: SplineCurve; at: TransformData } | null {
+ const world = app.world;
+ if (entity < 0 || !world.valid(entity as never)) return null;
+ const spline = world.tryGet(entity as never, Spline) as SplineData | null;
+ if (!spline || spline.points.length < 2) return null;
+ const at = world.tryGet(entity as never, Transform) as TransformData | null;
+ if (!at) return null;
+ const key = JSON.stringify([spline.points, spline.closed]);
+ let held = this.curves_.get(entity);
+ if (!held || held.key !== key) {
+ held = { key, curve: new SplineCurve(spline.points, spline.closed) };
+ this.curves_.set(entity, held);
+ }
+ return { curve: held.curve, at };
+ }
+
+ private follow(app: App, dt: number): void {
+ const world = app.world;
+ for (const entity of world.getEntitiesWithComponents([PathFollower, Transform])) {
+ const f = world.get(entity, PathFollower) as PathFollowerData;
+ if (!f.playing) continue;
+ const held = this.curveOf(app, f.spline);
+ if (!held) continue;
+ const { curve, at } = held;
+ const sx = at.worldScale.x, sy = at.worldScale.y, sz = at.worldScale.z;
+ // Speed is in world units and the curve's length is in its own: a scaled spline is longer in the world.
+ const unit = (Math.abs(sx) + Math.abs(sy) + Math.abs(sz)) / 3 || 1;
+ const length = curve.length * unit;
+ const travelled = f.distance + f.speed * dt;
+ const placed = pathPlace(travelled, length, f.mode, f.speed >= 0);
+ const local = curve.position(placed.s / unit);
+ const r = turn(at.worldRotation, local[0] * sx, local[1] * sy, local[2] * sz);
+ const t = world.get(entity, Transform) as TransformData;
+ t.position.x = r[0] + at.worldPosition.x;
+ t.position.y = r[1] + at.worldPosition.y;
+ t.position.z = r[2] + at.worldPosition.z;
+ if (f.orient !== PathOrient.None) {
+ const tan = curve.tangent(placed.s / unit);
+ const d = turn(at.worldRotation, tan[0] * sx, tan[1] * sy, tan[2] * sz);
+ // Going backwards along the curve faces the other way.
+ const dir = f.speed < 0 ? -1 : 1;
+ if (f.orient === PathOrient.FaceXZ) {
+ const h = Math.atan2(d[0] * dir, d[2] * dir) / 2;
+ t.rotation.x = 0; t.rotation.y = Math.sin(h); t.rotation.z = 0; t.rotation.w = Math.cos(h);
+ } else {
+ const h = Math.atan2(d[1] * dir, d[0] * dir) / 2;
+ t.rotation.x = 0; t.rotation.y = 0; t.rotation.z = Math.sin(h); t.rotation.w = Math.cos(h);
+ }
+ }
+ world.set(entity, Transform, t);
+ const ended = f.mode === PathMode.Once && placed.done;
+ world.set(entity, PathFollower, { ...f, distance: ended ? placed.s : travelled, playing: !ended });
+ }
+ // A curve nobody reads any more is let go.
+ for (const key of [...this.curves_.keys()]) if (!world.valid(key as never)) this.curves_.delete(key);
}
}
diff --git a/sdk/tests/path-follower.test.ts b/sdk/tests/path-follower.test.ts
new file mode 100644
index 000000000..bef3cbaea
--- /dev/null
+++ b/sdk/tests/path-follower.test.ts
@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { describe, expect, it } from 'vitest';
+import { afterEach, beforeAll, beforeEach } from 'vitest';
+import { World } from '../src/ecs/world';
+import { Transform } from '../src/ecs/component';
+import type { CppRegistry, ESEngineModule } from '../src/wasm';
+import { HAS_WASM, loadWasmModule } from './helpers/loadWasm';
+import {
+ Spline, PathFollower, PathMode, PathOrient, SplinePlugin, pathPlace, type PathFollowerData,
+} from '../src/spline/splinePlugin';
+
+describe('pathPlace', () => {
+ it('stops at either end of a Once path and says which way it ran out', () => {
+ expect(pathPlace(3, 10, PathMode.Once)).toEqual({ s: 3, done: false });
+ expect(pathPlace(12, 10, PathMode.Once)).toEqual({ s: 10, done: true });
+ expect(pathPlace(-2, 10, PathMode.Once, false)).toEqual({ s: 0, done: true });
+ // Standing at the start, about to go forward, is not the end.
+ expect(pathPlace(0, 10, PathMode.Once, true).done).toBe(false);
+ });
+
+ it('goes round on a Loop, in either direction', () => {
+ expect(pathPlace(13, 10, PathMode.Loop).s).toBeCloseTo(3);
+ expect(pathPlace(-3, 10, PathMode.Loop).s).toBeCloseTo(7);
+ });
+
+ it('turns back at the ends of a PingPong', () => {
+ expect(pathPlace(4, 10, PathMode.PingPong).s).toBeCloseTo(4);
+ expect(pathPlace(14, 10, PathMode.PingPong).s).toBeCloseTo(6);
+ expect(pathPlace(24, 10, PathMode.PingPong).s).toBeCloseTo(4);
+ });
+
+ it('is still on a curve with no length', () => {
+ expect(pathPlace(5, 0, PathMode.Loop)).toEqual({ s: 0, done: false });
+ });
+});
+
+/** The engine's own world: Transform is a C++ component, so a follower can only be tried against the real registry. */
+describe.skipIf(!HAS_WASM)('PathFollower', () => {
+ let engine: ESEngineModule, registry: CppRegistry, world: World;
+ beforeAll(async () => { engine = await loadWasmModule(); });
+ beforeEach(() => { registry = new engine.Registry(); world = new World(); world.connectCpp(registry, engine); });
+ afterEach(() => { for (const e of world.getAllEntities()) world.despawn(e); world.disconnectCpp(); registry.delete(); });
+
+ /** A straight 10-unit path along x on a rail at `at` (scaled by `scale`), and a follower on an entity of its own. */
+ function setup(follower: Partial<PathFollowerData>, at = { x: 0, y: 0, z: 0 }, scale = 1) {
+ const rail = world.spawn();
+ world.insert(rail, Transform, { position: at, worldPosition: at, scale: { x: scale, y: scale, z: scale }, worldScale: { x: scale, y: scale, z: scale } } as never);
+ world.insert(rail, Spline, { points: [{ x: 0, y: 0, z: 0, width: 1 }, { x: 10, y: 0, z: 0, width: 1 }], closed: false });
+ const mover = world.spawn();
+ world.insert(mover, Transform);
+ world.insert(mover, PathFollower, { spline: rail as number, speed: 2, mode: PathMode.Once, ...follower });
+ const plugin = new SplinePlugin();
+ const step = (dt: number): void => (plugin as unknown as { follow(app: unknown, dt: number): void }).follow({ world }, dt);
+ return { mover, step };
+ }
+
+ it('moves along the curve at its speed', () => {
+ const { mover, step } = setup({});
+ step(1); step(1);
+ expect(world.get(mover, Transform).position.x).toBeCloseTo(4, 1);
+ expect(world.get(mover, Transform).position.y).toBeCloseTo(0);
+ expect(world.get(mover, PathFollower).distance).toBeCloseTo(4, 1);
+ });
+
+ it('stops itself at the end of a Once path', () => {
+ const { mover, step } = setup({ speed: 8 });
+ for (let i = 0; i < 4; i++) step(1);
+ expect(world.get(mover, Transform).position.x).toBeCloseTo(10, 1);
+ expect(world.get(mover, PathFollower).playing).toBe(false);
+ });
+
+ it("reads the curve through the rail's own Transform", () => {
+ const { mover, step } = setup({ speed: 5 }, { x: 100, y: 0, z: 7 }, 2);
+ step(1);
+ const p = world.get(mover, Transform).position;
+ // 5 world units along a curve doubled in size, from the rail's origin.
+ expect(p.x).toBeCloseTo(105, 1);
+ expect(p.z).toBeCloseTo(7, 1);
+ });
+
+ it('turns to face along the curve about z for a 2D sprite', () => {
+ const { mover, step } = setup({ orient: PathOrient.FaceXY });
+ step(1);
+ const r = world.get(mover, Transform).rotation;
+ expect(r.z).toBeCloseTo(0);
+ expect(r.w).toBeCloseTo(1);
+ });
+
+ it('does nothing while it is not playing, or when its spline is gone', () => {
+ const idle = setup({ playing: false });
+ idle.step(1);
+ expect(world.get(idle.mover, Transform).position.x).toBeCloseTo(0);
+ const lost = setup({ spline: -1 });
+ lost.step(1);
+ expect(world.get(lost.mover, Transform).position.x).toBeCloseTo(0);
+ });
+});