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.

25.1 KB
Raw Blame

API surface — esengine/ai

Symbols: 0 public · 0 beta · 163 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: "bool" | "entity" | "number" | "string"

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: "bool" | "enum" | "number" | "string"

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

activeWhen: ComponentDef<BehaviorTreeAgentData>[]
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

activeWhen: ComponentDef<StateMachineAgentData>[]
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

@internal topologyRevision: number
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, opts?: NavQueryOptions) => boolean
isWalkable: (gx: number, gy: number) => boolean
nearestWalkable: (gx: number, gy: number, maxRadius?: number, clearance?: number) => Cell | null
originX: number
originY: number
originZ: number
queryWorldPath: (from: NavPoint, to: NavPoint, opts?: NavQueryOptions) => NavPathResult
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, opts?: NavQueryOptions) => boolean
linkCount: number
maxVertsPerPoly: number
neis: Int32Array<ArrayBufferLike>
polyCount: number
polys: Int32Array<ArrayBufferLike>
queryWorldPath: (from: NavPoint, to: NavPoint, opts?: NavQueryOptions) => NavPathResult
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

NavPathResult — interface @experimental

path: Vec3[] | null
reason: "building" | "diagnostics-unavailable" | "disconnected" | "insufficient-clearance" | "no-surface" | "none" | "radius-mismatch" | "start-unavailable" | "target-unavailable"
status: "complete" | "partial" | "unavailable" | "unknown"

NavPlugin — class @experimental

activeWhen: (ComponentDef<NavAgentData> | ComponentDef<NavVolumeData>)[]
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, opts?: NavQueryOptions) => boolean
queryWorldPath: ((from: NavPoint, to: NavPoint, opts?: NavQueryOptions) => NavPathResult) | undefined
up: Vec3

NavSurfaceSink — interface @experimental

border: (a: Vec3, b: Vec3) => void
face: (corners: readonly Vec3[]) => void
link: (a: Vec3, b: Vec3) => void

NavSurfaceUpdate — interface @experimental

cancel: () => boolean
cancelled: boolean
commit: (surface: NavSurface | null) => boolean
pending: boolean
version: number

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

beginSurfaceUpdate: () => NavSurfaceUpdate
findWorldPath: (from: NavPoint, to: NavPoint, opts?: NavQueryOptions) => Vec3[] | null
hasSurface: () => boolean
invalidatePaths: () => void
maxPlansPerFrame: number
pathRevision: number
planningBudgetMs: number
planningStats: { completed: number; pending: number; elapsedMs: number; }
queryWorldPath: (from: NavPoint, to: NavPoint, opts?: NavQueryOptions) => NavPathResult
setSurface: (surface: NavSurface | null) => void
surface: NavSurface | null
surfaceUpdatePending: boolean
static new (): Navigation
static prototype: Navigation

Noise — const @experimental

EventDef<NoisePayload>

NoisePayload — interface @experimental

loudness: number
source: number
x: number
y: number
z: number

PathfindOptions — interface @experimental

clearance: number | undefined
diagonal: boolean | undefined
snapRadius: number | undefined

Perceiver — const @experimental

ComponentDef<PerceiverData>

PerceiverData — interface @experimental

facingAxis: FacingAxis
fovDegrees: number
hearingRange: number
losLayers: number
range: number

Perception — const @experimental

ComponentDef<PerceptionData>

PerceptionData — interface @experimental

dirX: number
dirY: number
dirZ: number
distance: number
heard: boolean
noiseX: number
noiseY: number
noiseZ: number
sinceHeard: number
targetX: number
targetY: number
targetZ: number
visible: boolean

PerceptionPlugin — class @experimental

activeWhen: ComponentDef<PerceiverData>[]
build: (app: App) => void
name: string
static new (): PerceptionPlugin
static prototype: PerceptionPlugin

PerceptionTarget — const @experimental

ComponentDef<{}>

PerceptionWorldView — interface @experimental

ensureTransformsComposed: (() => void) | undefined
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" | "onExit" | "onUpdate", 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, noises?: readonly NoisePayload[], dt?: number): 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