A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(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.mdindex 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: Heightfieldheight: (x: number, z: number) => number | nullinfinite: false@@ -4188,6 +4189,7 @@ maxHeight: numberminHeight: numbernormal: (x: number, z: number) => [number, number, number] | nullpaint: (x: number, z: number, h: number, ny: number) => LayerWeights+splats: () => { a: Splat | null; b: Splat | null; }toData: () => FieldSourceDatastatic fromData: (d: FieldSourceData) => FieldSourcestatic 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: PathColorholes: 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) => voidname: stringstatic new (): SplinePluginstatic prototype: SplinePlugin@@ -10813,6 +10840,7 @@ collisionReadyAt: (x: number, z: number) => booleandeleteModifier: (id: string) => voidfindPath: (from: { x: number; z: number; }, to: { x: number; z: number; }, options?: ReachOptions) => ReachResultgroundData: () => GroundData | null+groundEdit: (entity: Entity) => GroundEdit | nullgroundKnownAt: (x: number, z: number) => booleanheightAt: (x: number, z: number) => number | nullheightBeneathAt: (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): numberdiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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: Heightfieldheight: (x: number, z: number) => number | nullinfinite: false@@ -4196,6 +4197,7 @@ maxHeight: numberminHeight: numbernormal: (x: number, z: number) => [number, number, number] | nullpaint: (x: number, z: number, h: number, ny: number) => LayerWeights+splats: () => { a: Splat | null; b: Splat | null; }toData: () => FieldSourceDatastatic fromData: (d: FieldSourceData) => FieldSourcestatic 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: PathColorholes: 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) => voidname: stringstatic new (): SplinePluginstatic prototype: SplinePlugin@@ -11026,6 +11053,7 @@ collisionReadyAt: (x: number, z: number) => booleandeleteModifier: (id: string) => voidfindPath: (from: { x: number; z: number; }, to: { x: number; z: number; }, options?: ReachOptions) => ReachResultgroundData: () => GroundData | null+groundEdit: (entity: Entity) => GroundEdit | nullgroundKnownAt: (x: number, z: number) => booleanheightAt: (x: number, z: number) => number | nullheightBeneathAt: (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): numberdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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: Heightfieldheight: (x: number, z: number) => number | nullinfinite: false@@ -4183,6 +4184,7 @@ maxHeight: numberminHeight: numbernormal: (x: number, z: number) => [number, number, number] | nullpaint: (x: number, z: number, h: number, ny: number) => LayerWeights+splats: () => { a: Splat | null; b: Splat | null; }toData: () => FieldSourceDatastatic fromData: (d: FieldSourceData) => FieldSourcestatic 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: PathColorholes: 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) => voidname: stringstatic new (): SplinePluginstatic prototype: SplinePlugin@@ -10808,6 +10835,7 @@ collisionReadyAt: (x: number, z: number) => booleandeleteModifier: (id: string) => voidfindPath: (from: { x: number; z: number; }, to: { x: number; z: number; }, options?: ReachOptions) => ReachResultgroundData: () => GroundData | null+groundEdit: (entity: Entity) => GroundEdit | nullgroundKnownAt: (x: number, z: number) => booleanheightAt: (x: number, z: number) => number | nullheightBeneathAt: (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): numberdiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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: Heightfieldheight: (x: number, z: number) => number | nullinfinite: false@@ -4183,6 +4184,7 @@ maxHeight: numberminHeight: numbernormal: (x: number, z: number) => [number, number, number] | nullpaint: (x: number, z: number, h: number, ny: number) => LayerWeights+splats: () => { a: Splat | null; b: Splat | null; }toData: () => FieldSourceDatastatic fromData: (d: FieldSourceData) => FieldSourcestatic 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: PathColorholes: 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) => voidname: stringstatic new (): SplinePluginstatic prototype: SplinePlugin@@ -11103,6 +11130,7 @@ collisionReadyAt: (x: number, z: number) => booleandeleteModifier: (id: string) => voidfindPath: (from: { x: number; z: number; }, to: { x: number; z: number; }, options?: ReachOptions) => ReachResultgroundData: () => GroundData | null+groundEdit: (entity: Entity) => GroundEdit | nullgroundKnownAt: (x: number, z: number) => booleanheightAt: (x: number, z: number) => number | nullheightBeneathAt: (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): numberdiff --git a/sdk/etc/spline.api.md b/sdk/etc/spline.api.mdindex 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) => voidname: stringstatic new (): SplinePluginstatic prototype: SplinePlugin@@ -50,6 +75,11 @@ y: numberz: number```+## pathPlace — function @experimental+```+(travelled: number, length: number, mode: number, forward?: boolean): { s: number; done: boolean; }+```+## splinePlugin — const @experimental```Plugindiff --git a/sdk/etc/terrain.api.md b/sdk/etc/terrain.api.mdindex 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: Heightfieldheight: (x: number, z: number) => number | nullinfinite: false@@ -33,12 +50,39 @@ maxHeight: numberminHeight: numbernormal: (x: number, z: number) => [number, number, number] | nullpaint: (x: number, z: number, h: number, ny: number) => LayerWeights+splats: () => { a: Splat | null; b: Splat | null; }toData: () => FieldSourceDatastatic fromData: (d: FieldSourceData) => FieldSourcestatic 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): FieldSourcestatic 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): PageTablestatic 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) => booleandeleteModifier: (id: string) => voidfindPath: (from: { x: number; z: number; }, to: { x: number; z: number; }, options?: ReachOptions) => ReachResultgroundData: () => GroundData | null+groundEdit: (entity: Entity) => GroundEdit | nullgroundKnownAt: (x: number, z: number) => booleanheightAt: (x: number, z: number) => number | nullheightBeneathAt: (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.mdindex 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: Heightfieldheight: (x: number, z: number) => number | nullinfinite: false@@ -4183,6 +4184,7 @@ maxHeight: numberminHeight: numbernormal: (x: number, z: number) => [number, number, number] | nullpaint: (x: number, z: number, h: number, ny: number) => LayerWeights+splats: () => { a: Splat | null; b: Splat | null; }toData: () => FieldSourceDatastatic fromData: (d: FieldSourceData) => FieldSourcestatic 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: PathColorholes: 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) => voidname: stringstatic new (): SplinePluginstatic prototype: SplinePlugin@@ -10815,6 +10842,7 @@ collisionReadyAt: (x: number, z: number) => booleandeleteModifier: (id: string) => voidfindPath: (from: { x: number; z: number; }, to: { x: number; z: number; }, options?: ReachOptions) => ReachResultgroundData: () => GroundData | null+groundEdit: (entity: Entity) => GroundEdit | nullgroundKnownAt: (x: number, z: number) => booleanheightAt: (x: number, z: number) => number | nullheightBeneathAt: (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): numberdiff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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);+ });+});