redscript-mc 2.5.0 → 2.6.2

package/src/stdlib/dialog.mcrs

@@ -0,0 +1,55 @@
+// MC tellraw dialog system — high-level wrapper for player messaging.
+// Usage: import "stdlib/dialog.mcrs"
+//
+// Provides tellraw-based chat messages, title/subtitle display, and
+// actionbar notifications. All text is sent as raw JSON chat components.
+
+module library
+
+/// Send a plain white message to a player.
+fn dialog_say(p: selector, msg: string) {
+    raw("tellraw {p} {\"text\":\"{msg}\"}");
+}
+
+/// Broadcast a plain white message to all players.
+fn dialog_broadcast(msg: string) {
+    raw("tellraw @a {\"text\":\"{msg}\"}");
+}
+
+/// Send a colored message to a player.
+/// color: 0=white, 1=red, 2=green, 3=gold, 4=aqua
+fn dialog_say_color(p: selector, msg: string, color: int) {
+    if (color == 1) {
+        raw("tellraw {p} {\"text\":\"{msg}\",\"color\":\"red\"}");
+    } else {
+        if (color == 2) {
+            raw("tellraw {p} {\"text\":\"{msg}\",\"color\":\"green\"}");
+        } else {
+            if (color == 3) {
+                raw("tellraw {p} {\"text\":\"{msg}\",\"color\":\"gold\"}");
+            } else {
+                if (color == 4) {
+                    raw("tellraw {p} {\"text\":\"{msg}\",\"color\":\"aqua\"}");
+                } else {
+                    raw("tellraw {p} {\"text\":\"{msg}\",\"color\":\"white\"}");
+                }
+            }
+        }
+    }
+}
+
+/// Display a large title and subtitle on a player's screen.
+fn dialog_title(p: selector, title: string, subtitle: string) {
+    raw("title {p} title {\"text\":\"{title}\"}");
+    raw("title {p} subtitle {\"text\":\"{subtitle}\"}");
+}
+
+/// Clear the title from a player's screen.
+fn dialog_title_clear(p: selector) {
+    raw("title {p} clear");
+}
+
+/// Display a message on the player's actionbar (above hotbar).
+fn dialog_actionbar(p: selector, msg: string) {
+    raw("title {p} actionbar {\"text\":\"{msg}\"}");
+}

package/src/stdlib/ecs.mcrs

@@ -0,0 +1,238 @@
+// ecs.mcrs — Entity Component System for Minecraft Java datapacks.
+//
+// ─── What is ECS? ────────────────────────────────────────────────────────────
+//
+// Entity Component System (ECS) is a data-driven pattern for attaching typed
+// "components" (structured data) to game entities. In Minecraft Java Edition,
+// datapacks have no built-in component system (unlike Bedrock). ECS fills this
+// gap by using:
+//
+//   - Scoreboard objectives  → integer fields (HP, velocity, etc.)
+//   - Entity tags            → component presence flags
+//   - NBT storage            → complex/string data (via raw())
+//
+// Without ECS you'd write 100+ lines of raw NBT per component type, hard-coded
+// per entity. With ecs.mcrs, component state is captured in an int[] "state
+// array" that can be passed around, modified, and read with typed helpers.
+//
+// ─── Usage example ───────────────────────────────────────────────────────────
+//
+//   // Initialise health for entity with score-ID 42, max HP 100
+//   let hp_state: int[] = ecs_health_init(42, 100)
+//
+//   // Take damage
+//   hp_state = ecs_health_damage(hp_state, 30)
+//
+//   // Initialise velocity (×1000 fixed-point)
+//   let vel_state: int[] = ecs_vel_init(1000, 0, 500)  // 1.0, 0.0, 0.5
+//
+//   // Apply gravity each tick
+//   vel_state = ecs_vel_apply_gravity(vel_state, 980)
+//
+//   // Tag the entity in MC (run via raw() or a separate mcfunction):
+//   //   tag @e[scores={ecs_entity=42}] add ecs_has_health
+//   //   tag @e[scores={ecs_entity=42}] add ecs_has_velocity
+//
+// ─── Tag naming convention ───────────────────────────────────────────────────
+//
+//   Entities should carry tag: ecs_has_<comp_name>
+//   e.g.  ecs_has_health, ecs_has_velocity, ecs_has_damage
+//
+//   This lets selectors filter: @e[tag=ecs_has_health]
+//
+// ─── Component type IDs ──────────────────────────────────────────────────────
+
+module library
+
+// Pre-defined component type IDs (used with ecs_register / ecs_is_registered)
+let ECS_COMP_HEALTH: int = 1
+let ECS_COMP_VELOCITY: int = 2
+let ECS_COMP_DAMAGE: int = 3
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ECS Registry
+// Tracks which component types are active in this datapack.
+// Registry is a 16-element int[] where registry[comp_id] == 1 means registered.
+// ─────────────────────────────────────────────────────────────────────────────
+
+// ecs_registry_new(): allocate a blank 16-slot registry
+fn ecs_registry_new(): int[] {
+    let reg: int[] = []
+    let i: int = 0
+    while (i < 16) {
+        reg.push(0)
+        i = i + 1
+    }
+    return reg
+}
+
+// ecs_register(reg, comp_id): mark comp_id as registered; returns updated reg
+fn ecs_register(reg: int[], comp_id: int): int[] {
+    if (comp_id >= 0) {
+        if (comp_id < 16) {
+            reg[comp_id] = 1
+        }
+    }
+    return reg
+}
+
+// ecs_is_registered(reg, comp_id): 1 if registered, 0 otherwise
+fn ecs_is_registered(reg: int[], comp_id: int): int {
+    if (comp_id >= 0) {
+        if (comp_id < 16) {
+            return reg[comp_id]
+        }
+    }
+    return 0
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Health Component
+//
+// State layout (int[], 8 elements):
+//   [0] entity_score  — scoreboard score used as entity identifier
+//   [1] current_hp    — current hit points
+//   [2] max_hp        — maximum hit points
+//   [3..7] reserved   — 0
+// ─────────────────────────────────────────────────────────────────────────────
+
+// ecs_health_init(entity_score, max_hp): create a health component state
+// Sets current_hp = max_hp (full health at spawn)
+fn ecs_health_init(entity_score: int, max_hp: int): int[] {
+    let s: int[] = []
+    s.push(entity_score)
+    s.push(max_hp)
+    s.push(max_hp)
+    s.push(0)
+    s.push(0)
+    s.push(0)
+    s.push(0)
+    s.push(0)
+    return s
+}
+
+// ecs_health_get(state): return current HP
+fn ecs_health_get(state: int[]): int {
+    return state[1]
+}
+
+// ecs_health_max(state): return maximum HP
+fn ecs_health_max(state: int[]): int {
+    return state[2]
+}
+
+// ecs_health_set(state, hp): set current HP (clamped to [0, max]), return state
+fn ecs_health_set(state: int[], hp: int): int[] {
+    let clamped: int = hp
+    if (clamped < 0) { clamped = 0 }
+    if (clamped > state[2]) { clamped = state[2] }
+    state[1] = clamped
+    return state
+}
+
+// ecs_health_damage(state, amount): subtract amount from HP, clamp to 0
+fn ecs_health_damage(state: int[], amount: int): int[] {
+    let next: int = state[1] - amount
+    if (next < 0) { next = 0 }
+    state[1] = next
+    return state
+}
+
+// ecs_health_heal(state, amount): add amount to HP, clamp to max
+fn ecs_health_heal(state: int[], amount: int): int[] {
+    let next: int = state[1] + amount
+    if (next > state[2]) { next = state[2] }
+    state[1] = next
+    return state
+}
+
+// ecs_health_is_dead(state): 1 if HP <= 0, else 0
+fn ecs_health_is_dead(state: int[]): int {
+    if (state[1] <= 0) { return 1 }
+    return 0
+}
+
+// ecs_health_pct(state): HP percentage as fixed-point ×10000
+// e.g. 50 HP out of 100 max → 5000  (= 50.00%)
+fn ecs_health_pct(state: int[]): int {
+    if (state[2] <= 0) { return 0 }
+    return state[1] * 10000 / state[2]
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Velocity Component
+//
+// State layout (int[], 8 elements):
+//   [0] vx  — x velocity ×1000 fixed-point
+//   [1] vy  — y velocity ×1000 fixed-point
+//   [2] vz  — z velocity ×1000 fixed-point
+//   [3..7] reserved — 0
+//
+// Fixed-point convention: 1000 = 1.0 block/tick
+// ─────────────────────────────────────────────────────────────────────────────
+
+// ecs_vel_init(vx, vy, vz): create a velocity component state
+fn ecs_vel_init(vx: int, vy: int, vz: int): int[] {
+    let s: int[] = []
+    s.push(vx)
+    s.push(vy)
+    s.push(vz)
+    s.push(0)
+    s.push(0)
+    s.push(0)
+    s.push(0)
+    s.push(0)
+    return s
+}
+
+// ecs_vel_get_x(state): return vx
+fn ecs_vel_get_x(state: int[]): int {
+    return state[0]
+}
+
+// ecs_vel_get_y(state): return vy
+fn ecs_vel_get_y(state: int[]): int {
+    return state[1]
+}
+
+// ecs_vel_get_z(state): return vz
+fn ecs_vel_get_z(state: int[]): int {
+    return state[2]
+}
+
+// ecs_vel_set(state, vx, vy, vz): set all velocity components, return state
+fn ecs_vel_set(state: int[], vx: int, vy: int, vz: int): int[] {
+    state[0] = vx
+    state[1] = vy
+    state[2] = vz
+    return state
+}
+
+// ecs_vel_speed(state): magnitude of velocity vector ×1000
+// Uses sqrt_fixed: speed = sqrt(vx² + vy² + vz²) in fixed-point units
+// e.g. ecs_vel_speed([3000, 4000, 0, ...]) == 5000
+fn ecs_vel_speed(state: int[]): int {
+    let vx: int = state[0]
+    let vy: int = state[1]
+    let vz: int = state[2]
+    // mag_sq in units of ×1000² = ×1000000
+    // sqrt_fixed expects value in same ×1000 scale, so divide by 1000 first
+    let mag_sq: int = vx * vx / 1000 + vy * vy / 1000 + vz * vz / 1000
+    return sqrt_fixed(mag_sq)
+}
+
+// ecs_vel_apply_gravity(state, gravity_fx): subtract gravity from vy
+// gravity_fx is fixed-point ×1000 (e.g. 980 ≈ 0.980 blocks/tick², roughly 0.08g per tick)
+fn ecs_vel_apply_gravity(state: int[], gravity_fx: int): int[] {
+    state[1] = state[1] - gravity_fx
+    return state
+}
+
+// ecs_vel_damp(state, factor_fx): multiply each velocity component by factor_fx/10000
+// factor_fx: friction factor ×10000 (e.g. 8000 = 0.80 damping)
+fn ecs_vel_damp(state: int[], factor_fx: int): int[] {
+    state[0] = state[0] * factor_fx / 10000
+    state[1] = state[1] * factor_fx / 10000
+    state[2] = state[2] * factor_fx / 10000
+    return state
+}

package/src/stdlib/events.mcrs

@@ -0,0 +1,29 @@
+module events
+// RedScript event dispatcher — detects MC events and dispatches to function tags.
+// Handlers register via @on(EventType) decorator (compiler-generated tag JSON).
+
+@load fn __events_load() {
+    raw("scoreboard objectives add rs.deaths deathCount")
+    raw("scoreboard objectives add rs.kills totalKillCount")
+    raw("scoreboard objectives add rs.item_use minecraft.used:minecraft.carrot_on_a_stick")
+}
+
+@tick fn __events_tick() {
+    // PlayerJoin: players without rs.joined tag
+    raw("execute as @a[tag=!rs.joined] run function #rs:on_player_join")
+    raw("tag @a[tag=!rs.joined] add rs.joined")
+
+    // PlayerDeath
+    raw("execute as @a[scores={rs.deaths=1..}] run function #rs:on_player_death")
+    raw("scoreboard players set @a rs.deaths 0")
+
+    // EntityKill
+    raw("execute as @a[scores={rs.kills=1..}] run function #rs:on_entity_kill")
+    raw("scoreboard players set @a rs.kills 0")
+
+    // ItemUse (carrot_on_a_stick by default)
+    raw("execute as @a[scores={rs.item_use=1..}] run function #rs:on_item_use")
+    raw("scoreboard players set @a rs.item_use 0")
+
+    // BlockBreak requires advancement JSON (not yet implemented)
+}

package/src/stdlib/expr.mcrs

@@ -0,0 +1,117 @@
+// expr.mcrs — RPN (Reverse Polish Notation) expression evaluator.
+//
+// All values use ×10000 fixed-point scale.
+// For dynamic expression evaluation: game formulas, configurable easing, etc.
+//
+// Requires: import "stdlib/math" for sin_fixed, cos_fixed, sqrt_fx, abs
+
+module library;
+
+// ─── Token encoding ───────────────────────────────────────────────────────────
+//
+// Positive tokens  — literal value (already ×10000)
+// -10000           — variable x (substituted with the x parameter)
+// -1  = ADD        — pop b, a; push a + b
+// -2  = SUB        — pop b, a; push a - b
+// -3  = MUL        — pop b, a; push a * b / 10000  (fixed-point multiply)
+// -4  = DIV        — pop b, a; push a * 10000 / b  (fixed-point divide)
+// -5  = SIN        — pop a (degrees ×10000); push sin_fixed(a/10000) * 10
+// -6  = COS        — pop a (degrees ×10000); push cos_fixed(a/10000) * 10
+// -7  = SQRT       — pop a; push sqrt_fx(a)
+// -8  = ABS        — pop a; push abs(a)
+//
+// Stack: 16-element internal int array, top tracked by sp index.
+//
+// Example: 2*x + 1 in RPN: [20000, -10000, -3, 10000, -1]
+//   With x = 15000 (1.5): result = mulfix10k(20000, 15000) + 10000
+//                                 = 30000 + 10000 = 40000 (4.0)
+
+// expr_eval(tokens, n, x): evaluate n RPN tokens, substituting x for -10000.
+// Returns the top-of-stack value (×10000 scale).
+// Undefined behaviour if the token stream is malformed (stack underflow/overflow).
+fn expr_eval(tokens: int[], n: int, x: int): int {
+    let stack: int[] = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0];
+    let sp: int = 0;  // stack pointer: number of items on stack
+
+    let i: int = 0;
+    while (i < n) {
+        let tok: int = tokens[i];
+
+        if (tok == -10000) {
+            // Variable x
+            stack[sp] = x;
+            sp = sp + 1;
+        } else if (tok == -1) {
+            // ADD
+            let b: int = stack[sp - 1];
+            let a: int = stack[sp - 2];
+            sp = sp - 2;
+            stack[sp] = a + b;
+            sp = sp + 1;
+        } else if (tok == -2) {
+            // SUB
+            let b: int = stack[sp - 1];
+            let a: int = stack[sp - 2];
+            sp = sp - 2;
+            stack[sp] = a - b;
+            sp = sp + 1;
+        } else if (tok == -3) {
+            // MUL (fixed-point ×10000)
+            let b: int = stack[sp - 1];
+            let a: int = stack[sp - 2];
+            sp = sp - 2;
+            stack[sp] = a * b / 10000;
+            sp = sp + 1;
+        } else if (tok == -4) {
+            // DIV (fixed-point ×10000)
+            let b: int = stack[sp - 1];
+            let a: int = stack[sp - 2];
+            sp = sp - 2;
+            if (b == 0) {
+                stack[sp] = 0;
+            } else {
+                stack[sp] = a * 10000 / b;
+            }
+            sp = sp + 1;
+        } else if (tok == -5) {
+            // SIN: input degrees ×10000, result ×10000
+            // sin_fixed takes integer degrees (×1), returns ×1000
+            let a: int = stack[sp - 1];
+            sp = sp - 1;
+            let deg: int = a / 10000;
+            stack[sp] = sin_fixed(deg) * 10;
+            sp = sp + 1;
+        } else if (tok == -6) {
+            // COS: input degrees ×10000, result ×10000
+            let a: int = stack[sp - 1];
+            sp = sp - 1;
+            let deg: int = a / 10000;
+            stack[sp] = cos_fixed(deg) * 10;
+            sp = sp + 1;
+        } else if (tok == -7) {
+            // SQRT: input ×10000, result ×10000
+            let a: int = stack[sp - 1];
+            sp = sp - 1;
+            stack[sp] = sqrt_fx(a);
+            sp = sp + 1;
+        } else if (tok == -8) {
+            // ABS
+            let a: int = stack[sp - 1];
+            sp = sp - 1;
+            if (a < 0) {
+                stack[sp] = 0 - a;
+            } else {
+                stack[sp] = a;
+            }
+            sp = sp + 1;
+        } else {
+            // Positive literal (or any unrecognised token treated as literal)
+            stack[sp] = tok;
+            sp = sp + 1;
+        }
+
+        i = i + 1;
+    }
+
+    return stack[sp - 1];
+}

package/src/stdlib/fft.mcrs

@@ -0,0 +1,177 @@
+// fft.mcrs — Discrete Fourier Transform (DFT) for RedScript datapacks.
+//
+// ── DFT vs FFT ───────────────────────────────────────────────────────────────
+//
+// A true Cooley-Tukey FFT requires recursion (O(n log n)), which RedScript
+// forbids in datapacks. This module implements the O(n²) straight DFT, which
+// is practical for the small transform sizes that datapacks ever need (n ≤ 16).
+//
+// For n=4:   DFT=16 mults,  FFT=8 mults  → comparable
+// For n=8:   DFT=64 mults,  FFT=24 mults → 2.7× slower
+// For n=16:  DFT=256 mults, FFT=64 mults → 4× slower
+//
+// At n=16 (the hard limit recommended here), the DFT still runs in well under
+// 1 ms per server tick, making it acceptable for Minecraft datapacks.
+//
+// ── Fixed-point convention ────────────────────────────────────────────────────
+//
+// Inputs and outputs use ×10000 scaling:
+//   1.0  → 10000
+//   0.5  → 5000
+//   -1.0 → -10000
+//
+// Trig (sin_fixed / cos_fixed from math.mcrs) uses ×1000 scaling.
+// When multiplying x[n] (×10000) × cos/sin (×1000) we divide by 1000 to keep
+// the output in ×10000 scale.
+//
+// ── Limitation ───────────────────────────────────────────────────────────────
+//
+// n ≤ 16 is strongly recommended. The DFT inner loop is O(n²): n=16 runs 256
+// multiply-divide pairs per call, and n=32 would run 1024, risking tick lag.
+//
+// ── Usage example: detect dominant frequency ─────────────────────────────────
+//
+//   // Sample 4 frames of a signal at 4 Hz
+//   let sig: int[] = [10000, 0, -10000, 0]   // 1 Hz square wave
+//   let re: int[] = [0, 0, 0, 0]
+//   let im: int[] = [0, 0, 0, 0]
+//   dft_real(sig, 4, re, im)
+//
+//   // Find bin with maximum power
+//   let max_power: int = 0
+//   let dominant_k: int = 0
+//   let k: int = 0
+//   while (k < 4) {
+//       let pw: int = dft_power(re, im, k)
+//       if (pw > max_power) { max_power = pw; dominant_k = k; }
+//       k = k + 1
+//   }
+//   // dominant frequency = dft_freq_bin(4, 4, dominant_k)  → 1 Hz
+
+module library;
+
+// ─── dft_noop ────────────────────────────────────────────────────────────────
+// Default onDone callback for dft_coro. Does nothing. Replace with your own.
+fn dft_noop(): void {
+    let _unused: int = 0;
+}
+
+// ─── dft_real ────────────────────────────────────────────────────────────────
+//
+// Compute the Discrete Fourier Transform of `input[0..n-1]`.
+//
+// X[k] = Σ_{j=0}^{n-1}  x[j] * cos(360*k*j/n)  (real part)
+//                       - x[j] * sin(360*k*j/n)  (imaginary part)
+//
+// Parameters:
+//   input  — signal samples in fixed-point ×10000
+//   n      — number of samples (≤ 16 recommended)
+//   out_re — output array for real parts  (×10000, must be pre-allocated to n)
+//   out_im — output array for imaginary parts (×10000, must be pre-allocated to n)
+//
+// The caller must pre-fill out_re and out_im to zero before calling.
+fn dft_real(input: int[], n: int, out_re: int[], out_im: int[]) {
+    let k: int = 0;
+    while (k < n) {
+        let sum_re: int = 0;
+        let sum_im: int = 0;
+        let j: int = 0;
+        while (j < n) {
+            // angle in integer degrees (sin_fixed/cos_fixed take plain degrees 0-360)
+            let angle: int = 360 * k * j / n;
+            let c: int = cos_fixed(angle);   // ×1000
+            let s: int = sin_fixed(angle);   // ×1000
+            // x[j] is ×10000, c/s are ×1000 → product is ×10000000 → /1000 → ×10000
+            sum_re = sum_re + input[j] * c / 1000;
+            sum_im = sum_im - input[j] * s / 1000;
+            j = j + 1;
+        }
+        out_re[k] = sum_re;
+        out_im[k] = sum_im;
+        k = k + 1;
+    }
+}
+
+// ─── dft_magnitude ───────────────────────────────────────────────────────────
+//
+// Return |X[k]| = sqrt(re[k]² + im[k]²) in ×10000 fixed-point.
+//
+// Uses sqrt_fixed from math.mcrs (which returns ×1000).
+// We scale the result ×10 to convert from ×1000 back to ×10000 output scale.
+//
+// Note: squaring ×10000 values can reach ~10^9 per term, which fits in int32
+// as long as |re[k]| and |im[k]| stay below ~46340 (≈ 4.6× the input peak).
+// For typical signals this is fine; for amplitudes > 10000 per sample, divide
+// inputs by a scale factor before calling to avoid overflow.
+fn dft_magnitude(re: int[], im: int[], k: int): int {
+    // sum_sq is in ×10000² = ×100000000 scale
+    // We want the result in ×10000, so we compute sqrt( re² + im² ) directly.
+    // sqrt_fixed(x) = sqrt(x * 1000) / 1 = isqrt(x * 1000)
+    // We need sqrt(re²+im²) in ×10000, so:
+    //   sqrt_fixed takes x in ×10000 → returns sqrt(x) in ×10000 (approx)
+    // Actually sqrt_fixed(x) returns sqrt(x) * 1000 / sqrt(1000) ...
+    // Simplest: compute isqrt(re[k]*re[k] + im[k]*im[k]) which gives ×10000.
+    let r: int = re[k];
+    let i: int = im[k];
+    // Both are ×10000. isqrt(r*r + i*i) = sqrt(r²+i²) still in ×10000 scale.
+    // e.g. r=20000, i=0 → isqrt(400000000) = 20000 ✓
+    let sum_sq: int = r * r / 10000 + i * i / 10000;
+    return isqrt(sum_sq * 10000);
+}
+
+// ─── dft_power ───────────────────────────────────────────────────────────────
+//
+// Return the power spectrum value for bin k: re[k]²/10000 + im[k]²/10000.
+//
+// Division by 10000 prevents int32 overflow for values up to ~46340 (×10000).
+// The result is in ×10000 scale (power units).
+fn dft_power(re: int[], im: int[], k: int): int {
+    let r: int = re[k];
+    let i: int = im[k];
+    return r * r / 10000 + i * i / 10000;
+}
+
+// ─── dft_coro ────────────────────────────────────────────────────────────────
+//
+// Coroutine variant of dft_real.  Processes 4 output bins (k values) per tick.
+// Results are pushed into out_re and out_im as each batch completes.
+// Use onDone for notification when the full DFT is finished.
+//
+// Parameters: same as dft_real.
+// The caller must pre-fill out_re and out_im to zero before starting.
+@coroutine(batch=4, onDone=dft_noop)
+fn dft_coro(input: int[], n: int, out_re: int[], out_im: int[]) {
+    let k: int = 0;
+    while (k < n) {
+        let sum_re: int = 0;
+        let sum_im: int = 0;
+        let j: int = 0;
+        while (j < n) {
+            let angle: int = 360 * k * j / n;
+            let c: int = cos_fixed(angle);
+            let s: int = sin_fixed(angle);
+            sum_re = sum_re + input[j] * c / 1000;
+            sum_im = sum_im - input[j] * s / 1000;
+            j = j + 1;
+        }
+        out_re[k] = sum_re;
+        out_im[k] = sum_im;
+        k = k + 1;
+    }
+}
+
+// ─── dft_freq_bin ────────────────────────────────────────────────────────────
+//
+// Return the frequency (in Hz) corresponding to DFT bin k.
+//
+//   freq = sample_rate_hz * k / n
+//
+// Example: dft_freq_bin(44100, 16, 4) = 44100 * 4 / 16 = 11025 Hz
+//
+// Parameters:
+//   sample_rate_hz — sampling rate in Hz (e.g. 20 for Minecraft tick rate)
+//   n              — transform size
+//   k              — bin index (0 .. n-1)
+fn dft_freq_bin(sample_rate_hz: int, n: int, k: int): int {
+    return sample_rate_hz * k / n;
+}