@v12-engine/engine 0.1.0 → 0.4.0

package/dist/navigation/recast.d.ts

@@ -1,8 +1,12 @@
 import { type NavigationBuilds } from './builds';
 import type { Rect, Vec2 } from '#engine/math';
-import type { Terrain } from '#engine/terrain';
-import type { AgentParams, AgentSave, AgentState, NavDebugGeometry, Navigation } from './navigation';
-/** @beta */
+import { type Terrain } from '#engine/terrain';
+import type { AgentMirrors, AgentMotion, AgentParams, AgentSave, AgentState, CellArea, NavDebugGeometry, Navigation } from './navigation';
+/**
+ * The options a Recast navigation is made with: who builds it, the agents' size and slope limits, and the room for agents, obstacles and path steps
+ *
+ * @beta
+ */
 export interface RecastNavigationOptions {
     /** Who builds it and where what was built is kept: this thread and the process's memory when left out */
     builds?: NavigationBuilds;
@@ -29,10 +33,11 @@ export interface RecastNavigationOptions {
     /**
      * Navigations cut for units of these sizes, each unit on the one for the biggest size it is not smaller than: a
      * big unit keeps from walls as far as it needs, where all keep 0.5 when left out. Each size is a navigation of its
-     * own, with its own crowd: units of different sizes walk through each other rather than around (see
-     * `SizedNavigation`)
+     * own, with its own crowd, and the units of the other sizes stand in that crowd as mirrors, so they keep apart as on
+     * one navigation (see `SizedNavigation`)
      */
     radii?: number[];
+    /** How big a cell is, in world units; the engine's own when left out */
     cellSize?: number;
     /**
      * What it is a navigation of: the ground, walked on, or the deep water, sailed on (`Terrain.buildWaterMesh`), at
@@ -55,6 +60,17 @@ export interface RecastNavigationOptions {
      * its line and loses a tenth of its speed to it
      */
     separation?: number;
+    /**
+     * How a walking agent minds the walls, the edges of the ground it may walk (cliffs, buildings, trees). `'soft'` when
+     * left out: an agent steers among velocities (Detour's obstacle avoidance) only while another agent, walking or
+     * standing, is within its reach (eight of its radii), and otherwise follows its path, still pushed apart from those near it
+     * (`separation`); where it does steer, a wall ahead weighs less (`SOFT_WALLS`). It keeps its speed between trees and
+     * round corners. `'detour'` is Detour's own: every walking agent steers every tick, by `DEFAULT_AVOIDANCE`, and one
+     * in a gap or hugging a corner, on ground cut its radius from every wall, goes slower or sideways for it
+     *
+     * @beta
+     */
+    walls?: 'soft' | 'detour';
     /**
      * How fast one on foot goes over the ground at a point, as a multiplier (`groundSpeedOfCell`): what a path weighs,
      * so that a way around slow ground wins where it is quicker (EN2). Asked as the ground is cut, and again for the tiles
@@ -71,18 +87,35 @@ export interface RecastNavigationOptions {
  * @beta
  */
 export interface AvoidanceParams {
+    /** How far the velocity samples may stray from the velocity the agent wants, 0..1 */
     velBias: number;
+    /** How much a sample is penalised for differing from the speed the agent wants */
     weightDesVel: number;
+    /** How much a sample is penalised for differing from the velocity the agent has */
     weightCurVel: number;
+    /** How much a sample is penalised for not passing on the preferred side */
     weightSide: number;
+    /** How much a sample is penalised for hitting something soon */
     weightToi: number;
+    /** How many seconds ahead a sample is checked for hitting something */
     horizTime: number;
     /** Samples a side in the grid sampling, odd. Only the adaptive sampling is used by the engine, which goes by the three below */
     gridSize: number;
+    /** How many divisions the adaptive sampling's pattern has */
     adaptiveDivs: number;
+    /** How many rings of samples the adaptive sampling has */
     adaptiveRings: number;
+    /** How many times the adaptive sampling is refined around the best sample */
     adaptiveDepth: number;
 }
+/**
+ * What `walls: 'soft'` changes of `DEFAULT_AVOIDANCE`, under the level and a game's own numbers: what is ahead counts
+ * within 1.5 s (Detour's 2.5) and weighs 1.5 (2.5), and going the speed it wants weighs 3 (2), so that a slower
+ * velocity that would touch a wall a little later no longer wins
+ *
+ * @beta
+ */
+export declare const SOFT_WALLS: Readonly<Partial<AvoidanceParams>>;
 /**
  * How carefully a crowd steers: `'low'` samples fewer velocities, a cost a tick that grows with the crowd, `'high'` more
  *
@@ -96,7 +129,7 @@ export type AvoidanceLevel = 'low' | 'medium' | 'high';
  * @beta
  */
 export declare const AVOIDANCE_LEVELS: Readonly<Record<AvoidanceLevel, Readonly<Partial<AvoidanceParams>>>>;
-export declare class RecastNavigation implements Navigation {
+export declare class RecastNavigation implements Navigation, AgentMirrors {
     private readonly terrain;
     private navMesh;
     private tileCache;
@@ -114,16 +147,30 @@ export declare class RecastNavigation implements Navigation {
     /** How its agents steer around each other, and how hard they push apart (`RecastNavigationOptions`) */
     readonly avoidance: Readonly<AvoidanceParams>;
     readonly separation: number;
+    /** How its agents mind the walls (`RecastNavigationOptions.walls`) */
+    readonly walls: 'soft' | 'detour';
     /** Where its tiles are: to make again those a slowing layer changed on, and to know which an obstacle touches */
     private tiles;
     /** The height of what it is a navigation of, at a point: the ground, or the water's surface */
     private readonly heightAt;
-    /** What a path weighs (`speedAt`) */
+    /** What a path weighs (`speedAt`), and how the ground was cut (`config`): to cut a part of it again (`groundChanged`) */
     private readonly ground?;
     /** What it is cut from, the ground as it is now, the way it was first cut: to cut it again (`reshape`) */
     private readonly cut?;
-    version: number;
+    /** One more each time walkable space changes (`version`) */
+    private changes;
+    /** What the ground's changes asked and is not done yet: none, mostly */
+    private asked;
     private agents;
+    private mirrors;
+    /**
+     * The crowd of the agents that walk through others (`setPhasing`), on the same navmesh, made as the first comes:
+     * Detour has no way to keep an agent out of the others' neighbours, so it walks where there are none. Walls,
+     * cliffs and obstacles are the navmesh's, and stop it as they stop anyone
+     */
+    private phasers;
+    /** How many agents the crowd of those that phase has room for now */
+    private phasersRoom;
     private obstacles;
     /** The room the crowd was first made with: a crowd made anew (`reseat`) starts there, as a loaded world's does */
     private firstMaxAgents;
@@ -133,22 +180,111 @@ export declare class RecastNavigation implements Navigation {
     /** Requests waiting while held, and the columns of the tile grid they touch (x * 65536 + z) */
     private held;
     private readonly heldColumns;
+    /** Points handed to the module, which copies them in: one, and a second for a path's end */
     private readonly scratch;
+    private readonly scratchEnd;
+    /** How far `closestPoint` looks, set for each ask */
+    private readonly closestQuery;
+    /** What `steer` works in each tick, kept: the agents that count, where they are, and a grid of them */
+    private readonly near;
+    private nearX;
+    private nearZ;
+    private nearNext;
+    private readonly nearHeads;
+    /** The tiles made again alone since the ground was last cut whole (`groundChanged`, `reshape` of a part) */
+    private overridden;
+    /**
+     * The obstacles about each column of the grid (`columnsOf`), by their keys, in the order they were put down: what a
+     * column made alone is made with. Kept while tiles are made alone, made from `obstacles` as the first is
+     */
+    private byColumn;
+    /** The grid the whole was cut on (`tileGridOf`): a part is made again alone only where the ground is cut on the same */
+    private grid;
+    /** Columns of the grid obstacles were put down or taken up on, while tiles are made alone: made again from theirs */
+    private readonly requested;
     private constructor();
     static create(terrain: Terrain, options?: RecastNavigationOptions): Promise<RecastNavigation>;
+    private static made;
+    /** One more each time walkable space changes: what the ground's changes asked of it done first (`settleGround`) */
+    get version(): number;
     /**
-     * The ground it is a navigation of was reshaped (`World.reshapeGround`): cut again from the ground as it is now, at
-     * once and on this thread, as it was cut first (its options, its slow ground); what is in the way put down again where
-     * it was, in the order it was, and every agent moved over as it stood, as a crowd that grows is. Every machine cuts it
-     * the same. False, and the navigation left as it was, where the ground as it is now cannot be cut (no water left)
+     * The ground it is a navigation of was reshaped (`World.reshapeGround`): cut again from the ground as it is now, on
+     * this thread, as it was cut first (its options, its slow ground); what is in the way put down again where it was, in
+     * the order it was, and every agent moved over as it stood, as a crowd that grows is. Every machine cuts it the same.
+     *
+     * Told the part that changed (`area`, in cells), only the tiles it reaches are cut again (`reshapeTiles`), where the
+     * ground is still cut on the same grid and that is under half of the tiles: the rest of the navmesh, what is in the
+     * way and every agent stay as they are, and an agent whose way went over a tile cut again finds it again, as when a
+     * building goes up on it.
+     *
+     * Not at once: at the first thing asked of it after, or as the tick ends (`settleGround`), with what the other
+     * changes of the ground asked before then (a slowing layer painted on the same part, `groundChanged`), each tile once.
+     * Nothing asked of it sees the ground as it was. True where it has a ground to cut again; one that cannot be cut as it
+     * is now (no water left) is left as it was when the time comes
+     */
+    reshape(area?: CellArea): boolean;
+    /** What the ground's changes ask of it, one more ask */
+    private ask;
+    /**
+     * Does what the ground's changes asked of it and it has not done yet (`reshape`, `groundChanged`), all together: a
+     * tile reached by several once, from the ground as it is now. Each ask was weighed as it came (cut whole, or its
+     * tiles), so that what comes out is what doing them one by one makes, tile for tile: where a part of the ground was
+     * reshaped, the tiles it reaches cut again of the whole ground as it is now, with those a layer was painted on; a
+     * layer painted alone, of the ground about its tiles (`groundPart`). The version goes up once for each ask, as it
+     * would have. Asked before anything else is asked of it, and by the world as each tick ends
+     */
+    settleGround(): void;
+    /** Cut again whole, of the ground as it is now, what is in the way and every agent put back as they were: false where it cannot be */
+    private cutWhole;
+    /**
+     * A slowing layer of cells changed on these cells (`World.setCells`): the tiles they are in are cut again alone from
+     * the ground as it is now (`retile`), its triangles marked with their cells' speeds as a whole
+     * cut marks them, so that the polygons part where the speed does now and the navmesh is the one a world made or
+     * loaded now cuts whole, tile for tile and area for area: a game saved after it plays out the same loaded. Only the
+     * ground about those tiles is read (`groundPart`). Where the change may have made cells walkable or not
+     * (`walkability`, a thicket), the tiles whose border reaches them too: the ground kept from them by the agents' radius
+     * reaches over the tile's edge. Never cut whole, however many tiles: cutting them alone is quicker, even all of them
+     * (half the time of a whole cut on a 128 x 128 map, which also puts every obstacle and agent back). Not at once: with
+     * what the other changes of the ground asked, before the next thing asked of it or as the tick ends (`settleGround`)
+     */
+    groundChanged(cells: readonly number[], walkability?: boolean): void;
+    /** The navmesh's tiles of a column of the grid made again: from its layers made alone where it is one of them */
+    private buildTilesAt;
+    /** Takes every layer of a column out of the navmesh */
+    private removeTilesAt;
+    /**
+     * Cuts again only these tiles (their keys: those a part of the ground reshaped reaches, `reshape`, and those a slowing
+     * layer was painted on, `groundChanged`) of the whole ground as it is now (`retile`). False, with nothing changed,
+     * where it cannot be (the ground cut on another grid now): it is cut whole
      */
-    reshape(): boolean;
+    private reshapeTiles;
     /**
-     * A slowing layer of cells changed on these cells (`World.setCells`): the tiles they are on are made again, each
-     * polygon's area the speed under it now. As fine as the polygons the ground was cut into: a patch painted in play in
-     * the middle of one counts where the polygon's middle is
+     * Cuts these columns of the grid again alone (their keys, in order), each from the build as a whole cut of it would
+     * make it (`groundTileLayers`; `speedOf` where the build is a part of the ground), and keeps their layers apart from
+     * the whole's tile cache (`overridden`, which Recast cannot take a tile out of): the navmesh's tiles there made again
+     * from them with the obstacles on them, in order (`buildColumn`). Only what these columns need is done, however many
+     * were made alone before. False, with nothing changed, where they could not be made: it is cut whole
      */
-    groundChanged(cells: readonly number[]): void;
+    private retile;
+    /**
+     * The navmesh's tiles of a column made alone (`retile`) made again from its layers, as the whole's tile cache makes a
+     * tile: through a tile cache of that column alone, in the whole's allocator and compressor, with every obstacle about
+     * it put down on it (Detour carves an obstacle into the tiles it touches as it is put down, so the layers go in
+     * first), a batch at a time as Detour queues them. Every layer of the column taken out of the navmesh first: the
+     * ground as it is now may have fewer than it had. Every layer is made again, each once: those an obstacle touches by
+     * Detour as it puts it down, the rest after (an obstacle `columnsOf` puts about a column may touch none of it)
+     */
+    private buildColumn;
+    /** An obstacle put in the columns it is about (`byColumn`), or taken out of them */
+    private indexObstacle;
+    /** The tiles made alone let go of: the whole's tile cache is the navmesh's again */
+    private dropOverridden;
+    /**
+     * A step of the whole's tile cache's work on what was put down or taken up. Once it is done, the columns made alone
+     * that it made again from its own layers, or that an obstacle came to or went from (`requested`), are made again from
+     * theirs. Whether the whole's is done
+     */
+    private updateTiles;
     /** The limits it was made with, from the map's size or the options: obstacles, and the steps of a path search */
     get limits(): {
         maxObstacles: number;
@@ -161,9 +297,36 @@ export declare class RecastNavigation implements Navigation {
      * one is made and every agent moved over as it is: where it is, how fast it goes, where to
      */
     private grow;
+    /** Makes room for twice as many agents that phase, as `grow` does for the others: their crowd made anew */
+    private growPhasers;
+    /** The crowd an agent walks on: the one of those that phase, or everyone's */
+    private crowdFor;
     private toVec3;
     addAgent(id: number, position: Vec2, params: AgentParams): void;
+    /** An agent put on the crowd, or on the crowd of those that phase (`setPhasing`) */
+    private place;
+    /** An agent put on the crowd of those that phase: made as the first comes, and made bigger as it fills, as `seat` does */
+    private seatPhasing;
+    /**
+     * An agent walks through every other and every other through it (`BuffDef.phasing`), or no longer does: moved over to
+     * the crowd of those that phase, or back, as it stands (where, how fast, where to)
+     */
+    setPhasing(id: number, phasing: boolean): void;
+    /** An agent put on the crowd. A full crowd says so with an index of -1, and an agent like that never moves: room is made, and it goes in again */
+    private seat;
     removeAgent(id: number): void;
+    readMotion(id: number, out: AgentMotion): boolean;
+    addMirror(id: number, motion: AgentMotion, radius: number, ghost: boolean): void;
+    /** Asleep from the first (Detour's `INVALID`, as an anchored agent is): of the crowd's step it is only ever a neighbour */
+    private mirrorAt;
+    moveMirror(id: number, motion: AgentMotion): void;
+    /** Written only where it changed, each number a call into WebAssembly: one standing still costs nothing */
+    private moveMirrorTo;
+    setMirrorGhost(id: number, ghost: boolean): void;
+    setMirrorPhasing(id: number, phasing: boolean): void;
+    removeMirror(id: number): void;
+    /** The mirrors put on a crowd made anew, after its agents and in the order they were, as they stood */
+    private remakeMirrors;
     hasAgent(id: number): boolean;
     setDestination(id: number, target: Vec2): boolean;
     clearDestination(id: number): void;
@@ -179,6 +342,17 @@ export declare class RecastNavigation implements Navigation {
     settle(version: number): void;
     readAgent(id: number, out: AgentState): boolean;
     update(dt: number): void;
+    /** The flags an agent steers by, set on the crowd only where they change: one call into WebAssembly */
+    private setFlags;
+    /**
+     * `walls: 'soft'`: an agent walking somewhere steers among velocities (obstacle avoidance) only while another agent
+     * (walking or standing, anchored too, not a ghost) is within its reach, its collision query range (eight of its
+     * radii); otherwise it follows its path, pushed apart from those near it (separation) but never slowed by a wall it
+     * touches. Read from where every agent is as the tick starts, in a grid of cells as large as the longest reach, so
+     * that a game loaded from a save steers as the game it was saved from (Detour's own lists of neighbours are of the
+     * tick before, and a crowd made anew has none)
+     */
+    private steer;
     addObstacle(key: number, rect: Rect): boolean;
     /**
      * Holds obstacles back (true) or lets them go (false): while held, a request to put one down or take one up waits in
@@ -195,7 +369,9 @@ export declare class RecastNavigation implements Navigation {
     private makeRoom;
     /**
      * The columns of the tile grid an obstacle touches, or more: Detour takes a box obstacle's bounds as a square 1.41 times
-     * its longer half side about its middle, here 1.5 times, so that rounding never leaves one out
+     * its longer half side about its middle, here 1.5 times, so that rounding never leaves one out. More, then, and not
+     * Detour's own test (which also weighs each layer's walkable cells and heights): what is done with a column here holds
+     * for one the obstacle does not touch (`buildColumn` makes every layer of it however that falls out)
      */
     private columnsOf;
     /** Every held request made into tiles: the tile cache up to date */