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.

fix(app): build order is declared, not the shape of an array

esengined5979fe9af31
diff --git a/sdk/etc/ai.api.md b/sdk/etc/ai.api.md
new file mode 100644
index 000000000..18108cec4
--- /dev/null
+++ b/sdk/etc/ai.api.md
@@ -0,0 +1,1073 @@
+# API surface — esengine/ai
+
+<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
+Symbols: 0 public · 0 beta · 159 experimental · 0 deprecated
+
+## AiAction — type @experimental
+```
+(
+ ctx: Ctx,
+ bb: Blackboard,
+ arg?: string,
+ params?: AiParams,
+ out?: AiOutputs,
+) => void | Status
+```
+
+## AiActionInput — interface @experimental
+```
+arg: string | undefined
+params: Readonly<Record<string, AiParamValue>> | undefined
+```
+
+## AiActionSpec — interface @experimental
+```
+outputs: readonly AiOutputDef[] | undefined
+params: readonly AiParamDef[] | undefined
+pure: boolean | undefined
+run: AiAction<Ctx>
+separator: string | undefined
+touches: AiTouchesSource | undefined
+```
+
+## AiBt — const @experimental
+```
+ResourceDef<BehaviorTrees>
+```
+
+## AiCondition — type @experimental
+```
+(ctx: Ctx, bb: Blackboard) => boolean
+```
+
+## AiContext — interface @experimental
+```
+blackboard: Blackboard
+commands: CommandsInstance
+dt: number
+entity: number
+get: <C extends AnyComponentDef>(component: C) => ComponentData<C>
+has: (component: AnyComponentDef) => boolean
+input: InputState
+set: <C extends AnyComponentDef>(component: C, data: ComponentData<C>) => void
+world: World
+```
+
+## AiFsm — const @experimental
+```
+ResourceDef<StateMachines>
+```
+
+## AiOutputDef — interface @experimental
+```
+label: string | undefined
+name: string
+tooltip: string | undefined
+type: "string" | "number" | "bool" | "entity"
+```
+
+## AiOutputs — type @experimental
+```
+Record<string, AiParamValue>
+```
+
+## AiParamDef — interface @experimental
+```
+label: string | undefined
+max: number | undefined
+min: number | undefined
+name: string
+options: readonly { label: string; value: string; }[] | undefined
+optionsSource: string | undefined
+step: number | undefined
+tooltip: string | undefined
+type: "string" | "number" | "bool" | "enum"
+```
+
+## AiParamValue — type @experimental
+```
+string | number | boolean
+```
+
+## AiParams — type @experimental
+```
+Readonly<Record<string, AiParamValue>>
+```
+
+## AiRegistry — class @experimental
+```
+actionNames: () => string[]
+actionTouches: (name: string, input?: AiActionInput) => AiTouches | undefined
+clear: () => void
+conditionNames: () => string[]
+conditionTouches: (name: string) => AiTouches | undefined
+getAction: (name: string) => AiAction<Ctx> | undefined
+getActionOutputs: (name: string) => readonly AiOutputDef[]
+getActionParams: (name: string) => readonly AiParamDef[]
+getActionSeparator: (name: string) => string
+getCondition: (name: string) => AiCondition<Ctx> | undefined
+hasAction: (name: string) => boolean
+hasCondition: (name: string) => boolean
+isActionPure: (name: string) => boolean
+registerAction: (name: string, fn: AiAction<Ctx> | AiActionSpec<Ctx>) => void
+registerCondition: (name: string, fn: AiCondition<Ctx> | AiConditionSpec<Ctx>) => void
+registerValue: (name: string, spec: AiValueSpec<Ctx>) => void
+static new <Ctx = unknown>(): AiRegistry<Ctx>
+static prototype: AiRegistry<any>
+```
+
+## AiTouches — interface @experimental
+```
+opaque: boolean | undefined
+reads: readonly string[] | undefined
+writes: readonly string[] | undefined
+```
+
+## AiValueSpec — interface @experimental
+```
+evaluate: (ctx: Ctx, bb: Blackboard, params: AiParams, out: AiOutputs) => void
+outputs: readonly AiOutputDef[]
+params: readonly AiParamDef[] | undefined
+touches: AiTouches | undefined
+```
+
+## AiWorldView — interface @experimental
+```
+get: <C extends AnyComponentDef>(entity: Entity, component: C) => ComponentData<C>
+getEntitiesWithComponents: (components: readonly AnyComponentDef[]) => readonly Entity[]
+has: (entity: Entity, component: AnyComponentDef) => boolean
+set: <C extends AnyComponentDef>(entity: Entity, component: C, data: ComponentData<C>) => void
+```
+
+## BehaviorTreeAgent — const @experimental
+```
+ComponentDef<BehaviorTreeAgentData>
+```
+
+## BehaviorTreeAgentData — interface @experimental
+```
+bt: string
+status: string
+```
+
+## BehaviorTrees — class @experimental
+```
+blackboard: (entity: Entity) => Blackboard
+status: (entity: Entity) => string | null
+static new (states: Map<Entity, BtAgentState>): BehaviorTrees
+static prototype: BehaviorTrees
+```
+
+## Blackboard — class @experimental
+```
+clearTriggers: () => void
+consume: (trigger: string) => void
+delete: (key: string) => void
+fire: (trigger: string) => void
+get: <T = unknown>(key: string) => T | undefined
+has: (key: string) => boolean
+isFired: (trigger: string) => boolean
+set: (key: string, value: unknown) => void
+static new (): Blackboard
+static prototype: Blackboard
+```
+
+## BlackboardGuard — interface @experimental
+```
+key: string
+op: CompareOp
+value: string | number | boolean | undefined
+```
+
+## BtDefinition — interface @experimental
+```
+orphans: BtNode[] | undefined
+root: BtNode
+```
+
+## BtEdge — interface @experimental
+```
+from: string
+id: string
+to: string
+```
+
+## BtNode — interface @experimental
+```
+arg: string | undefined
+children: BtNode[] | undefined
+count: number | undefined
+id: string | undefined
+name: string | undefined
+params: Record<string, AiParamValue> | undefined
+policy: "all" | "one" | undefined
+seconds: number | undefined
+type: BtNodeType
+x: number | undefined
+y: number | undefined
+```
+
+## BtNodeType — type @experimental
+```
+| 'sequence' | 'selector' | 'parallel'
+ // decorators (one child)
+ | 'inverter' | 'succeeder' | 'repeater' | 'wait'
+ // leaves
+ | 'action' | 'condition'
+```
+
+## BtPlugin — class @experimental
+```
+build: (app: App) => void
+name: string
+static new (): BtPlugin
+static prototype: BtPlugin
+```
+
+## BtRunState — type @experimental
+```
+Map<string, NodeState>
+```
+
+## BuildNavMeshOptions — interface @experimental
+```
+agentHeight: number | undefined
+agentRadius: number | undefined
+areas: readonly NavAreaBox[] | undefined
+cellHeight: number
+cellSize: number
+links: readonly NavLinkSegment[] | undefined
+max: Vec3
+maxEdgeLength: number | undefined
+maxSimplificationError: number | undefined
+maxSlopeDegrees: number | undefined
+maxVertsPerPoly: number | undefined
+min: Vec3
+minRegionArea: number | undefined
+obstacles: readonly NavObstacleBox[] | undefined
+stepHeight: number | undefined
+```
+
+## Cell — interface @experimental
+```
+x: number
+y: number
+```
+
+## CollectNavGeometryOptions — interface @experimental
+```
+layers: number | undefined
+max: Vec3
+min: Vec3
+```
+
+## CompareOp — type @experimental
+```
+'==' | '!=' | '<' | '<=' | '>' | '>=' | 'truthy' | 'falsy'
+```
+
+## CompiledFsm — interface @experimental
+```
+initial: string
+states: Map<string, FsmState>
+```
+
+## FIRST_AREA — const @experimental
+```
+2
+```
+
+## FacingAxis — type @experimental
+```
+'x' | '-z'
+```
+
+## FsmActionRef — type @experimental
+```
+string | { name: string; arg?: string; params?: Record<string, AiParamValue> }
+```
+
+## FsmDefinition — interface @experimental
+```
+initial: string
+states: FsmState[]
+```
+
+## FsmEdge — type @experimental
+```
+from: string
+id: string
+index: number
+to: string
+transition: FsmTransition
+```
+
+## FsmPlugin — class @experimental
+```
+build: (app: App) => void
+name: string
+static new (): FsmPlugin
+static prototype: FsmPlugin
+```
+
+## FsmRunState — interface @experimental
+```
+current: string
+entered: boolean
+previous: string | null
+```
+
+## FsmState — interface @experimental
+```
+name: string
+onEnter: FsmActionRef | undefined
+onExit: FsmActionRef | undefined
+onUpdate: FsmActionRef | undefined
+transitions: FsmTransition[] | undefined
+x: number | undefined
+y: number | undefined
+```
+
+## FsmTransition — interface @experimental
+```
+condition: string | undefined
+guard: BlackboardGuard | BlackboardGuard[] | undefined
+to: string
+trigger: string | undefined
+```
+
+## FsmWorldView — interface @experimental
+```
+get: <C extends AnyComponentDef>(entity: Entity, component: C) => ComponentData<C>
+getEntitiesWithComponents: (components: readonly AnyComponentDef[]) => readonly Entity[]
+has: (entity: Entity, component: AnyComponentDef) => boolean
+set: <C extends AnyComponentDef>(entity: Entity, component: C, data: ComponentData<C>) => void
+```
+
+## LosCheck — type @experimental
+```
+(
+ from: Vec3, to: Vec3,
+ observer: Entity, target: Entity,
+ layers: number,
+) => boolean
+```
+
+## Nav — const @experimental
+```
+ResourceDef<Navigation>
+```
+
+## NavAgent — const @experimental
+```
+ComponentDef<NavAgentData>
+```
+
+## NavAgentData — interface @experimental
+```
+arriveRadius: number
+arrived: boolean
+hasTarget: boolean
+radius: number
+repathInterval: number
+speed: number
+targetX: number
+targetY: number
+targetZ: number
+```
+
+## NavArea — const @experimental
+```
+ComponentDef<NavAreaData>
+```
+
+## NavAreaBox — interface @experimental
+```
+area: number
+center: Vec3
+halfExtents: Vec3
+rotation: Quat
+```
+
+## NavAreaData — interface @experimental
+```
+cost: number
+enabled: boolean
+halfExtents: Vec3
+```
+
+## NavDebugDraw — const @experimental
+```
+ResourceDef<NavDebugDrawConfig>
+```
+
+## NavDebugDrawConfig — interface @experimental
+```
+enabled: boolean
+showBorders: boolean
+showFaces: boolean
+showLinks: boolean
+```
+
+## NavGeometry — interface @experimental
+```
+bodyCount: number
+indices: Uint32Array<ArrayBufferLike>
+verts: Float32Array<ArrayBufferLike>
+```
+
+## NavGrid — class @experimental
+```
+cellSize: number
+cellToWorld: (gx: number, gy: number) => Vec3
+clearCosts: () => void
+clearObstructions: () => void
+clearanceAt: (gx: number, gy: number) => number
+costAt: (gx: number, gy: number) => number
+describe: (sink: NavSurfaceSink) => void
+findWorldPath: (from: NavPoint, to: NavPoint, opts?: NavQueryOptions) => Vec3[] | null
+height: number
+inBounds: (gx: number, gy: number) => boolean
+index: (gx: number, gy: number) => number
+isNavigable: (p: NavPoint) => boolean
+isWalkable: (gx: number, gy: number) => boolean
+nearestWalkable: (gx: number, gy: number, maxRadius?: number, clearance?: number) => Cell | null
+originX: number
+originY: number
+originZ: number
+setCost: (gx: number, gy: number, cost: number) => void
+setObstructed: (gx: number, gy: number, obstructed: boolean) => void
+setWalkable: (gx: number, gy: number, walkable: boolean) => void
+up: Vec3
+walkable: Uint8Array<ArrayBufferLike>
+width: number
+worldToCell: (p: NavPoint) => Cell
+static new (opts: NavGridOptions): NavGrid
+static prototype: NavGrid
+```
+
+## NavGridOptions — interface @experimental
+```
+cellSize: number
+height: number
+origin: { x: number; y: number; z?: number; } | undefined
+walkable: ArrayLike<number> | undefined
+width: number
+```
+
+## NavLink — const @experimental
+```
+ComponentDef<NavLinkData>
+```
+
+## NavLinkData — interface @experimental
+```
+bidirectional: boolean
+enabled: boolean
+end: Vec3
+radius: number
+start: Vec3
+```
+
+## NavLinkSegment — interface @experimental
+```
+bidirectional: boolean
+end: Vec3
+radius: number
+start: Vec3
+```
+
+## NavMesh — class @experimental
+```
+agentRadius: number
+areas: Uint8Array<ArrayBufferLike>
+connect: (segments: readonly NavLinkSegment[]) => void
+contains: (p: number, x: number, z: number) => boolean
+corner: (p: number, i: number, out: Vec3) => Vec3
+costOf: (p: number) => number
+describe: (sink: NavSurfaceSink) => void
+findPoly: (p: NavPoint, out?: Vec3, snap?: number) => number
+findWorldPath: (from: NavPoint, to: NavPoint, opts?: NavQueryOptions) => Vec3[] | null
+heightAt: (p: number, x: number, z: number) => number
+isNavigable: (p: NavPoint) => boolean
+linkCount: number
+maxVertsPerPoly: number
+neis: Int32Array<ArrayBufferLike>
+polyCount: number
+polys: Int32Array<ArrayBufferLike>
+setAreaCost: (area: number, cost: number) => void
+snapDistance: number
+up: Vec3
+vertexCount: (p: number) => number
+verticalReach: number
+verts: Float32Array<ArrayBufferLike>
+static new (data: NavMeshData): NavMesh
+static prototype: NavMesh
+```
+
+## NavMeshData — interface @experimental
+```
+agentRadius: number
+areas: Uint8Array<ArrayBufferLike>
+maxVertsPerPoly: number
+neis: Int32Array<ArrayBufferLike>
+polyCount: number
+polys: Int32Array<ArrayBufferLike>
+snapDistance: number
+verticalReach: number
+verts: Float32Array<ArrayBufferLike>
+```
+
+## NavObstacle — const @experimental
+```
+ComponentDef<NavObstacleData>
+```
+
+## NavObstacleBox — interface @experimental
+```
+center: Vec3
+halfExtents: Vec3
+rotation: Quat
+```
+
+## NavObstacleData — interface @experimental
+```
+enabled: boolean
+halfExtents: Vec3
+```
+
+## NavPlugin — class @experimental
+```
+build: (app: App) => void
+name: string
+static new (): NavPlugin
+static prototype: NavPlugin
+```
+
+## NavPoint — interface @experimental
+```
+x: number
+y: number
+z: number | undefined
+```
+
+## NavQueryOptions — interface @experimental
+```
+radius: number | undefined
+```
+
+## NavSurface — interface @experimental
+```
+describe: (sink: NavSurfaceSink) => void
+findWorldPath: (from: NavPoint, to: NavPoint, opts?: NavQueryOptions) => Vec3[] | null
+isNavigable: (p: NavPoint) => boolean
+up: Vec3
+```
+
+## NavSurfaceSink — interface @experimental
+```
+border: (a: Vec3, b: Vec3) => void
+face: (corners: readonly Vec3[]) => void
+link: (a: Vec3, b: Vec3) => void
+```
+
+## NavVolume — const @experimental
+```
+ComponentDef<NavVolumeData>
+```
+
+## NavVolumeData — interface @experimental
+```
+agentHeight: number
+agentRadius: number
+cellHeight: number
+cellSize: number
+halfExtents: Vec3
+layers: number
+maxSlopeDegrees: number
+stepHeight: number
+```
+
+## Navigation — class @experimental
+```
+findWorldPath: (from: NavPoint, to: NavPoint, opts?: NavQueryOptions) => Vec3[] | null
+hasSurface: () => boolean
+setSurface: (surface: NavSurface | null) => void
+surface: NavSurface | null
+static new (): Navigation
+static prototype: Navigation
+```
+
+## PathfindOptions — interface @experimental
+```
+clearance: number | undefined
+diagonal: boolean | undefined
+snapRadius: number | undefined
+```
+
+## Perceiver — const @experimental
+```
+ComponentDef<PerceiverData>
+```
+
+## PerceiverData — interface @experimental
+```
+facingAxis: FacingAxis
+fovDegrees: number
+losLayers: number
+range: number
+```
+
+## Perception — const @experimental
+```
+ComponentDef<PerceptionData>
+```
+
+## PerceptionData — interface @experimental
+```
+dirX: number
+dirY: number
+dirZ: number
+distance: number
+targetX: number
+targetY: number
+targetZ: number
+visible: boolean
+```
+
+## PerceptionPlugin — class @experimental
+```
+build: (app: App) => void
+name: string
+static new (): PerceptionPlugin
+static prototype: PerceptionPlugin
+```
+
+## PerceptionTarget — const @experimental
+```
+ComponentDef<{}>
+```
+
+## PerceptionWorldView — interface @experimental
+```
+get: <C extends AnyComponentDef>(entity: Entity, component: C) => ComponentData<C>
+getEntitiesWithComponents: (components: readonly AnyComponentDef[]) => readonly Entity[]
+has: (entity: Entity, component: AnyComponentDef) => boolean
+insert: <C extends AnyComponentDef>(entity: Entity, component: C, data?: Partial<ComponentData<C>>) => unknown
+set: <C extends AnyComponentDef>(entity: Entity, component: C, data: ComponentData<C>) => void
+```
+
+## SenseResult — interface @experimental
+```
+dir: Vec3
+distance: number
+visible: boolean
+```
+
+## StateMachineAgent — const @experimental
+```
+ComponentDef<StateMachineAgentData>
+```
+
+## StateMachineAgentData — interface @experimental
+```
+current: string
+fsm: string
+```
+
+## StateMachines — class @experimental
+```
+blackboard: (entity: Entity) => Blackboard
+fire: (entity: Entity, trigger: string) => void
+state: (entity: Entity) => string | null
+static new (states: Map<Entity, AgentState>): StateMachines
+static prototype: StateMachines
+```
+
+## Status — enum @experimental
+```
+Failure = "failure"
+Running = "running"
+Success = "success"
+```
+
+## actionRefArg — function @experimental
+```
+(ref: FsmActionRef | undefined): string | undefined
+```
+
+## actionRefName — function @experimental
+```
+(ref: FsmActionRef | undefined): string
+```
+
+## actionRefParams — function @experimental
+```
+(ref: FsmActionRef | undefined): Record<string, AiParamValue> | undefined
+```
+
+## addBtChild — function @experimental
+```
+(def: BtDefinition, parentId: string, type: BtNodeType, x?: number, y?: number): BtDefinition
+```
+
+## addBtOrphan — function @experimental
+```
+(def: BtDefinition, type: BtNodeType, x?: number, y?: number): BtDefinition
+```
+
+## addState — function @experimental
+```
+(def: FsmDefinition, name: string, x?: number, y?: number): FsmDefinition
+```
+
+## addTransition — function @experimental
+```
+(def: FsmDefinition, from: string, to: string): FsmDefinition
+```
+
+## agentBlackboard — function @experimental
+```
+(states: Map<Entity, AgentState>, entity: Entity): Blackboard
+```
+
+## agentBtBlackboard — function @experimental
+```
+(states: Map<Entity, BtAgentState>, entity: Entity): Blackboard
+```
+
+## aiRegistry — const @experimental
+```
+AiRegistry<AiContext>
+```
+
+## applyAreasToGrid — function @experimental
+```
+(grid: NavGrid, areas: ReadonlyArray<NavAreaBox & { cost: number; }>): void
+```
+
+## applyObstaclesToGrid — function @experimental
+```
+(grid: NavGrid, obstacles: readonly NavObstacleBox[]): void
+```
+
+## btEdges — function @experimental
+```
+(def: BtDefinition): BtEdge[]
+```
+
+## btNodes — function @experimental
+```
+(def: BtDefinition): BtNode[]
+```
+
+## btPlugin — const @experimental
+```
+BtPlugin
+```
+
+## buildNavMesh — function @experimental
+```
+(verts: Float32Array, indices: ArrayLike<number>, opts: BuildNavMeshOptions): NavMesh
+```
+
+## canHaveChildren — function @experimental
+```
+(type: BtNodeType): boolean
+```
+
+## clearBtStore — function @experimental
+```
+(): void
+```
+
+## clearFsmStore — function @experimental
+```
+(): void
+```
+
+## collectNavAreas — function @experimental
+```
+(world: World): Array<NavAreaBox & { cost: number; }>
+```
+
+## collectNavGeometry — function @experimental
+```
+(world: World, opts: CollectNavGeometryOptions): NavGeometry
+```
+
+## collectNavLinks — function @experimental
+```
+(world: World): NavLinkSegment[]
+```
+
+## collectNavObstacles — function @experimental
+```
+(world: World): NavObstacleBox[]
+```
+
+## compileFsm — function @experimental
+```
+(def: FsmDefinition): CompiledFsm
+```
+
+## createBtRunState — function @experimental
+```
+(): BtRunState
+```
+
+## createFsmRunState — function @experimental
+```
+(fsm: CompiledFsm): FsmRunState
+```
+
+## drawNavDebug — function @experimental
+```
+(surface: NavSurface | null, cfg: NavDebugDrawConfig): void
+```
+
+## emptyBt — function @experimental
+```
+(): BtDefinition
+```
+
+## emptyFsm — function @experimental
+```
+(): FsmDefinition
+```
+
+## ensureBtIds — function @experimental
+```
+(def: BtDefinition): BtDefinition
+```
+
+## ensureBuiltinAiRegistrations — function @experimental
+```
+(): void
+```
+
+## evalGuard — function @experimental
+```
+(bb: Blackboard, guard: BlackboardGuard): boolean
+```
+
+## evalGuards — function @experimental
+```
+(bb: Blackboard, guards: BlackboardGuard | BlackboardGuard[]): boolean
+```
+
+## facingFromRotation — function @experimental
+```
+(rot: Quat, axis?: FacingAxis): Vec3
+```
+
+## findPath — function @experimental
+```
+(grid: NavGrid, start: Cell, goal: Cell, opts?: PathfindOptions): Cell[] | null
+```
+
+## formatActionArg — function @experimental
+```
+(params: Readonly<Record<string, AiParamValue>> | undefined, defs: readonly AiParamDef[], separator?: string): string | undefined
+```
+
+## fsmEdges — function @experimental
+```
+(def: FsmDefinition): FsmEdge[]
+```
+
+## fsmPlugin — const @experimental
+```
+FsmPlugin
+```
+
+## getBt — function @experimental
+```
+(key: string): BtDefinition | undefined
+```
+
+## getFsm — function @experimental
+```
+(key: string): CompiledFsm | undefined
+```
+
+## invokeAction — function @experimental
+```
+<Ctx>(registry: AiRegistry<Ctx>, name: string, ctx: Ctx, bb: Blackboard, input?: AiActionInput, out?: AiOutputs): void | Status
+```
+
+## makeLosCheck — function @experimental
+```
+(physics: Physics2DAPI): LosCheck
+```
+
+## maxChildren — function @experimental
+```
+(type: BtNodeType): number
+```
+
+## moveBtNode — function @experimental
+```
+(def: BtDefinition, id: string, x: number, y: number): BtDefinition
+```
+
+## moveState — function @experimental
+```
+(def: FsmDefinition, name: string, x: number, y: number): FsmDefinition
+```
+
+## navAreaDigest — function @experimental
+```
+(areas: ReadonlyArray<NavAreaBox>): number
+```
+
+## navGeometryReady — function @experimental
+```
+(world: World, layers?: number): boolean
+```
+
+## navLinkDigest — function @experimental
+```
+(links: readonly NavLinkSegment[]): number
+```
+
+## navObstacleDigest — function @experimental
+```
+(obstacles: readonly NavObstacleBox[]): number
+```
+
+## navPlugin — const @experimental
+```
+NavPlugin
+```
+
+## normalizeAngle — function @experimental
+```
+(a: number): number
+```
+
+## parseActionArg — function @experimental
+```
+(arg: string | undefined, params: readonly AiParamDef[], separator?: string): Record<string, AiParamValue>
+```
+
+## pathToWorld — function @experimental
+```
+(grid: NavGrid, path: Cell[]): Vec3[]
+```
+
+## perceptionPlugin — const @experimental
+```
+PerceptionPlugin
+```
+
+## registerAction — function @experimental
+```
+(name: string, fn: AiAction<AiContext> | AiActionSpec<AiContext>): void
+```
+
+## registerBt — function @experimental
+```
+(key: string, def: BtDefinition): BtDefinition
+```
+
+## registerCondition — function @experimental
+```
+(name: string, fn: AiCondition<AiContext>): void
+```
+
+## registerFsm — function @experimental
+```
+(key: string, def: FsmDefinition): CompiledFsm
+```
+
+## registerValue — function @experimental
+```
+(name: string, spec: AiValueSpec<AiContext>): void
+```
+
+## removeBtNode — function @experimental
+```
+(def: BtDefinition, id: string): BtDefinition
+```
+
+## removeState — function @experimental
+```
+(def: FsmDefinition, name: string): FsmDefinition
+```
+
+## removeTransition — function @experimental
+```
+(def: FsmDefinition, from: string, index: number): FsmDefinition
+```
+
+## renameState — function @experimental
+```
+(def: FsmDefinition, oldName: string, newName: string): FsmDefinition
+```
+
+## reparentBtNode — function @experimental
+```
+(def: BtDefinition, id: string, newParentId: string): BtDefinition
+```
+
+## senseTarget — function @experimental
+```
+(observer: Vec3, facing: Vec3, target: Vec3, range: number, halfFov: number, isBlocked?: (from: Vec3, to: Vec3) => boolean): SenseResult
+```
+
+## setBtNodeField — function @experimental
+```
+(def: BtDefinition, id: string, patch: Partial<BtNode>): BtDefinition
+```
+
+## setInitial — function @experimental
+```
+(def: FsmDefinition, name: string): FsmDefinition
+```
+
+## setNavDestination — function @experimental
+```
+(world: World, entity: Entity, target: { x: number; y: number; z?: number; }): void
+```
+
+## setStateHook — function @experimental
+```
+(def: FsmDefinition, name: string, hook: "onEnter" | "onUpdate" | "onExit", action: string, arg?: string, params?: Record<string, AiParamValue>): FsmDefinition
+```
+
+## stepBehaviorTrees — function @experimental
+```
+(world: AiWorldView, commands: CommandsInstance, dt: number, states: Map<Entity, BtAgentState>, resolveTree?: (ref: string) => BtDefinition | undefined, input?: InputState): void
+```
+
+## stepFsm — function @experimental
+```
+<Ctx>(fsm: CompiledFsm, run: FsmRunState, ctx: Ctx, bb: Blackboard, registry: AiRegistry<Ctx>): boolean
+```
+
+## stepPerception — function @experimental
+```
+(world: PerceptionWorldView, isBlocked?: LosCheck): void
+```
+
+## stepStateMachines — function @experimental
+```
+(world: FsmWorldView, commands: CommandsInstance, dt: number, states: Map<Entity, AgentState>, resolveFsm?: (ref: string) => CompiledFsm | undefined, input?: InputState): void
+```
+
+## stopNavAgent — function @experimental
+```
+(world: World, entity: Entity): void
+```
+
+## tickBt — function @experimental
+```
+<Ctx>(def: BtDefinition, ctx: Ctx, bb: Blackboard, registry: AiRegistry<Ctx>, rs: BtRunState, dt: number): Status
+```
+
+## updateTransition — function @experimental
+```
+(def: FsmDefinition, from: string, index: number, patch: Partial<FsmTransition>): FsmDefinition
+```
+
diff --git a/sdk/etc/logic.api.md b/sdk/etc/logic.api.md
new file mode 100644
index 000000000..8721e6d93
--- /dev/null
+++ b/sdk/etc/logic.api.md
@@ -0,0 +1,437 @@
+# API surface — esengine/logic
+
+<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
+Symbols: 0 public · 0 beta · 72 experimental · 0 deprecated
+
+## AiScriptGraphs — const @experimental
+```
+ResourceDef<ScriptGraphs>
+```
+
+## BUILTIN_NODE_KINDS — const @experimental
+```
+readonly string[]
+```
+
+## CompiledScriptGraph — interface @experimental
+```
+dataSources: Map<string, { node: string; port: string; }>
+destroys: string[]
+events: Map<string, string[]>
+execTargets: Map<string, string>
+graph: ScriptGraph
+inputNode: string | undefined
+nodes: Map<string, ScriptGraphNode>
+outputNode: string | undefined
+prefabs: Map<string, PreparedPrefab>
+problems: string[]
+shapes: Map<string, ScriptNodeShape>
+starts: string[]
+starvedInputs: Map<string, string[]>
+updates: string[]
+```
+
+## DEFAULT_STEP_BUDGET — const @experimental
+```
+4096
+```
+
+## MAX_CALL_DEPTH — const @experimental
+```
+16
+```
+
+## SCRIPT_GRAPH_VERSION — const @experimental
+```
+"1.0"
+```
+
+## ScriptFrame — interface @experimental
+```
+calls: Map<string, ScriptFrame>
+produced: Map<string, Record<string, ScriptValue>>
+timers: Map<string, number>
+vars: Map<string, ScriptValue>
+```
+
+## ScriptGraph — interface @experimental
+```
+edges: ScriptGraphEdge[]
+inputs: ScriptGraphPort[] | undefined
+name: string | undefined
+nodes: ScriptGraphNode[]
+outputs: ScriptGraphPort[] | undefined
+variables: ScriptGraphVariable[] | undefined
+version: string
+```
+
+## ScriptGraphAgent — const @experimental
+```
+ComponentDef<ScriptGraphAgentData>
+```
+
+## ScriptGraphAgentData — interface @experimental
+```
+graph: string
+```
+
+## ScriptGraphEdge — interface @experimental
+```
+from: string
+fromPort: string
+id: string
+to: string
+toPort: string
+```
+
+## ScriptGraphNode — interface @experimental
+```
+id: string
+kind: string
+literals: Record<string, ScriptValue> | undefined
+ref: string | undefined
+x: number | undefined
+y: number | undefined
+```
+
+## ScriptGraphPlugin — class @experimental
+```
+build: (app: App) => void
+name: string
+static new (): ScriptGraphPlugin
+static prototype: ScriptGraphPlugin
+```
+
+## ScriptGraphPort — interface @experimental
+```
+default: ScriptValue | undefined
+label: string | undefined
+name: string
+type: "string" | "number" | "bool" | "entity" | "any"
+```
+
+## ScriptGraphSignature — interface @experimental
+```
+inputs: readonly ScriptGraphPort[]
+outputs: readonly ScriptGraphPort[]
+```
+
+## ScriptGraphVariable — interface @experimental
+```
+default: ScriptValue | undefined
+name: string
+type: "string" | "number" | "bool" | "entity"
+```
+
+## ScriptGraphWorldView — interface @experimental
+```
+get: <C extends AnyComponentDef>(entity: Entity, component: C) => ComponentData<C>
+getEntitiesWithComponents: (components: readonly AnyComponentDef[]) => readonly Entity[]
+has: (entity: Entity, component: AnyComponentDef) => boolean
+set: <C extends AnyComponentDef>(entity: Entity, component: C, data: ComponentData<C>) => void
+```
+
+## ScriptGraphs — class @experimental
+```
+blackboard: (entity: Entity) => Blackboard
+halted: (entity: Entity) => boolean
+setVariable: (entity: Entity, name: string, value: ScriptValue) => void
+variable: (entity: Entity, name: string) => ScriptValue
+static new (states: Map<Entity, AgentState>): ScriptGraphs
+static prototype: ScriptGraphs
+```
+
+## ScriptNodeShape — interface @experimental
+```
+entry: "start" | "event" | "update" | "destroy" | undefined
+execIn: boolean
+execOut: readonly string[]
+inputs: readonly ScriptPort[]
+outputs: readonly ScriptPort[]
+pure: boolean
+```
+
+## ScriptPort — interface @experimental
+```
+label: string | undefined
+name: string
+type: ScriptValueType
+```
+
+## ScriptRunState — interface @experimental
+```
+calls: Map<string, ScriptFrame>
+halted: boolean
+produced: Map<string, Record<string, ScriptValue>>
+reported: Set<string>
+started: boolean
+timers: Map<string, number>
+vars: Map<string, ScriptValue>
+```
+
+## ScriptTickContext — interface @experimental
+```
+bb: Blackboard
+budget: number | undefined
+ctx: Ctx
+dt: number
+onProblem: ((message: string) => void) | undefined
+registry: AiRegistry<Ctx>
+resolveGraph: ((ref: string) => CompiledScriptGraph | undefined) | undefined
+world: World | undefined
+```
+
+## ScriptValue — type @experimental
+```
+boolean | number | string | null
+```
+
+## ScriptValueType — type @experimental
+```
+'exec' | 'bool' | 'number' | 'string' | 'entity' | 'any'
+```
+
+## ScriptVerbCatalog — interface @experimental
+```
+getActionOutputs: (name: string) => readonly AiOutputDef[]
+getActionParams: (name: string) => readonly AiParamDef[]
+graphSignature: (ref: string) => ScriptGraphSignature | null
+hasAction: (name: string) => boolean
+isActionPure: (name: string) => boolean
+```
+
+## THEN — const @experimental
+```
+"then"
+```
+
+## addScriptGraphPort — function @experimental
+```
+(graph: ScriptGraph, side: "inputs" | "outputs", port: ScriptGraphPort): ScriptGraph
+```
+
+## addScriptNode — function @experimental
+```
+(graph: ScriptGraph, kind: string, x: number, y: number, ref?: string): { graph: ScriptGraph; id: string; }
+```
+
+## addScriptVariable — function @experimental
+```
+(graph: ScriptGraph, variable: ScriptGraphVariable): ScriptGraph
+```
+
+## agentGraphBlackboard — function @experimental
+```
+(states: Map<Entity, AgentState>, entity: Entity): Blackboard
+```
+
+## allScriptGraphs — function @experimental
+```
+(): Iterable<CompiledScriptGraph>
+```
+
+## canConnect — function @experimental
+```
+(from: ScriptValueType, to: ScriptValueType): boolean
+```
+
+## canConnectPorts — function @experimental
+```
+(graph: ScriptGraph, catalog: ScriptVerbCatalog, from: string, fromPort: string, to: string, toPort: string): boolean
+```
+
+## clearScriptGraphStore — function @experimental
+```
+(): void
+```
+
+## coerceValue — function @experimental
+```
+(value: ScriptValue, type: ScriptValueType): ScriptValue
+```
+
+## compileAgainstRegistry — function @experimental
+```
+(graph: ScriptGraph, signatures?: ReadonlyMap<string, ScriptGraphSignature>): CompiledScriptGraph
+```
+
+## compileScriptGraph — function @experimental
+```
+(graph: ScriptGraph, catalog: ScriptVerbCatalog): CompiledScriptGraph
+```
+
+## connectScriptNodes — function @experimental
+```
+(graph: ScriptGraph, catalog: ScriptVerbCatalog, from: string, fromPort: string, to: string, toPort: string): ScriptGraph
+```
+
+## createScriptRunState — function @experimental
+```
+(compiled: CompiledScriptGraph): ScriptRunState
+```
+
+## defaultForType — function @experimental
+```
+(type: ScriptValueType): ScriptValue
+```
+
+## describeNode — function @experimental
+```
+(node: ScriptGraphNode, graph: ScriptGraph, catalog: ScriptVerbCatalog): ScriptNodeShape | null
+```
+
+## destroyScriptGraph — function @experimental
+```
+<Ctx>(compiled: CompiledScriptGraph, run: ScriptRunState, tick: ScriptTickContext<Ctx>): void
+```
+
+## disconnectScriptExec — function @experimental
+```
+(graph: ScriptGraph, from: string, fromPort: string): ScriptGraph
+```
+
+## disconnectScriptInput — function @experimental
+```
+(graph: ScriptGraph, to: string, toPort: string): ScriptGraph
+```
+
+## emptyScriptGraph — function @experimental
+```
+(name?: string): ScriptGraph
+```
+
+## ensureBuiltinScriptNodes — function @experimental
+```
+(): void
+```
+
+## fireScriptGraphEvent — function @experimental
+```
+<Ctx>(compiled: CompiledScriptGraph, run: ScriptRunState, tick: ScriptTickContext<Ctx>, type: string, target: number, other?: number): void
+```
+
+## getScriptGraph — function @experimental
+```
+(key: string): CompiledScriptGraph | undefined
+```
+
+## graphCallRef — function @experimental
+```
+(node: ScriptGraphNode): string
+```
+
+## isCallableGraph — function @experimental
+```
+(graph: ScriptGraph): boolean
+```
+
+## moveScriptNode — function @experimental
+```
+(graph: ScriptGraph, id: string, x: number, y: number): ScriptGraph
+```
+
+## registerScriptGraph — function @experimental
+```
+(key: string, graph: ScriptGraph): CompiledScriptGraph
+```
+
+## removeScriptEdge — function @experimental
+```
+(graph: ScriptGraph, id: string): ScriptGraph
+```
+
+## removeScriptGraphPort — function @experimental
+```
+(graph: ScriptGraph, side: "inputs" | "outputs", name: string): ScriptGraph
+```
+
+## removeScriptNode — function @experimental
+```
+(graph: ScriptGraph, id: string): ScriptGraph
+```
+
+## removeScriptVariable — function @experimental
+```
+(graph: ScriptGraph, name: string): ScriptGraph
+```
+
+## renameScriptGraphPort — function @experimental
+```
+(graph: ScriptGraph, side: "inputs" | "outputs", from: string, to: string): ScriptGraph
+```
+
+## renameScriptVariable — function @experimental
+```
+(graph: ScriptGraph, from: string, to: string): ScriptGraph
+```
+
+## retypeScriptGraphPort — function @experimental
+```
+(graph: ScriptGraph, side: "inputs" | "outputs", name: string, type: ScriptGraphPort["type"]): ScriptGraph
+```
+
+## scriptCatalog — function @experimental
+```
+(verbs: Omit<ScriptVerbCatalog, "graphSignature">, signatures?: ReadonlyMap<string, ScriptGraphSignature>): ScriptVerbCatalog
+```
+
+## scriptGraphCallRefs — function @experimental
+```
+(graph: ScriptGraph): string[]
+```
+
+## scriptGraphEdges — function @experimental
+```
+(graph: ScriptGraph): readonly ScriptGraphEdge[]
+```
+
+## scriptGraphLeaves — function @experimental
+```
+(compiled: CompiledScriptGraph): Iterable<LeafRef>
+```
+
+## scriptGraphPlugin — const @experimental
+```
+ScriptGraphPlugin
+```
+
+## scriptGraphPrefabRefs — function @experimental
+```
+(graph: ScriptGraph): string[]
+```
+
+## scriptGraphTouches — function @experimental
+```
+(app: App): SystemTouches
+```
+
+## sequenceCount — function @experimental
+```
+(node: ScriptGraphNode): number
+```
+
+## setScriptNodeLiteral — function @experimental
+```
+(graph: ScriptGraph, id: string, port: string, value: ScriptValue): ScriptGraph
+```
+
+## signatureOf — function @experimental
+```
+(graph: ScriptGraph): ScriptGraphSignature
+```
+
+## spawnPrefabRef — function @experimental
+```
+(node: ScriptGraphNode): string
+```
+
+## stepScriptGraph — function @experimental
+```
+<Ctx>(compiled: CompiledScriptGraph, run: ScriptRunState, tick: ScriptTickContext<Ctx>): void
+```
+
+## stepScriptGraphs — function @experimental
+```
+(world: ScriptGraphWorldView, commands: CommandsInstance, dt: number, states: Map<Entity, AgentState>, resolveGraph?: (ref: string) => CompiledScriptGraph | undefined, onProblem?: (entity: Entity, message: string) => void, input?: InputState): void
+```
+
diff --git a/sdk/etc/tilemap.api.md b/sdk/etc/tilemap.api.md
new file mode 100644
index 000000000..947691187
--- /dev/null
+++ b/sdk/etc/tilemap.api.md
@@ -0,0 +1,883 @@
+# API surface — esengine/tilemap
+
+<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
+Symbols: 0 public · 5 beta · 135 experimental · 0 deprecated
+
+## BuildNavGridOptions — interface @experimental
+```
+blockedTileIds: Iterable<number> | undefined
+cellSize: number
+height: number
+isBlocked: ((tileId: number) => boolean) | undefined
+origin: Vec2 | undefined
+width: number
+```
+
+## CHUNK_SIZE — const @experimental
+```
+16
+```
+
+## COLLISION_BRUSHES — const @experimental
+```
+CollisionBrush[]
+```
+
+## COLLISION_PALETTE_REF — const @experimental
+```
+"builtin:collision"
+```
+
+## CollectionGridTile — interface @experimental
+```
+id: number
+pixels: Uint8Array<ArrayBufferLike>
+```
+
+## CollisionBrush — interface @experimental
+```
+collision: ResolvedTileCollision
+id: number
+key: string
+```
+
+## CollisionMaterial — interface @experimental
+```
+density: number | undefined
+friction: number | undefined
+restitution: number | undefined
+```
+
+## DecodedChunk — interface @experimental
+```
+tiles: Uint16Array<ArrayBufferLike>
+x: number
+y: number
+```
+
+## LayerCollisionTable — interface @experimental
+```
+boxIds: ReadonlySet<number>
+shapes: ReadonlyMap<number, ResolvedTileCollision>
+```
+
+## LoadedTilemapLayer — type @experimental
+```
+TiledLayerData
+```
+
+## LoadedTilemapSource — interface @experimental
+```
+collisionTileIds: number[] | undefined
+hexSideLength: number | undefined
+layers: TiledLayerData[]
+objectGroups: TiledObjectGroupData[] | undefined
+orientation: string | undefined
+staggerAxis: string | undefined
+staggerIndex: string | undefined
+tileAnimations: Map<number, { tileId: number; duration: number; }[]> | undefined
+tileHeight: number
+tileProperties: Map<number, Map<string, string>> | undefined
+tileShapes: Map<number, ResolvedTileCollision> | undefined
+tileWidth: number
+tilesets: LoadedTilemapTileset[]
+```
+
+## LoadedTilemapTileset — interface @experimental
+```
+columns: number
+firstId: number
+margin: number
+rows: number
+spacing: number
+textureHandle: number
+```
+
+## MergedRect — interface @experimental
+```
+col: number
+height: number
+row: number
+width: number
+```
+
+## PublishedTilemap — interface @experimental
+```
+source: LoadedTilemapSource
+```
+
+## PublishedTileset — interface @experimental
+```
+resolved: ResolvedTileset
+```
+
+## ResolvedTileCollision — interface @experimental
+```
+density: number | undefined
+friction: number | undefined
+oneWay: { nx: number; ny: number; } | undefined
+restitution: number | undefined
+sensor: boolean | undefined
+shape: { type: "box"; } | { type: "polygon"; points: [number, number][]; } | { type: "circle"; cx: number; cy: number; r: number; }
+```
+
+## ResolvedTileset — interface @experimental
+```
+asset: TilesetAsset
+textureHandle: number
+textureHeight: number | undefined
+textureWidth: number | undefined
+```
+
+## TB_E — const @experimental
+```
+2
+```
+
+## TB_N — const @experimental
+```
+1
+```
+
+## TB_NE — const @experimental
+```
+16
+```
+
+## TB_NW — const @experimental
+```
+128
+```
+
+## TB_S — const @experimental
+```
+4
+```
+
+## TB_SE — const @experimental
+```
+32
+```
+
+## TB_SW — const @experimental
+```
+64
+```
+
+## TB_W — const @experimental
+```
+8
+```
+
+## TERRAIN_NEIGHBORS — const @experimental
+```
+readonly { dx: number; dy: number; bit: number; }[]
+```
+
+## TILESET_FORMAT_VERSION — const @experimental
+```
+"1"
+```
+
+## TILE_FLAGS_MASK — const @experimental
+```
+number
+```
+
+## TILE_FLIP_D — const @experimental
+```
+32768
+```
+
+## TILE_FLIP_H — const @experimental
+```
+8192
+```
+
+## TILE_FLIP_V — const @experimental
+```
+16384
+```
+
+## TILE_ID_MASK — const @experimental
+```
+8191
+```
+
+## TerrainColor — interface @experimental
+```
+color: string
+name: string
+```
+
+## TerrainIndex — interface @experimental
+```
+byMask: Map<number, number>
+mode: TerrainMode
+```
+
+## TerrainIndices — interface @experimental
+```
+sets: Map<number, TerrainIndex>
+tileTerrain: Map<number, number>
+```
+
+## TerrainMode — type @experimental
+```
+'edge' | 'corner' | 'wang'
+```
+
+## TextureDimensions — interface @experimental
+```
+height: number
+width: number
+```
+
+## TileCollisionPiece — interface @experimental
+```
+center: Vec2
+circles: { c: Vec2; r: number; }[]
+oneWay: { nx: number; ny: number; } | null
+polylines: Vec2[][]
+sensor: boolean
+```
+
+## TileCollisionShape — type @experimental
+```
+| { type: 'box' }
+ | { type: 'polygon'; points: [number, number][] }
+ | { type: 'circle'; cx: number; cy: number; r: number }
+```
+
+## TileFlags — interface @experimental
+```
+flipD: boolean
+flipH: boolean
+flipV: boolean
+```
+
+## TileGridParams — interface @experimental
+```
+hexSideLength: number | undefined
+orientation: number
+staggerAxisX: boolean | undefined
+staggerIndexEven: boolean | undefined
+tileHeight: number
+tileWidth: number
+```
+
+## TileStamp — interface @experimental
+```
+cells: number[]
+h: number
+w: number
+```
+
+## TiledAnimFrame — interface @experimental
+```
+duration: number
+tileId: number
+```
+
+## TiledCollectionTile — interface @experimental
+```
+height: number
+id: number
+image: string
+width: number
+```
+
+## TiledLayerData — interface @experimental
+```
+chunks: TiledChunkData[]
+height: number
+infinite: boolean
+name: string
+opacity: number
+parallaxX: number
+parallaxY: number
+tiles: Uint16Array<ArrayBufferLike>
+tintColor: { r: number; g: number; b: number; a: number; }
+visible: boolean
+width: number
+```
+
+## TiledMapData — interface @experimental
+```
+collisionTileIds: number[]
+height: number
+hexSideLength: number
+layers: TiledLayerData[]
+objectGroups: TiledObjectGroupData[]
+orientation: string
+staggerAxis: string
+staggerIndex: string
+tileAnimations: Map<number, TiledAnimFrame[]>
+tileHeight: number
+tileProperties: Map<number, Map<string, string>>
+tileShapes: Map<number, ResolvedTileCollision>
+tileWidth: number
+tilesets: TiledTilesetData[]
+width: number
+```
+
+## TiledObjectData — interface @experimental
+```
+gid: number | undefined
+height: number
+id: number
+name: string
+properties: Map<string, unknown>
+rotation: number
+shape: TiledObjectShape
+type: string
+vertices: number[] | null
+visible: boolean
+width: number
+x: number
+y: number
+```
+
+## TiledObjectGroupData — interface @experimental
+```
+name: string
+objects: TiledObjectData[]
+properties: Map<string, unknown>
+visible: boolean
+```
+
+## TiledObjectShape — type @experimental
+```
+'rect' | 'ellipse' | 'polygon' | 'polyline' | 'point'
+```
+
+## TiledTilesetData — interface @experimental
+```
+collectionTiles: TiledCollectionTile[] | undefined
+columns: number
+firstGid: number
+image: string
+margin: number | undefined
+name: string
+spacing: number | undefined
+tileCount: number
+tileHeight: number
+tileWidth: number
+```
+
+## Tilemap — const @experimental
+```
+ComponentDef<TilemapData>
+```
+
+## TilemapAPI — const @experimental
+```
+{ initLayer(entity: number, width: number, height: number, tileWidth: number, tileHeight: number): void; destroyLayer(entity: number): void; setTile(entity: number, x: number, y: number, tileId: number): void; getTile(entity: number, x: number, y: number): number; fillRect(entity: number, x: number, y: number, w: number, h: number, tileId: number): void; setTiles(entity: number, tiles: Uint16Array): void; setTilesets(entity: number, slots: { firstId: number; textureHandle: number; columns: number; margin?: number; spacing?: number; extrude?: number; }[]): void; hasLayer(entity: number): boolean; setRenderProps(entity: number, textureHandle: number, tilesetColumns: number, uvTileW: number, uvTileH: number, sortLayer: number, depth: number, parallaxX: number, parallaxY: number): void; setTint(entity: number, r: number, g: number, b: number, a: number, opacity: number): void; setVisible(entity: number, visible: boolean): void; setOriginEntity(layerKey: number, originEntity: number): void; setTileAnimation(entity: number, tileId: number, frames: { tileId: number; duration: number; }[]): void; clearTileAnimations(entity: number): void; advanceAnimations(entity: number, dtMs: number): void; setTileProperty(entity: number, tileId: number, key: string, value: string): void; getTileProperty(entity: number, x: number, y: number, key: string): string; flipTile(entity: number, x: number, y: number, flipH: boolean, flipV: boolean, flipD: boolean): void; rotateTile(entity: number, x: number, y: number, degrees: number): void; initInfiniteLayer(entity: number, tileWidth: number, tileHeight: number): void; setChunkTiles(entity: number, chunkX: number, chunkY: number, tiles: Uint16Array, width: number, height: number): void; setGridType(entity: number, type: number): void; setHexParams(entity: number, sideLength: number, staggerAxisX: boolean, staggerIndexEven: boolean): void; tileToWorld(entity: number, tx: number, ty: number, originX: number, originY: number): { x: number; y: number; }; worldToTile(entity: number, wx: number, wy: number, originX: number, originY: number): { x: number; y: number; }; exportChunks(entity: number): string; importChunks(entity: number, encoded: string): boolean; }
+```
+
+## TilemapData — interface @experimental
+```
+source: string
+```
+
+## TilemapLayer — const @beta
+```
+BuiltinComponentDef<TilemapLayerData>
+```
+
+## TilemapLayerData — interface @beta
+```
+cellSize: Vec2
+hexSideLength: number
+opacity: number
+orientation: TilemapOrientation
+originOffset: Vec2
+parallaxFactor: Vec2
+renderLayer: number
+staggerAxis: TilemapStaggerAxis
+staggerIndex: TilemapStaggerIndex
+tileset: number
+tilesetColumns: number
+tintColor: Color
+visible: boolean
+```
+
+## TilemapLiveSync — const @experimental
+```
+{ setLayerTilesets(app: App, entity: number, refs: readonly string[]): void; }
+```
+
+## TilemapLoadOptions — interface @experimental
+```
+collisionTileIds: number[] | undefined
+generateObjectCollision: boolean | undefined
+```
+
+## TilemapOrientation — enum @beta
+```
+Hexagonal = 3
+Isometric = 1
+Orthogonal = 0
+Staggered = 2
+```
+
+## TilemapPlugin — class @experimental
+```
+build: (app: App) => void
+cleanup: (app?: App) => void
+name: string
+static new (): TilemapPlugin
+static prototype: TilemapPlugin
+```
+
+## TilemapRuntime — class @experimental
+```
+dispose: () => void
+install: (app: App) => void
+resetLayers: () => void
+setLayerTilesets: (entity: number, refs: readonly string[]) => void
+static new (): TilemapRuntime
+static prototype: TilemapRuntime
+```
+
+## TilemapStaggerAxis — enum @beta
+```
+X = 1
+Y = 0
+```
+
+## TilemapStaggerIndex — enum @beta
+```
+Even = 1
+Odd = 0
+```
+
+## Tilemaps — const @experimental
+```
+ResourceDef<{ initLayer(entity: number, width: number, height: number, tileWidth: number, tileHeight: number): void; destroyLayer(entity: number): void; setTile(entity: number, x: number, y: number, tileId: number): void; getTile(entity: number, x: number, y: number): number; fillRect(entity: number, x: number, y: number, w: number, h: number, tileId: number): void; setTiles(entity: number, tiles: Uint16Array): void; setTilesets(entity: number, slots: { firstId: number; textureHandle: number; columns: number; margin?: number; spacing?: number; extrude?: number; }[]): void; hasLayer(entity: number): boolean; setRenderProps(entity: number, textureHandle: number, tilesetColumns: number, uvTileW: number, uvTileH: number, sortLayer: number, depth: number, parallaxX: number, parallaxY: number): void; setTint(entity: number, r: number, g: number, b: number, a: number, opacity: number): void; setVisible(entity: number, visible: boolean): void; setOriginEntity(layerKey: number, originEntity: number): void; setTileAnimation(entity: number, tileId: number, frames: { tileId: number; duration: number; }[]): void; clearTileAnimations(entity: number): void; advanceAnimations(entity: number, dtMs: number): void; setTileProperty(entity: number, tileId: number, key: string, value: string): void; getTileProperty(entity: number, x: number, y: number, key: string): string; flipTile(entity: number, x: number, y: number, flipH: boolean, flipV: boolean, flipD: boolean): void; rotateTile(entity: number, x: number, y: number, degrees: number): void; initInfiniteLayer(entity: number, tileWidth: number, tileHeight: number): void; setChunkTiles(entity: number, chunkX: number, chunkY: number, tiles: Uint16Array, width: number, height: number): void; setGridType(entity: number, type: number): void; setHexParams(entity: number, sideLength: number, staggerAxisX: boolean, staggerIndexEven: boolean): void; tileToWorld(entity: number, tx: number, ty: number, originX: number, originY: number): { x: number; y: number; }; worldToTile(entity: number, wx: number, wy: number, originX: number, originY: number): { x: number; y: number; }; exportChunks(entity: number): string; importChunks(entity: number, encoded: string): boolean; }>
+```
+
+## TilesetAnimFrame — interface @experimental
+```
+durationMs: number
+tile: number
+```
+
+## TilesetAsset — interface @experimental
+```
+columns: number
+extrude: number
+margin: number
+spacing: number
+terrains: TilesetTerrain[] | undefined
+texture: string
+tileCount: number | undefined
+tileHeight: number
+tileWidth: number
+tiles: Record<number, TilesetTile>
+version: string
+```
+
+## TilesetCollision — type @experimental
+```
+TileCollisionShape & {
+ /** One-way (jump-through) platform: contacts from behind this normal pass through. */
+ oneWay?: { nx: number; ny: number };
+ /** Non-solid trigger volume (fires events, no physical response). */
+ sensor?: boolean;
+ /** Physics material overrides (absent = engine defaults). */
+ density?: number;
+ friction?: number;
+ restitution?: number;
+}
+```
+
+## TilesetModel — interface @experimental
+```
+animations: Map<number, { tileId: number; duration: number; }[]>
+collidableTileIds: number[]
+slots: TilesetModelSlot[]
+tileShapes: Map<number, ResolvedTileCollision>
+```
+
+## TilesetModelSlot — interface @experimental
+```
+columns: number
+extrude: number
+firstId: number
+margin: number
+spacing: number
+textureHandle: number
+```
+
+## TilesetTerrain — interface @experimental
+```
+color: string | undefined
+colors: TerrainColor[] | undefined
+mode: TerrainMode
+name: string
+```
+
+## TilesetTile — interface @experimental
+```
+animation: TilesetAnimFrame[] | undefined
+collision: TilesetCollision | undefined
+probability: number | undefined
+properties: Record<string, string> | undefined
+terrain: TilesetTileTerrain | undefined
+```
+
+## TilesetTileTerrain — interface @experimental
+```
+corners: number[] | undefined
+mask: number | undefined
+set: number
+```
+
+## Vec2Like — interface @experimental
+```
+x: number
+y: number
+```
+
+## WangIndex — interface @experimental
+```
+byKey: Map<number, number>
+```
+
+## WangIndices — interface @experimental
+```
+sets: Map<number, WangIndex>
+tileTerrain: Map<number, number>
+```
+
+## atlasCells — function @experimental
+```
+(size: number, margin: number, tileSize: number, spacing: number): number
+```
+
+## buildCollisionPaletteModel — function @experimental
+```
+(material?: CollisionMaterial): TilesetModel
+```
+
+## buildTerrainIndices — function @experimental
+```
+(asset: TilesetAsset): TerrainIndices
+```
+
+## buildWangIndices — function @experimental
+```
+(asset: TilesetAsset): WangIndices
+```
+
+## canonicalMask — function @experimental
+```
+(mode: TerrainMode, mask: number): number
+```
+
+## collidableTileIds — function @experimental
+```
+(asset: TilesetAsset): number[]
+```
+
+## collisionRefWithMaterial — function @experimental
+```
+(material: CollisionMaterial): string
+```
+
+## createTileset — function @experimental
+```
+(texture: string, tileWidth?: number, tileHeight?: number, columns?: number): TilesetAsset
+```
+
+## decodeTilemapChunks — function @experimental
+```
+(blob: string): DecodedChunk[]
+```
+
+## encodeTile — function @experimental
+```
+(id: number, flags?: TileFlags): number
+```
+
+## flipFlagsH — function @experimental
+```
+(flags: TileFlags): TileFlags
+```
+
+## flipFlagsV — function @experimental
+```
+(flags: TileFlags): TileFlags
+```
+
+## flipStampH — function @experimental
+```
+(s: TileStamp): TileStamp
+```
+
+## flipStampV — function @experimental
+```
+(s: TileStamp): TileStamp
+```
+
+## generateChunkCollision — function @experimental
+```
+(world: World, chunks: { x: number; y: number; tiles: Uint16Array; }[], collisionIds: Set<number>, tileW: number, tileH: number, originX: number, originY: number, pixelsPerUnit?: number): Entity[]
+```
+
+## generateChunkPolygonCollision — function @experimental
+```
+(world: World, chunks: { x: number; y: number; tiles: Uint16Array; }[], polygonShapes: Map<number, readonly [number, number][]>, tileW: number, tileH: number, originX: number, originY: number, pixelsPerUnit?: number): Entity[]
+```
+
+## generateChunkTileShapes — function @experimental
+```
+(world: World, chunks: { x: number; y: number; tiles: Uint16Array; }[], tileShapes: Map<number, ResolvedTileCollision>, tileW: number, tileH: number, originX: number, originY: number, pixelsPerUnit?: number): Entity[]
+```
+
+## generateLayerCollision — function @experimental
+```
+(world: World, tiles: ArrayLike<number>, gridWidth: number, gridHeight: number, tileW: number, tileH: number, collisionIds: Set<number>, originX: number, originY: number, pixelsPerUnit?: number): Entity[]
+```
+
+## generateLayerTileShapes — function @experimental
+```
+(world: World, tiles: ArrayLike<number>, gridWidth: number, gridHeight: number, tileShapes: Map<number, ResolvedTileCollision>, tileW: number, tileH: number, originX: number, originY: number, pixelsPerUnit?: number): Entity[]
+```
+
+## generateObjectCollision — function @experimental
+```
+(world: World, groups: TiledObjectGroupData[], originX: number, originY: number, pixelsPerUnit?: number): Entity[]
+```
+
+## generateTileCollision — function @experimental
+```
+(world: World, layer: TiledLayerData, mapData: TiledMapData, collisionIds: Set<number>, originX: number, originY: number): Entity[]
+```
+
+## getTextureDimensions — function @experimental
+```
+(handle: number): TextureDimensions | null
+```
+
+## isCollisionObjectGroup — function @experimental
+```
+(group: TiledObjectGroupData): boolean
+```
+
+## isCollisionPaletteRef — function @experimental
+```
+(refs: readonly string[]): boolean
+```
+
+## isEmptyStamp — function @experimental
+```
+(s: TileStamp): boolean
+```
+
+## isHexOrientation — function @experimental
+```
+(orientation: number): boolean
+```
+
+## isNonOrthogonal — function @experimental
+```
+(orientation: number): boolean
+```
+
+## isTileSolid — function @experimental
+```
+(layer: Entity | number, x: number, y: number): boolean
+```
+
+## loadTiledCollisionObjects — function @experimental
+```
+(world: World, mapData: TiledMapData, mapOriginX: number, mapOriginY: number, pixelsPerUnit?: number): Entity[]
+```
+
+## loadTiledMap — function @experimental
+```
+(world: World, mapData: TiledMapData, textureHandles: Map<string, number>, options?: TilemapLoadOptions): Entity[]
+```
+
+## mergeCollisionTiles — function @experimental
+```
+(tiles: ArrayLike<number>, mapWidth: number, mapHeight: number, collisionTileIds: Set<number>): MergedRect[]
+```
+
+## navGridFromTilemapLayer — function @experimental
+```
+(entity: Entity, opts: BuildNavGridOptions): NavGrid
+```
+
+## navGridFromTiles — function @experimental
+```
+(getTile: (x: number, y: number) => number, opts: BuildNavGridOptions): NavGrid
+```
+
+## normalizeCornerMask — function @experimental
+```
+(mask: number): number
+```
+
+## oneWayNormalWorld — function @experimental
+```
+(nx: number, ny: number, fH: boolean, fV: boolean, fD: boolean): { x: number; y: number; }
+```
+
+## orientationPerm — function @experimental
+```
+(flags: TileFlags): Perm
+```
+
+## packCollectionGrid — function @experimental
+```
+(tiles: CollectionGridTile[], tileWidth: number, tileHeight: number): { pixels: Uint8Array; columns: number; rows: number; width: number; height: number; }
+```
+
+## packCorners — function @experimental
+```
+(tl: number, tr: number, br: number, bl: number): number
+```
+
+## parseCollisionMaterial — function @experimental
+```
+(refs: readonly string[]): CollisionMaterial
+```
+
+## parseTileset — function @experimental
+```
+(rawJson: unknown): TilesetAsset
+```
+
+## parseTmjJson — function @experimental
+```
+(json: Record<string, unknown>): TiledMapData | null
+```
+
+## parseTmjWithExternals — function @experimental
+```
+(json: Record<string, unknown>, resolveExternal: (source: string) => Promise<string>): Promise<TiledMapData | null>
+```
+
+## polygonLocalVerts — function @experimental
+```
+(norm: ReadonlyArray<readonly [number, number]>, tileW: number, tileH: number, flipH: boolean, flipV: boolean, flipD: boolean): { x: number; y: number; }[]
+```
+
+## resolveAutotile — function @experimental
+```
+(index: TerrainIndex, neighbors: readonly boolean[]): number
+```
+
+## resolveRelativePath — function @experimental
+```
+(basePath: string, relativePath: string): string
+```
+
+## resolveTilesetModel — function @experimental
+```
+(tilesets: ResolvedTileset[]): TilesetModel
+```
+
+## resolveWang — function @experimental
+```
+(index: WangIndex, corners: readonly number[]): number
+```
+
+## resolvedTileset — function @experimental
+```
+(assets: AssetsData | null | undefined, ref: string): ResolvedTileset | undefined
+```
+
+## rotateFlagsCW — function @experimental
+```
+(flags: TileFlags): TileFlags
+```
+
+## rotateStampCW — function @experimental
+```
+(s: TileStamp): TileStamp
+```
+
+## serializeTileset — function @experimental
+```
+(asset: TilesetAsset): Record<string, unknown>
+```
+
+## singleStamp — function @experimental
+```
+(raw: number): TileStamp
+```
+
+## spawnObjectRegion — function @experimental
+```
+(world: World, obj: TiledObjectData, parent: Entity, pixelsPerUnit: number, sensor: boolean): Entity | null
+```
+
+## tileCellCenter — function @experimental
+```
+(p: TileGridParams, tx: number, ty: number): Vec2Like
+```
+
+## tileCellOutline — function @experimental
+```
+(p: TileGridParams): Vec2Like[]
+```
+
+## tileColliderShape — function @experimental
+```
+(rc: ResolvedTileCollision, tileW: number, tileH: number, flipH: boolean, flipV: boolean, flipD: boolean): Collider2DShape
+```
+
+## tileCollisionAt — function @experimental
+```
+(layer: Entity | number, x: number, y: number): ResolvedTileCollision | null
+```
+
+## tileCollisionAtWorld — function @experimental
+```
+(layer: Entity | number, worldX: number, worldY: number, originX?: number, originY?: number): ResolvedTileCollision | null
+```
+
+## tileCollisionOutlines — function @experimental
+```
+(chunks: DecodedChunk[], model: TilesetModel, tileW: number, tileH: number, originX: number, originY: number): TileCollisionPiece[]
+```
+
+## tileFlagsOf — function @experimental
+```
+(raw: number): TileFlags
+```
+
+## tileIdOf — function @experimental
+```
+(raw: number): number
+```
+
+## tiledCollisionMods — function @experimental
+```
+(props: Array<Record<string, unknown>> | undefined): Partial<Pick<ResolvedTileCollision, "oneWay" | "sensor" | "density" | "friction" | "restitution">>
+```
+
+## tiledObjectgroupShape — function @experimental
+```
+(objects: Array<Record<string, unknown>> | undefined, tw: number, th: number): ResolvedTileCollision["shape"] | null
+```
+
+## tilemapPlugin — const @experimental
+```
+TilemapPlugin
+```
+
+## tilemapSource — function @experimental
+```
+(assets: AssetsData | null | undefined, ref: string): LoadedTilemapSource | undefined
+```
+
+## usesStagger — function @experimental
+```
+(orientation: number): boolean
+```
+
diff --git a/sdk/src/app/pluginSets.ts b/sdk/src/app/pluginSets.ts
index 6fca12031..36255532f 100644
--- a/sdk/src/app/pluginSets.ts
+++ b/sdk/src/app/pluginSets.ts
@@ -62,6 +62,31 @@ export const presentationBasePlugins = (): Plugin[] => [
postProcessPlugin, timelinePlugin, gameplayPlugin,
];
+/**
+ * The order the stack is built in, by plugin name. Build order decides resource
+ * insertion and per-schedule system order, and a plugin may arrive from a base
+ * set or from `entryPlugins()` — so the order is declared, not positional.
+ */
+export const PLUGIN_BUILD_ORDER: readonly string[] = [
+ 'Diagnostics', 'timer', 'velocity', 'lifecycle', 'animation', 'audio', 'video',
+ 'particle', 'trail', 'meshRenderer', 'tilemap', 'postProcess', 'timeline',
+ 'gameplay',
+ 'perception', 'fsm', 'bt', 'scriptGraph', 'nav', 'eventBinding', 'replication',
+ 'services',
+];
+
+/**
+ * `plugins`, in {@link PLUGIN_BUILD_ORDER}. A name the order does not mention
+ * keeps its place relative to the others, after everything it does.
+ */
+export function inBuildOrder(plugins: readonly Plugin[]): Plugin[] {
+ const rank = (p: Plugin): number => {
+ const i = p.name === undefined ? -1 : PLUGIN_BUILD_ORDER.indexOf(p.name);
+ return i < 0 ? PLUGIN_BUILD_ORDER.length : i;
+ };
+ return plugins.map((p, i) => ({ p, i })).sort((a, b) => rank(a.p) - rank(b.p) || a.i - b.i).map(({ p }) => p);
+}
+
/**
* The full stack, in the order the web factory has always built it (build order
* decides resource insertion and per-schedule system order, so it is preserved
diff --git a/sdk/src/runtime/webAppFactory.ts b/sdk/src/runtime/webAppFactory.ts
index 5685ce357..0fd612235 100644
--- a/sdk/src/runtime/webAppFactory.ts
+++ b/sdk/src/runtime/webAppFactory.ts
@@ -7,7 +7,7 @@ import { prefabsPlugin } from '../prefab/prefabServer';
import { sceneManagerPlugin } from '../scene/scenePlugin';
import { seedEngineComponents } from '../ecs/component';
import { uiPlugins } from '../app/uiPlugins';
-import { simulationBasePlugins, webBasePlugins } from '../app/pluginSets';
+import { simulationBasePlugins, webBasePlugins, inBuildOrder } from '../app/pluginSets';
import { createFetchSideModuleHost, type SideModuleHost } from '../sideModules';
// The optional subsystems an ENTRY installs. A mini-game inlines the SDK, so a
// subsystem reached from here is in every package whether a project uses it or
@@ -38,7 +38,10 @@ export function createWebApp(module: ESEngineModule, options?: CreateWebAppOptio
// Spine and DragonBones each fetch their wasm only when asked, so installing
// them costs nothing at RUN time. BUILD time is what they cost, which is why
// the entry decides and this does not.
- const plugins = [...uiPlugins, ...basePlugins, ...entryPlugins(), ...(options?.plugins ?? [])];
+
+ // Ordered, not concatenated: where a plugin came from is not where it goes.
+ const plugins = [...uiPlugins, ...inBuildOrder([...basePlugins, ...entryPlugins()]),
+ ...(options?.plugins ?? [])];
return _createWebApp(module, { ...options, sideModules, plugins });
}
@@ -75,7 +78,9 @@ export function createHeadlessApp(module: ESEngineModule, options?: HeadlessAppO
app.addPlugin(assetPlugin);
app.addPlugin(prefabsPlugin);
app.addPlugin(sceneManagerPlugin);
- app.addPlugins(headlessBasePlugins());
+ // A server steps what the client steps: the optional subsystems an entry
+ // installed run here too.
+ app.addPlugins(inBuildOrder([...headlessBasePlugins(), ...entryPlugins()]));
if (options?.plugins) app.addPlugins(options.plugins);
return app;
}
diff --git a/sdk/src/tilemap/index.ts b/sdk/src/tilemap/index.ts
index 26d9e915a..cdc83497b 100644
--- a/sdk/src/tilemap/index.ts
+++ b/sdk/src/tilemap/index.ts
@@ -1,9 +1,9 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
export { Tilemap, TilemapLayer, type TilemapData, type TilemapLayerData } from './components';
-export { TilemapAPI, Tilemaps, initTilemapAPI, shutdownTilemapAPI } from './tilemapAPI';
+export { TilemapAPI, Tilemaps } from './tilemapAPI';
export { TilemapLiveSync } from './tilemapLiveSync';
-export { TilemapPlugin, tilemapPlugin, TilemapRuntime, TilemapRuntimeState } from './tilemapPlugin';
+export { TilemapPlugin, tilemapPlugin, TilemapRuntime } from './tilemapPlugin';
export {
parseTmjJson, parseTmjWithExternals, loadTiledMap, loadTiledCollisionObjects,
generateTileCollision, generateLayerCollision, generateChunkCollision,
diff --git a/sdk/tests/tilemap.test.ts b/sdk/tests/tilemap.test.ts
index 991e3e55e..14a57f255 100644
--- a/sdk/tests/tilemap.test.ts
+++ b/sdk/tests/tilemap.test.ts
@@ -5,9 +5,9 @@ import {
Tilemap,
TilemapLayer,
TilemapAPI,
- initTilemapAPI,
- shutdownTilemapAPI,
} from '../src/tilemap';
+// Not on the subpath: binding the API to an engine is the plugin's, not a game's.
+import { initTilemapAPI, shutdownTilemapAPI } from '../src/tilemap/tilemapAPI';
import type { LoadedTilemapSource } from '../src/tilemap/tilesetCache';
import {
loadTiledMap, parseTmjJson, parseTmjWithExternals, resolveRelativePath, loadTiledCollisionObjects,
diff --git a/tools/lib/sdkProgram.mjs b/tools/lib/sdkProgram.mjs
index 834ba13f6..64e46ed3e 100644
--- a/tools/lib/sdkProgram.mjs
+++ b/tools/lib/sdkProgram.mjs
@@ -58,6 +58,9 @@ export const ENTRIES = {
'physics3d': 'src/physics3d/index.ts',
'spine': 'src/spine/index.ts',
'dragonbones': 'src/dragonbones/index.ts',
+ 'tilemap': 'src/tilemap/index.ts',
+ 'logic': 'src/logic/index.ts',
+ 'ai': 'src/ai/index.ts',
'wasm': 'src/wasm.ts',
'wechat': 'src/index.wechat.ts',
'minigame': 'src/index.minigame.ts',
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index ae6521782..92baca6a5 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -690,6 +690,10 @@ export const NOTED = {
{ internal: 'the wording of a message the export already printed' },
'fix(details): the Inspector names the new reason a texture ships raw':
{ note: 'A texture that encodes larger than its source now ships as the source.' },
+ 'fix(app): build order is declared, not the shape of an array':
+ { internal: 'the order a stack of plugins is assembled in' },
+ 'docs(manual): the AI, tilemap and script-graph pages import from their subpaths':
+ { internal: "a manual page's import line, following the move it documents" },
'refactor(ai): the AI runtimes move to their own subpath':
{ note: "The AI runtimes are a subpath: `import { NavAgent } from 'esengine/ai'`." },
'refactor(ai): the editor imports the AI runtimes from their subpath':