redscript-mc 3.0.1 → 3.0.2

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

@@ -0,0 +1,104 @@
+# Sort
+
+> Auto-generated from `src/stdlib/sort.mcrs` — do not edit manually.
+
+## API
+
+- [insertion_sort](#insertion-sort)
+- [insertion_sort_desc](#insertion-sort-desc)
+- [sort_merge](#sort-merge)
+- [merge_sort_noop](#merge-sort-noop)
+
+---
+
+## `insertion_sort` <Badge type="info" text="v1.0.0" />
+
+Sort an integer array ascending in-place using insertion sort.
+
+```redscript
+fn insertion_sort(arr: int[], len: int)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `arr` | Integer array to sort (mutated in-place) |
+| `len` | Number of elements to sort (arr[0..len-1]) |
+
+**Returns:** void — arr is sorted ascending after this call
+
+**Example**
+
+```redscript
+let data: int[] = [30, 10, 50, 20]
+insertion_sort(data, 4)
+// data is now [10, 20, 30, 50]
+```
+
+---
+
+## `insertion_sort_desc` <Badge type="info" text="v1.0.0" />
+
+Sort an integer array descending in-place using insertion sort.
+
+```redscript
+fn insertion_sort_desc(arr: int[], len: int)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `arr` | Integer array to sort (mutated in-place) |
+| `len` | Number of elements to sort (arr[0..len-1]) |
+
+**Returns:** void — arr is sorted descending after this call
+
+**Example**
+
+```redscript
+let scores: int[] = [30, 10, 50, 20]
+insertion_sort_desc(scores, 4)
+// scores is now [50, 30, 20, 10]
+```
+
+---
+
+## `sort_merge` <Badge type="info" text="v1.0.0" />
+
+Merge two sorted integer arrays into a new sorted array.
+
+```redscript
+fn sort_merge(a: int[], la: int, b: int[], lb: int): int[]
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `a` | First sorted array |
+| `la` | Number of elements in a (a[0..la-1]) |
+| `b` | Second sorted array |
+| `lb` | Number of elements in b (b[0..lb-1]) |
+
+**Returns:** New sorted int[] of length la+lb containing all elements of a and b
+
+**Example**
+
+```redscript
+let merged: int[] = sort_merge([1, 3, 5], 3, [2, 4, 6], 3)
+// result: [1, 2, 3, 4, 5, 6]
+```
+
+---
+
+## `merge_sort_noop` <Badge type="info" text="v1.0.0" />
+
+Default no-op callback for merge_sort_coro. Replace with your own handler to react when sorting completes.
+
+```redscript
+fn merge_sort_noop()
+```
+
+---

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

@@ -0,0 +1,147 @@
+# Spawn
+
+> Auto-generated from `src/stdlib/spawn.mcrs` — do not edit manually.
+
+## API
+
+- [teleport_to](#teleport-to)
+- [teleport_to_entity](#teleport-to-entity)
+- [spread_players](#spread-players)
+- [gather_all](#gather-all)
+- [launch_up](#launch-up)
+- [goto_lobby](#goto-lobby)
+- [goto_arena](#goto-arena)
+
+---
+
+## `teleport_to`
+
+Teleports the target selector to fixed world coordinates.
+
+```redscript
+fn teleport_to(target: selector, x: int, y: int, z: int)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `target` | Target selector to move |
+| `x` | Destination X coordinate |
+| `y` | Destination Y coordinate |
+| `z` | Destination Z coordinate |
+
+**Example**
+
+```redscript
+teleport_to(@p, 0, 64, 0)
+```
+
+---
+
+## `teleport_to_entity`
+
+Teleports the target selector to another entity.
+
+```redscript
+fn teleport_to_entity(target: selector, dest: selector)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `target` | Selector to teleport |
+| `dest` | Selector whose current position is used as the destination |
+
+---
+
+## `spread_players`
+
+Placeholder helper for spreading all players randomly in an area.
+The raw `spreadplayers` command is noted here but not emitted yet.
+Current behavior only broadcasts a status message.
+
+```redscript
+fn spread_players(x: int, z: int, radius: int)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `x` | Center X coordinate |
+| `z` | Center Z coordinate |
+| `radius` | Maximum spread radius in blocks |
+
+---
+
+## `gather_all`
+
+Teleports all players to one location.
+
+```redscript
+fn gather_all(x: int, y: int, z: int)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `x` | Destination X coordinate |
+| `y` | Destination Y coordinate |
+| `z` | Destination Z coordinate |
+
+---
+
+## `launch_up`
+
+Teleports the target upward relative to its current position.
+Useful for launch pads or scripted knock-up effects.
+
+```redscript
+fn launch_up(target: selector, height: int)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `target` | Selector to move |
+| `height` | Relative Y offset in blocks |
+
+---
+
+## `goto_lobby`
+
+Teleports the target to the hard-coded lobby position.
+This helper also shows a welcome title and should be customized per map.
+
+```redscript
+fn goto_lobby(target: selector)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `target` | Selector to move to the lobby |
+
+---
+
+## `goto_arena`
+
+Teleports the target to the hard-coded arena position.
+This helper also shows a fight title and should be customized per map.
+
+```redscript
+fn goto_arena(target: selector)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `target` | Selector to move to the arena |
+
+---

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

@@ -0,0 +1,142 @@
+# State
+
+> Auto-generated from `src/stdlib/state.mcrs` — do not edit manually.
+
+## API
+
+- [get_state](#get-state)
+- [set_state](#set-state)
+- [is_state](#is-state)
+- [init_state](#init-state)
+- [transition](#transition)
+
+---
+
+## `get_state` <Badge type="info" text="v1.0.0" />
+
+Read the current state of an entity.
+
+Returns `-1` if the entity has not been initialised (score is 0 = unset in
+Minecraft, but we reserve `-1` as the sentinel for "never set via
+`init_state`").
+
+```redscript
+fn get_state(entity: selector) -> int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `entity` | Selector for the target entity |
+
+**Returns:** Current state value stored in `rs.state`, or `-1` if unset
+
+**Example**
+
+```redscript
+let s: int = get_state(@s)
+```
+
+---
+
+## `set_state` <Badge type="info" text="v1.0.0" />
+
+Write a state value to an entity.
+
+```redscript
+fn set_state(entity: selector, state: int)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `entity` | Selector for the target entity |
+| `state` | Integer state constant to write |
+
+**Example**
+
+```redscript
+set_state(@s, 1)
+```
+
+---
+
+## `is_state` <Badge type="info" text="v1.0.0" />
+
+Check whether an entity is currently in the given state.
+
+```redscript
+fn is_state(entity: selector, state: int) -> int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `entity` | Selector for the target entity |
+| `state` | Integer state constant to compare against |
+
+**Returns:** `1` if the entity is in `state`, `0` otherwise
+
+**Example**
+
+```redscript
+if (is_state(@s, STATE_COMBAT) == 1) { /* per-tick combat logic */ }
+```
+
+---
+
+## `init_state` <Badge type="info" text="v1.0.0" />
+
+Initialise an entity's state only if it has not been set yet (score == -1).
+
+Call once on spawn or load to avoid overwriting an in-progress state.
+
+```redscript
+fn init_state(entity: selector, initial: int)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `entity` | Selector for the target entity |
+| `initial` | State constant to write when the entity is uninitialised |
+
+**Example**
+
+```redscript
+init_state(@s, STATE_IDLE)
+```
+
+---
+
+## `transition` <Badge type="info" text="v1.0.0" />
+
+Attempt a guarded transition from `from` to `to`.
+
+Only performs the transition when the entity is currently in `from`.
+
+```redscript
+fn transition(entity: selector, from: int, to: int) -> int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `entity` | Selector for the target entity |
+| `from` | Required current state |
+| `to` | State to transition into |
+
+**Returns:** `1` on success, `0` if the entity was not in `from`
+
+**Example**
+
+```redscript
+let ok: int = transition(@s, STATE_IDLE, STATE_COMBAT)
+```
+
+---

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

@@ -0,0 +1,154 @@
+# Strings
+
+> Auto-generated from `src/stdlib/strings.mcrs` — do not edit manually.
+
+## API
+
+- [str_len](#str-len)
+- [str_concat](#str-concat)
+- [str_contains](#str-contains)
+- [str_slice](#str-slice)
+
+---
+
+## `str_len` <Badge type="info" text="v1.0.0" />
+
+Returns the length of the string stored at rs:strings.{s}.
+
+LIMITATION (MC 1.21.4): `execute store result score ... run data get storage`
+returns 1 for any plain string NBT tag, not the character count. To get a
+true character count, the string must be stored as an NBT list of single-char
+strings (e.g. ["h","e","l","l","o"]), in which case data_get returns the list
+length correctly.
+
+For literal strings whose length is known at compile time, prefer using
+the constant directly — the compiler will fold it.
+
+```redscript
+fn str_len(s: string) -> int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `s` | NBT field name in rs:strings (e.g. "A") |
+
+**Returns:** 1 for plain string tags; list element count for char-list strings.
+
+**Example**
+
+```redscript
+str_len("A")  // result: 1 (plain string) or char count (char-list)
+```
+
+---
+
+## `str_concat` <Badge type="info" text="v1.0.0" />
+
+Concatenates two strings from rs:strings and writes the result to
+rs:strings.Result as an NBT list [a_value, b_value].
+
+The result list is suitable for use in tellraw JSON text components:
+  tellraw @a {"nbt":"Result","storage":"rs:strings","interpret":false}
+
+LIMITATION (MC 1.21.4): MC has no native string concatenation command.
+Single-string concatenation (e.g. "ab" from "a"+"b") requires a
+recursive macro helper function; this is out of scope for a pure stdlib.
+The NBT list representation works for display (tellraw) but cannot be
+passed back to further string operations without conversion.
+
+ALTERNATIVE for display: use a tellraw JSON array directly:
+  tellraw @a [{"storage":"rs:strings","nbt":"A"},{"storage":"rs:strings","nbt":"B"}]
+
+```redscript
+fn str_concat(a: string, b: string)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `a` | NBT field name of the first string in rs:strings (e.g. "A") |
+| `b` | NBT field name of the second string in rs:strings (e.g. "B") |
+
+**Returns:** rs:strings.Result is set to an NBT list [valueA, valueB]
+
+**Example**
+
+```redscript
+str_concat("A", "B")  // rs:strings.Result = ["hello", "world"]
+```
+
+---
+
+## `str_contains` <Badge type="info" text="v1.0.0" />
+
+Checks whether the string at rs:strings.{s} contains the substring at
+rs:strings.{sub}. Returns 1 if found, 0 if not found.
+
+NOT FEASIBLE (MC 1.21.4): Minecraft datapacks do not provide a native
+substring search command. There is no `execute if data` form that tests
+whether one string is contained within another.
+
+THIS FUNCTION ALWAYS RETURNS 0.
+
+WORKAROUNDS for datapack authors:
+  1. If sub is a compile-time constant and the check position is known,
+     use str_slice to extract a window and compare via scoreboard.
+  2. Pre-process strings server-side and store a presence flag in NBT.
+  3. Use a macro function (MC 1.20.2+) that iterates over character
+     positions with `$(var)` substitution and returns early on match.
+
+```redscript
+fn str_contains(s: string, sub: string) -> int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `s` | NBT field name of the haystack string in rs:strings |
+| `sub` | NBT field name of the needle string in rs:strings |
+
+**Returns:** 0 (always — not implemented due to MC limitation)
+
+---
+
+## `str_slice` <Badge type="info" text="v2.2.0" />
+
+Extracts a substring from rs:strings.{s} and writes it to rs:strings.Result.
+Uses the MC 1.20.2+ `data modify ... set string ... start end` feature.
+
+Indices follow Java/Python slicing semantics:
+  - start is inclusive, 0-based.
+  - end is exclusive (end = start + length).
+  - Negative end counts from the end of the string (e.g. -1 = all but last char).
+  - Omitting end (use a very large positive int like 999999) copies to end of string.
+
+Examples:
+  str_slice("A", 0, 5)  → first 5 characters of rs:strings.A
+  str_slice("A", 2, -1) → all but first 2 and last 1 characters
+
+```redscript
+fn str_slice(s: string, start: int, end: int)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `s` | NBT field name of the source string in rs:strings (e.g. "A") |
+| `start` | Start index (inclusive, 0-based) |
+| `end` | End index (exclusive); negative counts from string end |
+
+**Returns:** rs:strings.Result contains the extracted substring
+
+**Example**
+
+```redscript
+str_slice("A", 0, 5)   // first 5 chars of rs:strings.A
+str_slice("A", 2, -1)  // drop first 2 and last 1 chars
+```
+
+---