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(sdk): timelines are an optional module, installed by a TimelinePlayer or an .estimeline

yhh8ea5c7676d8d
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 39a2854df..fe0788219 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,7 +16,8 @@ published separately; it ships inside the editor.
### Changed
-- **Terrain and Foliage are optional modules.** Terrain and Foliage are now optional modules, esengine/terrain and esengine/foliage: a package carries them when a scene has a Terrain or Foliage component or a script imports the subpath, and a game with neither ships none of them (about 33 KB less in a UI-only mini-game). Import `Terrain`, `Foliage` and their helpers from `esengine/terrain` and `esengine/foliage` rather than `esengine`; the export installs the module for a scene that uses either component.
+- **Timelines are an optional module.** Timelines are now an optional module, esengine/timeline: a package carries the timeline runtime and its loader when a scene has a TimelinePlayer, the content has an .estimeline, or a script imports the subpath, and a game with none of them ships neither. The API is unchanged and still reachable from `esengine`.
+- **Terrain and Foliage are optional modules.** Terrain and Foliage are now optional modules, esengine/terrain and esengine/foliage: a package carries them when a scene has a Terrain or Foliage component or a script imports the subpath, and a game with neither ships none of them (about 33 KB less in a UI-only mini-game). The API is unchanged and still reachable from `esengine`; the export installs the module for a scene that uses either component.
## [0.94.0] - 2026-10-22
diff --git a/docs/astro/src/content/docs/animation/timeline.mdx b/docs/astro/src/content/docs/animation/timeline.mdx
index 809070aeb..29a1d8119 100644
--- a/docs/astro/src/content/docs/animation/timeline.mdx
+++ b/docs/astro/src/content/docs/animation/timeline.mdx
@@ -249,6 +249,10 @@ you can call it yourself:
Sampling covers property tracks; event-like tracks (audio, markers, custom
events) fire edge-detected during playback, not on a sample.
+## In a package
+
+Timelines are an optional module: a package carries the runtime and the loader when a scene has a `TimelinePlayer`, the content has an `.estimeline`, or a script imports `esengine/timeline`. A game with none of them ships neither.
+
## Best practices
- **Author in the Sequencer** — the timeline asset holds the tracks; code just plays
diff --git a/docs/astro/src/content/docs/zh-cn/animation/timeline.mdx b/docs/astro/src/content/docs/zh-cn/animation/timeline.mdx
index 167b8f430..7a1483661 100644
--- a/docs/astro/src/content/docs/zh-cn/animation/timeline.mdx
+++ b/docs/astro/src/content/docs/zh-cn/animation/timeline.mdx
@@ -210,6 +210,10 @@ API 里。映射与行为:
采样只覆盖属性轨道;事件型轨道(音频、标记、自定义事件)在播放中按边沿检测触发,
采样不会触发它们。
+## 在包里
+
+时间轴是可选模块:场景里有 `TimelinePlayer`、内容里有 `.estimeline`,或脚本导入了 `esengine/timeline`,包里才会带上运行时和加载器;三者都没有的游戏两样都不带。
+
## 最佳实践
- **在 Sequencer 里编辑**——时间轴资源持有轨道,代码只负责播放与定位。
diff --git a/pipeline/src/bundle/engineInstalls.ts b/pipeline/src/bundle/engineInstalls.ts
index cf2381af4..e10bb2a44 100644
--- a/pipeline/src/bundle/engineInstalls.ts
+++ b/pipeline/src/bundle/engineInstalls.ts
@@ -24,6 +24,7 @@ import { ESENGINE_SUBPATHS } from './engineSubpaths';
* scene says "script graph", the `.esgraph` it references does. */
const ASSET_SUBPATH: Readonly<Record<string, string>> = {
'.esgraph': 'esengine/logic',
+ '.estimeline': 'esengine/timeline',
'.esfsm': 'esengine/ai',
'.esbt': 'esengine/ai',
};
diff --git a/pipeline/src/bundle/engineSubpaths.ts b/pipeline/src/bundle/engineSubpaths.ts
index 7a7da03ea..9b23a396a 100644
--- a/pipeline/src/bundle/engineSubpaths.ts
+++ b/pipeline/src/bundle/engineSubpaths.ts
@@ -13,6 +13,7 @@ export const ESENGINE_SUBPATHS: Readonly<Record<string, string>> = {
'esengine/spine': 'spine/index.js',
'esengine/tilemap': 'tilemap/index.js',
'esengine/terrain': 'terrain/index.js',
+ 'esengine/timeline': 'timeline/index.js',
'esengine/foliage': 'foliage/index.js',
'esengine/logic': 'logic/index.js',
'esengine/debug-channel': 'debug-channel/index.js',
diff --git a/pipeline/src/project/targetSupport.ts b/pipeline/src/project/targetSupport.ts
index 3030d3ef9..957d15638 100644
--- a/pipeline/src/project/targetSupport.ts
+++ b/pipeline/src/project/targetSupport.ts
@@ -27,7 +27,7 @@ import { NATIVE_PLATFORMS, type ExportPlatform } from './platforms';
/** An engine subsystem a build target may lack. */
export type Subsystem =
- | 'text' | 'tilemap' | 'terrain' | 'foliage' | 'particles' | 'postprocess' | 'physics' | 'physics3d'
+ | 'text' | 'tilemap' | 'terrain' | 'foliage' | 'timeline' | 'particles' | 'postprocess' | 'physics' | 'physics3d'
| 'spine' | 'dragonbones' | 'video' | 'ai' | 'logic' | 'replication' | 'gameplay';
/**
@@ -40,6 +40,7 @@ export const SUBSYSTEM_COMPONENTS: Readonly<Record<Subsystem, readonly string[]>
text: ['Text', 'BitmapText'],
tilemap: ['Tilemap', 'TilemapLayer'],
terrain: ['Terrain'],
+ timeline: ['TimelinePlayer'],
foliage: ['Foliage'],
particles: ['ParticleEmitter', 'ParticleForceField'],
postprocess: ['PostProcessVolume'],
@@ -72,6 +73,7 @@ export const SUBSYSTEM_LABEL: Readonly<Record<Subsystem, string>> = {
text: 'Text',
tilemap: 'Tilemaps',
terrain: 'Terrain',
+ timeline: 'Timelines',
foliage: 'Foliage',
particles: 'Particles',
postprocess: 'Post-processing',
@@ -98,6 +100,7 @@ export const SUBSYSTEM_INSTALL: Readonly<Record<Subsystem, string>> = {
postprocess: 'base',
tilemap: 'esengine/tilemap',
terrain: 'esengine/terrain',
+ timeline: 'esengine/timeline',
foliage: 'esengine/foliage',
physics: 'esengine/physics',
physics3d: 'esengine/physics3d',
diff --git a/pipeline/tests/engine-installs.test.ts b/pipeline/tests/engine-installs.test.ts
index 408e8994a..d609c2155 100644
--- a/pipeline/tests/engine-installs.test.ts
+++ b/pipeline/tests/engine-installs.test.ts
@@ -25,6 +25,11 @@ describe('the engine modules a package installs', () => {
expect(engineInstalls({ subsystems: ['particles'] }).subpaths).toEqual([]);
});
+ it('takes timelines from a TimelinePlayer or from the .estimeline it plays', () => {
+ expect(engineInstalls({ subsystems: ['timeline'] }).subpaths).toEqual(['esengine/timeline']);
+ expect(engineInstalls({ assetPaths: ['assets/cutscenes/Intro.estimeline'] }).subpaths).toEqual(['esengine/timeline']);
+ });
+
it('takes one a document names by asset rather than by component', () => {
// Nothing in a scene says "script graph"; the .esgraph it references does.
expect(engineInstalls({ assetPaths: ['assets/logic/Door.esgraph'] }).subpaths)
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index e6a951600..1c87e0dc5 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 · 1671 experimental · 3 deprecated
+Symbols: 115 public · 159 beta · 1706 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -1640,6 +1640,15 @@ op: CompareOp
value: string | number | boolean | undefined
```
+## BladeParams — interface @experimental
+```
+height: number
+paint: { base: [number, number, number]; tip: [number, number, number]; } | null | undefined
+segments: number
+thin: number
+width: number
+```
+
## BlendCurve — type @experimental
```
(typeof BlendCurve)[keyof typeof BlendCurve]
@@ -2171,6 +2180,14 @@ rgb: Float32Array<ArrayBufferLike>
width: number
```
+## CardRect — interface @experimental
+```
+u0: number
+u1: number
+v0: number
+v1: number
+```
+
## Catalog — class @experimental
```
addressOf: (path: string) => string | null
@@ -4023,6 +4040,59 @@ isFocused: boolean
tabIndex: number
```
+## Foliage — const @experimental
+```
+ComponentDef<FoliageData>
+```
+
+## FoliageData — interface @experimental
+```
+bladeHeight: number
+bladeWidth: number
+cardTent: number
+cardU0: number
+cardU1: number
+cardV0: number
+cardV1: number
+cellSize: number
+count: number
+drawDistance: number
+heightMax: number
+heightMin: number
+lodDistance: number
+material: number
+maxScale: number
+mesh: number
+minScale: number
+minUp: number
+seed: number
+sizeX: number
+sizeZ: number
+```
+
+## FoliageField — class @experimental
+```
+@internal built_: Map<number, BuiltFoliage>
+cellCount: number
+pending: number
+static new (): FoliageField
+static prototype: FoliageField
+```
+
+## FoliagePlugin — class @experimental
+```
+build: (app: App) => void
+cleanup: (app?: App) => void
+name: string
+static new (): FoliagePlugin
+static prototype: FoliagePlugin
+```
+
+## FoliageRes — const @experimental
+```
+ResourceDef<FoliageField>
+```
+
## FollowTarget — const @experimental
```
ComponentDef<FollowTargetData>
@@ -4377,6 +4447,11 @@ static new (opts: GridLayoutOptions): GridLayoutProvider
static prototype: GridLayoutProvider
```
+## Ground — type @experimental
+```
+(x: number, z: number) => { y: number; up: number } | null
+```
+
## HdrFormat — interface @experimental
```
effective: string
@@ -4392,6 +4467,13 @@ plugins: Plugin[] | undefined
sideModules: SideModuleHost | undefined
```
+## Heightfield — interface @experimental
+```
+data: Float32Array<ArrayBufferLike>
+height: number
+width: number
+```
+
## HingeJoint2D — const @experimental
```
ComponentDef<HingeJoint2DData>
@@ -6231,6 +6313,17 @@ updated: boolean | undefined
width: number | undefined
```
+## Plant — interface @experimental
+```
+phase: number
+scale: number
+shade: number
+x: number
+y: number
+yaw: number
+z: number
+```
+
## PlatformAdapter — interface @experimental
```
bindInputEvents: (callbacks: InputEventCallbacks, target?: unknown) => void
@@ -6827,6 +6920,16 @@ fingerprint: string
pending: PendingSystemEntry[]
```
+## ProceduralParams — interface @experimental
+```
+frequency: number
+octaves: number
+persistence: number
+resolution: number
+ridged: number
+seed: number
+```
+
## ProcessedEntity — interface @experimental
```
children: number[]
@@ -7668,6 +7771,21 @@ setJSON: <T>(key: string, value: T) => void
(typeof ScaleMode)[keyof typeof ScaleMode]
```
+## ScatterParams — interface @experimental
+```
+cellKey: number
+centerX: number
+centerZ: number
+count: number
+heightMax: number
+heightMin: number
+maxScale: number
+minScale: number
+minUp: number
+seed: number
+size: number
+```
+
## SceneAmbientLight — interface @experimental
```
drawEnvironment: boolean
@@ -9277,6 +9395,81 @@ setPaused: (paused: boolean) => void
suspendAudio: () => void
```
+## Terrain — const @experimental
+```
+ComponentDef<TerrainData>
+```
+
+## TerrainData — interface @experimental
+```
+chunkCells: number
+chunks: number
+detail: number
+dirtHeight: number
+frequency: number
+height: number
+heightmap: number
+layerColor0: Color
+layerColor1: Color
+layerColor2: Color
+layerColor3: Color
+lodLevels: number
+material: number
+octaves: number
+persistence: number
+resolution: number
+ridged: number
+rockSlope: number
+seed: number
+sizeX: number
+sizeZ: number
+snowHeight: number
+splatmap: number
+```
+
+## TerrainPaint — type @experimental
+```
+(
+ u: number, v: number, height01: number, slope: number,
+) => [number, number, number, number]
+```
+
+## TerrainPlugin — class @experimental
+```
+build: (app: App) => void
+cleanup: (app?: App) => void
+name: string
+static new (): TerrainPlugin
+static prototype: TerrainPlugin
+```
+
+## TerrainShape — interface @experimental
+```
+chunkCells: number
+chunks: number
+height: number
+sizeX: number
+sizeZ: number
+```
+
+## Terrains — class @experimental
+```
+@internal app_: App | null
+@internal built_: Map<number, Built>
+@internal revision_: number
+heightAt: (x: number, z: number) => number | null
+loading: boolean
+normalAt: (x: number, z: number) => [number, number, number] | null
+pending: number
+static new (): Terrains
+static prototype: Terrains
+```
+
+## TerrainsRes — const @experimental
+```
+ResourceDef<Terrains>
+```
+
## Text — const @public
```
ComponentDef<TextData>
@@ -11617,11 +11810,31 @@ MotionDriver<AnimatorBlend2DMotion>
(overrides: readonly PrefabOverride[]): Map<PrefabEntityId, PrefabOverride[]>
```
+## buildBillboardMesh — function @experimental
+```
+(plants: readonly Plant[], width: number, height: number, rect: CardRect, paint?: BladeParams["paint"], triangle?: boolean): MeshData
+```
+
+## buildChunkMesh — function @experimental
+```
+(field: Heightfield, shape: TerrainShape, cx: number, cz: number, lod: number, paint: TerrainPaint): MeshData
+```
+
## buildFrameProfile — function @experimental
```
(input: FrameProfileInput): FrameProfile
```
+## buildGrassMesh — function @experimental
+```
+(plants: readonly Plant[], blade: BladeParams): MeshData
+```
+
+## buildInstancedMesh — function @experimental
+```
+(source: MeshData, plants: readonly Plant[], paint?: BladeParams["paint"]): MeshData
+```
+
## buildText — function @experimental
```
(init?: TextInit): TextData
@@ -11732,11 +11945,21 @@ MotionDriver<AnimatorBlend2DMotion>
(cellX: number, cellZ: number, cellSize: number): { minX: number; minZ: number; maxX: number; maxZ: number; }
```
+## cellsAtLod — function @experimental
+```
+(shape: TerrainShape, lod: number): number
+```
+
## censusProbeIds — function @experimental
```
(): string[]
```
+## chunkCenter — function @experimental
+```
+(shape: TerrainShape, cx: number, cz: number): [number, number]
+```
+
## clearAnimatorControllerStore — function @experimental
```
(): void
@@ -12517,6 +12740,11 @@ FocusPlugin
(config: AssetGroupsConfig | null | undefined, folder: string): AssetGroupMode
```
+## foliagePlugin — const @experimental
+```
+Plugin
+```
+
## formatActionArg — function @experimental
```
(params: Readonly<Record<string, AiParamValue>> | undefined, defs: readonly AiParamDef[], separator?: string): string | undefined
@@ -12757,6 +12985,11 @@ FocusPlugin
() => Plugin[]
```
+## heightfieldFromPixels — function @experimental
+```
+(width: number, height: number, pixels: ArrayLike<number>): Heightfield
+```
+
## imageBitmapOptions — function @experimental
```
(flip: boolean): ImageBitmapOptions
@@ -13057,6 +13290,11 @@ LifecyclePlugin
LocalizationPlugin
```
+## lodCount — function @experimental
+```
+(shape: TerrainShape, wanted?: number): number
+```
+
## log — const @experimental
```
Logger
@@ -13222,6 +13460,11 @@ MeshRendererPlugin
(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId" | "screenFit" | "aot" | "debugChannel">): { physicsEnabled?: boolean; physicsConfig?: Physics2DPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; screenFit?: PackagedGameConfig["screenFit"]; aot?: PackagedGameConfig["aot"]; debugChannel?: DebugChannelConfig; }
```
+## paintWeights — function @experimental
+```
+(h: number, ny: number, t: Pick<TerrainData, "rockSlope" | "dirtHeight" | "snowHeight">): [number, number, number, number]
+```
+
## panoramaDirection — function @experimental
```
(u: number, v: number): [number, number, number]
@@ -13512,6 +13755,11 @@ PrefabsPlugin
(register: () => Promise<void>): Promise<ProbedRegistrations>
```
+## proceduralHeightfield — function @experimental
+```
+(p: ProceduralParams): Heightfield
+```
+
## projectSideModuleIds — function @experimental
```
(): string[]
@@ -13827,6 +14075,11 @@ PrefabsPlugin
(base: "dark" | "light", overrides?: ThemeOverrides): ThemeTokens
```
+## rng — function @experimental
+```
+(seed: number): () => number
+```
+
## rotateVec3ByQuat — function @experimental
```
(rot: Quat, v: Vec3): Vec3
@@ -13847,6 +14100,11 @@ PrefabsPlugin
SafeAreaPlugin
```
+## sampleHeight — function @experimental
+```
+(field: Heightfield, u: number, v: number): number
+```
+
## sampleKeyframes — function @experimental
```
(keys: readonly Keyframe[], at: number): number
@@ -13872,6 +14130,11 @@ SafeAreaPlugin
{ readonly clamp: (x: number, min: number, max: number) => number; readonly clamp01: (x: number) => number; readonly lerp: (a: number, b: number, t: number) => number; readonly inverseLerp: (a: number, b: number, value: number) => number; readonly remap: (value: number, inMin: number, inMax: number, outMin: number, outMax: number) => number; readonly deg2rad: (deg: number) => number; readonly rad2deg: (rad: number) => number; readonly approximately: (a: number, b: number, epsilon?: number) => boolean; readonly smoothstep: (edge0: number, edge1: number, x: number) => number; readonly mod: (x: number, n: number) => number; readonly sign: (x: number) => number; }
```
+## scatterCell — function @experimental
+```
+(p: ScatterParams, ground: Ground): Plant[]
+```
+
## sceneAmbientLights — function @experimental
```
(entities: readonly EnvironmentLightEntity[], exists: (ref: string) => boolean): SceneAmbientLight[]
@@ -14327,6 +14590,16 @@ StatsPlugin
(ctx?: CensusContext): Census
```
+## terrainNormal — function @experimental
+```
+(field: Heightfield, u: number, v: number, sizeX: number, sizeZ: number, heightScale: number): [number, number, number]
+```
+
+## terrainPlugin — const @experimental
+```
+Plugin
+```
+
## textInputPlugin — const @experimental
```
TextInputPlugin
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index c5f4ba3d9..a1333ff3b 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 · 1690 experimental · 3 deprecated
+Symbols: 115 public · 164 beta · 1725 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -1640,6 +1640,15 @@ op: CompareOp
value: string | number | boolean | undefined
```
+## BladeParams — interface @experimental
+```
+height: number
+paint: { base: [number, number, number]; tip: [number, number, number]; } | null | undefined
+segments: number
+thin: number
+width: number
+```
+
## BlendCurve — type @experimental
```
(typeof BlendCurve)[keyof typeof BlendCurve]
@@ -2171,6 +2180,14 @@ rgb: Float32Array<ArrayBufferLike>
width: number
```
+## CardRect — interface @experimental
+```
+u0: number
+u1: number
+v0: number
+v1: number
+```
+
## Catalog — class @experimental
```
addressOf: (path: string) => string | null
@@ -4031,6 +4048,59 @@ isFocused: boolean
tabIndex: number
```
+## Foliage — const @experimental
+```
+ComponentDef<FoliageData>
+```
+
+## FoliageData — interface @experimental
+```
+bladeHeight: number
+bladeWidth: number
+cardTent: number
+cardU0: number
+cardU1: number
+cardV0: number
+cardV1: number
+cellSize: number
+count: number
+drawDistance: number
+heightMax: number
+heightMin: number
+lodDistance: number
+material: number
+maxScale: number
+mesh: number
+minScale: number
+minUp: number
+seed: number
+sizeX: number
+sizeZ: number
+```
+
+## FoliageField — class @experimental
+```
+@internal built_: Map<number, BuiltFoliage>
+cellCount: number
+pending: number
+static new (): FoliageField
+static prototype: FoliageField
+```
+
+## FoliagePlugin — class @experimental
+```
+build: (app: App) => void
+cleanup: (app?: App) => void
+name: string
+static new (): FoliagePlugin
+static prototype: FoliagePlugin
+```
+
+## FoliageRes — const @experimental
+```
+ResourceDef<FoliageField>
+```
+
## FollowTarget — const @experimental
```
ComponentDef<FollowTargetData>
@@ -4385,6 +4455,11 @@ static new (opts: GridLayoutOptions): GridLayoutProvider
static prototype: GridLayoutProvider
```
+## Ground — type @experimental
+```
+(x: number, z: number) => { y: number; up: number } | null
+```
+
## HdrFormat — interface @experimental
```
effective: string
@@ -4400,6 +4475,13 @@ plugins: Plugin[] | undefined
sideModules: SideModuleHost | undefined
```
+## Heightfield — interface @experimental
+```
+data: Float32Array<ArrayBufferLike>
+height: number
+width: number
+```
+
## HingeJoint2D — const @experimental
```
ComponentDef<HingeJoint2DData>
@@ -6434,6 +6516,17 @@ updated: boolean | undefined
width: number | undefined
```
+## Plant — interface @experimental
+```
+phase: number
+scale: number
+shade: number
+x: number
+y: number
+yaw: number
+z: number
+```
+
## PlatformAdapter — interface @experimental
```
bindInputEvents: (callbacks: InputEventCallbacks, target?: unknown) => void
@@ -7030,6 +7123,16 @@ fingerprint: string
pending: PendingSystemEntry[]
```
+## ProceduralParams — interface @experimental
+```
+frequency: number
+octaves: number
+persistence: number
+resolution: number
+ridged: number
+seed: number
+```
+
## ProcessedEntity — interface @experimental
```
children: number[]
@@ -7881,6 +7984,21 @@ setJSON: <T>(key: string, value: T) => void
(typeof ScaleMode)[keyof typeof ScaleMode]
```
+## ScatterParams — interface @experimental
+```
+cellKey: number
+centerX: number
+centerZ: number
+count: number
+heightMax: number
+heightMin: number
+maxScale: number
+minScale: number
+minUp: number
+seed: number
+size: number
+```
+
## SceneAmbientLight — interface @experimental
```
drawEnvironment: boolean
@@ -9490,6 +9608,81 @@ setPaused: (paused: boolean) => void
suspendAudio: () => void
```
+## Terrain — const @experimental
+```
+ComponentDef<TerrainData>
+```
+
+## TerrainData — interface @experimental
+```
+chunkCells: number
+chunks: number
+detail: number
+dirtHeight: number
+frequency: number
+height: number
+heightmap: number
+layerColor0: Color
+layerColor1: Color
+layerColor2: Color
+layerColor3: Color
+lodLevels: number
+material: number
+octaves: number
+persistence: number
+resolution: number
+ridged: number
+rockSlope: number
+seed: number
+sizeX: number
+sizeZ: number
+snowHeight: number
+splatmap: number
+```
+
+## TerrainPaint — type @experimental
+```
+(
+ u: number, v: number, height01: number, slope: number,
+) => [number, number, number, number]
+```
+
+## TerrainPlugin — class @experimental
+```
+build: (app: App) => void
+cleanup: (app?: App) => void
+name: string
+static new (): TerrainPlugin
+static prototype: TerrainPlugin
+```
+
+## TerrainShape — interface @experimental
+```
+chunkCells: number
+chunks: number
+height: number
+sizeX: number
+sizeZ: number
+```
+
+## Terrains — class @experimental
+```
+@internal app_: App | null
+@internal built_: Map<number, Built>
+@internal revision_: number
+heightAt: (x: number, z: number) => number | null
+loading: boolean
+normalAt: (x: number, z: number) => [number, number, number] | null
+pending: number
+static new (): Terrains
+static prototype: Terrains
+```
+
+## TerrainsRes — const @experimental
+```
+ResourceDef<Terrains>
+```
+
## Text — const @public
```
ComponentDef<TextData>
@@ -11845,11 +12038,31 @@ MotionDriver<AnimatorBlend2DMotion>
(overrides: readonly PrefabOverride[]): Map<PrefabEntityId, PrefabOverride[]>
```
+## buildBillboardMesh — function @experimental
+```
+(plants: readonly Plant[], width: number, height: number, rect: CardRect, paint?: BladeParams["paint"], triangle?: boolean): MeshData
+```
+
+## buildChunkMesh — function @experimental
+```
+(field: Heightfield, shape: TerrainShape, cx: number, cz: number, lod: number, paint: TerrainPaint): MeshData
+```
+
## buildFrameProfile — function @experimental
```
(input: FrameProfileInput): FrameProfile
```
+## buildGrassMesh — function @experimental
+```
+(plants: readonly Plant[], blade: BladeParams): MeshData
+```
+
+## buildInstancedMesh — function @experimental
+```
+(source: MeshData, plants: readonly Plant[], paint?: BladeParams["paint"]): MeshData
+```
+
## buildText — function @experimental
```
(init?: TextInit): TextData
@@ -11960,11 +12173,21 @@ MotionDriver<AnimatorBlend2DMotion>
(cellX: number, cellZ: number, cellSize: number): { minX: number; minZ: number; maxX: number; maxZ: number; }
```
+## cellsAtLod — function @experimental
+```
+(shape: TerrainShape, lod: number): number
+```
+
## censusProbeIds — function @experimental
```
(): string[]
```
+## chunkCenter — function @experimental
+```
+(shape: TerrainShape, cx: number, cz: number): [number, number]
+```
+
## clearAnimatorControllerStore — function @experimental
```
(): void
@@ -12770,6 +12993,11 @@ FocusPlugin
(config: AssetGroupsConfig | null | undefined, folder: string): AssetGroupMode
```
+## foliagePlugin — const @experimental
+```
+Plugin
+```
+
## formatActionArg — function @experimental
```
(params: Readonly<Record<string, AiParamValue>> | undefined, defs: readonly AiParamDef[], separator?: string): string | undefined
@@ -13010,6 +13238,11 @@ FocusPlugin
() => Plugin[]
```
+## heightfieldFromPixels — function @experimental
+```
+(width: number, height: number, pixels: ArrayLike<number>): Heightfield
+```
+
## imageBitmapOptions — function @experimental
```
(flip: boolean): ImageBitmapOptions
@@ -13320,6 +13553,11 @@ LifecyclePlugin
LocalizationPlugin
```
+## lodCount — function @experimental
+```
+(shape: TerrainShape, wanted?: number): number
+```
+
## log — const @experimental
```
Logger
@@ -13485,6 +13723,11 @@ MeshRendererPlugin
(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId" | "screenFit" | "aot" | "debugChannel">): { physicsEnabled?: boolean; physicsConfig?: Physics2DPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; screenFit?: PackagedGameConfig["screenFit"]; aot?: PackagedGameConfig["aot"]; debugChannel?: DebugChannelConfig; }
```
+## paintWeights — function @experimental
+```
+(h: number, ny: number, t: Pick<TerrainData, "rockSlope" | "dirtHeight" | "snowHeight">): [number, number, number, number]
+```
+
## panoramaDirection — function @experimental
```
(u: number, v: number): [number, number, number]
@@ -13775,6 +14018,11 @@ PrefabsPlugin
(register: () => Promise<void>): Promise<ProbedRegistrations>
```
+## proceduralHeightfield — function @experimental
+```
+(p: ProceduralParams): Heightfield
+```
+
## projectSideModuleIds — function @experimental
```
(): string[]
@@ -14090,6 +14338,11 @@ PrefabsPlugin
(base: "dark" | "light", overrides?: ThemeOverrides): ThemeTokens
```
+## rng — function @experimental
+```
+(seed: number): () => number
+```
+
## rotateVec3ByQuat — function @experimental
```
(rot: Quat, v: Vec3): Vec3
@@ -14110,6 +14363,11 @@ PrefabsPlugin
SafeAreaPlugin
```
+## sampleHeight — function @experimental
+```
+(field: Heightfield, u: number, v: number): number
+```
+
## sampleKeyframes — function @experimental
```
(keys: readonly Keyframe[], at: number): number
@@ -14135,6 +14393,11 @@ SafeAreaPlugin
{ readonly clamp: (x: number, min: number, max: number) => number; readonly clamp01: (x: number) => number; readonly lerp: (a: number, b: number, t: number) => number; readonly inverseLerp: (a: number, b: number, value: number) => number; readonly remap: (value: number, inMin: number, inMax: number, outMin: number, outMax: number) => number; readonly deg2rad: (deg: number) => number; readonly rad2deg: (rad: number) => number; readonly approximately: (a: number, b: number, epsilon?: number) => boolean; readonly smoothstep: (edge0: number, edge1: number, x: number) => number; readonly mod: (x: number, n: number) => number; readonly sign: (x: number) => number; }
```
+## scatterCell — function @experimental
+```
+(p: ScatterParams, ground: Ground): Plant[]
+```
+
## sceneAmbientLights — function @experimental
```
(entities: readonly EnvironmentLightEntity[], exists: (ref: string) => boolean): SceneAmbientLight[]
@@ -14590,6 +14853,16 @@ StatsPlugin
(ctx?: CensusContext): Census
```
+## terrainNormal — function @experimental
+```
+(field: Heightfield, u: number, v: number, sizeX: number, sizeZ: number, heightScale: number): [number, number, number]
+```
+
+## terrainPlugin — const @experimental
+```
+Plugin
+```
+
## textInputPlugin — const @experimental
```
TextInputPlugin
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 7e1a3cebc..ff267e6d3 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 · 1670 experimental · 3 deprecated
+Symbols: 115 public · 161 beta · 1705 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -1635,6 +1635,15 @@ op: CompareOp
value: string | number | boolean | undefined
```
+## BladeParams — interface @experimental
+```
+height: number
+paint: { base: [number, number, number]; tip: [number, number, number]; } | null | undefined
+segments: number
+thin: number
+width: number
+```
+
## BlendCurve — type @experimental
```
(typeof BlendCurve)[keyof typeof BlendCurve]
@@ -2166,6 +2175,14 @@ rgb: Float32Array<ArrayBufferLike>
width: number
```
+## CardRect — interface @experimental
+```
+u0: number
+u1: number
+v0: number
+v1: number
+```
+
## Catalog — class @experimental
```
addressOf: (path: string) => string | null
@@ -4018,6 +4035,59 @@ isFocused: boolean
tabIndex: number
```
+## Foliage — const @experimental
+```
+ComponentDef<FoliageData>
+```
+
+## FoliageData — interface @experimental
+```
+bladeHeight: number
+bladeWidth: number
+cardTent: number
+cardU0: number
+cardU1: number
+cardV0: number
+cardV1: number
+cellSize: number
+count: number
+drawDistance: number
+heightMax: number
+heightMin: number
+lodDistance: number
+material: number
+maxScale: number
+mesh: number
+minScale: number
+minUp: number
+seed: number
+sizeX: number
+sizeZ: number
+```
+
+## FoliageField — class @experimental
+```
+@internal built_: Map<number, BuiltFoliage>
+cellCount: number
+pending: number
+static new (): FoliageField
+static prototype: FoliageField
+```
+
+## FoliagePlugin — class @experimental
+```
+build: (app: App) => void
+cleanup: (app?: App) => void
+name: string
+static new (): FoliagePlugin
+static prototype: FoliagePlugin
+```
+
+## FoliageRes — const @experimental
+```
+ResourceDef<FoliageField>
+```
+
## FollowTarget — const @experimental
```
ComponentDef<FollowTargetData>
@@ -4372,6 +4442,11 @@ static new (opts: GridLayoutOptions): GridLayoutProvider
static prototype: GridLayoutProvider
```
+## Ground — type @experimental
+```
+(x: number, z: number) => { y: number; up: number } | null
+```
+
## HdrFormat — interface @experimental
```
effective: string
@@ -4387,6 +4462,13 @@ plugins: Plugin[] | undefined
sideModules: SideModuleHost | undefined
```
+## Heightfield — interface @experimental
+```
+data: Float32Array<ArrayBufferLike>
+height: number
+width: number
+```
+
## HingeJoint2D — const @experimental
```
ComponentDef<HingeJoint2DData>
@@ -6226,6 +6308,17 @@ updated: boolean | undefined
width: number | undefined
```
+## Plant — interface @experimental
+```
+phase: number
+scale: number
+shade: number
+x: number
+y: number
+yaw: number
+z: number
+```
+
## PlatformAdapter — interface @experimental
```
bindInputEvents: (callbacks: InputEventCallbacks, target?: unknown) => void
@@ -6822,6 +6915,16 @@ fingerprint: string
pending: PendingSystemEntry[]
```
+## ProceduralParams — interface @experimental
+```
+frequency: number
+octaves: number
+persistence: number
+resolution: number
+ridged: number
+seed: number
+```
+
## ProcessedEntity — interface @experimental
```
children: number[]
@@ -7663,6 +7766,21 @@ setJSON: <T>(key: string, value: T) => void
(typeof ScaleMode)[keyof typeof ScaleMode]
```
+## ScatterParams — interface @experimental
+```
+cellKey: number
+centerX: number
+centerZ: number
+count: number
+heightMax: number
+heightMin: number
+maxScale: number
+minScale: number
+minUp: number
+seed: number
+size: number
+```
+
## SceneAmbientLight — interface @experimental
```
drawEnvironment: boolean
@@ -9272,6 +9390,81 @@ setPaused: (paused: boolean) => void
suspendAudio: () => void
```
+## Terrain — const @experimental
+```
+ComponentDef<TerrainData>
+```
+
+## TerrainData — interface @experimental
+```
+chunkCells: number
+chunks: number
+detail: number
+dirtHeight: number
+frequency: number
+height: number
+heightmap: number
+layerColor0: Color
+layerColor1: Color
+layerColor2: Color
+layerColor3: Color
+lodLevels: number
+material: number
+octaves: number
+persistence: number
+resolution: number
+ridged: number
+rockSlope: number
+seed: number
+sizeX: number
+sizeZ: number
+snowHeight: number
+splatmap: number
+```
+
+## TerrainPaint — type @experimental
+```
+(
+ u: number, v: number, height01: number, slope: number,
+) => [number, number, number, number]
+```
+
+## TerrainPlugin — class @experimental
+```
+build: (app: App) => void
+cleanup: (app?: App) => void
+name: string
+static new (): TerrainPlugin
+static prototype: TerrainPlugin
+```
+
+## TerrainShape — interface @experimental
+```
+chunkCells: number
+chunks: number
+height: number
+sizeX: number
+sizeZ: number
+```
+
+## Terrains — class @experimental
+```
+@internal app_: App | null
+@internal built_: Map<number, Built>
+@internal revision_: number
+heightAt: (x: number, z: number) => number | null
+loading: boolean
+normalAt: (x: number, z: number) => [number, number, number] | null
+pending: number
+static new (): Terrains
+static prototype: Terrains
+```
+
+## TerrainsRes — const @experimental
+```
+ResourceDef<Terrains>
+```
+
## Text — const @public
```
ComponentDef<TextData>
@@ -11612,11 +11805,31 @@ MotionDriver<AnimatorBlend2DMotion>
(overrides: readonly PrefabOverride[]): Map<PrefabEntityId, PrefabOverride[]>
```
+## buildBillboardMesh — function @experimental
+```
+(plants: readonly Plant[], width: number, height: number, rect: CardRect, paint?: BladeParams["paint"], triangle?: boolean): MeshData
+```
+
+## buildChunkMesh — function @experimental
+```
+(field: Heightfield, shape: TerrainShape, cx: number, cz: number, lod: number, paint: TerrainPaint): MeshData
+```
+
## buildFrameProfile — function @experimental
```
(input: FrameProfileInput): FrameProfile
```
+## buildGrassMesh — function @experimental
+```
+(plants: readonly Plant[], blade: BladeParams): MeshData
+```
+
+## buildInstancedMesh — function @experimental
+```
+(source: MeshData, plants: readonly Plant[], paint?: BladeParams["paint"]): MeshData
+```
+
## buildText — function @experimental
```
(init?: TextInit): TextData
@@ -11727,11 +11940,21 @@ MotionDriver<AnimatorBlend2DMotion>
(cellX: number, cellZ: number, cellSize: number): { minX: number; minZ: number; maxX: number; maxZ: number; }
```
+## cellsAtLod — function @experimental
+```
+(shape: TerrainShape, lod: number): number
+```
+
## censusProbeIds — function @experimental
```
(): string[]
```
+## chunkCenter — function @experimental
+```
+(shape: TerrainShape, cx: number, cz: number): [number, number]
+```
+
## clearAnimatorControllerStore — function @experimental
```
(): void
@@ -12512,6 +12735,11 @@ FocusPlugin
(config: AssetGroupsConfig | null | undefined, folder: string): AssetGroupMode
```
+## foliagePlugin — const @experimental
+```
+Plugin
+```
+
## formatActionArg — function @experimental
```
(params: Readonly<Record<string, AiParamValue>> | undefined, defs: readonly AiParamDef[], separator?: string): string | undefined
@@ -12752,6 +12980,11 @@ FocusPlugin
() => Plugin[]
```
+## heightfieldFromPixels — function @experimental
+```
+(width: number, height: number, pixels: ArrayLike<number>): Heightfield
+```
+
## imageBitmapOptions — function @experimental
```
(flip: boolean): ImageBitmapOptions
@@ -13057,6 +13290,11 @@ LifecyclePlugin
LocalizationPlugin
```
+## lodCount — function @experimental
+```
+(shape: TerrainShape, wanted?: number): number
+```
+
## log — const @experimental
```
Logger
@@ -13227,6 +13465,11 @@ NodePlatformAdapter
(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId" | "screenFit" | "aot" | "debugChannel">): { physicsEnabled?: boolean; physicsConfig?: Physics2DPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; screenFit?: PackagedGameConfig["screenFit"]; aot?: PackagedGameConfig["aot"]; debugChannel?: DebugChannelConfig; }
```
+## paintWeights — function @experimental
+```
+(h: number, ny: number, t: Pick<TerrainData, "rockSlope" | "dirtHeight" | "snowHeight">): [number, number, number, number]
+```
+
## panoramaDirection — function @experimental
```
(u: number, v: number): [number, number, number]
@@ -13517,6 +13760,11 @@ PrefabsPlugin
(register: () => Promise<void>): Promise<ProbedRegistrations>
```
+## proceduralHeightfield — function @experimental
+```
+(p: ProceduralParams): Heightfield
+```
+
## projectSideModuleIds — function @experimental
```
(): string[]
@@ -13832,6 +14080,11 @@ PrefabsPlugin
(base: "dark" | "light", overrides?: ThemeOverrides): ThemeTokens
```
+## rng — function @experimental
+```
+(seed: number): () => number
+```
+
## rotateVec3ByQuat — function @experimental
```
(rot: Quat, v: Vec3): Vec3
@@ -13852,6 +14105,11 @@ PrefabsPlugin
SafeAreaPlugin
```
+## sampleHeight — function @experimental
+```
+(field: Heightfield, u: number, v: number): number
+```
+
## sampleKeyframes — function @experimental
```
(keys: readonly Keyframe[], at: number): number
@@ -13877,6 +14135,11 @@ SafeAreaPlugin
{ readonly clamp: (x: number, min: number, max: number) => number; readonly clamp01: (x: number) => number; readonly lerp: (a: number, b: number, t: number) => number; readonly inverseLerp: (a: number, b: number, value: number) => number; readonly remap: (value: number, inMin: number, inMax: number, outMin: number, outMax: number) => number; readonly deg2rad: (deg: number) => number; readonly rad2deg: (rad: number) => number; readonly approximately: (a: number, b: number, epsilon?: number) => boolean; readonly smoothstep: (edge0: number, edge1: number, x: number) => number; readonly mod: (x: number, n: number) => number; readonly sign: (x: number) => number; }
```
+## scatterCell — function @experimental
+```
+(p: ScatterParams, ground: Ground): Plant[]
+```
+
## sceneAmbientLights — function @experimental
```
(entities: readonly EnvironmentLightEntity[], exists: (ref: string) => boolean): SceneAmbientLight[]
@@ -14332,6 +14595,16 @@ StatsPlugin
(ctx?: CensusContext): Census
```
+## terrainNormal — function @experimental
+```
+(field: Heightfield, u: number, v: number, sizeX: number, sizeZ: number, heightScale: number): [number, number, number]
+```
+
+## terrainPlugin — const @experimental
+```
+Plugin
+```
+
## textInputPlugin — const @experimental
```
TextInputPlugin
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 0d5a9e779..cd2ecd6c7 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 · 1692 experimental · 3 deprecated
+Symbols: 115 public · 159 beta · 1727 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -1635,6 +1635,15 @@ op: CompareOp
value: string | number | boolean | undefined
```
+## BladeParams — interface @experimental
+```
+height: number
+paint: { base: [number, number, number]; tip: [number, number, number]; } | null | undefined
+segments: number
+thin: number
+width: number
+```
+
## BlendCurve — type @experimental
```
(typeof BlendCurve)[keyof typeof BlendCurve]
@@ -2166,6 +2175,14 @@ rgb: Float32Array<ArrayBufferLike>
width: number
```
+## CardRect — interface @experimental
+```
+u0: number
+u1: number
+v0: number
+v1: number
+```
+
## Catalog — class @experimental
```
addressOf: (path: string) => string | null
@@ -4018,6 +4035,59 @@ isFocused: boolean
tabIndex: number
```
+## Foliage — const @experimental
+```
+ComponentDef<FoliageData>
+```
+
+## FoliageData — interface @experimental
+```
+bladeHeight: number
+bladeWidth: number
+cardTent: number
+cardU0: number
+cardU1: number
+cardV0: number
+cardV1: number
+cellSize: number
+count: number
+drawDistance: number
+heightMax: number
+heightMin: number
+lodDistance: number
+material: number
+maxScale: number
+mesh: number
+minScale: number
+minUp: number
+seed: number
+sizeX: number
+sizeZ: number
+```
+
+## FoliageField — class @experimental
+```
+@internal built_: Map<number, BuiltFoliage>
+cellCount: number
+pending: number
+static new (): FoliageField
+static prototype: FoliageField
+```
+
+## FoliagePlugin — class @experimental
+```
+build: (app: App) => void
+cleanup: (app?: App) => void
+name: string
+static new (): FoliagePlugin
+static prototype: FoliagePlugin
+```
+
+## FoliageRes — const @experimental
+```
+ResourceDef<FoliageField>
+```
+
## FollowTarget — const @experimental
```
ComponentDef<FollowTargetData>
@@ -4372,6 +4442,11 @@ static new (opts: GridLayoutOptions): GridLayoutProvider
static prototype: GridLayoutProvider
```
+## Ground — type @experimental
+```
+(x: number, z: number) => { y: number; up: number } | null
+```
+
## HdrFormat — interface @experimental
```
effective: string
@@ -4387,6 +4462,13 @@ plugins: Plugin[] | undefined
sideModules: SideModuleHost | undefined
```
+## Heightfield — interface @experimental
+```
+data: Float32Array<ArrayBufferLike>
+height: number
+width: number
+```
+
## HingeJoint2D — const @experimental
```
ComponentDef<HingeJoint2DData>
@@ -6519,6 +6601,17 @@ updated: boolean | undefined
width: number | undefined
```
+## Plant — interface @experimental
+```
+phase: number
+scale: number
+shade: number
+x: number
+y: number
+yaw: number
+z: number
+```
+
## PlatformAdapter — interface @experimental
```
bindInputEvents: (callbacks: InputEventCallbacks, target?: unknown) => void
@@ -7115,6 +7208,16 @@ fingerprint: string
pending: PendingSystemEntry[]
```
+## ProceduralParams — interface @experimental
+```
+frequency: number
+octaves: number
+persistence: number
+resolution: number
+ridged: number
+seed: number
+```
+
## ProcessedEntity — interface @experimental
```
children: number[]
@@ -7956,6 +8059,21 @@ setJSON: <T>(key: string, value: T) => void
(typeof ScaleMode)[keyof typeof ScaleMode]
```
+## ScatterParams — interface @experimental
+```
+cellKey: number
+centerX: number
+centerZ: number
+count: number
+heightMax: number
+heightMin: number
+maxScale: number
+minScale: number
+minUp: number
+seed: number
+size: number
+```
+
## SceneAmbientLight — interface @experimental
```
drawEnvironment: boolean
@@ -9565,6 +9683,81 @@ setPaused: (paused: boolean) => void
suspendAudio: () => void
```
+## Terrain — const @experimental
+```
+ComponentDef<TerrainData>
+```
+
+## TerrainData — interface @experimental
+```
+chunkCells: number
+chunks: number
+detail: number
+dirtHeight: number
+frequency: number
+height: number
+heightmap: number
+layerColor0: Color
+layerColor1: Color
+layerColor2: Color
+layerColor3: Color
+lodLevels: number
+material: number
+octaves: number
+persistence: number
+resolution: number
+ridged: number
+rockSlope: number
+seed: number
+sizeX: number
+sizeZ: number
+snowHeight: number
+splatmap: number
+```
+
+## TerrainPaint — type @experimental
+```
+(
+ u: number, v: number, height01: number, slope: number,
+) => [number, number, number, number]
+```
+
+## TerrainPlugin — class @experimental
+```
+build: (app: App) => void
+cleanup: (app?: App) => void
+name: string
+static new (): TerrainPlugin
+static prototype: TerrainPlugin
+```
+
+## TerrainShape — interface @experimental
+```
+chunkCells: number
+chunks: number
+height: number
+sizeX: number
+sizeZ: number
+```
+
+## Terrains — class @experimental
+```
+@internal app_: App | null
+@internal built_: Map<number, Built>
+@internal revision_: number
+heightAt: (x: number, z: number) => number | null
+loading: boolean
+normalAt: (x: number, z: number) => [number, number, number] | null
+pending: number
+static new (): Terrains
+static prototype: Terrains
+```
+
+## TerrainsRes — const @experimental
+```
+ResourceDef<Terrains>
+```
+
## Text — const @public
```
ComponentDef<TextData>
@@ -11911,11 +12104,31 @@ MotionDriver<AnimatorBlend2DMotion>
(overrides: readonly PrefabOverride[]): Map<PrefabEntityId, PrefabOverride[]>
```
+## buildBillboardMesh — function @experimental
+```
+(plants: readonly Plant[], width: number, height: number, rect: CardRect, paint?: BladeParams["paint"], triangle?: boolean): MeshData
+```
+
+## buildChunkMesh — function @experimental
+```
+(field: Heightfield, shape: TerrainShape, cx: number, cz: number, lod: number, paint: TerrainPaint): MeshData
+```
+
## buildFrameProfile — function @experimental
```
(input: FrameProfileInput): FrameProfile
```
+## buildGrassMesh — function @experimental
+```
+(plants: readonly Plant[], blade: BladeParams): MeshData
+```
+
+## buildInstancedMesh — function @experimental
+```
+(source: MeshData, plants: readonly Plant[], paint?: BladeParams["paint"]): MeshData
+```
+
## buildText — function @experimental
```
(init?: TextInit): TextData
@@ -12026,11 +12239,21 @@ MotionDriver<AnimatorBlend2DMotion>
(cellX: number, cellZ: number, cellSize: number): { minX: number; minZ: number; maxX: number; maxZ: number; }
```
+## cellsAtLod — function @experimental
+```
+(shape: TerrainShape, lod: number): number
+```
+
## censusProbeIds — function @experimental
```
(): string[]
```
+## chunkCenter — function @experimental
+```
+(shape: TerrainShape, cx: number, cz: number): [number, number]
+```
+
## clearAnimatorControllerStore — function @experimental
```
(): void
@@ -12816,6 +13039,11 @@ FocusPlugin
(config: AssetGroupsConfig | null | undefined, folder: string): AssetGroupMode
```
+## foliagePlugin — const @experimental
+```
+Plugin
+```
+
## formatActionArg — function @experimental
```
(params: Readonly<Record<string, AiParamValue>> | undefined, defs: readonly AiParamDef[], separator?: string): string | undefined
@@ -13056,6 +13284,11 @@ FocusPlugin
() => Plugin[]
```
+## heightfieldFromPixels — function @experimental
+```
+(width: number, height: number, pixels: ArrayLike<number>): Heightfield
+```
+
## imageBitmapOptions — function @experimental
```
(flip: boolean): ImageBitmapOptions
@@ -13366,6 +13599,11 @@ LifecyclePlugin
LocalizationPlugin
```
+## lodCount — function @experimental
+```
+(shape: TerrainShape, wanted?: number): number
+```
+
## log — const @experimental
```
Logger
@@ -13531,6 +13769,11 @@ MeshRendererPlugin
(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId" | "screenFit" | "aot" | "debugChannel">): { physicsEnabled?: boolean; physicsConfig?: Physics2DPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; screenFit?: PackagedGameConfig["screenFit"]; aot?: PackagedGameConfig["aot"]; debugChannel?: DebugChannelConfig; }
```
+## paintWeights — function @experimental
+```
+(h: number, ny: number, t: Pick<TerrainData, "rockSlope" | "dirtHeight" | "snowHeight">): [number, number, number, number]
+```
+
## panoramaDirection — function @experimental
```
(u: number, v: number): [number, number, number]
@@ -13821,6 +14064,11 @@ PrefabsPlugin
(register: () => Promise<void>): Promise<ProbedRegistrations>
```
+## proceduralHeightfield — function @experimental
+```
+(p: ProceduralParams): Heightfield
+```
+
## projectSideModuleIds — function @experimental
```
(): string[]
@@ -14136,6 +14384,11 @@ PrefabsPlugin
(base: "dark" | "light", overrides?: ThemeOverrides): ThemeTokens
```
+## rng — function @experimental
+```
+(seed: number): () => number
+```
+
## rotateVec3ByQuat — function @experimental
```
(rot: Quat, v: Vec3): Vec3
@@ -14156,6 +14409,11 @@ PrefabsPlugin
SafeAreaPlugin
```
+## sampleHeight — function @experimental
+```
+(field: Heightfield, u: number, v: number): number
+```
+
## sampleKeyframes — function @experimental
```
(keys: readonly Keyframe[], at: number): number
@@ -14181,6 +14439,11 @@ SafeAreaPlugin
{ readonly clamp: (x: number, min: number, max: number) => number; readonly clamp01: (x: number) => number; readonly lerp: (a: number, b: number, t: number) => number; readonly inverseLerp: (a: number, b: number, value: number) => number; readonly remap: (value: number, inMin: number, inMax: number, outMin: number, outMax: number) => number; readonly deg2rad: (deg: number) => number; readonly rad2deg: (rad: number) => number; readonly approximately: (a: number, b: number, epsilon?: number) => boolean; readonly smoothstep: (edge0: number, edge1: number, x: number) => number; readonly mod: (x: number, n: number) => number; readonly sign: (x: number) => number; }
```
+## scatterCell — function @experimental
+```
+(p: ScatterParams, ground: Ground): Plant[]
+```
+
## sceneAmbientLights — function @experimental
```
(entities: readonly EnvironmentLightEntity[], exists: (ref: string) => boolean): SceneAmbientLight[]
@@ -14636,6 +14899,16 @@ StatsPlugin
(ctx?: CensusContext): Census
```
+## terrainNormal — function @experimental
+```
+(field: Heightfield, u: number, v: number, sizeX: number, sizeZ: number, heightScale: number): [number, number, number]
+```
+
+## terrainPlugin — const @experimental
+```
+Plugin
+```
+
## textInputPlugin — const @experimental
```
TextInputPlugin
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index b469f52c6..af6c3ebf8 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 · 1683 experimental · 3 deprecated
+Symbols: 115 public · 159 beta · 1718 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -1635,6 +1635,15 @@ op: CompareOp
value: string | number | boolean | undefined
```
+## BladeParams — interface @experimental
+```
+height: number
+paint: { base: [number, number, number]; tip: [number, number, number]; } | null | undefined
+segments: number
+thin: number
+width: number
+```
+
## BlendCurve — type @experimental
```
(typeof BlendCurve)[keyof typeof BlendCurve]
@@ -2166,6 +2175,14 @@ rgb: Float32Array<ArrayBufferLike>
width: number
```
+## CardRect — interface @experimental
+```
+u0: number
+u1: number
+v0: number
+v1: number
+```
+
## Catalog — class @experimental
```
addressOf: (path: string) => string | null
@@ -4018,6 +4035,59 @@ isFocused: boolean
tabIndex: number
```
+## Foliage — const @experimental
+```
+ComponentDef<FoliageData>
+```
+
+## FoliageData — interface @experimental
+```
+bladeHeight: number
+bladeWidth: number
+cardTent: number
+cardU0: number
+cardU1: number
+cardV0: number
+cardV1: number
+cellSize: number
+count: number
+drawDistance: number
+heightMax: number
+heightMin: number
+lodDistance: number
+material: number
+maxScale: number
+mesh: number
+minScale: number
+minUp: number
+seed: number
+sizeX: number
+sizeZ: number
+```
+
+## FoliageField — class @experimental
+```
+@internal built_: Map<number, BuiltFoliage>
+cellCount: number
+pending: number
+static new (): FoliageField
+static prototype: FoliageField
+```
+
+## FoliagePlugin — class @experimental
+```
+build: (app: App) => void
+cleanup: (app?: App) => void
+name: string
+static new (): FoliagePlugin
+static prototype: FoliagePlugin
+```
+
+## FoliageRes — const @experimental
+```
+ResourceDef<FoliageField>
+```
+
## FollowTarget — const @experimental
```
ComponentDef<FollowTargetData>
@@ -4372,6 +4442,11 @@ static new (opts: GridLayoutOptions): GridLayoutProvider
static prototype: GridLayoutProvider
```
+## Ground — type @experimental
+```
+(x: number, z: number) => { y: number; up: number } | null
+```
+
## HdrFormat — interface @experimental
```
effective: string
@@ -4387,6 +4462,13 @@ plugins: Plugin[] | undefined
sideModules: SideModuleHost | undefined
```
+## Heightfield — interface @experimental
+```
+data: Float32Array<ArrayBufferLike>
+height: number
+width: number
+```
+
## HingeJoint2D — const @experimental
```
ComponentDef<HingeJoint2DData>
@@ -6233,6 +6315,17 @@ updated: boolean | undefined
width: number | undefined
```
+## Plant — interface @experimental
+```
+phase: number
+scale: number
+shade: number
+x: number
+y: number
+yaw: number
+z: number
+```
+
## PlatformAdapter — interface @experimental
```
bindInputEvents: (callbacks: InputEventCallbacks, target?: unknown) => void
@@ -6829,6 +6922,16 @@ fingerprint: string
pending: PendingSystemEntry[]
```
+## ProceduralParams — interface @experimental
+```
+frequency: number
+octaves: number
+persistence: number
+resolution: number
+ridged: number
+seed: number
+```
+
## ProcessedEntity — interface @experimental
```
children: number[]
@@ -7670,6 +7773,21 @@ setJSON: <T>(key: string, value: T) => void
(typeof ScaleMode)[keyof typeof ScaleMode]
```
+## ScatterParams — interface @experimental
+```
+cellKey: number
+centerX: number
+centerZ: number
+count: number
+heightMax: number
+heightMin: number
+maxScale: number
+minScale: number
+minUp: number
+seed: number
+size: number
+```
+
## SceneAmbientLight — interface @experimental
```
drawEnvironment: boolean
@@ -9279,6 +9397,81 @@ setPaused: (paused: boolean) => void
suspendAudio: () => void
```
+## Terrain — const @experimental
+```
+ComponentDef<TerrainData>
+```
+
+## TerrainData — interface @experimental
+```
+chunkCells: number
+chunks: number
+detail: number
+dirtHeight: number
+frequency: number
+height: number
+heightmap: number
+layerColor0: Color
+layerColor1: Color
+layerColor2: Color
+layerColor3: Color
+lodLevels: number
+material: number
+octaves: number
+persistence: number
+resolution: number
+ridged: number
+rockSlope: number
+seed: number
+sizeX: number
+sizeZ: number
+snowHeight: number
+splatmap: number
+```
+
+## TerrainPaint — type @experimental
+```
+(
+ u: number, v: number, height01: number, slope: number,
+) => [number, number, number, number]
+```
+
+## TerrainPlugin — class @experimental
+```
+build: (app: App) => void
+cleanup: (app?: App) => void
+name: string
+static new (): TerrainPlugin
+static prototype: TerrainPlugin
+```
+
+## TerrainShape — interface @experimental
+```
+chunkCells: number
+chunks: number
+height: number
+sizeX: number
+sizeZ: number
+```
+
+## Terrains — class @experimental
+```
+@internal app_: App | null
+@internal built_: Map<number, Built>
+@internal revision_: number
+heightAt: (x: number, z: number) => number | null
+loading: boolean
+normalAt: (x: number, z: number) => [number, number, number] | null
+pending: number
+static new (): Terrains
+static prototype: Terrains
+```
+
+## TerrainsRes — const @experimental
+```
+ResourceDef<Terrains>
+```
+
## Text — const @public
```
ComponentDef<TextData>
@@ -11643,11 +11836,31 @@ MotionDriver<AnimatorBlend2DMotion>
(overrides: readonly PrefabOverride[]): Map<PrefabEntityId, PrefabOverride[]>
```
+## buildBillboardMesh — function @experimental
+```
+(plants: readonly Plant[], width: number, height: number, rect: CardRect, paint?: BladeParams["paint"], triangle?: boolean): MeshData
+```
+
+## buildChunkMesh — function @experimental
+```
+(field: Heightfield, shape: TerrainShape, cx: number, cz: number, lod: number, paint: TerrainPaint): MeshData
+```
+
## buildFrameProfile — function @experimental
```
(input: FrameProfileInput): FrameProfile
```
+## buildGrassMesh — function @experimental
+```
+(plants: readonly Plant[], blade: BladeParams): MeshData
+```
+
+## buildInstancedMesh — function @experimental
+```
+(source: MeshData, plants: readonly Plant[], paint?: BladeParams["paint"]): MeshData
+```
+
## buildText — function @experimental
```
(init?: TextInit): TextData
@@ -11758,11 +11971,21 @@ MotionDriver<AnimatorBlend2DMotion>
(cellX: number, cellZ: number, cellSize: number): { minX: number; minZ: number; maxX: number; maxZ: number; }
```
+## cellsAtLod — function @experimental
+```
+(shape: TerrainShape, lod: number): number
+```
+
## censusProbeIds — function @experimental
```
(): string[]
```
+## chunkCenter — function @experimental
+```
+(shape: TerrainShape, cx: number, cz: number): [number, number]
+```
+
## clearAnimatorControllerStore — function @experimental
```
(): void
@@ -12543,6 +12766,11 @@ FocusPlugin
(config: AssetGroupsConfig | null | undefined, folder: string): AssetGroupMode
```
+## foliagePlugin — const @experimental
+```
+Plugin
+```
+
## formatActionArg — function @experimental
```
(params: Readonly<Record<string, AiParamValue>> | undefined, defs: readonly AiParamDef[], separator?: string): string | undefined
@@ -12783,6 +13011,11 @@ FocusPlugin
() => Plugin[]
```
+## heightfieldFromPixels — function @experimental
+```
+(width: number, height: number, pixels: ArrayLike<number>): Heightfield
+```
+
## imageBitmapOptions — function @experimental
```
(flip: boolean): ImageBitmapOptions
@@ -13093,6 +13326,11 @@ LifecyclePlugin
LocalizationPlugin
```
+## lodCount — function @experimental
+```
+(shape: TerrainShape, wanted?: number): number
+```
+
## log — const @experimental
```
Logger
@@ -13258,6 +13496,11 @@ MeshRendererPlugin
(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId" | "screenFit" | "aot" | "debugChannel">): { physicsEnabled?: boolean; physicsConfig?: Physics2DPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; screenFit?: PackagedGameConfig["screenFit"]; aot?: PackagedGameConfig["aot"]; debugChannel?: DebugChannelConfig; }
```
+## paintWeights — function @experimental
+```
+(h: number, ny: number, t: Pick<TerrainData, "rockSlope" | "dirtHeight" | "snowHeight">): [number, number, number, number]
+```
+
## panoramaDirection — function @experimental
```
(u: number, v: number): [number, number, number]
@@ -13548,6 +13791,11 @@ PrefabsPlugin
(register: () => Promise<void>): Promise<ProbedRegistrations>
```
+## proceduralHeightfield — function @experimental
+```
+(p: ProceduralParams): Heightfield
+```
+
## projectSideModuleIds — function @experimental
```
(): string[]
@@ -13863,6 +14111,11 @@ PrefabsPlugin
(base: "dark" | "light", overrides?: ThemeOverrides): ThemeTokens
```
+## rng — function @experimental
+```
+(seed: number): () => number
+```
+
## rotateVec3ByQuat — function @experimental
```
(rot: Quat, v: Vec3): Vec3
@@ -13883,6 +14136,11 @@ PrefabsPlugin
SafeAreaPlugin
```
+## sampleHeight — function @experimental
+```
+(field: Heightfield, u: number, v: number): number
+```
+
## sampleKeyframes — function @experimental
```
(keys: readonly Keyframe[], at: number): number
@@ -13908,6 +14166,11 @@ SafeAreaPlugin
{ readonly clamp: (x: number, min: number, max: number) => number; readonly clamp01: (x: number) => number; readonly lerp: (a: number, b: number, t: number) => number; readonly inverseLerp: (a: number, b: number, value: number) => number; readonly remap: (value: number, inMin: number, inMax: number, outMin: number, outMax: number) => number; readonly deg2rad: (deg: number) => number; readonly rad2deg: (rad: number) => number; readonly approximately: (a: number, b: number, epsilon?: number) => boolean; readonly smoothstep: (edge0: number, edge1: number, x: number) => number; readonly mod: (x: number, n: number) => number; readonly sign: (x: number) => number; }
```
+## scatterCell — function @experimental
+```
+(p: ScatterParams, ground: Ground): Plant[]
+```
+
## sceneAmbientLights — function @experimental
```
(entities: readonly EnvironmentLightEntity[], exists: (ref: string) => boolean): SceneAmbientLight[]
@@ -14363,6 +14626,16 @@ StatsPlugin
(ctx?: CensusContext): Census
```
+## terrainNormal — function @experimental
+```
+(field: Heightfield, u: number, v: number, sizeX: number, sizeZ: number, heightScale: number): [number, number, number]
+```
+
+## terrainPlugin — const @experimental
+```
+Plugin
+```
+
## textInputPlugin — const @experimental
```
TextInputPlugin
diff --git a/sdk/package.json b/sdk/package.json
index 474d8f581..2947b47fc 100644
--- a/sdk/package.json
+++ b/sdk/package.json
@@ -18,6 +18,7 @@
"./dist/spine/index.js",
"./dist/tilemap/index.js",
"./dist/terrain/index.js",
+ "./dist/timeline/index.js",
"./dist/foliage/index.js",
"./dist/logic/index.js",
"./dist/debug-channel/index.js",
@@ -73,6 +74,10 @@
"import": "./dist/tilemap/index.js",
"types": "./dist/tilemap/index.d.ts"
},
+ "./timeline": {
+ "import": "./dist/timeline/index.js",
+ "types": "./dist/timeline/index.d.ts"
+ },
"./terrain": {
"import": "./dist/terrain/index.js",
"types": "./dist/terrain/index.d.ts"
diff --git a/sdk/rolldown.config.js b/sdk/rolldown.config.js
index ce2b14fb8..dbc3f63b4 100644
--- a/sdk/rolldown.config.js
+++ b/sdk/rolldown.config.js
@@ -98,6 +98,7 @@ export default defineConfig([
'spine/index': 'src/spine/index.ts',
'tilemap/index': 'src/tilemap/index.ts',
'terrain/index': 'src/terrain/index.ts',
+ 'timeline/index': 'src/timeline/entry.ts',
'foliage/index': 'src/foliage/index.ts',
'logic/index': 'src/logic/index.ts',
'debug-channel/index': 'src/debug-channel/index.ts',
diff --git a/sdk/src/app/pluginSets.ts b/sdk/src/app/pluginSets.ts
index d5b1bd275..1a1160b63 100644
--- a/sdk/src/app/pluginSets.ts
+++ b/sdk/src/app/pluginSets.ts
@@ -29,7 +29,6 @@ import { trailPlugin } from '../trail';
import { meshRendererPlugin } from '../render/meshRenderer';
import { staticBatchPlugin } from '../render/staticBatchPlugin';
import { postProcessPlugin } from '../postprocess';
-import { timelinePlugin } from '../timeline';
import { timerPlugin } from '../ecs/timer';
import { velocityPlugin } from '../velocity';
import { lifecyclePlugin } from '../ecs/lifecycle';
@@ -58,7 +57,7 @@ export const simulationBasePlugins = (): Plugin[] => [
/** What exists to be seen. Every entry drives the engine through `engineApi`. */
export const presentationBasePlugins = (): Plugin[] => [
animationPlugin, videoPlugin, particlePlugin, trailPlugin, meshRendererPlugin, staticBatchPlugin,
- postProcessPlugin, timelinePlugin,
+ postProcessPlugin,
];
/**
@@ -94,7 +93,7 @@ export function inBuildOrder(plugins: readonly Plugin[]): Plugin[] {
export const webBasePlugins = (): Plugin[] => [
diagnosticsPlugin,
timerPlugin, velocityPlugin, lifecyclePlugin, animationPlugin, audioPlugin, videoPlugin,
- particlePlugin, trailPlugin, meshRendererPlugin, staticBatchPlugin, postProcessPlugin, timelinePlugin,
+ particlePlugin, trailPlugin, meshRendererPlugin, staticBatchPlugin, postProcessPlugin,
eventBindingPlugin,
servicesPlugin,
];
diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.ts
index ad3412cfa..8b33bd06b 100644
--- a/sdk/src/asset/Assets.ts
+++ b/sdk/src/asset/Assets.ts
@@ -44,7 +44,6 @@ import { ProbeVolumeAssetLoader } from './loaders/ProbeVolumeAssetLoader';
import { FontAssetLoader } from './loaders/FontAssetLoader';
import { AudioAssetLoader } from './loaders/AudioAssetLoader';
import { AnimClipAssetLoader } from './loaders/AnimClipAssetLoader';
-import { TimelineAssetLoader } from './loaders/TimelineAssetLoader';
import { PrefabAssetLoader } from './loaders/PrefabAssetLoader';
import { AnimatorControllerAssetLoader } from './loaders/AnimatorControllerAssetLoader';
import { AvatarAssetLoader } from './loaders/AvatarAssetLoader';
@@ -2643,7 +2642,6 @@ export class Assets {
// invalidate have no LoadContext), so it shares Assets' lazy accessor.
this.register(new AudioAssetLoader(() => this.getAudio_()));
this.register(new AnimClipAssetLoader());
- this.register(new TimelineAssetLoader());
this.register(new PrefabAssetLoader());
// A recipe is bound to an exact era, just like a resolved material.
// Use the same pending cache, generation ledger and dependency graph.
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index 284d860b1..a26a09bac 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -779,7 +779,25 @@ export {
StaticBatch, StaticBatching, StaticBatchingRes, StaticBatchPlugin, staticBatchPlugin,
StaticBatchState, type StaticBatchData, type StaticBatchSummary,
} from './render/staticBatchPlugin';
-// Terrain and Foliage are optional modules: `esengine/terrain` and `esengine/foliage`.
+// Terrain and Foliage are optional modules (`esengine/terrain`, `esengine/foliage` install them). Their API stays reachable from
+// here: a shared chunk is side-effect-free, so what nothing uses is not bundled.
+export {
+ Terrain, Terrains, TerrainsRes, TerrainPlugin, terrainPlugin, paintWeights, type TerrainData,
+} from './terrain/terrainPlugin';
+export {
+ Foliage, FoliageField, FoliageRes, FoliagePlugin, foliagePlugin, type FoliageData,
+} from './foliage/foliagePlugin';
+export {
+ scatterCell, buildGrassMesh, buildInstancedMesh, buildBillboardMesh, rng,
+ type Plant, type Ground, type ScatterParams, type BladeParams, type CardRect,
+} from './foliage/builder';
+export {
+ heightfieldFromPixels, proceduralHeightfield, sampleHeight, terrainNormal,
+ type Heightfield, type ProceduralParams,
+} from './terrain/heightfield';
+export {
+ buildChunkMesh, cellsAtLod, chunkCenter, lodCount, type TerrainShape, type TerrainPaint,
+} from './terrain/mesh';
export {
mergeMeshes, planStaticBatches, STATIC_BATCH_DEFAULTS,
type StaticBatchGroup, type StaticBatchLimits, type StaticBatchRefusal, type StaticBatchReport,
diff --git a/sdk/src/platform/nativeModuleRegistry.ts b/sdk/src/platform/nativeModuleRegistry.ts
index f6c4d9e9c..400e22aa9 100644
--- a/sdk/src/platform/nativeModuleRegistry.ts
+++ b/sdk/src/platform/nativeModuleRegistry.ts
@@ -25,6 +25,7 @@ import * as SpineModule from '../spine';
import * as DragonBonesModule from '../dragonbones';
import * as TilemapModule from '../tilemap';
import * as TerrainModule from '../terrain';
+import * as TimelineModule from '../timeline/entry';
import * as FoliageModule from '../foliage';
import * as ScriptGraphModule from '../logic';
import * as AiModule from '../ai';
@@ -46,6 +47,7 @@ export const NATIVE_MODULE_NAMESPACES: Readonly<Record<string, unknown>> = {
'esengine/dragonbones': DragonBonesModule,
'esengine/tilemap': TilemapModule,
'esengine/terrain': TerrainModule,
+ 'esengine/timeline': TimelineModule,
'esengine/foliage': FoliageModule,
'esengine/logic': ScriptGraphModule,
'esengine/ai': AiModule,
diff --git a/sdk/src/runtime/optionalPlugins.ts b/sdk/src/runtime/optionalPlugins.ts
index 86c8ef5cf..c94ea73dc 100644
--- a/sdk/src/runtime/optionalPlugins.ts
+++ b/sdk/src/runtime/optionalPlugins.ts
@@ -20,6 +20,7 @@ import { registerDragonBonesSupport } from '../dragonbones/dragonBonesSupport';
import { registerPhysics2DSupport } from '../physics/physicsSupport';
import { registerPhysics3DSupport } from '../physics3d/physics3dSupport';
import { registerTilemapSupport } from '../tilemap/tilemapSupport';
+import { registerTimelineSupport } from '../timeline/timelineSupport';
import { registerTerrainSupport } from '../terrain/terrainSupport';
import { registerFoliageSupport } from '../foliage/foliageSupport';
import { registerScriptGraphSupport } from '../logic/logicSupport';
@@ -34,6 +35,7 @@ export function installOptionalPlugins(): void {
registerPhysics2DSupport();
registerPhysics3DSupport();
registerTilemapSupport();
+ registerTimelineSupport();
registerTerrainSupport();
registerFoliageSupport();
registerScriptGraphSupport();
diff --git a/sdk/src/timeline/entry.ts b/sdk/src/timeline/entry.ts
new file mode 100644
index 000000000..35b868e08
--- /dev/null
+++ b/sdk/src/timeline/entry.ts
@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * The `esengine/timeline` subpath: the public timeline API, and importing it INSTALLS timelines — see tilemap/index.ts.
+ * Named, not `export *`: `./index` also carries what the module keeps to itself.
+ */
+export {
+ TimelinePlugin,
+ timelinePlugin,
+ parseTimelineAsset,
+ Timeline,
+ TimelineAPI,
+ TimelinePlayer,
+ TIMELINE_MOTION,
+ createTimelineMotionDriver,
+ type TimelinePlayerData,
+} from './index';
+export {
+ sampleTimeline, sampleTimelineInWorld, evaluateChannel, applyWrapMode,
+ serializeTimelineAsset, serializeTimelineToJson, resolveChildEntity, parseAnimationClip,
+ TrackType, InterpType, WrapMode, TIMELINE_FORMAT_VERSION,
+ isRootPlacementChannel, sampleRootPlacement, createRootPlacement,
+ playheadRuns, runCrosses, collectCustomEvents,
+ type RootPlacement, type PlayheadRun,
+ type CustomEvent, type CustomEventTrack,
+ type SampleWorld, type SampleDeps, type SampleOptions,
+ type TimelineAsset, type Track, type PropertyTrack, type PropertyChannel, type Keyframe,
+ type SpriteAnimTrack, type AudioTrack, type ActivationTrack, type SpineTrack, type AnimFramesTrack,
+ type CameraClip, type CameraTrack, type SequenceClip, type SequenceTrack,
+ MAX_SEQUENCE_DEPTH, collectSequenceLayers, wouldNestCycle, resolveShot, resolveActiveShot,
+ type SequenceLayer, type SequenceLookup, type ShotState, type ActiveShot,
+} from './index';
+
+import { registerTimelineSupport } from './timelineSupport';
+
+registerTimelineSupport();
diff --git a/sdk/src/timeline/timelineSupport.ts b/sdk/src/timeline/timelineSupport.ts
new file mode 100644
index 000000000..3956943e0
--- /dev/null
+++ b/sdk/src/timeline/timelineSupport.ts
@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file timelineSupport.ts — what a build that ships timelines tells the core.
+ *
+ * A call, not a file's side effect — see tilemap/tilemapSupport.ts. The plugin an app installs, and the loader
+ * that reads a `.estimeline`: the asset layer no longer constructs it for every package.
+ */
+import { addEntryPlugin } from '../runtime/entryPlugins';
+import { addAssetLoader } from '../asset/optionalLoaders';
+import { TimelinePlugin } from './TimelinePlugin';
+import { TimelineAssetLoader } from '../asset/loaders/TimelineAssetLoader';
+
+export function registerTimelineSupport(): void {
+ addEntryPlugin('timeline', () => new TimelinePlugin());
+ addAssetLoader('timeline', () => new TimelineAssetLoader() as never);
+}
diff --git a/sdk/tests/realm-registry-isolation.test.ts b/sdk/tests/realm-registry-isolation.test.ts
index f896cb00d..9ddea8ae0 100644
--- a/sdk/tests/realm-registry-isolation.test.ts
+++ b/sdk/tests/realm-registry-isolation.test.ts
@@ -18,6 +18,10 @@ import { Catalog } from '../src/asset/Catalog';
import { Assets as AssetsResource } from '../src/asset/AssetPlugin';
import { fsmTouches } from '../src/ai/fsm/FsmPlugin';
import { btTouches } from '../src/ai/bt/BtPlugin';
+import { registerTimelineSupport } from '../src/timeline/timelineSupport';
+
+// Timelines are an optional module: a package that plays one has registered it.
+registerTimelineSupport();
import { StateMachineAgent, clearFsmStore, registerFsm,
type StateMachineAgentData } from '../src/ai/fsm/StateMachineAgent';
import { FsmPlugin, stepStateMachines } from '../src/ai/fsm/FsmPlugin';
diff --git a/tools/lib/sdkProgram.mjs b/tools/lib/sdkProgram.mjs
index 8a508529d..2b50bb211 100644
--- a/tools/lib/sdkProgram.mjs
+++ b/tools/lib/sdkProgram.mjs
@@ -60,6 +60,7 @@ export const ENTRIES = {
'dragonbones': 'src/dragonbones/index.ts',
'tilemap': 'src/tilemap/index.ts',
'terrain': 'src/terrain/index.ts',
+ 'timeline': 'src/timeline/entry.ts',
'foliage': 'src/foliage/index.ts',
'logic': 'src/logic/index.ts',
'debug-channel': 'src/debug-channel/index.ts',
diff --git a/tools/nativeScriptModules.js b/tools/nativeScriptModules.js
index f47669b66..26ee1a682 100644
--- a/tools/nativeScriptModules.js
+++ b/tools/nativeScriptModules.js
@@ -66,6 +66,7 @@ export const MODULES = {
'esengine/dragonbones': { disposition: 'native-subpath' },
'esengine/tilemap': { disposition: 'native-subpath' },
'esengine/terrain': { disposition: 'native-subpath' },
+ 'esengine/timeline': { disposition: 'native-subpath' },
'esengine/foliage': { disposition: 'native-subpath' },
'esengine/logic': { disposition: 'native-subpath' },
'esengine/ai': { disposition: 'native-subpath' },
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 437d44db4..e20d96138 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -2529,6 +2529,8 @@ export const NOTED = {
{"internal":"art source and review images of an in-development game under games/, which no creator using the engine or editor can observe"},
"feat(sdk): terrain and foliage are optional modules, so a package carries them only when its content does":
{"note":"Terrain and Foliage are now optional modules, esengine/terrain and esengine/foliage: a package carries them when a scene has a Terrain or Foliage component or a script imports the subpath, and a game with neither ships none of them (about 33 KB less in a UI-only mini-game)."},
+ "feat(sdk): timelines are an optional module, installed by a TimelinePlayer or an .estimeline":
+ {"note":"Timelines are now an optional module, esengine/timeline: a package carries the timeline runtime and its loader when a scene has a TimelinePlayer, the content has an .estimeline, or a script imports the subpath, and a game with none of them ships neither."},
"chore(tools): the gates run in parallel with --jobs, and the reds a full run gathered are cleared":
{"internal":"tooling for the static gates, and fixes to checks that had drifted from the code they guard"},
"fix(render): a wire narrower than a pixel is no longer painted over by the sky in dashes":