redscript-mc 3.0.1 → 3.0.2

package/redscript-docs/docs/en/stdlib/queue.md

@@ -0,0 +1,134 @@
+# Queue
+
+> Auto-generated from `src/stdlib/queue.mcrs` — do not edit manually.
+
+## API
+
+- [queue_push](#queue-push)
+- [queue_pop](#queue-pop)
+- [queue_peek](#queue-peek)
+- [queue_size](#queue-size)
+- [queue_empty](#queue-empty)
+- [queue_clear](#queue-clear)
+
+---
+
+## `queue_push` <Badge type="info" text="v3.0.0" />
+
+Enqueue a value into the queue.
+
+The value is appended to the end of `storage rs:arrays Queue`.
+
+```redscript
+fn queue_push(val: int)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `val` | Value to enqueue |
+
+**Example**
+
+```redscript
+queue_push(42)
+```
+
+---
+
+## `queue_pop` <Badge type="info" text="v3.0.0" />
+
+Dequeue and return the front value.
+
+Advances the head pointer by one. If the queue is empty, returns `-1`.
+
+```redscript
+fn queue_pop(): int
+```
+
+**Returns:** Front value, or -1 if empty
+
+**Example**
+
+```redscript
+let v: int = queue_pop()
+```
+
+---
+
+## `queue_peek` <Badge type="info" text="v3.0.0" />
+
+Peek at the front value without removing it.
+
+If the queue is empty, returns `-1`.
+
+```redscript
+fn queue_peek(): int
+```
+
+**Returns:** Front value, or -1 if empty
+
+**Example**
+
+```redscript
+let front: int = queue_peek()
+```
+
+---
+
+## `queue_size` <Badge type="info" text="v3.0.0" />
+
+Get the number of elements in the queue.
+
+This is the count of un-popped elements: `raw_size - head`.
+
+```redscript
+fn queue_size(): int
+```
+
+**Returns:** Queue size
+
+**Example**
+
+```redscript
+let n: int = queue_size()
+```
+
+---
+
+## `queue_empty` <Badge type="info" text="v3.0.0" />
+
+Check if the queue is empty.
+
+```redscript
+fn queue_empty(): int
+```
+
+**Returns:** 1 if empty, 0 otherwise
+
+**Example**
+
+```redscript
+if (queue_empty() == 1) { }
+```
+
+---
+
+## `queue_clear` <Badge type="info" text="v3.0.0" />
+
+Clear all elements from the queue.
+
+Resets `storage rs:arrays Queue` to an empty list and the head pointer to 0.
+
+```redscript
+fn queue_clear()
+```
+
+**Example**
+
+```redscript
+queue_clear()
+```
+
+---

package/redscript-docs/docs/en/stdlib/random.md

@@ -0,0 +1,223 @@
+# Random
+
+> Auto-generated from `src/stdlib/random.mcrs` — do not edit manually.
+
+## API
+
+- [next_lcg](#next-lcg)
+- [random_range](#random-range)
+- [random_bool](#random-bool)
+- [pcg_next_lo](#pcg-next-lo)
+- [pcg_next_hi](#pcg-next-hi)
+- [pcg_output](#pcg-output)
+- [binomial_sample](#binomial-sample)
+- [hypergeometric_sample](#hypergeometric-sample)
+
+---
+
+## `next_lcg` <Badge type="info" text="v1.0.0" />
+
+Advance the LCG state by one step, returning the next pseudo-random int32.
+The returned value is also the new seed for the next call.
+
+```redscript
+fn next_lcg(seed: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `seed` | Current LCG state (any non-zero integer to start) |
+
+**Returns:** Next pseudo-random int32 (also serves as next seed)
+
+**Example**
+
+```redscript
+let seed: int = 12345
+seed = next_lcg(seed)
+seed = next_lcg(seed)  // advance two steps
+```
+
+---
+
+## `random_range` <Badge type="info" text="v1.0.0" />
+
+Generate a pseudo-random integer in the range [lo, hi).
+
+```redscript
+fn random_range(seed: int, lo: int, hi: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `seed` | LCG output value (result of next_lcg) |
+| `lo` | Inclusive lower bound |
+| `hi` | Exclusive upper bound (must be > lo) |
+
+**Returns:** Integer in [lo, hi)
+
+**Example**
+
+```redscript
+seed = next_lcg(seed)
+let roll: int = random_range(seed, 1, 7)  // dice roll: 1-6
+```
+
+---
+
+## `random_bool` <Badge type="info" text="v1.0.0" />
+
+Generate a pseudo-random boolean (0 or 1) with equal probability.
+
+```redscript
+fn random_bool(seed: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `seed` | LCG output value (result of next_lcg) |
+
+**Returns:** 0 or 1 with ~50% probability each
+
+**Example**
+
+```redscript
+seed = next_lcg(seed)
+let coin: int = random_bool(seed)  // 0 or 1
+```
+
+---
+
+## `pcg_next_lo` <Badge type="info" text="v1.0.0" />
+
+Advance the PCG low-word state by one step.
+Call together with pcg_next_hi; use pcg_output to extract the random value.
+
+```redscript
+fn pcg_next_lo(state_lo: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `state_lo` | Current low word of PCG state |
+
+**Returns:** New low word
+
+**Example**
+
+```redscript
+let lo: int = pcg_next_lo(state_lo)
+```
+
+---
+
+## `pcg_next_hi` <Badge type="info" text="v1.0.0" />
+
+Advance the PCG high-word state by one step.
+
+```redscript
+fn pcg_next_hi(state_hi: int, state_lo: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `state_hi` | Current high word of PCG state |
+| `state_lo` | Current low word of PCG state (previous, before pcg_next_lo) |
+
+**Returns:** New high word
+
+**Example**
+
+```redscript
+let hi: int = pcg_next_hi(state_hi, state_lo)
+```
+
+---
+
+## `pcg_output` <Badge type="info" text="v1.0.0" />
+
+Extract an output value from the PCG low word using XSH-RR permutation.
+
+```redscript
+fn pcg_output(state_lo: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `state_lo` | Current low word of PCG state (after pcg_next_lo) |
+
+**Returns:** Pseudo-random output value (unsigned, any int)
+
+**Example**
+
+```redscript
+let rng: int = pcg_output(state_lo)
+```
+
+---
+
+## `binomial_sample` <Badge type="info" text="v1.0.0" />
+
+Simulate n Bernoulli trials and count the number of successes (binomial distribution).
+
+```redscript
+fn binomial_sample(n: int, p_x10000: int, seed: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `n` | Number of trials |
+| `p_x10000` | Success probability ×10000 (e.g. 5000 = 50%, 3000 = 30%) |
+| `seed` | LCG seed (any non-zero integer) |
+
+**Returns:** Number of successes in [0, n]
+
+**Example**
+
+```redscript
+let hits: int = binomial_sample(10, 5000, 99999)  // ~5 successes on average
+```
+
+---
+
+## `hypergeometric_sample` <Badge type="info" text="v1.0.0" />
+
+Draw `draws` items without replacement from a population and count successes (hypergeometric distribution).
+
+```redscript
+fn hypergeometric_sample(pop_size: int, success_states: int, draws: int, seed: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `pop_size` | Total population size |
+| `success_states` | Number of "success" items in the population |
+| `draws` | Number of items to draw |
+| `seed` | LCG seed (any non-zero integer) |
+
+**Returns:** Number of successes drawn, in [0, min(draws, success_states)]
+
+**Example**
+
+```redscript
+// 52-card deck, 4 aces, draw 5 cards
+let aces: int = hypergeometric_sample(52, 4, 5, 42)
+```
+
+---

package/redscript-docs/docs/en/stdlib/result.md

@@ -0,0 +1,143 @@
+# Result
+
+> Auto-generated from `src/stdlib/result.mcrs` — do not edit manually.
+
+## API
+
+- [result_ok](#result-ok)
+- [result_err](#result-err)
+- [result_is_ok](#result-is-ok)
+- [result_is_err](#result-is-err)
+- [result_value](#result-value)
+- [result_code](#result-code)
+- [result_divide](#result-divide)
+
+---
+
+## `result_ok` <Badge type="info" text="v1.0.0" />
+
+Construct a successful Result with the given value.
+
+```redscript
+fn result_ok(value: int): Result
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `value` | The success value (any integer) |
+
+**Returns:** Result::Ok(value)
+
+**Example**
+
+```redscript
+let r = result_ok(42)  // Ok result carrying 42
+```
+
+---
+
+## `result_err` <Badge type="info" text="v1.0.0" />
+
+Construct a failed Result with the given error code.
+
+```redscript
+fn result_err(code: int): Result
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `code` | Error code (use negative by convention: -1 generic, -2 div/zero) |
+
+**Returns:** Result::Err(code)
+
+**Example**
+
+```redscript
+let r = result_err(-2)  // division-by-zero error
+```
+
+---
+
+## `result_is_ok` <Badge type="info" text="v1.0.0" />
+
+Returns 1 if the Result is Ok, 0 otherwise.
+
+```redscript
+fn result_is_ok(r: Result): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `r` | The Result to test |
+
+**Returns:** 1 if Ok, 0 if Err
+
+**Example**
+
+```redscript
+let ok = result_is_ok(result_ok(5))  // result: 1
+```
+
+---
+
+## `result_is_err`
+
+Returns 1 if the Result is Err, 0 otherwise.
+
+```redscript
+fn result_is_err(r: Result): int
+```
+
+---
+
+## `result_value` <Badge type="info" text="v1.0.0" />
+
+Extract the value from an Ok result.
+Returns 0 if the Result is Err (check result_is_ok first).
+
+```redscript
+fn result_value(r: Result): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `r` | The Result to unwrap |
+
+**Returns:** The Ok value, or 0 if Err
+
+**Example**
+
+```redscript
+let v = result_value(result_ok(99))  // result: 99
+```
+
+---
+
+## `result_code`
+
+Extract the error code from an Err result.
+Returns 0 if the Result is Ok (check result_is_err first).
+
+```redscript
+fn result_code(r: Result): int
+```
+
+---
+
+## `result_divide`
+
+Divide a by b; returns Err(-2) on division by zero.
+
+```redscript
+fn result_divide(a: int, b: int): Result
+```
+
+---

package/redscript-docs/docs/en/stdlib/scheduler.md

@@ -0,0 +1,183 @@
+# Scheduler
+
+> Auto-generated from `src/stdlib/scheduler.mcrs` — do not edit manually.
+
+## API
+
+- [task_schedule](#task-schedule)
+- [task_cancel](#task-cancel)
+- [task_ready](#task-ready)
+- [gtask_schedule](#gtask-schedule)
+- [gtask_cancel](#gtask-cancel)
+- [gtask_ready](#gtask-ready)
+- [scheduler_tick](#scheduler-tick)
+
+---
+
+## `task_schedule` <Badge type="info" text="v1.0.0" />
+
+Schedule slot `task_id` (0–7) to fire after `delay` ticks for player `p`.
+
+```redscript
+fn task_schedule(p: selector, task_id: int, delay: int)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `p` | Recipient player or entity selector |
+| `task_id` | Slot index in range [0, 7] |
+| `delay` | Number of ticks to wait before firing |
+
+**Example**
+
+```redscript
+task_schedule(@s, 0, 40)
+```
+
+---
+
+## `task_cancel` <Badge type="info" text="v1.0.0" />
+
+Cancel slot `task_id` for player `p` (zeroes the counter).
+
+```redscript
+fn task_cancel(p: selector, task_id: int)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `p` | Recipient player or entity selector |
+| `task_id` | Slot index in range [0, 7] |
+
+**Example**
+
+```redscript
+task_cancel(@s, 0)
+```
+
+---
+
+## `task_ready` <Badge type="info" text="v1.0.0" />
+
+Returns `1` if slot `task_id` fired on this tick (counter reached 1), `0` otherwise.
+
+Automatically clears the slot once it fires so subsequent calls return `0`.
+
+```redscript
+fn task_ready(p: selector, task_id: int) -> int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `p` | Player or entity selector to check |
+| `task_id` | Slot index in range [0, 7] |
+
+**Returns:** `1` when the task is ready, `0` otherwise
+
+**Example**
+
+```redscript
+if (task_ready(@s, 0) == 1) { /* handle event */ }
+```
+
+---
+
+## `gtask_schedule` <Badge type="info" text="v1.0.0" />
+
+Schedule global slot `task_id` (0–7) to fire after `delay` ticks.
+
+Global tasks are stored on the `#rs` fake-player and are not bound to any
+specific player entity.
+
+```redscript
+fn gtask_schedule(task_id: int, delay: int)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `task_id` | Slot index in range [0, 7] |
+| `delay` | Number of ticks to wait before firing |
+
+**Example**
+
+```redscript
+gtask_schedule(0, 200)
+```
+
+---
+
+## `gtask_cancel` <Badge type="info" text="v1.0.0" />
+
+Cancel global slot `task_id` by zeroing its counter.
+
+```redscript
+fn gtask_cancel(task_id: int)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `task_id` | Slot index in range [0, 7] |
+
+**Example**
+
+```redscript
+gtask_cancel(0)
+```
+
+---
+
+## `gtask_ready` <Badge type="info" text="v1.0.0" />
+
+Returns `1` if global slot `task_id` fired this tick, `0` otherwise.
+
+Automatically clears the slot once it fires.
+
+```redscript
+fn gtask_ready(task_id: int) -> int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `task_id` | Slot index in range [0, 7] |
+
+**Returns:** `1` when the task is ready, `0` otherwise
+
+**Example**
+
+```redscript
+if (gtask_ready(0) == 1) { /* handle global event */ }
+```
+
+---
+
+## `scheduler_tick` <Badge type="info" text="v1.0.0" />
+
+Decrement all active per-player and global timers by 1 each tick.
+
+Call this inside your `@tick` function (executed as `@a`). Counters are
+clamped to 0 so they never go negative.
+
+```redscript
+fn scheduler_tick()
+```
+
+**Example**
+
+```redscript
+// In your @tick mcfunction:
+scheduler_tick()
+```
+
+---