@bendyline/molen-pathfinding 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Bendyline LLC
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,75 @@
1
+ # @bendyline/molen-pathfinding
2
+
3
+ Grid flow fields for many-unit movement in Molen: one Dijkstra integration per goal, sampled by
4
+ any number of agents heading there.
5
+
6
+ Part of [Molen](https://molen.dev), an AI-legible 3D experience engine: a deterministic headless
7
+ kernel, a three.js client, and a dev loop an agent can drive end to end.
8
+
9
+ ## Install
10
+
11
+ ```sh
12
+ npm i @bendyline/molen-pathfinding
13
+ ```
14
+
15
+ Node >= 22.13, ESM only, one `.` export, and no peer requirements at all: the built module imports
16
+ nothing — no three.js, no WASM, not even the kernel (the example below pulls it in only to show
17
+ where the directions get spent). It registers no components and no systems either, so you build
18
+ the grid from your own collision data and steer your units yourself.
19
+
20
+ ## Use
21
+
22
+ ```ts
23
+ import { Transform } from '@bendyline/molen-kernel';
24
+ import { MoveIntent } from '@bendyline/molen-kernel/character';
25
+ import { computeFlowField, Grid } from '@bendyline/molen-pathfinding';
26
+
27
+ const grid = new Grid({ cols: 256, rows: 256, cellSize: 1, origin: [0, 0] });
28
+ for (let cz = 40; cz < 200; cz++) grid.setBlocked(128, cz); // a wall to walk around
29
+
30
+ // One sweep per goal, not per unit — that is the whole point of a flow field.
31
+ const field = computeFlowField(grid, [200, 200]);
32
+
33
+ world.addSystem(
34
+ (w) => {
35
+ for (const [id, transform] of w.query(Transform)) {
36
+ const [x, , z] = transform.pos;
37
+ const [dx, dz] = field.directionAt(x, z); // unit step to the goal, [0, 0] if unreachable
38
+ w.set(id, MoveIntent, { dir: [dx, dz], jump: false });
39
+ }
40
+ },
41
+ { phase: 'update', name: 'steer' },
42
+ );
43
+ ```
44
+
45
+ Pure and deterministic: no `Math.random`, no clock, stable tie-breaking by cell index, and
46
+ diagonal moves never cut a blocked corner. The same grid and goal give the same field everywhere.
47
+
48
+ ## What's in it
49
+
50
+ - `Grid` — a uniform XZ grid with per-cell blocked flags, `worldToCell` / `cellToWorld`, and
51
+ out-of-bounds treated as blocked.
52
+ - `computeFlowField(grid, goal)` — a `FlowField` with per-cell `cost` to the goal plus `dirX` /
53
+ `dirZ`, read through `directionAt(x, z)` and `reachable(cx, cz)`.
54
+ - `DEFAULT_MAX_CELLS` — the cell-count ceiling, and `GridOptions.maxCells` to raise it.
55
+
56
+ ## Status
57
+
58
+ 0.x, on one fixed version line with every other `@bendyline/molen-*` package.
59
+
60
+ Mind the cost, because it scales with the whole grid rather than the distance walked: every
61
+ `computeFlowField` call allocates three `Float32Array`s over every cell plus heap entries —
62
+ about 13 bytes per cell — and runs a full Dijkstra sweep of every passable cell. Budget roughly
63
+ 12 MB and about a second per query per million cells, and reuse one field for every agent with
64
+ the same goal. That is why `cols * rows` is capped at `DEFAULT_MAX_CELLS` (4,000,000 — a
65
+ 2000x2000 grid): a bigger grid throws a `RangeError` naming the limit instead of quietly
66
+ allocating, and `maxCells` raises it as a deliberate, measured opt-in. Prefer a coarser `cellSize`
67
+ over a bigger grid.
68
+
69
+ ## Docs
70
+
71
+ - [Examples gallery](https://molen.dev/guide/examples) — the capability layers, this one included
72
+ - [Scripting](https://molen.dev/guide/scripting) — where the directions usually get spent
73
+ - [Authoring a capability package](https://molen.dev/guide/capability-authoring)
74
+
75
+ MIT © Bendyline LLC
@@ -0,0 +1,70 @@
1
+ //#region src/index.d.ts
2
+ /**
3
+ * Default ceiling on `cols * rows` (a 2000x2000 grid). Sized off the per-query cost, not off
4
+ * what fits in memory: one `computeFlowField` allocates three `Float32Array`s over every cell
5
+ * (plus heap entries) — about 13 bytes per cell — and runs a full Dijkstra sweep, so 4M cells
6
+ * is roughly 52 MB and a couple of seconds per query on a worker thread.
7
+ */
8
+ declare const DEFAULT_MAX_CELLS = 4e6;
9
+ interface GridOptions {
10
+ cols: number;
11
+ rows: number;
12
+ /** World size of one cell (square). */
13
+ cellSize: number;
14
+ /** World XZ of the (0,0) cell's corner. */
15
+ origin?: [number, number];
16
+ /**
17
+ * Opt-in ceiling on `cols * rows` (default {@link DEFAULT_MAX_CELLS} = 4,000,000). Raise it
18
+ * only after measuring: every {@link computeFlowField} call costs about 13 bytes per cell and
19
+ * a full Dijkstra sweep over the grid, so a 10,000x10,000 grid is ~1.3 GB and minutes of
20
+ * blocked worker per query. Prefer a coarser `cellSize` over a bigger grid.
21
+ */
22
+ maxCells?: number;
23
+ }
24
+ /**
25
+ * A uniform grid mapping world XZ to cells, with per-cell blocked flags.
26
+ *
27
+ * Cell count is capped ({@link GridOptions.maxCells}, default {@link DEFAULT_MAX_CELLS}) because
28
+ * the grid itself is the cheap part: the Uint8Array of blocked flags is 1 byte per cell, while
29
+ * each flow-field query over it costs about 13 bytes per cell and a full Dijkstra sweep.
30
+ */
31
+ declare class Grid {
32
+ readonly cols: number;
33
+ readonly rows: number;
34
+ readonly cellSize: number;
35
+ readonly origin: [number, number];
36
+ /** The cell-count ceiling this grid was built under (see {@link GridOptions.maxCells}). */
37
+ readonly maxCells: number;
38
+ private readonly blocked;
39
+ constructor(opts: GridOptions);
40
+ index(cx: number, cz: number): number;
41
+ inBounds(cx: number, cz: number): boolean;
42
+ setBlocked(cx: number, cz: number, value?: boolean): void;
43
+ isBlocked(cx: number, cz: number): boolean;
44
+ /** World XZ → cell coordinates (floored). */
45
+ worldToCell(x: number, z: number): [number, number];
46
+ /** Cell center in world XZ. */
47
+ cellToWorld(cx: number, cz: number): [number, number];
48
+ }
49
+ /** A flow field: per-cell cost-to-goal and a unit direction toward the goal. */
50
+ declare class FlowField {
51
+ private readonly grid;
52
+ readonly cost: Float32Array;
53
+ readonly dirX: Float32Array;
54
+ readonly dirZ: Float32Array;
55
+ constructor(grid: Grid, cost: Float32Array, dirX: Float32Array, dirZ: Float32Array);
56
+ reachable(cx: number, cz: number): boolean;
57
+ /** Direction toward the goal at a world position (zero if blocked/unreachable). */
58
+ directionAt(x: number, z: number): [number, number];
59
+ }
60
+ /**
61
+ * Compute a flow field over the grid toward a goal world position (Dijkstra integration).
62
+ *
63
+ * Cost scales with the whole grid, not with the distance walked: three `Float32Array`s over
64
+ * every cell plus heap entries — about 13 bytes per cell — and one Dijkstra sweep of every
65
+ * passable cell. Budget roughly 12 MB and ~1 s per query per million cells, and reuse one field
66
+ * for every agent heading to the same goal (that is the point of a flow field).
67
+ */
68
+ declare function computeFlowField(grid: Grid, goal: [number, number]): FlowField;
69
+ //#endregion
70
+ export { DEFAULT_MAX_CELLS, FlowField, Grid, GridOptions, computeFlowField };
package/dist/index.mjs ADDED
@@ -0,0 +1,242 @@
1
+ //#region src/index.ts
2
+ const SQRT2 = Math.SQRT2;
3
+ /**
4
+ * Default ceiling on `cols * rows` (a 2000x2000 grid). Sized off the per-query cost, not off
5
+ * what fits in memory: one `computeFlowField` allocates three `Float32Array`s over every cell
6
+ * (plus heap entries) — about 13 bytes per cell — and runs a full Dijkstra sweep, so 4M cells
7
+ * is roughly 52 MB and a couple of seconds per query on a worker thread.
8
+ */
9
+ const DEFAULT_MAX_CELLS = 4e6;
10
+ /**
11
+ * A uniform grid mapping world XZ to cells, with per-cell blocked flags.
12
+ *
13
+ * Cell count is capped ({@link GridOptions.maxCells}, default {@link DEFAULT_MAX_CELLS}) because
14
+ * the grid itself is the cheap part: the Uint8Array of blocked flags is 1 byte per cell, while
15
+ * each flow-field query over it costs about 13 bytes per cell and a full Dijkstra sweep.
16
+ */
17
+ var Grid = class {
18
+ cols;
19
+ rows;
20
+ cellSize;
21
+ origin;
22
+ /** The cell-count ceiling this grid was built under (see {@link GridOptions.maxCells}). */
23
+ maxCells;
24
+ blocked;
25
+ constructor(opts) {
26
+ if (!Number.isSafeInteger(opts.cols) || opts.cols <= 0) throw new RangeError("grid cols must be a positive safe integer");
27
+ if (!Number.isSafeInteger(opts.rows) || opts.rows <= 0) throw new RangeError("grid rows must be a positive safe integer");
28
+ if (!Number.isFinite(opts.cellSize) || opts.cellSize <= 0) throw new RangeError("grid cellSize must be finite and greater than 0");
29
+ if (opts.origin !== void 0 && (!Number.isFinite(opts.origin[0]) || !Number.isFinite(opts.origin[1]))) throw new RangeError("grid origin coordinates must be finite");
30
+ if (opts.maxCells !== void 0 && (!Number.isSafeInteger(opts.maxCells) || opts.maxCells <= 0)) throw new RangeError("grid maxCells must be a positive safe integer");
31
+ const maxCells = opts.maxCells ?? 4e6;
32
+ const cellCount = opts.cols * opts.rows;
33
+ if (!Number.isSafeInteger(cellCount)) throw new RangeError(`grid is too large: ${opts.cols}x${opts.rows} cells overflows exact integer arithmetic`);
34
+ if (cellCount > maxCells) throw new RangeError(`grid is too large: ${opts.cols}x${opts.rows} = ${cellCount} cells exceeds the ${maxCells}-cell limit (each computeFlowField query costs about 13 bytes per cell plus a full Dijkstra sweep). Use a coarser cellSize, or pass maxCells to raise the limit deliberately.`);
35
+ this.cols = opts.cols;
36
+ this.rows = opts.rows;
37
+ this.cellSize = opts.cellSize;
38
+ this.origin = opts.origin ?? [0, 0];
39
+ this.maxCells = maxCells;
40
+ this.blocked = new Uint8Array(cellCount);
41
+ }
42
+ index(cx, cz) {
43
+ return cz * this.cols + cx;
44
+ }
45
+ inBounds(cx, cz) {
46
+ return cx >= 0 && cz >= 0 && cx < this.cols && cz < this.rows;
47
+ }
48
+ setBlocked(cx, cz, value = true) {
49
+ if (this.inBounds(cx, cz)) this.blocked[this.index(cx, cz)] = value ? 1 : 0;
50
+ }
51
+ isBlocked(cx, cz) {
52
+ return !this.inBounds(cx, cz) || this.blocked[this.index(cx, cz)] === 1;
53
+ }
54
+ /** World XZ → cell coordinates (floored). */
55
+ worldToCell(x, z) {
56
+ return [Math.floor((x - this.origin[0]) / this.cellSize), Math.floor((z - this.origin[1]) / this.cellSize)];
57
+ }
58
+ /** Cell center in world XZ. */
59
+ cellToWorld(cx, cz) {
60
+ return [this.origin[0] + (cx + .5) * this.cellSize, this.origin[1] + (cz + .5) * this.cellSize];
61
+ }
62
+ };
63
+ const NEIGHBOURS = [
64
+ [
65
+ 1,
66
+ 0,
67
+ 1
68
+ ],
69
+ [
70
+ -1,
71
+ 0,
72
+ 1
73
+ ],
74
+ [
75
+ 0,
76
+ 1,
77
+ 1
78
+ ],
79
+ [
80
+ 0,
81
+ -1,
82
+ 1
83
+ ],
84
+ [
85
+ 1,
86
+ 1,
87
+ SQRT2
88
+ ],
89
+ [
90
+ 1,
91
+ -1,
92
+ SQRT2
93
+ ],
94
+ [
95
+ -1,
96
+ 1,
97
+ SQRT2
98
+ ],
99
+ [
100
+ -1,
101
+ -1,
102
+ SQRT2
103
+ ]
104
+ ];
105
+ /** A flow field: per-cell cost-to-goal and a unit direction toward the goal. */
106
+ var FlowField = class {
107
+ grid;
108
+ cost;
109
+ dirX;
110
+ dirZ;
111
+ constructor(grid, cost, dirX, dirZ) {
112
+ this.grid = grid;
113
+ this.cost = cost;
114
+ this.dirX = dirX;
115
+ this.dirZ = dirZ;
116
+ }
117
+ reachable(cx, cz) {
118
+ return this.grid.inBounds(cx, cz) && this.cost[this.grid.index(cx, cz)] !== Number.POSITIVE_INFINITY;
119
+ }
120
+ /** Direction toward the goal at a world position (zero if blocked/unreachable). */
121
+ directionAt(x, z) {
122
+ const [cx, cz] = this.grid.worldToCell(x, z);
123
+ if (!this.grid.inBounds(cx, cz)) return [0, 0];
124
+ const i = this.grid.index(cx, cz);
125
+ return [this.dirX[i], this.dirZ[i]];
126
+ }
127
+ };
128
+ var MinHeap = class {
129
+ cost = [];
130
+ idx = [];
131
+ get size() {
132
+ return this.cost.length;
133
+ }
134
+ push(cost, idx) {
135
+ this.cost.push(cost);
136
+ this.idx.push(idx);
137
+ let c = this.cost.length - 1;
138
+ while (c > 0) {
139
+ const p = c - 1 >> 1;
140
+ if (this.less(c, p)) {
141
+ this.swap(c, p);
142
+ c = p;
143
+ } else break;
144
+ }
145
+ }
146
+ pop() {
147
+ const top = this.idx[0];
148
+ const lastC = this.cost.pop();
149
+ const lastI = this.idx.pop();
150
+ if (this.cost.length > 0) {
151
+ this.cost[0] = lastC;
152
+ this.idx[0] = lastI;
153
+ let c = 0;
154
+ const n = this.cost.length;
155
+ for (;;) {
156
+ const l = 2 * c + 1;
157
+ const r = l + 1;
158
+ let m = c;
159
+ if (l < n && this.less(l, m)) m = l;
160
+ if (r < n && this.less(r, m)) m = r;
161
+ if (m === c) break;
162
+ this.swap(c, m);
163
+ c = m;
164
+ }
165
+ }
166
+ return top;
167
+ }
168
+ less(a, b) {
169
+ const ca = this.cost[a];
170
+ const cb = this.cost[b];
171
+ return ca < cb || ca === cb && this.idx[a] < this.idx[b];
172
+ }
173
+ swap(a, b) {
174
+ [this.cost[a], this.cost[b]] = [this.cost[b], this.cost[a]];
175
+ [this.idx[a], this.idx[b]] = [this.idx[b], this.idx[a]];
176
+ }
177
+ };
178
+ /**
179
+ * Compute a flow field over the grid toward a goal world position (Dijkstra integration).
180
+ *
181
+ * Cost scales with the whole grid, not with the distance walked: three `Float32Array`s over
182
+ * every cell plus heap entries — about 13 bytes per cell — and one Dijkstra sweep of every
183
+ * passable cell. Budget roughly 12 MB and ~1 s per query per million cells, and reuse one field
184
+ * for every agent heading to the same goal (that is the point of a flow field).
185
+ */
186
+ function computeFlowField(grid, goal) {
187
+ const n = grid.cols * grid.rows;
188
+ const cost = new Float32Array(n).fill(Number.POSITIVE_INFINITY);
189
+ const dirX = new Float32Array(n);
190
+ const dirZ = new Float32Array(n);
191
+ const [gx, gz] = grid.worldToCell(goal[0], goal[1]);
192
+ if (!grid.inBounds(gx, gz) || grid.isBlocked(gx, gz)) return new FlowField(grid, cost, dirX, dirZ);
193
+ const heap = new MinHeap();
194
+ const gi = grid.index(gx, gz);
195
+ cost[gi] = 0;
196
+ heap.push(0, gi);
197
+ while (heap.size > 0) {
198
+ const i = heap.pop();
199
+ const cz = Math.floor(i / grid.cols);
200
+ const cx = i - cz * grid.cols;
201
+ const base = cost[i];
202
+ for (const [dx, dz, w] of NEIGHBOURS) {
203
+ const nx = cx + dx;
204
+ const nz = cz + dz;
205
+ if (grid.isBlocked(nx, nz)) continue;
206
+ if (dx !== 0 && dz !== 0 && (grid.isBlocked(cx + dx, cz) || grid.isBlocked(cx, cz + dz))) continue;
207
+ const ni = grid.index(nx, nz);
208
+ const nc = base + w * grid.cellSize;
209
+ if (nc < cost[ni]) {
210
+ cost[ni] = nc;
211
+ heap.push(nc, ni);
212
+ }
213
+ }
214
+ }
215
+ for (let cz = 0; cz < grid.rows; cz++) for (let cx = 0; cx < grid.cols; cx++) {
216
+ const i = grid.index(cx, cz);
217
+ if (cost[i] === Number.POSITIVE_INFINITY) continue;
218
+ let bestCost = cost[i];
219
+ let bx = 0;
220
+ let bz = 0;
221
+ for (const [dx, dz] of NEIGHBOURS) {
222
+ const nx = cx + dx;
223
+ const nz = cz + dz;
224
+ if (grid.isBlocked(nx, nz)) continue;
225
+ if (dx !== 0 && dz !== 0 && (grid.isBlocked(cx + dx, cz) || grid.isBlocked(cx, cz + dz))) continue;
226
+ const c = cost[grid.index(nx, nz)];
227
+ if (c < bestCost) {
228
+ bestCost = c;
229
+ bx = dx;
230
+ bz = dz;
231
+ }
232
+ }
233
+ const len = Math.sqrt(bx * bx + bz * bz);
234
+ if (len > 0) {
235
+ dirX[i] = bx / len;
236
+ dirZ[i] = bz / len;
237
+ }
238
+ }
239
+ return new FlowField(grid, cost, dirX, dirZ);
240
+ }
241
+ //#endregion
242
+ export { DEFAULT_MAX_CELLS, FlowField, Grid, computeFlowField };
package/package.json ADDED
@@ -0,0 +1,51 @@
1
+ {
2
+ "name": "@bendyline/molen-pathfinding",
3
+ "version": "0.0.1",
4
+ "private": false,
5
+ "publishConfig": {
6
+ "access": "public"
7
+ },
8
+ "type": "module",
9
+ "engines": {
10
+ "node": ">=22.13.0"
11
+ },
12
+ "description": "Molen pathfinding: grid flow fields for many-unit (RTS) movement",
13
+ "license": "MIT",
14
+ "repository": {
15
+ "type": "git",
16
+ "url": "git+https://github.com/bendyline/molen.git",
17
+ "directory": "packages/pathfinding"
18
+ },
19
+ "homepage": "https://github.com/bendyline/molen/tree/main/packages/pathfinding",
20
+ "bugs": {
21
+ "url": "https://github.com/bendyline/molen/issues"
22
+ },
23
+ "keywords": [
24
+ "molen",
25
+ "3d",
26
+ "pathfinding",
27
+ "navigation"
28
+ ],
29
+ "exports": {
30
+ ".": {
31
+ "types": "./dist/index.d.mts",
32
+ "default": "./dist/index.mjs"
33
+ }
34
+ },
35
+ "files": [
36
+ "dist"
37
+ ],
38
+ "devDependencies": {
39
+ "@biomejs/biome": "^2.5.0",
40
+ "tsdown": "^0.22.2",
41
+ "typescript": "^6.0.3",
42
+ "vitest": "^4.1.8",
43
+ "@bendyline/molen-kernel": "0.0.1"
44
+ },
45
+ "scripts": {
46
+ "build": "tsdown",
47
+ "typecheck": "tsc -p tsconfig.json",
48
+ "lint": "biome check src",
49
+ "test:unit": "vitest run --passWithNoTests"
50
+ }
51
+ }