@typeonce/ritmo-math 0.22.0 → 0.23.0

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/src/FlowField.ts CHANGED
@@ -7,6 +7,22 @@
7
7
  * goal. Cells are blocked where a body of `clearance` would touch a wall, so
8
8
  * the ways it gives keep bodies off the walls.
9
9
  *
10
+ * A cell is blocked by its center alone, so a step between two open cells
11
+ * can pass over a wall more than `clearance` from every center the step
12
+ * needs open. A wall `width` by `height` can be stepped through somewhere
13
+ * exactly when
14
+ * `hypot(max(0, cellSize - width), max(0, cellSize - height)) > 2 * clearance`:
15
+ * a fence thinner than `cellSize - 2 * clearance` between two cell centers,
16
+ * or a post smaller than a cell where four open cells meet, which the
17
+ * diagonal step crosses (the corner rule lets it only between four open
18
+ * cells). No step crosses a wall at least `cellSize - clearance * √2` thick
19
+ * both ways, and none crosses any wall when `cellSize <= clearance * √2`. At
20
+ * cells of a body's diameter (`2 * clearance`), no wall a cell long or more
21
+ * can be stepped through, only a shorter one. A game with thinner walls
22
+ * (fences, pillars, thin boxes) makes the cells smaller or the clearance
23
+ * larger until the rule holds; otherwise a way can lead a body into such a
24
+ * wall, where `Collide2.moveCircle` stops it.
25
+ *
10
26
  * The grid covers the area the walls span. The walls are taken again only
11
27
  * when they change, and distances are worked out again only when the goal
12
28
  * moves to another cell, so calling `setWalls` and `setGoal` every step is
@@ -53,21 +69,45 @@ export interface FlowField {
53
69
  * Takes `boxes` as the walls, blocking every cell whose center is within
54
70
  * `clearance` of one, over the area the walls span. Does nothing when the
55
71
  * walls and clearance are the same as last time.
72
+ *
73
+ * A wall at least `cellSize - clearance * √2` thick both ways stops every
74
+ * step, and every wall does when `cellSize <= clearance * √2`. A thinner
75
+ * one can fall between the centers of open cells and be stepped through:
76
+ * a fence under `cellSize - 2 * clearance` thick, or a post smaller than a
77
+ * cell where four open cells meet (the module docs give the exact rule).
78
+ * For thin walls, use smaller cells or a larger clearance.
56
79
  */
57
80
  setWalls(boxes: ReadonlyArray<Box2>, clearance: number): void
58
81
  /**
59
82
  * Makes `goal` the place every way leads to, searching again only when it
60
83
  * is in another cell than last time (or the walls changed). The goal's own
61
- * cell may be blocked (a target standing against a wall).
84
+ * cell may be blocked (a target standing against a wall, or backed into a
85
+ * corner): the ways then lead to the nearest open cells around it that it
86
+ * can see in a straight line, however many blocked cells deep it stands.
62
87
  */
63
88
  setGoal(goal: Vec2): void
64
89
  /**
65
90
  * The unit direction from `at` toward the center of the neighboring cell
66
91
  * closest to the goal, or `undefined` when there is none: outside the grid,
67
- * walled off from the goal, or already in the goal's cell.
92
+ * walled off from the goal, or already there (in the goal's cell, or in an
93
+ * open cell next to a goal in a blocked one, where the straight line to the
94
+ * goal is the way). From a blocked cell with no open neighbor to step to (a
95
+ * body pressed into a corner) it leads to the nearest open cells it can see
96
+ * in a straight line, to the one closest to the goal.
97
+ *
98
+ * It agrees with {@link distance}: `way` gives a direction exactly where
99
+ * `distance` is a number, except where the body is already there.
68
100
  */
69
101
  way(at: Vec2): Vec2 | undefined
70
- /** The path distance from the cell holding `at` to the goal, or `undefined` outside the grid or when walled off. */
102
+ /**
103
+ * The path distance, in cells, from the cell holding `at` to the goal, or
104
+ * `undefined` outside the grid or when walled off. From a blocked cell
105
+ * other than the goal's (a body pressed against a wall or into a corner),
106
+ * which the search does not cross, it is the distance out along the steps
107
+ * {@link way} takes: to the nearest open cells it can head for, plus their
108
+ * distance, so it is more than theirs. It is `undefined` exactly where
109
+ * `way` is, except where the body is already there.
110
+ */
71
111
  distance(at: Vec2): number | undefined
72
112
  }
73
113
 
@@ -77,6 +117,12 @@ const stepX = Int8Array.of(1, -1, 0, 0, 1, 1, -1, -1)
77
117
  const stepY = Int8Array.of(0, 0, 1, -1, 1, -1, 1, -1)
78
118
  const stepCost = Float64Array.of(1, 1, 1, 1, Math.SQRT2, Math.SQRT2, Math.SQRT2, Math.SQRT2)
79
119
 
120
+ /** The length of the shortest path of steps over (`dx`, `dy`) cells: diagonal ones first, then straight. */
121
+ const pathLength = (dx: number, dy: number): number => {
122
+ const shorter = Math.min(Math.abs(dx), Math.abs(dy))
123
+ return Math.max(Math.abs(dx), Math.abs(dy)) - shorter + shorter * Math.SQRT2
124
+ }
125
+
80
126
  class Field implements FlowField {
81
127
  readonly cellSize: number
82
128
  private columns = 0
@@ -178,7 +224,8 @@ class Field implements FlowField {
178
224
  const columns = this.columns
179
225
  this.queued = 0
180
226
  distances[start] = 0
181
- this.push(start, 0)
227
+ if (this.blocked[start] === 0) this.push(start, 0)
228
+ else this.pushBlocked(goal, start)
182
229
  while (this.queued > 0) {
183
230
  const queued = this.keys[0]!
184
231
  const cell = this.pop()
@@ -221,18 +268,189 @@ class Field implements FlowField {
221
268
  targetY = this.originY + (row + dy + 0.5) * this.cellSize
222
269
  found = true
223
270
  }
224
- if (!found) return undefined
271
+ if (!found) {
272
+ const out = this.blocked[cell] === 1 && cell !== this.goal ? this.cellOut(at, cell) : -1
273
+ if (out < 0) return undefined
274
+ const outColumn = out % columns
275
+ targetX = this.originX + (outColumn + 0.5) * this.cellSize
276
+ targetY = this.originY + ((out - outColumn) / columns + 0.5) * this.cellSize
277
+ }
225
278
  const length = Ops.hypot(targetX - at.x, targetY - at.y)
226
279
  return length > 1e-6 ? { x: (targetX - at.x) / length, y: (targetY - at.y) / length } : undefined
227
280
  }
228
281
 
282
+ /**
283
+ * Starts the search from a goal in a blocked cell: from the cell itself
284
+ * when it has an open neighbor to step to, else (backed into a corner, or
285
+ * more than a cell from the open ones) from the nearest open cells it can
286
+ * see in a straight line: the corner rule keeps bodies from cutting past a
287
+ * wall, not from reaching a goal at one. Kept out of `setGoal`, like
288
+ * `cellOut` out of `way`, so the usual path stays as small as it was:
289
+ * inside them, Node 22 allocated more on every call.
290
+ */
291
+ private pushBlocked(goal: Vec2, start: number): void {
292
+ const goalColumn = start % this.columns
293
+ const goalRow = (start - goalColumn) / this.columns
294
+ if (this.stepsOut(goalColumn, goalRow)) {
295
+ this.push(start, 0)
296
+ return
297
+ }
298
+ const distances = this.distances
299
+ for (let ring = 1, found = false, rings = this.rings(); !found && ring <= rings; ring++) {
300
+ // Around the ring: all of its top and bottom rows, the ends of the others.
301
+ for (let dy = -ring; dy <= ring; dy++) {
302
+ for (let dx = -ring; dx <= ring; dx += dy === -ring || dy === ring ? 1 : 2 * ring) {
303
+ const cell = this.openCell(goalColumn + dx, goalRow + dy)
304
+ if (cell < 0 || !this.sees(goal, goalColumn + dx, goalRow + dy)) continue
305
+ found = true
306
+ const distance = pathLength(dx, dy)
307
+ distances[cell] = distance
308
+ this.push(cell, distance)
309
+ }
310
+ }
311
+ }
312
+ }
313
+
314
+ /**
315
+ * The open cell a body in a blocked cell with no neighbor to step to
316
+ * (pressed into a corner) heads for: among the nearest open cells, the one
317
+ * it can see in a straight line that leaves it closest to the goal. -1
318
+ * when there is none.
319
+ */
320
+ private cellOut(at: Vec2, cell: number): number {
321
+ const distances = this.distances
322
+ const column = cell % this.columns
323
+ const row = (cell - column) / this.columns
324
+ let best = distances[cell]!
325
+ let out = -1
326
+ for (let ring = 1, near = false, rings = this.rings(); !near && ring <= rings; ring++) {
327
+ // Around the ring, as in `pushBlocked`.
328
+ for (let dy = -ring; dy <= ring; dy++) {
329
+ for (let dx = -ring; dx <= ring; dx += dy === -ring || dy === ring ? 1 : 2 * ring) {
330
+ const next = this.openCell(column + dx, row + dy)
331
+ if (next < 0) continue
332
+ near = true
333
+ const through = pathLength(dx, dy) + distances[next]!
334
+ if (through >= best || !this.sees(at, column + dx, row + dy)) continue
335
+ best = through
336
+ out = next
337
+ }
338
+ }
339
+ }
340
+ return out
341
+ }
342
+
343
+ /**
344
+ * How many rings of cells around a blocked cell to look through for open
345
+ * ones: enough to reach out of the clearance of any wall a body stands
346
+ * against (deeper is inside a wall, or where no body fits).
347
+ */
348
+ private rings(): number {
349
+ const clearance = this.walls![0]!
350
+ return Math.min(Math.max(this.columns, this.rows) - 1, Math.ceil(clearance / this.cellSize) + 2)
351
+ }
352
+
353
+ /** The cell at (`column`, `row`) when it is in the grid and open, or -1. */
354
+ private openCell(column: number, row: number): number {
355
+ if (column < 0 || row < 0 || column >= this.columns || row >= this.rows) return -1
356
+ const cell = row * this.columns + column
357
+ return this.blocked[cell] === 1 ? -1 : cell
358
+ }
359
+
360
+ /** Whether any step from the cell at (`column`, `row`) is {@link open}. */
361
+ private stepsOut(column: number, row: number): boolean {
362
+ for (let step = 0; step < 8; step++) if (this.open(column, row, stepX[step]!, stepY[step]!)) return true
363
+ return false
364
+ }
365
+
366
+ /**
367
+ * Whether the straight line from `from` to the center of the cell at
368
+ * (`column`, `row`) crosses no wall (touching one is fine). As in
369
+ * `Collide2.sweepCircle`, a wall that holds `from` is not in the way, so a
370
+ * body inside a wall sees out of it.
371
+ */
372
+ private sees(from: Vec2, column: number, row: number): boolean {
373
+ const walls = this.walls!
374
+ const toX = this.originX + (column + 0.5) * this.cellSize
375
+ const toY = this.originY + (row + 0.5) * this.cellSize
376
+ const dx = toX - from.x
377
+ const dy = toY - from.y
378
+ const lowX = Math.min(from.x, toX)
379
+ const highX = Math.max(from.x, toX)
380
+ const lowY = Math.min(from.y, toY)
381
+ const highY = Math.max(from.y, toY)
382
+ for (let at = 1; at < walls.length; at += 4) {
383
+ // A wall beside the line is not in the way: most are, so each side is
384
+ // read only once the ones before it did not rule the wall out.
385
+ const minX = walls[at]!
386
+ if (minX >= highX) continue
387
+ const maxX = walls[at + 2]!
388
+ if (maxX <= lowX) continue
389
+ const minY = walls[at + 1]!
390
+ if (minY >= highY) continue
391
+ const maxY = walls[at + 3]!
392
+ if (maxY <= lowY) continue
393
+ // Nor is a wall holding its start.
394
+ if (from.x > minX && from.x < maxX && from.y > minY && from.y < maxY) continue
395
+ // The part of the line inside the wall's slabs, x and y.
396
+ let enter = 0
397
+ let exit = 1
398
+ if (dx === 0) {
399
+ if (from.x <= minX || from.x >= maxX) continue
400
+ } else {
401
+ const t1 = (minX - from.x) / dx
402
+ const t2 = (maxX - from.x) / dx
403
+ enter = Math.max(enter, Math.min(t1, t2))
404
+ exit = Math.min(exit, Math.max(t1, t2))
405
+ }
406
+ if (dy === 0) {
407
+ if (from.y <= minY || from.y >= maxY) continue
408
+ } else {
409
+ const t1 = (minY - from.y) / dy
410
+ const t2 = (maxY - from.y) / dy
411
+ enter = Math.max(enter, Math.min(t1, t2))
412
+ exit = Math.min(exit, Math.max(t1, t2))
413
+ }
414
+ if (enter < exit) return false
415
+ }
416
+ return true
417
+ }
418
+
229
419
  distance(at: Vec2): number | undefined {
230
420
  const cell = this.cellOf(at)
231
421
  if (cell < 0) return undefined
232
- const distance = this.distances[cell]!
422
+ let distance = this.distances[cell]!
423
+ if (distance === Infinity && this.blocked[cell] === 1) distance = this.distanceOut(at, cell)
233
424
  return distance === Infinity ? undefined : distance
234
425
  }
235
426
 
427
+ /**
428
+ * The path distance from a blocked cell, which the search does not cross,
429
+ * out through the cells `way` heads for: the shortest step to an open
430
+ * neighbor plus its distance, as the search gives an open cell, or else
431
+ * the steps to the open cell `cellOut` picks plus its distance. Infinity
432
+ * where `way` gives no direction. Kept out of `distance`, like `cellOut`
433
+ * out of `way`.
434
+ */
435
+ private distanceOut(at: Vec2, cell: number): number {
436
+ const columns = this.columns
437
+ const distances = this.distances
438
+ const column = cell % columns
439
+ const row = (cell - column) / columns
440
+ let through = Infinity
441
+ for (let step = 0; step < 8; step++) {
442
+ const dx = stepX[step]!
443
+ const dy = stepY[step]!
444
+ if (!this.open(column, row, dx, dy)) continue
445
+ through = Math.min(through, distances[(row + dy) * columns + column + dx]! + stepCost[step]!)
446
+ }
447
+ if (through < Infinity) return through
448
+ const out = this.cellOut(at, cell)
449
+ if (out < 0) return Infinity
450
+ const outColumn = out % columns
451
+ return pathLength(outColumn - column, (out - outColumn) / columns - row) + distances[out]!
452
+ }
453
+
236
454
  /** Queues `cell` at `key` (a cell queued again with a shorter distance leaves its old entry behind, skipped when popped). */
237
455
  private push(cell: number, key: number): void {
238
456
  const cells = this.heap
package/src/Vec2.ts CHANGED
@@ -168,11 +168,16 @@ export const normalizeOr = (a: Vec2, fallback: Vec2): Vec2 => {
168
168
  export const lerp = (a: Vec2, b: Vec2, t: number): Vec2 => ({ x: a.x + (b.x - a.x) * t, y: a.y + (b.y - a.y) * t })
169
169
 
170
170
  /**
171
- * Moves `current` toward `target` by at most `maxDelta`, never overshooting.
171
+ * Moves `current` toward `target` by at most `maxDelta`, never overshooting:
172
+ * `target` itself once the distance is `maxDelta` or less, and `current`
173
+ * unchanged when `maxDelta` is 0 or less, so a speed that drops below 0 (a
174
+ * slow effect minus friction) stops the point instead of moving it away. For
175
+ * plain numbers use `Scalar.moveToward`, for angles `Angle.turnToward`.
172
176
  *
173
177
  * @category Operations
174
178
  */
175
179
  export const moveToward = (current: Vec2, target: Vec2, maxDelta: number): Vec2 => {
180
+ if (!(maxDelta > 0)) return current
176
181
  const dx = target.x - current.x
177
182
  const dy = target.y - current.y
178
183
  const len = Ops.hypot(dx, dy)
@@ -181,13 +186,17 @@ export const moveToward = (current: Vec2, target: Vec2, maxDelta: number): Vec2
181
186
  }
182
187
 
183
188
  /**
184
- * `a` with its length capped at `max`, keeping its direction.
189
+ * `a` with its length capped at `max`, keeping its direction. A `max` of 0
190
+ * or less caps it at 0 (the zero vector), never flipping it.
185
191
  *
186
192
  * @category Operations
187
193
  */
188
194
  export const clampLength = (a: Vec2, max: number): Vec2 => {
189
195
  const len = Ops.hypot(a.x, a.y)
190
- return len <= max ? a : { x: (a.x / len) * max, y: (a.y / len) * max }
196
+ if (len <= max) return a
197
+ if (max > 0) return { x: (a.x / len) * max, y: (a.y / len) * max }
198
+ // No length left: `+ 0` turns a -0 into 0, and NaN stays NaN.
199
+ return { x: a.x * 0 + 0, y: a.y * 0 + 0 }
191
200
  }
192
201
 
193
202
  /**