littlejsengine 1.19.3 → 1.20.0

package/plugins/pathFinder.js

@@ -34,7 +34,7 @@ class PathFinderNode
         this.pos = vec2(x, y);
         /** @property {Vector2} - World-space center of this tile (set by buildNodeData) */
         this.posWorld = vec2();
-        /** @property {boolean} - True if this cell is passable (cleared each findPath call) */
+        /** @property {boolean} - True if this cell is passable (set by buildNodeData) */
         this.walkable = false;
         /** @property {number} - Extra cost added to A* G-score for stepping on this cell */
         this.cost = 0;
@@ -42,26 +42,30 @@ class PathFinderNode
         this.g = 0;
         /** @property {number} - A* F-score: G + heuristic */
         this.f = 0;
-        /** @property {PathFinderNode|null} - Parent for path reconstruction */
+        /** @property {number} - A* heuristic: the estimated cost left to the goal, breaks ties between equal F */
+        this.h = 0;
+        /** @property {PathFinderNode|null} - Parent for path reconstruction
+         *  @type {PathFinderNode|null} */
         this.parent = null;
         /** @property {boolean} - In the A* open list */
         this.isOpen = false;
         /** @property {boolean} - In the A* closed list */
         this.isClosed = false;
+        /** @property {number} - Where it is in the A* open list's heap, while open */
+        this.heapIndex = 0;
     }
 
-    /** Reset per-search state (called at the start of buildNodeData). */
-    reset()
+    /** Clear what a search left on this node, keeping walkable and cost */
+    resetSearch()
     {
-        this.walkable = false;
-        this.cost = 0;
-        this.g = 0;
-        this.f = 0;
+        this.g = this.f = this.h = 0;
         this.parent = null;
-        this.isOpen = false;
-        this.isClosed = false;
+        this.isOpen = this.isClosed = false;
     }
 
+    /** Reset per-search state and walkability (called by buildNodeData). */
+    reset() { this.walkable = false; this.cost = 0; this.resetSearch(); }
+
     /** True if walkable and not blocked by cost. */
     isClear()
     {
@@ -89,29 +93,35 @@ class PathFinder
      *  overrides isWalkable). */
     constructor(source)
     {
-        // Accept either a Vector2 size or a TileCollisionLayer (which has a .size).
-        // We don't import TileCollisionLayer to avoid coupling; we duck-type on
-        // .size + .getCollisionData.
+        // Accept a Vector2 size, or a TileCollisionLayer or any object with its size and getCollisionData
         if (isVector2(source))
         {
-            /** @property {Vector2} - Grid dimensions in tiles */
-            this.size = source.floor();
-            /** @property {TileCollisionLayer|undefined} - Tile layer driving walkability, if any */
+            /** @property {Vector2} - Grid dimensions in tiles
+             *  @type {Vector2} */
+            this.size = /** @type {Vector2} */ (source).floor();
+            /** @property {TileCollisionLayer|undefined} - Tile layer driving walkability, if any
+             *  @type {TileCollisionLayer|undefined} */
             this.tileLayer = undefined;
         }
         else
         {
-            ASSERT(source && isVector2(source.size) && typeof source.getCollisionData === 'function',
+            const layer = /** @type {TileCollisionLayer} */ (source);
+            ASSERT(layer && isVector2(layer.size) && typeof layer.getCollisionData === 'function',
                 'PathFinder requires a Vector2 size or a TileCollisionLayer');
-            this.size = source.size;
-            this.tileLayer = source;
+            this.size = layer.size;
+            this.tileLayer = layer;
         }
 
         // Tunables (public, freely re-assignable).
         /** @property {number} - A* heuristic multiplier (1 = admissible, higher = greedier) */
         this.heuristicWeight = 1;
-        /** @property {number} - Maximum A* expansions before giving up */
-        this.maxLoop = 1e3;
+        /** @property {number|undefined} - Most A* expansions before giving up, undefined for the number of cells,
+         *  so a search always finishes; a lower one caps the time a search takes, see searchGaveUp
+         *  @type {number|undefined} */
+        this.maxLoop = undefined;
+        /** @property {boolean} - True when the last search stopped at maxLoop with no path, so it gave up rather
+         *  than that there is no way through */
+        this.searchGaveUp = false;
         /** @property {boolean} - If true, post-process paths with two-pass smoothing */
         this.smoothPath = true;
         /** @property {boolean} - If true, draw debug visualization during findPath */
@@ -119,18 +129,31 @@ class PathFinder
         /** @property {number} - Debug primitive lifetime in seconds (0 disables drawing) */
         this.debugTime = 1;
 
-        /** @property {Array<PathFinderNode>} - Flat row-major array of size.x*size.y nodes */
+        /** @property {Array<PathFinderNode>} - Flat row-major array of size.x*size.y nodes
+         *  @type {Array<PathFinderNode>} */
         this.nodes = new Array(this.size.x * this.size.y);
         for (let y = 0; y < this.size.y; ++y)
         for (let x = 0; x < this.size.x; ++x)
             this.nodes[x + y * this.size.x] = new PathFinderNode(x, y);
 
+        // Whether buildNodeData has run, a search without a rebuild builds it the first time.
+        /** @private */
+        this.nodeDataBuilt = false;
+
         // Scratch Vector2 reused to avoid allocations in the isWalkable hot path.
+        /** @private */
         this.collisionScratch = vec2();
+
+        // The nodes the last search changed, reset before the next one so a
+        // search without a rebuild starts as fresh as one after it.
+        /** @type {Array<PathFinderNode>}
+         *  @private */
+        this.searchNodes = [];
     }
 
     /** Default walkability: if a tile layer was provided, returns true when the
-     *  cell has no solid collision data; otherwise returns true. Override on
+     *  cell has no solid (positive) collision data, so negative data is open
+     *  like it is to the engine's collision; otherwise returns true. Override on
      *  the instance or via a subclass.
      *  @param {number} x - Tile x
      *  @param {number} y - Tile y
@@ -138,7 +161,7 @@ class PathFinder
     isWalkable(x, y)
     {
         if (!this.tileLayer) return true;
-        return !this.tileLayer.getCollisionData(this.collisionScratch.set(x, y));
+        return !(this.tileLayer.getCollisionData(this.collisionScratch.set(x, y)) > 0);
     }
 
     /** Default extra cost for stepping on a cell. Returns 0 (free) by default.
@@ -163,8 +186,7 @@ class PathFinder
 
     /** Convert a world-space position to integer tile coords (no clamping).
      *  @param {Vector2} worldPos
-     *  @returns {Vector2}
-     *  @memberof PathFinding */
+     *  @returns {Vector2} */
     worldToTile(worldPos)
     {
         const ox = this.tileLayer ? this.tileLayer.pos.x : 0;
@@ -175,8 +197,7 @@ class PathFinder
     /** Convert integer tile coords to the world-space center of that tile.
      *  @param {number} x
      *  @param {number} y
-     *  @returns {Vector2}
-     *  @memberof PathFinding */
+     *  @returns {Vector2} */
     tileToWorld(x, y)
     {
         const ox = this.tileLayer ? this.tileLayer.pos.x : 0;
@@ -186,10 +207,10 @@ class PathFinder
 
     /** Reset all nodes and re-populate walkable / cost / posWorld from the
      *  current isWalkable / getCost overrides. Called at the start of
-     *  findPath; exposed so tests and tooling can drive it directly.
-     *  @private */
+     *  findPath; call it directly before searches made with rebuild=false. */
     buildNodeData()
     {
+        this.nodeDataBuilt = true;
         const w = this.size.x;
         const h = this.size.y;
         const ox = this.tileLayer ? this.tileLayer.pos.x : 0;
@@ -208,16 +229,16 @@ class PathFinder
             if (this.debug && this.debugTime > 0)
             {
                 if (!walkable)
-                    debugRect(node.posWorld, PATHFINDER_TILE_VEC, rgb(1, 0, 0, 0.25), this.debugTime);
+                    debugRect(node.posWorld, PATHFINDER_TILE_VEC, rgb(1, 0, 0, 0.25), this.debugTime, 0, false, false);
                 else if (cost > 0)
-                    debugRect(node.posWorld, PATHFINDER_TILE_VEC, rgb(1, 0, 0, min(0.2, cost * 0.05)), this.debugTime);
+                    debugRect(node.posWorld, PATHFINDER_TILE_VEC, rgb(1, 0, 0, min(0.2, cost * 0.05)), this.debugTime, 0, false, false);
             }
         }
     }
 
     /** Core A* search loop. Expects buildNodeData() to have been called first.
      *  Marks node.parent for path reconstruction. Returns true if endNode was
-     *  reached; false on disconnected goal or maxLoop exhaustion.
+     *  reached; false on disconnected goal or maxLoop exhaustion, which sets searchGaveUp.
      *  @param {PathFinderNode} startNode
      *  @param {PathFinderNode} endNode
      *  @returns {boolean}
@@ -228,36 +249,78 @@ class PathFinder
         ASSERT(startNode !== endNode, 'aStarSearch: start and end must differ — caller should handle trivial case');
         ASSERT(startNode.walkable && endNode.walkable, 'aStarSearch: endpoints must be walkable');
 
-        const openList = [startNode];
-        startNode.isOpen = true;
-        let loopCount = 0;
-
-        while (openList.length > 0)
+        // Undo what the last search changed, so one without a rebuild starts
+        // from the same state; after buildNodeData these are fresh already.
+        const searchNodes = this.searchNodes;
+        for (const n of searchNodes) n.resetSearch();
+        searchNodes.length = 0;
+        searchNodes.push(startNode);
+
+        // The open list is a binary heap with the smallest f score on top, so a big map searches quickly.
+        // Equal scores go to the node nearer the goal, so open ground is
+        // crossed nearly straight instead of widening in a band of ties;
+        // the path is just as short, only which of equal paths can change.
+        // Scores are sums of diagonals, so equal is within a hair.
+        const openList = [];
+        const isBetter = (a, b)=> a.f < b.f - 1e-9 || a.f < b.f + 1e-9 && a.h < b.h;
+        const siftUp = (node)=>
+        {
+            // a new node, or one whose score went down, moves up past the ones it now beats
+            let i = node.heapIndex;
+            while (i)
+            {
+                const parent = (i - 1) >> 1;
+                if (!isBetter(node, openList[parent])) break;
+                (openList[i] = openList[parent]).heapIndex = i;
+                i = parent;
+            }
+            (openList[i] = node).heapIndex = i;
+        };
+        const popBest = ()=>
         {
-            // Find the open node with the smallest f score (linear scan).
-            // Same as the C++ — fine up to a few thousand nodes.
-            let bestIndex = 0;
-            let bestF = openList[0].f;
-            for (let i = 1; i < openList.length; ++i)
+            // take the top, then the last node sinks down from the top to where it belongs
+            const best = openList[0], last = openList.pop();
+            if (last !== best)
             {
-                if (openList[i].f < bestF)
+                let i = 0;
+                for (;;)
                 {
-                    bestF = openList[i].f;
-                    bestIndex = i;
+                    const left = 2*i + 1, right = left + 1;
+                    if (left >= openList.length) break;
+                    const child = right < openList.length && isBetter(openList[right], openList[left]) ? right : left;
+                    if (!isBetter(openList[child], last)) break;
+                    (openList[i] = openList[child]).heapIndex = i;
+                    i = child;
                 }
+                (openList[i] = last).heapIndex = i;
             }
-            const current = openList[bestIndex];
+            return best;
+        };
+        startNode.isOpen = true;
+        startNode.heapIndex = openList.length;
+        siftUp(startNode);
+        const maxLoop = this.maxLoop ?? this.size.x * this.size.y;
+        let loopCount = 0;
+        this.searchGaveUp = false;
 
+        while (openList.length > 0)
+        {
+            const current = openList[0];
             if (current === endNode) break;
-            if (++loopCount > this.maxLoop) break;
+            if (++loopCount > maxLoop)
+            {
+                // the goal may be found already, waiting its turn, and then the path to it comes back
+                this.searchGaveUp = !endNode.parent;
+                break;
+            }
 
             // Move current from open to closed.
+            popBest();
             current.isOpen = false;
-            openList.splice(bestIndex, 1);
             current.isClosed = true;
 
             if (this.debug && this.debugTime > 0)
-                debugRect(current.posWorld, PATHFINDER_TILE_VEC, rgb(1, 1, 1, 0.05), this.debugTime);
+                debugRect(current.posWorld, PATHFINDER_TILE_VEC, rgb(1, 1, 1, 0.05), this.debugTime, 0, false, false);
 
             // Expand all 8 neighbors.
             for (let dy = -1; dy <= 1; ++dy)
@@ -282,10 +345,13 @@ class PathFinder
                 }
 
                 const tentativeG = current.g + stepCost + neighbor.cost;
-                if (!neighbor.isOpen)
+                const wasOpen = neighbor.isOpen;
+                if (!wasOpen)
                 {
                     neighbor.isOpen = true;
+                    neighbor.heapIndex = openList.length;
                     openList.push(neighbor);
+                    searchNodes.push(neighbor);
                 }
                 else if (tentativeG >= neighbor.g)
                 {
@@ -300,7 +366,9 @@ class PathFinder
                 const adx = abs(endNode.pos.x - neighbor.pos.x);
                 const ady = abs(endNode.pos.y - neighbor.pos.y);
                 const h = max(adx, ady) + (Math.SQRT2 - 1) * min(adx, ady);
+                neighbor.h = h;
                 neighbor.f = neighbor.g + h * this.heuristicWeight;
+                siftUp(neighbor); // its place in the heap, new or with a lower score now
             }
         }
 
@@ -319,47 +387,12 @@ class PathFinder
      *  @param {Vector2} worldPos
      *  @param {number} [searchRange=10] - Max box-radius in tiles
      *  @param {boolean} [rebuild=true] - Whether to call buildNodeData first
-     *  @returns {PathFinderNode|null}
-     *  @memberof PathFinding */
+     *  @returns {PathFinderNode|null} */
     getNearestClearNode(worldPos, searchRange = 10, rebuild = true)
     {
         ASSERT(isVector2(worldPos), 'worldPos must be a Vector2');
-        if (rebuild) this.buildNodeData();
-
-        // Inline worldToTile to avoid a Vector2 allocation per call.
-        const ox = this.tileLayer ? this.tileLayer.pos.x : 0;
-        const oy = this.tileLayer ? this.tileLayer.pos.y : 0;
-        const centerX = floor(worldPos.x - ox);
-        const centerY = floor(worldPos.y - oy);
-
-        for (let offset = 0; offset <= searchRange; ++offset)
-        {
-            let nearest = null;
-            let nearestDistSq = 0;
-
-            for (let dy = -offset; dy <= offset; ++dy)
-            for (let dx = -offset; dx <= offset; ++dx)
-            {
-                // Only scan the perimeter of the current ring (skip the
-                // interior we've already searched in earlier iterations).
-                if (offset > 0 && abs(dx) !== offset && abs(dy) !== offset)
-                    continue;
-
-                const node = this.getNode(centerX + dx, centerY + dy);
-                if (!node || !node.isClear()) continue;
-
-                const ddx = node.posWorld.x - worldPos.x;
-                const ddy = node.posWorld.y - worldPos.y;
-                const distSq = ddx * ddx + ddy * ddy;
-                if (!nearest || distSq < nearestDistSq)
-                {
-                    nearest = node;
-                    nearestDistSq = distSq;
-                }
-            }
-            if (nearest) return nearest;
-        }
-        return null;
+        if (rebuild || !this.nodeDataBuilt) this.buildNodeData(); // a grid never built has nothing to walk yet
+        return pathFinderNearestNode(this, worldPos, searchRange, (node)=> node.isClear());
     }
 
     /** Smooth a node path by removing redundant turns and tightening corners
@@ -383,8 +416,9 @@ class PathFinder
             const dy = next.pos.y - prev.pos.y;
             const lenSq = dx * dx + dy * dy;
 
-            // dx,dy is the prev-to-current step direction; needed for the
-            // 135° "mostly vertical/horizontal" disambiguation.
+            // stepDx,stepDy is the prev-to-node step and stepDxNext,stepDyNext the node-to-next step; the 135°
+            // case uses them to tell mostly vertical from mostly horizontal, the straight case to tell a line
+            // from a bump
             const stepDx = node.pos.x - prev.pos.x;
             const stepDy = node.pos.y - prev.pos.y;
             const stepDxNext = next.pos.x - node.pos.x;
@@ -394,7 +428,7 @@ class PathFinder
             {
                 // 45° angle — middle node is off the straight line. Drop it.
                 if (this.debug && this.debugTime > 0)
-                    debugCircle(node.posWorld, 0.3, rgb(0.5, 0, 0.5, 0.5), this.debugTime);
+                    debugCircle(node.posWorld, 0.3, rgb(0.5, 0, 0.5, 0.5), this.debugTime, false, false);
                 path.splice(i, 1);
                 i = max(1, i - 1);
                 continue;
@@ -403,7 +437,7 @@ class PathFinder
             {
                 // 90° corner. Check the alternative-diagonal cell.
                 if (this.debug && this.debugTime > 0)
-                    debugCircle(node.posWorld, 0.3, rgb(1, 0, 0, 0.5), this.debugTime);
+                    debugCircle(node.posWorld, 0.3, rgb(1, 0, 0, 0.5), this.debugTime, false, false);
 
                 let sx, sy;
                 if (prev.pos.y === node.pos.y && next.pos.x === node.pos.x)
@@ -425,7 +459,7 @@ class PathFinder
                 // middle node to whichever of two candidate cells is closer
                 // to prev-of-prev, and only if the corner cut is also clear.
                 if (this.debug && this.debugTime > 0)
-                    debugCircle(node.posWorld, 0.3, rgb(1, 1, 0, 0.5), this.debugTime);
+                    debugCircle(node.posWorld, 0.3, rgb(1, 1, 0, 0.5), this.debugTime, false, false);
 
                 const prevPrev = i >= 2 ? path[i - 2] : prev;
                 let s1x, s1y, s2x, s2y;
@@ -447,8 +481,8 @@ class PathFinder
                 const dd2y = s2y - prevPrev.pos.y;
                 const dist1Sq = dd1x * dd1x + dd1y * dd1y;
                 const dist2Sq = dd2x * dd2x + dd2y * dd2y;
-                const sx = dist1Sq < dist2Sq ? s1x : s1x === s2x && s1y === s2y ? s1x : s2x;
-                const sy = dist1Sq < dist2Sq ? s1y : s1x === s2x && s1y === s2y ? s1y : s2y;
+                const useFirst = dist1Sq < dist2Sq;
+                const sx = useFirst ? s1x : s2x, sy = useFirst ? s1y : s2y;
 
                 const shortcut = this.getNode(sx, sy);
                 if (shortcut && shortcut !== node && shortcut.isClear())
@@ -469,7 +503,7 @@ class PathFinder
             {
                 // Straight line or a 1-cell bump.
                 if (this.debug && this.debugTime > 0)
-                    debugCircle(node.posWorld, 0.3, rgb(0, 1, 0, 0.5), this.debugTime);
+                    debugCircle(node.posWorld, 0.3, rgb(0, 1, 0, 0.5), this.debugTime, false, false);
 
                 if (stepDx === stepDxNext && stepDy === stepDyNext)
                 {
@@ -504,89 +538,42 @@ class PathFinder
      *  isLineClear permits, so the result can leave grid centers and cut
      *  cleanly across open spaces.
      *
-     *  Bails (leaves the path unchanged) if any node has nonzero cost — a
-     *  straight geometric shortcut can't be trusted to be the lowest-cost
-     *  route when cost-weighted terrain is in play.
+     *  A node with a cost is kept, and a shortcut only runs between clear
+     *  nodes: isLineClear passes only through clear cells, so a straight line
+     *  it accepts costs no more than the grid path it replaces.
      *
-     *  Port of ShortenPath2() in pathFinding.cpp.
+     *  Replaces the port of ShortenPath2() in pathFinding.cpp, which could
+     *  add a segment it had not checked.
      *  @param {PathFinderNode[]} path
      *  @private */
     smoothPathStringPull(path)
     {
         if (path.length <= 2) return;
-        for (const n of path)
-        {
-            if (!n.isClear()) return;
-        }
 
+        // Greedy: from each kept node, jump to the furthest node with a clear
+        // line to it, or else the next node. Every segment is one isLineClear
+        // accepted or one the path already had, so none can cross a wall.
         const original = path.slice();
         path.length = 0;
         path.push(original[0]);
-        let searchIndex = 0;
-
-        for (let i = 1; i < original.length; ++i)
+        for (let k = 0; k < original.length - 1;)
         {
-            const node = original[i];
-
-            // Skip if node is collinear with the search-window start and the
-            // previous node — it adds no information. Note: a == b is the
-            // degenerate i=1, searchIndex=0 case; skip the test then.
-            {
-                const a = original[searchIndex];
-                const b = original[i - 1];
-                if (a !== b)
-                {
-                    const cross =
-                        (b.pos.x - a.pos.x) * (node.pos.y - a.pos.y) -
-                        (b.pos.y - a.pos.y) * (node.pos.x - a.pos.x);
-                    if (cross === 0) continue;
-                }
-            }
-
-            if (!this.isLineClear(node.pos, path[path.length - 1].pos))
-            {
-                // Look ahead — if any later node has a clear shot to the
-                // back of our new path, skip this node and try later.
-                let foundClearAfter = false;
-                for (let j = i + 1; j < original.length; ++j)
-                {
-                    if (this.isLineClear(original[j].pos, path[path.length - 1].pos))
-                    {
-                        foundClearAfter = true;
-                        break;
-                    }
-                }
-                if (foundClearAfter)
-                {
-                    if (this.debug && this.debugTime > 0)
-                        debugLine(node.posWorld, path[path.length - 1].posWorld, rgb(0, 0, 1, 0.3), 0.02, this.debugTime);
-                    continue;
-                }
-
-                // No clear line ahead — fall back to the last waypoint we did
-                // have a clear line to. searchIndex tracks our scan position.
-                for (; searchIndex < original.length; ++searchIndex)
-                {
-                    const cand = original[searchIndex];
-                    if (this.isLineClear(node.pos, cand.pos))
-                    {
-                        path.push(cand);
-                        i = searchIndex;
-                        break;
-                    }
-                }
-                ASSERT(searchIndex < original.length, 'smoothPathStringPull: ran out of candidates');
-            }
+            let j = original.length - 1;
+            if (original[k].isClear()) // isLineClear needs both ends clear
+                while (j > k + 1 && !(original[j].isClear() && this.isLineClear(original[k].pos, original[j].pos)))
+                    --j;
+            else
+                j = k + 1;
+            path.push(original[j]);
+            k = j;
         }
-
-        path.push(original[original.length - 1]);
     }
 
     /** Drop any middle node that lies exactly on the line through its two
      *  neighbors. Backstop for the smoothing passes — the corners pass
      *  intentionally keeps truly-straight runs, and the string-pulling pass
-     *  checks collinearity against the original path, not the in-progress
-     *  result, so it can leave 3+ collinear nodes in some edge cases.
+     *  falls back to the next node where no longer line is clear, so it can
+     *  leave 3+ collinear nodes in some edge cases.
      *  @param {PathFinderNode[]} path
      *  @private */
     dropCollinearNodes(path)
@@ -733,22 +720,30 @@ class PathFinder
     /** Find a path from startPos to endPos in world space. Returns an array
      *  of world-space Vector2 points; empty array if no path exists.
      *
-     *  Start and end are snapped to the nearest walkable tile via
-     *  getNearestClearNode. Intermediate points are tile centers unless the
+     *  Start and end are snapped to the nearest walkable tile (a costed one
+     *  counts), within 10 tiles. Intermediate points are tile centers unless the
      *  string-pulling smoothing pass moves them off-grid.
+     *
+     *  By default, calls `buildNodeData()` first, which asks isWalkable and
+     *  getCost about every cell. When finding many paths with unchanged
+     *  walkability, pass `rebuild=false` and call `buildNodeData()` once
+     *  externally; the paths found are the same.
      *  @param {Vector2} startPos - World-space start
      *  @param {Vector2} endPos - World-space end
-     *  @returns {Vector2[]}
-     *  @memberof PathFinding */
-    findPath(startPos, endPos)
+     *  @param {boolean} [rebuild] - Whether to call buildNodeData first
+     *  @returns {Vector2[]} */
+    findPath(startPos, endPos, rebuild = true)
     {
         ASSERT(isVector2(startPos) && isVector2(endPos), 'findPath needs Vector2 endpoints');
 
-        this.buildNodeData();
+        this.searchGaveUp = false;
+        if (rebuild || !this.nodeDataBuilt) this.buildNodeData(); // a grid never built has nothing to walk yet
 
         // rebuild=false because we just built — avoid redundant work per snap.
-        const startNode = this.getNearestClearNode(startPos, 10, false);
-        const endNode = this.getNearestClearNode(endPos, 10, false);
+        // the ends go to the nearest cell that can be walked, whatever it costs to cross
+        const walkable = (node)=> node.walkable;
+        const startNode = pathFinderNearestNode(this, startPos, 10, walkable);
+        const endNode = pathFinderNearestNode(this, endPos, 10, walkable);
         if (!startNode || !endNode) return [];
 
         // Trivial case: start and end snapped to the same tile.
@@ -777,13 +772,51 @@ class PathFinder
         if (this.debug && this.debugTime > 0 && result.length > 0)
         {
             for (let i = 1; i < result.length; ++i)
-                debugLine(result[i - 1], result[i], RED, 0.1, this.debugTime);
+                debugLine(result[i - 1], result[i], RED, 0.1, this.debugTime, false);
             for (const p of result)
-                debugCircle(p, 0.5, rgb(1, 0, 0, 0.3), this.debugTime);
-            debugCircle(result[0], 0.5, rgb(0, 1, 0, 0.5), this.debugTime);
-            debugCircle(result[result.length - 1], 0.5, rgb(0, 1, 0, 0.5), this.debugTime);
+                debugCircle(p, 0.5, rgb(1, 0, 0, 0.3), this.debugTime, false, false);
+            debugCircle(result[0], 0.5, rgb(0, 1, 0, 0.5), this.debugTime, false, false);
+            debugCircle(result[result.length - 1], 0.5, rgb(0, 1, 0, 0.5), this.debugTime, false, false);
         }
 
         return result;
     }
 }
+
+// the node nearest a world position that passes a test, within a range of tiles, or null: the rings of cells around
+// the position are searched outward until the next ring cannot hold anything nearer than the best found, since the
+// best of one ring is not always the nearest, a cell one ring out can be closer
+function pathFinderNearestNode(finder, worldPos, searchRange, test)
+{
+    const center = finder.worldToTile(worldPos);
+    const centerX = center.x, centerY = center.y;
+
+    let nearest = null, nearestDistSq = 0;
+    for (let offset = 0; offset <= searchRange; ++offset)
+    {
+        // every cell of this ring is more than offset - .5 away along one axis
+        const bound = max(0, offset - .5);
+        if (nearest && bound * bound >= nearestDistSq) break;
+
+        for (let dy = -offset; dy <= offset; ++dy)
+        for (let dx = -offset; dx <= offset; ++dx)
+        {
+            // only the ring itself, the inside was searched already
+            if (offset > 0 && abs(dx) !== offset && abs(dy) !== offset)
+                continue;
+
+            const node = finder.getNode(centerX + dx, centerY + dy);
+            if (!node || !test(node)) continue;
+
+            const ddx = node.posWorld.x - worldPos.x;
+            const ddy = node.posWorld.y - worldPos.y;
+            const distSq = ddx * ddx + ddy * ddy;
+            if (!nearest || distSq < nearestDistSq)
+            {
+                nearest = node;
+                nearestDistSq = distSq;
+            }
+        }
+    }
+    return nearest;
+}

package/plugins/pluginExport.js

@@ -92,6 +92,7 @@ export
     drawNineSliceScreen,
     drawThreeSlice,
     drawThreeSliceScreen,
+    TileSlice,
     drawCrescent,
     getCrescentPoints,
 
@@ -106,6 +107,12 @@ export
     PathFinder,
     PathFinderNode,
 
+    // Tweakables
+    tweak,
+    tweakDivider,
+    tweakButton,
+    tweakEngineDefaults,
+
     // Math3D
     vec3,
     isVector3,
@@ -132,6 +139,7 @@ export
     Camera3D,
     EngineObject3D,
     Mesh,
+    InstancedMesh3D,
     buildLathe,
     buildCylinder,
     buildSphere,
@@ -146,6 +154,7 @@ export
     buildExtrude,
     buildText3D,
     HeightMap,
+    VoxelMap,
     Light3D,
     DirectionalLight3D,
     CameraControl3D,
@@ -157,6 +166,12 @@ export
     engineObjectsRaycast3D,
     parseOBJ,
     loadOBJ,
+    GLTFModel,
+    GLTFPart,
+    GLTFObject,
+    GLTFAnimation,
+    parseGLTF,
+    loadGLTF,
     debugBox3D,
     debugSphere3D,
     debugLine3D,