@typeonce/ritmo-math 0.8.0 → 0.10.0

package/src/Random.ts

@@ -3,16 +3,22 @@
  * integer.
  *
  * Keep the state in a resource, so a run replays exactly and saves with the
- * world: a system makes a generator from the stored state, draws from it,
- * then writes `random.state` back. Two generators made from the same state
- * draw the same sequence on every platform.
+ * world: declare it with this module as its validator, start it with
+ * `seed`, and draw in systems through `draw` over its write cell, which writes
+ * every draw back (rolled back with a failed system). Two generators made
+ * from the same state draw the same sequence on every platform. `make` is for
+ * a state that lives outside the world (a level generator seeded once).
  *
  * @example
  * ```ts
- * const random = Random.make(resources.rng.get().state)
- * const angle = random.range(0, Math.PI * 2)
- * const kind = random.pick(kinds) ?? "grunt"
- * resources.rng.set({ state: random.state })
+ * const Rng = Descriptor.ConstructedResource(Random)("Game/Rng")
+ * const runtime = Game.Runtime.make({ services, resources: { Rng: Random.seed(0x5eed) } })
+ *
+ * Game.System("Game/Spawn", { resources: { rng: Game.System.writeResource(Rng) } }, ({ resources }) => {
+ *   const random = Random.draw(resources.rng)
+ *   const angle = random.range(0, Math.PI * 2)
+ *   const kind = random.pick(kinds) ?? "grunt"
+ * })
  * ```
  *
  * @module Random
@@ -23,7 +29,13 @@
  *
  * @categoryDescription Construction
  * Making a generator from a stored state.
+ *
+ * @categoryDescription Resource
+ * Keeping the state in a world resource.
  */
+import type * as Brand from "@typeonce/ritmo/Brand"
+import type { WriteCell } from "@typeonce/ritmo/Query"
+import * as Result from "@typeonce/ritmo/Result"
 
 /**
  * A generator. Every draw advances `state`.
@@ -35,9 +47,9 @@ export interface Random {
   readonly state: number
   /** Uniform in [0, 1). */
   next(): number
-  /** Uniform in [min, max). */
+  /** Uniform in [min, max), or `min` when they are equal. Throws when `min > max` or a bound is not finite. */
   range(min: number, max: number): number
-  /** A uniform integer in [min, maxExclusive); both bounds are integers with min < maxExclusive. */
+  /** A uniform integer in [min, maxExclusive). Throws unless both bounds are integers with min < maxExclusive. */
   integer(min: number, maxExclusive: number): number
   /** A uniform element of `items`, or `undefined` when it is empty (no draw is made then). */
   pick<A>(items: ReadonlyArray<A>): A | undefined
@@ -47,7 +59,7 @@ export interface Random {
    * An element of `items` chosen with probability proportional to `weight`,
    * or `undefined` when no element has a positive finite weight (no draw is
    * made then). Elements with zero, negative, or non-finite weight are never
-   * chosen.
+   * chosen. `weight` is called once per element.
    */
   weighted<A>(items: ReadonlyArray<A>, weight: (item: A) => number): A | undefined
 }
@@ -70,10 +82,16 @@ class Mulberry32 implements Random {
   }
 
   range(min: number, max: number): number {
+    if (!(Number.isFinite(min) && Number.isFinite(max) && min <= max)) {
+      throw new Error(`Random.range needs finite bounds with min <= max, got [${min}, ${max})`)
+    }
     return min + (max - min) * this.next()
   }
 
   integer(min: number, maxExclusive: number): number {
+    if (!(Number.isSafeInteger(min) && Number.isSafeInteger(maxExclusive) && min < maxExclusive)) {
+      throw new Error(`Random.integer needs whole bounds with min below maxExclusive, got [${min}, ${maxExclusive})`)
+    }
     return min + Math.floor(this.next() * (maxExclusive - min))
   }
 
@@ -93,20 +111,21 @@ class Mulberry32 implements Random {
   }
 
   weighted<A>(items: ReadonlyArray<A>, weight: (item: A) => number): A | undefined {
+    // `weight` is called once per item: it may be costly or not pure.
+    const weights = items.map(weight)
     let total = 0
-    for (const item of items) {
-      const value = weight(item)
+    for (const value of weights) {
       if (usable(value)) total += value
     }
     if (!usable(total)) return undefined
     let roll = this.next() * total
     let last: A | undefined
-    for (const item of items) {
-      const value = weight(item)
+    for (let index = 0; index < items.length; index++) {
+      const value = weights[index]!
       if (!usable(value)) continue
-      last = item
+      last = items[index]
       roll -= value
-      if (roll < 0) return item
+      if (roll < 0) return items[index]
     }
     // Rounding can leave a sliver of the roll past the last bucket.
     return last
@@ -121,3 +140,72 @@ class Mulberry32 implements Random {
  * @category Construction
  */
 export const make = (state: number): Random => new Mulberry32(state)
+
+/**
+ * A generator's state as a resource holds it: an unsigned 32-bit integer.
+ * Only `seed`, `result`, and `decode` make one, so `draw` takes the cell of a
+ * random resource and nothing else.
+ *
+ * @category Resource
+ */
+export type State = Brand.Branded<number, "Random/State">
+
+/** Why a value is not a generator state. @category Resource */
+export interface InvalidState {
+  readonly _tag: "InvalidRandomState"
+  readonly value: unknown
+}
+
+const isState = (value: unknown): value is State =>
+  typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 0xffffffff
+
+/**
+ * Validates a state, for `Descriptor.ConstructedResource(Random)` and saves.
+ *
+ * @category Resource
+ */
+export const result = (raw: number): Result.Result<State, InvalidState> =>
+  isState(raw) ? Result.success(raw) : Result.failure({ _tag: "InvalidRandomState", value: raw })
+
+/**
+ * Validates a state read from untrusted data (a save).
+ *
+ * @category Resource
+ */
+export const decode = (raw: unknown): Result.Result<State, InvalidState> =>
+  isState(raw) ? Result.success(raw) : Result.failure({ _tag: "InvalidRandomState", value: raw })
+
+/**
+ * The starting state for a seed, reduced to an unsigned 32-bit integer like
+ * `make`: the value to give a random resource in `Game.Runtime.make`.
+ *
+ * @category Resource
+ */
+export const seed = (value: number): State => (value >>> 0) as State
+
+class CellRandom extends Mulberry32 {
+  readonly #cell: WriteCell<State>
+
+  constructor(cell: WriteCell<State>) {
+    super(cell.get())
+    this.#cell = cell
+  }
+
+  override next(): number {
+    // Read the cell each time, so two generators over one cell share one sequence.
+    this.state = this.#cell.get()
+    const value = super.next()
+    this.#cell.set(this.state as State)
+    return value
+  }
+}
+
+/**
+ * A generator over a random resource's write cell: every draw continues from
+ * the stored state and writes the new one back, so the system needs no
+ * `set` of its own, a failed run rolls the draws back, and generators made
+ * from the same cell in one run continue one sequence.
+ *
+ * @category Resource
+ */
+export const draw = (cell: WriteCell<State>): Random => new CellRandom(cell)

package/src/Scalar.ts

@@ -41,7 +41,11 @@ import type * as Result from "@typeonce/ritmo/Result"
  * Finite number brand.
  *
  * Values of this type are guaranteed not to be `NaN`, `Infinity`, or
- * `-Infinity`.
+ * `-Infinity` when they come from a validator (`result`, `decode`). The
+ * arithmetic helpers here and in `Vector2` keep the brand without
+ * re-validating, so their results are finite only while they stay within
+ * `±Number.MAX_VALUE`: game-sized values never come close, but validate
+ * again with `result` when inputs may be that large.
  *
  * @category Scalar Types
  */
@@ -112,7 +116,8 @@ export const clamp: (value: Finite, min: Finite, max: Finite) => Finite = intern
  * Interpolates between two finite values by one finite amount.
  *
  * The amount is not clamped. This stays a pure interpolation primitive rather
- * than mixing interpolation with policy.
+ * than mixing interpolation with policy. The result keeps the `Finite` brand
+ * without re-validating (see `Finite`).
  *
  * @category Operations
  */

package/src/SpatialGrid.ts

@@ -45,17 +45,34 @@ export interface SpatialGrid {
   readonly cellSize: Scalar.Positive
   /** Removes every circle, keeping the storage for the next rebuild. */
   clear(): void
-  /** Adds circle `index` (a non-negative integer) covering `[x ± r] × [y ± r]`. */
+  /**
+   * Adds circle `index` (a non-negative integer) covering `[x ± r] × [y ± r]`.
+   * A non-finite coordinate or radius throws: it would cover no cell or all of them.
+   */
   insert(index: number, x: number, y: number, r: number): void
   /**
    * Calls `visit` once for every circle whose cells overlap the box, in no
-   * particular order. `visit` must not insert into or query this grid.
+   * particular order. `visit` must not insert into or query this grid. A
+   * non-finite bound throws (an unbounded box would never finish); a box
+   * covering more cells than are occupied scans the occupied cells instead.
    */
   forEachIn(minX: number, minY: number, maxX: number, maxY: number, visit: (index: number) => void): void
 }
 
 const key = (cx: number, cy: number): number => ((cx + 32768) << 16) | ((cy + 32768) & 0xffff)
 
+// Keys repeat every 65,536 cells, so a longer span visits nothing new.
+const AXIS_CELLS = 65_536
+const lastCell = (first: number, last: number): number => Math.min(last, first + AXIS_CELLS - 1)
+/** Whether a cell coordinate packed in a key falls in `[first, last]`, counting the keys' wrap-around. */
+const coveredBy = (coordinate: number, first: number, last: number): boolean =>
+  (((coordinate - first) % AXIS_CELLS) + AXIS_CELLS) % AXIS_CELLS <= last - first
+
+const notFinite = (operation: string, ...values: ReadonlyArray<number>): never => {
+  const value = values.find((value) => !Number.isFinite(value))
+  throw new Error(`SpatialGrid.${operation} needs finite numbers, got ${value}`)
+}
+
 class Grid implements SpatialGrid {
   readonly cellSize: Scalar.Positive
   private readonly cells = new Map<number, Array<number>>()
@@ -74,11 +91,13 @@ class Grid implements SpatialGrid {
   }
 
   insert(index: number, x: number, y: number, r: number): void {
+    // `x - x === 0` is false only for NaN and ±Infinity, without a call per number.
+    if (x - x !== 0 || y - y !== 0 || r - r !== 0) notFinite("insert", x, y, r)
     const size = this.cellSize
     const minX = Math.floor((x - r) / size)
-    const maxX = Math.floor((x + r) / size)
+    const maxX = lastCell(minX, Math.floor((x + r) / size))
     const minY = Math.floor((y - r) / size)
-    const maxY = Math.floor((y + r) / size)
+    const maxY = lastCell(minY, Math.floor((y + r) / size))
     for (let cx = minX; cx <= maxX; cx++) {
       for (let cy = minY; cy <= maxY; cy++) {
         const cellKey = key(cx, cy)
@@ -99,6 +118,7 @@ class Grid implements SpatialGrid {
   }
 
   forEachIn(minX: number, minY: number, maxX: number, maxY: number, visit: (index: number) => void): void {
+    if (minX - minX !== 0 || minY - minY !== 0 || maxX - maxX !== 0 || maxY - maxY !== 0) notFinite("forEachIn", minX, minY, maxX, maxY)
     const size = this.cellSize
     // Start the marks over before the counter leaves the stamps' range (after
     // about two billion queries), so old marks never match a new query.
@@ -110,9 +130,23 @@ class Grid implements SpatialGrid {
     const query = this.query
     const stamp = this.stamp
     const x0 = Math.floor(minX / size)
-    const x1 = Math.floor(maxX / size)
+    const x1 = lastCell(x0, Math.floor(maxX / size))
     const y0 = Math.floor(minY / size)
-    const y1 = Math.floor(maxY / size)
+    const y1 = lastCell(y0, Math.floor(maxY / size))
+    if ((x1 - x0 + 1) * (y1 - y0 + 1) > this.cells.size) {
+      // A box larger than the occupied area: scan the cells that exist.
+      for (const [cellKey, cell] of this.cells) {
+        if (cell.length === 0) continue
+        if (!coveredBy(((cellKey >> 16) & 0xffff) - 32768, x0, x1) || !coveredBy((cellKey & 0xffff) - 32768, y0, y1)) continue
+        for (let offset = 0; offset < cell.length; offset++) {
+          const index = cell[offset]!
+          if (stamp[index] === query) continue
+          stamp[index] = query
+          visit(index)
+        }
+      }
+      return
+    }
     for (let cx = x0; cx <= x1; cx++) {
       for (let cy = y0; cy <= y1; cy++) {
         const cell = this.cells.get(key(cx, cy))

package/src/Vec2.ts

@@ -24,6 +24,8 @@
  * Immutable arithmetic, measurement, and steering helpers.
  */
 
+import * as Ops from "./Ops.ts"
+
 /**
  * A two-dimensional vector in world units.
  *
@@ -68,8 +70,8 @@ export const scale = (a: Vec2, factor: number): Vec2 => ({ x: a.x * factor, y: a
  * @category Operations
  */
 export const rotate = (a: Vec2, angle: number): Vec2 => {
-  const cos = Math.cos(angle)
-  const sin = Math.sin(angle)
+  const cos = Ops.cos(angle)
+  const sin = Ops.sin(angle)
   return { x: a.x * cos - a.y * sin, y: a.x * sin + a.y * cos }
 }
 
@@ -85,7 +87,7 @@ export const dot = (a: Vec2, b: Vec2): number => a.x * b.x + a.y * b.y
  *
  * @category Operations
  */
-export const length = (a: Vec2): number => Math.hypot(a.x, a.y)
+export const length = (a: Vec2): number => Ops.hypot(a.x, a.y)
 
 /**
  * Squared length of `a`, for comparisons without a square root.
@@ -99,7 +101,7 @@ export const lengthSquared = (a: Vec2): number => a.x * a.x + a.y * a.y
  *
  * @category Operations
  */
-export const distance = (a: Vec2, b: Vec2): number => Math.hypot(a.x - b.x, a.y - b.y)
+export const distance = (a: Vec2, b: Vec2): number => Ops.hypot(a.x - b.x, a.y - b.y)
 
 /**
  * Squared distance between two points, for comparisons without a square root.
@@ -120,7 +122,7 @@ export const distanceSquared = (a: Vec2, b: Vec2): number => {
  * @category Operations
  */
 export const normalizeOr = (a: Vec2, fallback: Vec2): Vec2 => {
-  const len = Math.hypot(a.x, a.y)
+  const len = Ops.hypot(a.x, a.y)
   return len < 1e-9 ? fallback : { x: a.x / len, y: a.y / len }
 }
 
@@ -139,7 +141,7 @@ export const lerp = (a: Vec2, b: Vec2, t: number): Vec2 => ({ x: a.x + (b.x - a.
 export const moveToward = (current: Vec2, target: Vec2, maxDelta: number): Vec2 => {
   const dx = target.x - current.x
   const dy = target.y - current.y
-  const len = Math.hypot(dx, dy)
+  const len = Ops.hypot(dx, dy)
   if (len <= maxDelta || len < 1e-9) return target
   return { x: current.x + (dx / len) * maxDelta, y: current.y + (dy / len) * maxDelta }
 }
@@ -150,6 +152,6 @@ export const moveToward = (current: Vec2, target: Vec2, maxDelta: number): Vec2
  * @category Operations
  */
 export const clampLength = (a: Vec2, max: number): Vec2 => {
-  const len = Math.hypot(a.x, a.y)
+  const len = Ops.hypot(a.x, a.y)
   return len <= max ? a : { x: (a.x / len) * max, y: (a.y / len) * max }
 }

package/src/Vector2.ts

@@ -154,24 +154,36 @@ export const zero: () => Vector2 = internal.zero
 /**
  * Returns the sum of two branded vectors.
  *
+ * Keeps the brands without re-validating: finite while the result stays
+ * within `±Number.MAX_VALUE` (see `Scalar.Finite`).
+ *
  * @category Operations
  */
 export const add: (left: Vector2, right: Vector2) => Vector2 = internal.add
 /**
  * Returns the component-wise difference between two branded vectors.
  *
+ * Keeps the brands without re-validating: finite while the result stays
+ * within `±Number.MAX_VALUE` (see `Scalar.Finite`).
+ *
  * @category Operations
  */
 export const subtract: (left: Vector2, right: Vector2) => Vector2 = internal.subtract
 /**
  * Scales one vector by one validated finite scalar.
  *
+ * Keeps the brands without re-validating: finite while the result stays
+ * within `±Number.MAX_VALUE` (see `Scalar.Finite`).
+ *
  * @category Operations
  */
 export const scale: (vector: Vector2, scalar: Scalar.Finite) => Vector2 = internal.scale
 /**
  * Returns the squared length of one vector.
  *
+ * Keeps the brands without re-validating: finite while the result stays
+ * within `±Number.MAX_VALUE` (see `Scalar.Finite`).
+ *
  * @category Operations
  */
 export const lengthSquared: (vector: Vector2) => Scalar.NonNegative = internal.lengthSquared

package/src/index.ts

@@ -10,12 +10,17 @@
  * `Box2` edges, `Collide2` swept circle collision, a `SpatialGrid` broad
  * phase, a `FlowField` for finding the way around walls, and a deterministic
  * `Random` whose state is one integer.
+ *
+ * `Ops` holds the math functions engines are allowed to approximate (`sin`,
+ * `cos`, `atan2`, `exp`, `pow`, `hypot`, ...) as ports that return the same
+ * bits everywhere: use them in simulation code instead of `Math`'s.
  */
 export * as Aabb from "./Aabb.ts"
 export * as Box2 from "./Box2.ts"
 export * as Collide2 from "./Collide2.ts"
 export * as FlowField from "./FlowField.ts"
 export * as InputAxis from "./InputAxis.ts"
+export * as Ops from "./Ops.ts"
 export * as Random from "./Random.ts"
 export * as Scalar from "./Scalar.ts"
 export * as Size2 from "./Size2.ts"