redscript-mc 2.5.0 → 2.6.2

package/src/stdlib/pathfind.mcrs

@@ -0,0 +1,321 @@
+// pathfind.mcrs — BFS grid pathfinding for RedScript datapacks.
+//
+// Implements breadth-first search on a 16×16 grid (x: 0–15, z: 0–15).
+//
+// Coordinate packing: packed = x * 16 + z  (unique within 16×16 grid)
+//   x = packed / 16
+//   z = packed % 16
+//
+// Obstacle map:
+//   Allocate with pf_new_map() — returns a 256-element int[] (all passable).
+//   pf_set_blocked(map, x, z) — mark a cell as impassable (value 1).
+//   pf_set_open(map, x, z)    — mark a cell as passable (value 0).
+//   pf_is_blocked(map, x, z)  — returns 1 if blocked or out-of-bounds, 0 otherwise.
+//
+// Pathfinding:
+//   pathfind_bfs(map, sx, sz, gx, gz)
+//     → returns int[] of packed coords from (sx,sz) to (gx,gz) inclusive,
+//       or [] if no path exists.
+//
+// Coroutine variant:
+//   pathfind_bfs_coro(map, sx, sz, gx, gz, out) — same BFS but spread across
+//   ticks via @coroutine(batch=16). Results are pushed into the caller-supplied
+//   out[] array. Use onDone to get notified when the path is ready.
+//
+// Example:
+//   let map: int[] = pf_new_map()
+//   pf_set_blocked(map, 3, 5)
+//   let path: int[] = pathfind_bfs(map, 0, 0, 7, 7)
+//   let step_x: int = pf_unpack_x(path[0])
+//   let step_z: int = pf_unpack_z(path[0])
+
+module library
+
+// ─── Coordinate utilities ─────────────────────────────────────────────────────
+
+// pf_pack(x, z): encode (x, z) as a single int (x*16+z)
+fn pf_pack(x: int, z: int): int { return x * 16 + z }
+
+// pf_unpack_x(packed): recover the x component
+fn pf_unpack_x(packed: int): int { return packed / 16 }
+
+// pf_unpack_z(packed): recover the z component
+fn pf_unpack_z(packed: int): int { return packed % 16 }
+
+// ─── Obstacle map ─────────────────────────────────────────────────────────────
+
+// pf_new_map(): allocate a 256-element map, all cells passable (value 0)
+fn pf_new_map(): int[] {
+    let map: int[] = []
+    let i: int = 0
+    while (i < 256) {
+        map.push(0)
+        i = i + 1
+    }
+    return map
+}
+
+// pf_set_blocked(map, x, z): mark cell (x, z) as impassable
+fn pf_set_blocked(map: int[], x: int, z: int) {
+    let idx: int = pf_pack(x, z)
+    map[idx] = 1
+}
+
+// pf_set_open(map, x, z): mark cell (x, z) as passable
+fn pf_set_open(map: int[], x: int, z: int) {
+    let idx: int = pf_pack(x, z)
+    map[idx] = 0
+}
+
+// pf_is_blocked(map, x, z): 1 if out-of-bounds or impassable, 0 otherwise
+fn pf_is_blocked(map: int[], x: int, z: int): int {
+    if (x < 0) { return 1 }
+    if (z < 0) { return 1 }
+    if (x >= 16) { return 1 }
+    if (z >= 16) { return 1 }
+    return map[pf_pack(x, z)]
+}
+
+// ─── Manhattan heuristic ──────────────────────────────────────────────────────
+
+// pf_heuristic(x1, z1, x2, z2): Manhattan distance ×10000 (fixed-point)
+// Informational — not used by BFS, but useful if you extend to A*.
+fn pf_heuristic(x1: int, z1: int, x2: int, z2: int): int {
+    let dx: int = x1 - x2
+    let dz: int = z1 - z2
+    if (dx < 0) { dx = 0 - dx }
+    if (dz < 0) { dz = 0 - dz }
+    return (dx + dz) * 10000
+}
+
+// ─── BFS pathfinding (synchronous) ───────────────────────────────────────────
+
+// pathfind_bfs(map, sx, sz, gx, gz): find shortest path via BFS
+//
+// Returns int[] of packed coords start→goal (inclusive), or [] if unreachable.
+//
+// Internal arrays (size 256):
+//   visited[] — 1 = cell was enqueued; 0 = not yet seen
+//   parent[]  — packed coord of predecessor (-1 = no parent / unvisited)
+//   queue[]   — BFS frontier; consumed via qhead index (no front-dequeue needed)
+fn pathfind_bfs(map: int[], sx: int, sz: int, gx: int, gz: int): int[] {
+    // Allocate visited and parent arrays (256 cells each)
+    let visited: int[] = []
+    let parent: int[] = []
+    let k: int = 0
+    while (k < 256) {
+        visited.push(0)
+        parent.push(-1)
+        k = k + 1
+    }
+
+    let queue: int[] = []
+    let qhead: int = 0
+    let qsize: int = 0
+
+    let start: int = pf_pack(sx, sz)
+    let goal: int = pf_pack(gx, gz)
+
+    visited[start] = 1
+    queue.push(start)
+    qsize = 1
+
+    let found: int = 0
+
+    while (qhead < qsize) {
+        let cur: int = queue[qhead]
+        qhead = qhead + 1
+
+        if (cur == goal) {
+            found = 1
+            qhead = qsize // stop BFS
+        } else {
+            let cx: int = pf_unpack_x(cur)
+            let cz: int = pf_unpack_z(cur)
+
+            // North (z-1)
+            if (pf_is_blocked(map, cx, cz - 1) == 0) {
+                let nb: int = pf_pack(cx, cz - 1)
+                if (visited[nb] == 0) {
+                    visited[nb] = 1
+                    parent[nb] = cur
+                    queue.push(nb)
+                    qsize = qsize + 1
+                }
+            }
+            // South (z+1)
+            if (pf_is_blocked(map, cx, cz + 1) == 0) {
+                let nb: int = pf_pack(cx, cz + 1)
+                if (visited[nb] == 0) {
+                    visited[nb] = 1
+                    parent[nb] = cur
+                    queue.push(nb)
+                    qsize = qsize + 1
+                }
+            }
+            // West (x-1)
+            if (pf_is_blocked(map, cx - 1, cz) == 0) {
+                let nb: int = pf_pack(cx - 1, cz)
+                if (visited[nb] == 0) {
+                    visited[nb] = 1
+                    parent[nb] = cur
+                    queue.push(nb)
+                    qsize = qsize + 1
+                }
+            }
+            // East (x+1)
+            if (pf_is_blocked(map, cx + 1, cz) == 0) {
+                let nb: int = pf_pack(cx + 1, cz)
+                if (visited[nb] == 0) {
+                    visited[nb] = 1
+                    parent[nb] = cur
+                    queue.push(nb)
+                    qsize = qsize + 1
+                }
+            }
+        }
+    }
+
+    let empty: int[] = []
+    if (found == 0) { return empty }
+
+    // Reconstruct path: walk parent[] links from goal back to start
+    let rev: int[] = []
+    let node: int = goal
+    let walking: int = 1
+    while (walking == 1) {
+        rev.push(node)
+        if (node == start) {
+            walking = 0
+        } else {
+            node = parent[node]
+        }
+    }
+
+    // Reverse rev[] into path[]
+    let path: int[] = []
+    let rlen: int = rev.len
+    let ri: int = rlen - 1
+    while (ri >= 0) {
+        path.push(rev[ri])
+        ri = ri - 1
+    }
+
+    return path
+}
+
+// ─── Coroutine BFS (tick-spread for server-friendly operation) ────────────────
+
+// pathfind_bfs_coro: identical BFS logic, spread across ticks via @coroutine.
+//
+// @coroutine(batch=16) processes 16 BFS iterations per server tick, preventing
+// lag spikes on busy grids. Results are pushed into caller-supplied out[] when done.
+//
+// Limitations:
+//   - @coroutine functions cannot return values; use the out[] ref pattern instead.
+//   - Replace pf_noop with your own handler if you need a done callback.
+//   - The out[] array must outlive the coroutine; store it in a scoreboard-backed var.
+//
+// Usage:
+//   let out: int[] = []
+//   pathfind_bfs_coro(map, 0, 0, 7, 7, out)
+//   // … several ticks later, out[] contains the packed-coord path
+
+@coroutine(batch=16, onDone=pf_noop)
+fn pathfind_bfs_coro(map: int[], sx: int, sz: int, gx: int, gz: int, out: int[]) {
+    let visited: int[] = []
+    let parent: int[] = []
+    let k: int = 0
+    while (k < 256) {
+        visited.push(0)
+        parent.push(-1)
+        k = k + 1
+    }
+
+    let queue: int[] = []
+    let qhead: int = 0
+    let qsize: int = 0
+
+    let start: int = pf_pack(sx, sz)
+    let goal: int = pf_pack(gx, gz)
+
+    visited[start] = 1
+    queue.push(start)
+    qsize = 1
+
+    let found: int = 0
+
+    // @coroutine spreads this loop: 16 iterations per tick
+    while (qhead < qsize) {
+        let cur: int = queue[qhead]
+        qhead = qhead + 1
+
+        if (cur == goal) {
+            found = 1
+            qhead = qsize
+        } else {
+            let cx: int = pf_unpack_x(cur)
+            let cz: int = pf_unpack_z(cur)
+
+            if (pf_is_blocked(map, cx, cz - 1) == 0) {
+                let nb: int = pf_pack(cx, cz - 1)
+                if (visited[nb] == 0) {
+                    visited[nb] = 1
+                    parent[nb] = cur
+                    queue.push(nb)
+                    qsize = qsize + 1
+                }
+            }
+            if (pf_is_blocked(map, cx, cz + 1) == 0) {
+                let nb: int = pf_pack(cx, cz + 1)
+                if (visited[nb] == 0) {
+                    visited[nb] = 1
+                    parent[nb] = cur
+                    queue.push(nb)
+                    qsize = qsize + 1
+                }
+            }
+            if (pf_is_blocked(map, cx - 1, cz) == 0) {
+                let nb: int = pf_pack(cx - 1, cz)
+                if (visited[nb] == 0) {
+                    visited[nb] = 1
+                    parent[nb] = cur
+                    queue.push(nb)
+                    qsize = qsize + 1
+                }
+            }
+            if (pf_is_blocked(map, cx + 1, cz) == 0) {
+                let nb: int = pf_pack(cx + 1, cz)
+                if (visited[nb] == 0) {
+                    visited[nb] = 1
+                    parent[nb] = cur
+                    queue.push(nb)
+                    qsize = qsize + 1
+                }
+            }
+        }
+    }
+
+    if (found == 1) {
+        let rev: int[] = []
+        let node: int = goal
+        let walking: int = 1
+        while (walking == 1) {
+            rev.push(node)
+            if (node == start) {
+                walking = 0
+            } else {
+                node = parent[node]
+            }
+        }
+        let rlen: int = rev.len
+        let ri: int = rlen - 1
+        while (ri >= 0) {
+            out.push(rev[ri])
+            ri = ri - 1
+        }
+    }
+}
+
+// pf_noop: default onDone callback — replace with your own handler
+fn pf_noop() {}

package/src/stdlib/quaternion.mcrs

@@ -0,0 +1,192 @@
+// quaternion.mcrs — Quaternion math for Display Entity rotations.
+//
+// MC Display Entities use quaternions [x, y, z, w] for left_rotation / right_rotation.
+// Quaternion components are floats in [-1, 1].
+//
+// Scale convention: all components ×10000
+//   qx=7071, qy=0, qz=0, qw=7071 → (0.7071, 0, 0, 0.7071) = 90° rotation around X
+//
+// A unit quaternion satisfies: qx²+qy²+qz²+qw² = 1 (i.e. sum of sq = 10000² = 100,000,000)
+//
+// Requires: stdlib/math (for sin_fixed, cos_fixed, mulfix, abs, isqrt)
+
+module library;
+
+// ─── Constructors ─────────────────────────────────────────────────────────────
+
+// quat_identity: returns W component of identity quaternion (x=y=z=0, w=1)
+fn quat_identity_w(): int { return 10000; }
+fn quat_identity_x(): int { return 0; }
+fn quat_identity_y(): int { return 0; }
+fn quat_identity_z(): int { return 0; }
+
+// quat_from_axis_x: rotation around X axis by angle degrees
+// sin_fixed/cos_fixed return ×1000; we scale to ×10000 by multiplying by 10
+// angle_deg: degrees (integer)
+fn quat_axis_x_x(angle_deg: int): int { return sin_fixed(angle_deg / 2) * 10; }
+fn quat_axis_x_y(angle_deg: int): int { return 0; }
+fn quat_axis_x_z(angle_deg: int): int { return 0; }
+fn quat_axis_x_w(angle_deg: int): int { return cos_fixed(angle_deg / 2) * 10; }
+
+// quat_from_axis_y: rotation around Y axis
+fn quat_axis_y_x(angle_deg: int): int { return 0; }
+fn quat_axis_y_y(angle_deg: int): int { return sin_fixed(angle_deg / 2) * 10; }
+fn quat_axis_y_z(angle_deg: int): int { return 0; }
+fn quat_axis_y_w(angle_deg: int): int { return cos_fixed(angle_deg / 2) * 10; }
+
+// quat_from_axis_z: rotation around Z axis
+fn quat_axis_z_x(angle_deg: int): int { return 0; }
+fn quat_axis_z_y(angle_deg: int): int { return 0; }
+fn quat_axis_z_z(angle_deg: int): int { return sin_fixed(angle_deg / 2) * 10; }
+fn quat_axis_z_w(angle_deg: int): int { return cos_fixed(angle_deg / 2) * 10; }
+
+// ─── Quaternion multiplication ────────────────────────────────────────────────
+// q = (ax,ay,az,aw) * (bx,by,bz,bw)
+// All components ×10000, result ×10000
+
+fn quat_mul_x(ax: int, ay: int, az: int, aw: int, bx: int, by: int, bz: int, bw: int): int {
+    // x = aw*bx + ax*bw + ay*bz - az*by
+    return mulfix(aw, bx) + mulfix(ax, bw) + mulfix(ay, bz) - mulfix(az, by);
+}
+
+fn quat_mul_y(ax: int, ay: int, az: int, aw: int, bx: int, by: int, bz: int, bw: int): int {
+    // y = aw*by - ax*bz + ay*bw + az*bx
+    return mulfix(aw, by) - mulfix(ax, bz) + mulfix(ay, bw) + mulfix(az, bx);
+}
+
+fn quat_mul_z(ax: int, ay: int, az: int, aw: int, bx: int, by: int, bz: int, bw: int): int {
+    // z = aw*bz + ax*by - ay*bx + az*bw
+    return mulfix(aw, bz) + mulfix(ax, by) - mulfix(ay, bx) + mulfix(az, bw);
+}
+
+fn quat_mul_w(ax: int, ay: int, az: int, aw: int, bx: int, by: int, bz: int, bw: int): int {
+    // w = aw*bw - ax*bx - ay*by - az*bz
+    return mulfix(aw, bw) - mulfix(ax, bx) - mulfix(ay, by) - mulfix(az, bz);
+}
+
+// ─── Quaternion conjugate (= inverse for unit quaternion) ────────────────────
+fn quat_conj_x(qx: int, qy: int, qz: int, qw: int): int { return 0 - qx; }
+fn quat_conj_y(qx: int, qy: int, qz: int, qw: int): int { return 0 - qy; }
+fn quat_conj_z(qx: int, qy: int, qz: int, qw: int): int { return 0 - qz; }
+fn quat_conj_w(qx: int, qy: int, qz: int, qw: int): int { return qw; }
+
+// ─── Magnitude squared ×10000 ─────────────────────────────────────────────────
+// For unit quaternion: should equal 10000 (= 1.0 in ×10000 scale)
+fn quat_mag_sq(qx: int, qy: int, qz: int, qw: int): int {
+    return mulfix(qx, qx) + mulfix(qy, qy) + mulfix(qz, qz) + mulfix(qw, qw);
+}
+
+// ─── Dot product ×10000 ──────────────────────────────────────────────────────
+fn quat_dot(ax: int, ay: int, az: int, aw: int, bx: int, by: int, bz: int, bw: int): int {
+    return mulfix(ax, bx) + mulfix(ay, by) + mulfix(az, bz) + mulfix(aw, bw);
+}
+
+// ─── SLERP (spherical linear interpolation) ──────────────────────────────────
+// Interpolate between two quaternions at t ∈ [0, 1000] (×1000)
+// For small angles, uses LERP + normalize approximation (cheaper, good enough for MC)
+// t=0 → a, t=1000 → b
+
+// ─── SLERP normalize helper ───────────────────────────────────────────────────
+// Components are ×10000. Normalize: mag² = (rx²+ry²+rz²+rw²)/10000
+// mag = sqrt((sum_sq)/10000) * 100   (in ×10000 units: actual ×100 for isqrt)
+// Normalize: component * 10000 / (isqrt(sum_sq / 100))
+// This gives correctly scaled unit quaternion ×10000.
+
+fn _quat_slerp_mag(rx: int, ry: int, rz: int, rw: int): int {
+    // sum_sq = rx²+ry²+rz²+rw² (each component ×10000, so sum_sq ×10000²/10000 = ×10000)
+    // Use integer arithmetic: sum_sq / 100 to fit isqrt
+    let ss: int = rx * rx / 100 + ry * ry / 100 + rz * rz / 100 + rw * rw / 100;
+    return isqrt(ss);  // returns ≈ 1000 for unit quaternion
+}
+
+fn quat_slerp_x(ax: int, ay: int, az: int, aw: int, bx: int, by: int, bz: int, bw: int, t: int): int {
+    let inv_t: int = 1000 - t;
+    let rx: int = ax * inv_t / 1000 + bx * t / 1000;
+    let ry: int = ay * inv_t / 1000 + by * t / 1000;
+    let rz: int = az * inv_t / 1000 + bz * t / 1000;
+    let rw: int = aw * inv_t / 1000 + bw * t / 1000;
+    let mag: int = _quat_slerp_mag(rx, ry, rz, rw);
+    if (mag == 0) { return 0; }
+    return rx * 1000 / mag;
+}
+
+fn quat_slerp_y(ax: int, ay: int, az: int, aw: int, bx: int, by: int, bz: int, bw: int, t: int): int {
+    let inv_t: int = 1000 - t;
+    let rx: int = ax * inv_t / 1000 + bx * t / 1000;
+    let ry: int = ay * inv_t / 1000 + by * t / 1000;
+    let rz: int = az * inv_t / 1000 + bz * t / 1000;
+    let rw: int = aw * inv_t / 1000 + bw * t / 1000;
+    let mag: int = _quat_slerp_mag(rx, ry, rz, rw);
+    if (mag == 0) { return 0; }
+    return ry * 1000 / mag;
+}
+
+fn quat_slerp_z(ax: int, ay: int, az: int, aw: int, bx: int, by: int, bz: int, bw: int, t: int): int {
+    let inv_t: int = 1000 - t;
+    let rx: int = ax * inv_t / 1000 + bx * t / 1000;
+    let ry: int = ay * inv_t / 1000 + by * t / 1000;
+    let rz: int = az * inv_t / 1000 + bz * t / 1000;
+    let rw: int = aw * inv_t / 1000 + bw * t / 1000;
+    let mag: int = _quat_slerp_mag(rx, ry, rz, rw);
+    if (mag == 0) { return 0; }
+    return rz * 1000 / mag;
+}
+
+fn quat_slerp_w(ax: int, ay: int, az: int, aw: int, bx: int, by: int, bz: int, bw: int, t: int): int {
+    let inv_t: int = 1000 - t;
+    let rx: int = ax * inv_t / 1000 + bx * t / 1000;
+    let ry: int = ay * inv_t / 1000 + by * t / 1000;
+    let rz: int = az * inv_t / 1000 + bz * t / 1000;
+    let rw: int = aw * inv_t / 1000 + bw * t / 1000;
+    let mag: int = _quat_slerp_mag(rx, ry, rz, rw);
+    if (mag == 0) { return 10000; }
+    return rw * 1000 / mag;
+}
+
+// ─── Euler angles → Quaternion (YXZ order, MC convention) ────────────────────
+// yaw: Y-axis rotation (°), pitch: X-axis rotation (°), roll: Z-axis rotation (°)
+// YXZ order: first yaw, then pitch, then roll
+
+fn quat_euler_x(yaw: int, pitch: int, roll: int): int {
+    let cy: int = cos_fixed(yaw / 2) * 10;
+    let sy: int = sin_fixed(yaw / 2) * 10;
+    let cp: int = cos_fixed(pitch / 2) * 10;
+    let sp: int = sin_fixed(pitch / 2) * 10;
+    let cr: int = cos_fixed(roll / 2) * 10;
+    let sr: int = sin_fixed(roll / 2) * 10;
+    // x = cy*sp*cr + sy*cp*sr
+    return mulfix(mulfix(cy, sp), cr) + mulfix(mulfix(sy, cp), sr);
+}
+
+fn quat_euler_y(yaw: int, pitch: int, roll: int): int {
+    let cy: int = cos_fixed(yaw / 2) * 10;
+    let sy: int = sin_fixed(yaw / 2) * 10;
+    let cp: int = cos_fixed(pitch / 2) * 10;
+    let sp: int = sin_fixed(pitch / 2) * 10;
+    let cr: int = cos_fixed(roll / 2) * 10;
+    let sr: int = sin_fixed(roll / 2) * 10;
+    // y = sy*cp*cr - cy*sp*sr
+    return mulfix(mulfix(sy, cp), cr) - mulfix(mulfix(cy, sp), sr);
+}
+
+fn quat_euler_z(yaw: int, pitch: int, roll: int): int {
+    let cy: int = cos_fixed(yaw / 2) * 10;
+    let sy: int = sin_fixed(yaw / 2) * 10;
+    let cp: int = cos_fixed(pitch / 2) * 10;
+    let sp: int = sin_fixed(pitch / 2) * 10;
+    let cr: int = cos_fixed(roll / 2) * 10;
+    let sr: int = sin_fixed(roll / 2) * 10;
+    // z = cy*cp*sr - sy*sp*cr
+    return mulfix(mulfix(cy, cp), sr) - mulfix(mulfix(sy, sp), cr);
+}
+
+fn quat_euler_w(yaw: int, pitch: int, roll: int): int {
+    let cy: int = cos_fixed(yaw / 2) * 10;
+    let sy: int = sin_fixed(yaw / 2) * 10;
+    let cp: int = cos_fixed(pitch / 2) * 10;
+    let sp: int = sin_fixed(pitch / 2) * 10;
+    let cr: int = cos_fixed(roll / 2) * 10;
+    let sr: int = sin_fixed(roll / 2) * 10;
+    // w = cy*cp*cr + sy*sp*sr
+    return mulfix(mulfix(cy, cp), cr) + mulfix(mulfix(sy, sp), sr);
+}

package/src/stdlib/random.mcrs

@@ -47,7 +47,7 @@ fn random_bool(seed: int): int {
 // pcg_next_lo(state_lo, state_hi): advance PCG state (low word).
 // Returns new low word. Use with pcg_next_hi.
 fn pcg_next_lo(state_lo: int): int {
-    return state_lo * 747796405 + 2891336453;
+    return state_lo * 747796405 + -1403630843;
 }
 
 // pcg_next_hi(state_lo, state_hi): advance PCG state (high word).
@@ -65,3 +65,48 @@ fn pcg_output(state_lo: int): int {
     if (xored < 0) { xored = 0 - xored; }
     return xored;
 }
+
+// ─── Statistical distributions ───────────────────────────────────────────────
+
+// _binom_loop(n, p, seed, acc): recursive helper for binomial_sample
+fn _binom_loop(n: int, p: int, seed: int, acc: int): int {
+    if (n <= 0) { return acc; }
+    let s2: int = next_lcg(seed);
+    let r: int = s2;
+    if (r < 0) { r = 0 - r; }
+    let hit: int = 0;
+    if (r % 10000 < p) { hit = 1; }
+    return _binom_loop(n - 1, p, s2, acc + hit);
+}
+
+// binomial_sample(n, p_x10000, seed): count successes in n Bernoulli trials
+// p_x10000: probability ×10000 (e.g. 5000 = 0.5 = 50%)
+// seed: LCG seed (any non-zero int)
+// Returns: number of successes ∈ [0, n]
+fn binomial_sample(n: int, p_x10000: int, seed: int): int {
+    return _binom_loop(n, p_x10000, seed, 0);
+}
+
+// _hyper_loop: recursive helper for hypergeometric_sample
+// rem_pop: remaining population, rem_succ: remaining successes, draws: draws left
+// seed: LCG seed, acc: successes so far
+fn _hyper_loop(rem_pop: int, rem_succ: int, draws: int, seed: int, acc: int): int {
+    if (draws <= 0) { return acc; }
+    if (rem_pop <= 0) { return acc; }
+    // Probability of success = rem_succ / rem_pop, scaled ×10000
+    let p: int = rem_succ * 10000 / rem_pop;
+    let s2: int = next_lcg(seed);
+    let r: int = s2;
+    if (r < 0) { r = 0 - r; }
+    let success: int = 0;
+    if (r % 10000 < p) { success = 1; }
+    return _hyper_loop(rem_pop - 1, rem_succ - success, draws - 1, s2, acc + success);
+}
+
+// hypergeometric_sample(pop_size, success_states, draws, seed):
+// Simulate drawing `draws` items without replacement from a population of `pop_size`
+// items of which `success_states` are successes.
+// seed: LCG seed. Returns: number of successes drawn ∈ [0, min(draws, success_states)].
+fn hypergeometric_sample(pop_size: int, success_states: int, draws: int, seed: int): int {
+    return _hyper_loop(pop_size, success_states, draws, seed, 0);
+}