redscript-mc 3.0.1 → 3.0.2

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

@@ -0,0 +1,185 @@
+# Heap
+
+> Auto-generated from `src/stdlib/heap.mcrs` — do not edit manually.
+
+## API
+
+- [heap_new](#heap-new)
+- [heap_size](#heap-size)
+- [heap_peek](#heap-peek)
+- [heap_push](#heap-push)
+- [heap_pop](#heap-pop)
+- [max_heap_push](#max-heap-push)
+- [max_heap_pop](#max-heap-pop)
+
+---
+
+## `heap_new` <Badge type="info" text="v1.0.0" />
+
+Allocate a new empty heap with capacity for 64 elements.
+
+```redscript
+fn heap_new(): int[]
+```
+
+**Returns:** int[] with h[0]=0 (size) and h[1..64] pre-allocated as zeros
+
+**Example**
+
+```redscript
+let h: int[] = heap_new()
+```
+
+---
+
+## `heap_size` <Badge type="info" text="v1.0.0" />
+
+Return the number of elements currently stored in the heap.
+
+```redscript
+fn heap_size(h: int[]): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `h` | Heap array (created with heap_new) |
+
+**Returns:** Current element count (h[0])
+
+**Example**
+
+```redscript
+let sz: int = heap_size(h)
+```
+
+---
+
+## `heap_peek` <Badge type="info" text="v1.0.0" />
+
+Return the root element without removing it (min for MinHeap, max for MaxHeap).
+
+```redscript
+fn heap_peek(h: int[]): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `h` | Non-empty heap array; precondition: heap_size(h) > 0 |
+
+**Returns:** The root element (h[1])
+
+**Example**
+
+```redscript
+let top: int = heap_peek(h)  // peek min without modifying heap
+```
+
+---
+
+## `heap_push` <Badge type="info" text="v1.0.0" />
+
+Insert a value into a MinHeap (smallest element at root).
+
+```redscript
+fn heap_push(h: int[], val: int): int[]
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `h` | Heap array (from heap_new) |
+| `val` | Value to insert |
+
+**Returns:** Updated heap array with val inserted and heap property maintained
+
+**Example**
+
+```redscript
+h = heap_push(h, 42)
+h = heap_push(h, 7)
+// heap_peek(h) == 7
+```
+
+---
+
+## `heap_pop` <Badge type="info" text="v1.0.0" />
+
+Remove and discard the minimum element from a MinHeap.
+
+```redscript
+fn heap_pop(h: int[]): int[]
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `h` | Non-empty MinHeap array; precondition: heap_size(h) > 0 |
+
+**Returns:** Updated heap array with minimum removed and heap property restored
+
+**Example**
+
+```redscript
+let min_val: int = heap_peek(h)
+h = heap_pop(h)  // remove the minimum
+```
+
+---
+
+## `max_heap_push` <Badge type="info" text="v1.0.0" />
+
+Insert a value into a MaxHeap (largest element at root).
+
+```redscript
+fn max_heap_push(h: int[], val: int): int[]
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `h` | Heap array (from heap_new) |
+| `val` | Value to insert |
+
+**Returns:** Updated heap array with val inserted and max-heap property maintained
+
+**Example**
+
+```redscript
+h = max_heap_push(h, 5)
+h = max_heap_push(h, 99)
+// heap_peek(h) == 99
+```
+
+---
+
+## `max_heap_pop` <Badge type="info" text="v1.0.0" />
+
+Remove and discard the maximum element from a MaxHeap.
+
+```redscript
+fn max_heap_pop(h: int[]): int[]
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `h` | Non-empty MaxHeap array; precondition: heap_size(h) > 0 |
+
+**Returns:** Updated heap array with maximum removed and max-heap property restored
+
+**Example**
+
+```redscript
+let max_val: int = heap_peek(h)
+h = max_heap_pop(h)  // remove the maximum
+```
+
+---

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

@@ -0,0 +1,179 @@
+# Interactions
+
+> Auto-generated from `src/stdlib/interactions.mcrs` — do not edit manually.
+
+## API
+
+- [interactions_init](#interactions-init)
+- [on_right_click](#on-right-click)
+- [example_right_click](#example-right-click)
+- [is_sneaking](#is-sneaking)
+- [on_sneak_start](#on-sneak-start)
+- [check_look_up](#check-look-up)
+- [check_look_down](#check-look-down)
+- [check_look_straight](#check-look-straight)
+- [check_holding_item](#check-holding-item)
+- [on_sneak_click](#on-sneak-click)
+- [DOUBLE_TAP_WINDOW](#double-tap-window)
+- [on_double_sneak](#on-double-sneak)
+
+---
+
+## `interactions_init`
+
+Initializes the scoreboard objectives used by this module.
+Call once during pack setup before any per-tick interaction checks.
+Creates `rs.click`, `rs.sneak`, and `rs.attack`.
+
+```redscript
+fn interactions_init()
+```
+
+---
+
+## `on_right_click`
+
+Detects right-click input using the `rs.click` scoreboard.
+Players with a positive click count are reset and tagged with `rs.clicked`.
+The `callback_fn` parameter is reserved for future callback dispatch and is
+not used by the current implementation.
+
+```redscript
+fn on_right_click(callback_fn: string)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `callback_fn` | Reserved callback identifier, currently unused |
+
+---
+
+## `example_right_click`
+
+Demonstrates how to consume `rs.click` directly.
+Broadcasts a message when a player right-clicks and resets the click count.
+
+```redscript
+fn example_right_click()
+```
+
+---
+
+## `is_sneaking`
+
+Returns whether the target is currently sneaking.
+This checks whether `rs.sneak` is greater than zero.
+
+```redscript
+fn is_sneaking(target: selector) -> int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `target` | Player selector to inspect |
+
+**Returns:** `1` if sneaking, otherwise `0`
+
+---
+
+## `on_sneak_start`
+
+Tags players who started sneaking on the current tick.
+Players with `rs.sneak == 1` receive the `rs.sneak_start` tag, and the tag
+is removed from everyone else.
+
+```redscript
+fn on_sneak_start()
+```
+
+---
+
+## `check_look_up`
+
+Tags players currently looking upward.
+Players with pitch from `-90` to `-45` receive the `rs.look_up` tag.
+
+```redscript
+fn check_look_up()
+```
+
+---
+
+## `check_look_down`
+
+Tags players currently looking downward.
+Players with pitch from `45` to `90` receive the `rs.look_down` tag.
+
+```redscript
+fn check_look_down()
+```
+
+---
+
+## `check_look_straight`
+
+Tags players currently looking roughly straight ahead.
+Players with pitch from `-45` to `45` receive the `rs.look_straight` tag.
+
+```redscript
+fn check_look_straight()
+```
+
+---
+
+## `check_holding_item`
+
+Placeholder helper for item-in-hand checks.
+The current implementation only prints guidance because robust item checks
+require predicates or explicit NBT checks.
+
+```redscript
+fn check_holding_item(item_id: string)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `item_id` | Expected item identifier or logical item key |
+
+---
+
+## `on_sneak_click`
+
+Detects a sneak-plus-right-click combo.
+Players who click while sneaking receive `rs.sneak_click`; otherwise they
+receive the normal `rs.clicked` tag. Click counters are reset in both cases.
+
+```redscript
+fn on_sneak_click()
+```
+
+---
+
+## `DOUBLE_TAP_WINDOW`
+
+Double-sneak detection window in ticks.
+A second sneak start within this many ticks counts as a double tap.
+
+```redscript
+const DOUBLE_TAP_WINDOW: int = 10;  // 0.5 second
+```
+
+---
+
+## `on_double_sneak`
+
+Detects a double-tap sneak pattern.
+Requires external scoreboards `rs.last_sneak` and `rs.tick` to be updated by
+the caller. Players who qualify receive the `rs.double_sneak` tag.
+
+```redscript
+fn on_double_sneak()
+```
+
+---

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

@@ -0,0 +1,97 @@
+# Inventory
+
+> Auto-generated from `src/stdlib/inventory.mcrs` — do not edit manually.
+
+## API
+
+- [clear_inventory](#clear-inventory)
+- [give_kit_warrior](#give-kit-warrior)
+- [give_kit_archer](#give-kit-archer)
+- [give_kit_mage](#give-kit-mage)
+- [remove_item](#remove-item)
+
+---
+
+## `clear_inventory`
+
+Clears all inventory slots from the target selector.
+
+```redscript
+fn clear_inventory(target: selector)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `target` | Player or entity selector whose inventory should be cleared |
+
+---
+
+## `give_kit_warrior`
+
+Gives a melee-focused warrior kit to the target selector.
+The kit includes iron armor, a sword, a shield, and food.
+
+```redscript
+fn give_kit_warrior(target: selector)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `target` | Player or entity selector receiving the kit |
+
+---
+
+## `give_kit_archer`
+
+Gives a ranged archer kit to the target selector.
+The kit includes a bow, arrows, light armor, and food.
+
+```redscript
+fn give_kit_archer(target: selector)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `target` | Player or entity selector receiving the kit |
+
+---
+
+## `give_kit_mage`
+
+Gives a utility-heavy mage kit to the target selector.
+The kit includes mobility, consumables, and splash damage items.
+
+```redscript
+fn give_kit_mage(target: selector)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `target` | Player or entity selector receiving the kit |
+
+---
+
+## `remove_item`
+
+Removes all copies of a specific item from the target selector.
+
+```redscript
+fn remove_item(target: selector, item: string)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `target` | Player or entity selector whose inventory will be filtered |
+| `item` | Item ID or item-with-NBT argument accepted by `clear` |
+
+---