redscript-mc 3.0.1 → 3.0.2

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

@@ -0,0 +1,353 @@
+# Color
+
+> Auto-generated from `src/stdlib/color.mcrs` — do not edit manually.
+
+## API
+
+- [rgb_pack](#rgb-pack)
+- [rgb_r](#rgb-r)
+- [rgb_g](#rgb-g)
+- [rgb_b](#rgb-b)
+- [rgb_lerp](#rgb-lerp)
+- [rgb_to_l](#rgb-to-l)
+- [rgb_to_s](#rgb-to-s)
+- [rgb_to_h](#rgb-to-h)
+- [hsl_to_r](#hsl-to-r)
+- [hsl_to_g](#hsl-to-g)
+- [hsl_to_b](#hsl-to-b)
+- [hsl_to_packed](#hsl-to-packed)
+- [rgb_to_hex](#rgb-to-hex)
+
+---
+
+## `rgb_pack` <Badge type="info" text="v1.0.0" />
+
+Pack RGB components into a single integer (0xRRGGBB format).
+
+```redscript
+fn rgb_pack(r: int, g: int, b: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `r` | Red channel, range [0, 255] |
+| `g` | Green channel, range [0, 255] |
+| `b` | Blue channel, range [0, 255] |
+
+**Returns:** r*65536 + g*256 + b
+
+**Example**
+
+```redscript
+let red: int = rgb_pack(255, 0, 0)  // result: 16711680 (0xFF0000)
+```
+
+---
+
+## `rgb_r` <Badge type="info" text="v1.0.0" />
+
+Extract the red component from a packed RGB integer.
+
+```redscript
+fn rgb_r(packed: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `packed` | Packed color integer (0xRRGGBB) |
+
+**Returns:** Red channel value in [0, 255]
+
+**Example**
+
+```redscript
+let r: int = rgb_r(16711680)  // result: 255
+```
+
+---
+
+## `rgb_g` <Badge type="info" text="v1.0.0" />
+
+Extract the green component from a packed RGB integer.
+
+```redscript
+fn rgb_g(packed: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `packed` | Packed color integer (0xRRGGBB) |
+
+**Returns:** Green channel value in [0, 255]
+
+**Example**
+
+```redscript
+let g: int = rgb_g(65280)  // result: 255 (0x00FF00)
+```
+
+---
+
+## `rgb_b` <Badge type="info" text="v1.0.0" />
+
+Extract the blue component from a packed RGB integer.
+
+```redscript
+fn rgb_b(packed: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `packed` | Packed color integer (0xRRGGBB) |
+
+**Returns:** Blue channel value in [0, 255]
+
+**Example**
+
+```redscript
+let b: int = rgb_b(255)  // result: 255 (0x0000FF)
+```
+
+---
+
+## `rgb_lerp` <Badge type="info" text="v1.0.0" />
+
+Linear interpolation between two packed RGB colors.
+
+```redscript
+fn rgb_lerp(a: int, b: int, t: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `a` | Start color (packed 0xRRGGBB) |
+| `b` | End color (packed 0xRRGGBB) |
+| `t` | Blend factor in [0, 1000] (0 = a, 1000 = b) |
+
+**Returns:** Packed RGB interpolated between a and b
+
+**Example**
+
+```redscript
+let mid: int = rgb_lerp(0xFF0000, 0x0000FF, 500)  // halfway between red and blue
+```
+
+---
+
+## `rgb_to_l` <Badge type="info" text="v1.0.0" />
+
+Compute the HSL lightness from RGB components (×10000 scale).
+
+```redscript
+fn rgb_to_l(r: int, g: int, b: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `r` | Red ×10000, range [0, 2550000] |
+| `g` | Green ×10000, range [0, 2550000] |
+| `b` | Blue ×10000, range [0, 2550000] |
+
+**Returns:** Lightness in [0, 10000] (0 = black, 10000 = white)
+
+**Example**
+
+```redscript
+let l: int = rgb_to_l(2550000, 2550000, 2550000)  // result: 10000 (white)
+```
+
+---
+
+## `rgb_to_s` <Badge type="info" text="v1.0.0" />
+
+Compute the HSL saturation from RGB components (×10000 scale).
+
+```redscript
+fn rgb_to_s(r: int, g: int, b: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `r` | Red ×10000, range [0, 2550000] |
+| `g` | Green ×10000, range [0, 2550000] |
+| `b` | Blue ×10000, range [0, 2550000] |
+
+**Returns:** Saturation in [0, 10000] (0 = grey, 10000 = fully saturated)
+
+**Example**
+
+```redscript
+let s: int = rgb_to_s(2550000, 0, 0)  // result: 10000 (pure red is fully saturated)
+```
+
+---
+
+## `rgb_to_h` <Badge type="info" text="v1.0.0" />
+
+Compute the HSL hue from RGB components (×10000 scale).
+
+```redscript
+fn rgb_to_h(r: int, g: int, b: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `r` | Red ×10000, range [0, 2550000] |
+| `g` | Green ×10000, range [0, 2550000] |
+| `b` | Blue ×10000, range [0, 2550000] |
+
+**Returns:** Hue in [0, 3600000] (degrees × 10000; 0=red, 1200000=green, 2400000=blue)
+
+**Example**
+
+```redscript
+let h: int = rgb_to_h(0, 2550000, 0)  // result: 1200000 (120°, pure green)
+```
+
+---
+
+## `hsl_to_r` <Badge type="info" text="v1.0.0" />
+
+Convert HSL to the red channel of RGB (×10000 scale).
+
+```redscript
+fn hsl_to_r(h: int, s: int, l: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `h` | Hue ×10000, range [0, 3600000] |
+| `s` | Saturation ×10000, range [0, 10000] |
+| `l` | Lightness ×10000, range [0, 10000] |
+
+**Returns:** Red channel ×10000, range [0, 2550000]; divide by 10000 for 0-255
+
+**Example**
+
+```redscript
+let r: int = hsl_to_r(0, 10000, 5000)  // pure red → 2550000
+```
+
+---
+
+## `hsl_to_g` <Badge type="info" text="v1.0.0" />
+
+Convert HSL to the green channel of RGB (×10000 scale).
+
+```redscript
+fn hsl_to_g(h: int, s: int, l: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `h` | Hue ×10000, range [0, 3600000] |
+| `s` | Saturation ×10000, range [0, 10000] |
+| `l` | Lightness ×10000, range [0, 10000] |
+
+**Returns:** Green channel ×10000, range [0, 2550000]
+
+**Example**
+
+```redscript
+let g: int = hsl_to_g(1200000, 10000, 5000)  // pure green → 2550000
+```
+
+---
+
+## `hsl_to_b` <Badge type="info" text="v1.0.0" />
+
+Convert HSL to the blue channel of RGB (×10000 scale).
+
+```redscript
+fn hsl_to_b(h: int, s: int, l: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `h` | Hue ×10000, range [0, 3600000] |
+| `s` | Saturation ×10000, range [0, 10000] |
+| `l` | Lightness ×10000, range [0, 10000] |
+
+**Returns:** Blue channel ×10000, range [0, 2550000]
+
+**Example**
+
+```redscript
+let b: int = hsl_to_b(2400000, 10000, 5000)  // pure blue → 2550000
+```
+
+---
+
+## `hsl_to_packed` <Badge type="info" text="v1.0.0" />
+
+Convert HSL (×10000 scale) to a packed RGB integer (0xRRGGBB).
+
+```redscript
+fn hsl_to_packed(h: int, s: int, l: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `h` | Hue ×10000, range [0, 3600000] |
+| `s` | Saturation ×10000, range [0, 10000] |
+| `l` | Lightness ×10000, range [0, 10000] |
+
+**Returns:** Packed RGB integer (0xRRGGBB), each channel 0-255
+
+**Example**
+
+```redscript
+let col: int = hsl_to_packed(0, 10000, 5000)  // pure red → 0xFF0000
+```
+
+---
+
+## `rgb_to_hex` <Badge type="info" text="v1.0.0" />
+
+Pack RGB into a 0xRRGGBB integer (alias for rgb_pack with explicit naming).
+
+```redscript
+fn rgb_to_hex(r: int, g: int, b: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `r` | Red channel, range [0, 255] |
+| `g` | Green channel, range [0, 255] |
+| `b` | Blue channel, range [0, 255] |
+
+**Returns:** r*65536 + g*256 + b (same as rgb_pack)
+
+**Example**
+
+```redscript
+let hex: int = rgb_to_hex(0, 128, 255)  // result: 32895 (0x0080FF)
+```
+
+---

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

@@ -0,0 +1,88 @@
+# Combat
+
+> Auto-generated from `src/stdlib/combat.mcrs` — do not edit manually.
+
+## API
+
+- [weapon_damage](#weapon-damage)
+- [take_damage](#take-damage)
+- [is_dead](#is-dead)
+
+---
+
+## `weapon_damage` <Badge type="info" text="v1.0.0" />
+
+Calculate total weapon damage from a base value plus a bonus.
+
+```redscript
+fn weapon_damage(base: int, bonus: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `base` | Base weapon damage value |
+| `bonus` | Additional damage modifier (e.g. from enchantments or buffs) |
+
+**Returns:** base + bonus
+
+**Example**
+
+```redscript
+let dmg: int = weapon_damage(10, 5)  // result: 15
+```
+
+---
+
+## `take_damage` <Badge type="info" text="v1.0.0" />
+
+Apply damage to a health value, clamping the result to a minimum of 0.
+
+```redscript
+fn take_damage(health: int, amount: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `health` | Current health value (e.g. from scoreboard) |
+| `amount` | Damage amount to subtract |
+
+**Returns:** health - amount, clamped to 0; use scoreboard_set after calling
+
+**Example**
+
+```redscript
+let new_hp: int = take_damage(current_hp, 8)
+scoreboard_set(@p, #health, new_hp)
+```
+
+---
+
+## `is_dead` <Badge type="info" text="v1.0.0" />
+
+Check whether an entity is dead (health at or below zero).
+
+```redscript
+fn is_dead(health: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `health` | Current health value to test |
+
+**Returns:** 1 if health <= 0 (dead), 0 otherwise (alive)
+
+**Example**
+
+```redscript
+if (is_dead(current_hp) == 1) {
+    // trigger death logic
+}
+```
+
+---

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

@@ -0,0 +1,82 @@
+# Cooldown
+
+> Auto-generated from `src/stdlib/cooldown.mcrs` — do not edit manually.
+
+## API
+
+- [cooldown_start](#cooldown-start)
+- [cooldown_ready](#cooldown-ready)
+- [cooldown_tick](#cooldown-tick)
+
+---
+
+## `cooldown_start` <Badge type="info" text="v1.2.0" />
+
+Start (or restart) a cooldown for the given slot.
+The cooldown expires after `ticks` game ticks.
+
+```redscript
+fn cooldown_start(name: string, ticks: int)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `name` | Cooldown slot identifier (reserved for future multi-slot support) |
+| `ticks` | Duration in game ticks (20 ticks = 1 second) |
+
+**Example**
+
+```redscript
+cooldown_start("sword", 40); // 2-second cooldown
+```
+
+---
+
+## `cooldown_ready` <Badge type="info" text="v1.2.0" />
+
+Check whether the cooldown has expired (i.e. is ready to fire again).
+
+```redscript
+fn cooldown_ready(name: string) -> int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `name` | Cooldown slot identifier (reserved for future multi-slot support) |
+
+**Returns:** 1 if the cooldown is ready (inactive or ticks remaining ≤ 0), 0 otherwise
+
+**Example**
+
+```redscript
+if (cooldown_ready("sword") == 1) { attack(); cooldown_start("sword", 40); }
+```
+
+---
+
+## `cooldown_tick` <Badge type="info" text="v1.2.0" />
+
+Advance the cooldown by one tick. Call this every tick from a `@tick` function.
+Automatically marks the cooldown inactive when the remaining ticks reach zero.
+
+```redscript
+fn cooldown_tick(name: string)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `name` | Cooldown slot identifier (reserved for future multi-slot support) |
+
+**Example**
+
+```redscript
+@tick fn game_tick() { cooldown_tick("sword"); }
+```
+
+---

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

@@ -0,0 +1,155 @@
+# Dialog
+
+> Auto-generated from `src/stdlib/dialog.mcrs` — do not edit manually.
+
+## API
+
+- [dialog_say](#dialog-say)
+- [dialog_broadcast](#dialog-broadcast)
+- [dialog_say_color](#dialog-say-color)
+- [dialog_title](#dialog-title)
+- [dialog_title_clear](#dialog-title-clear)
+- [dialog_actionbar](#dialog-actionbar)
+
+---
+
+## `dialog_say` <Badge type="info" text="v1.0.0" />
+
+Sends a plain white chat message to a player or selector.
+
+```redscript
+fn dialog_say(p: selector, msg: string)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `p` | Recipient selector |
+| `msg` | Plain text message content |
+
+**Example**
+
+```redscript
+dialog_say(@p, "Quest updated")
+```
+
+---
+
+## `dialog_broadcast` <Badge type="info" text="v1.0.0" />
+
+Broadcasts a plain white chat message to all players.
+
+```redscript
+fn dialog_broadcast(msg: string)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `msg` | Plain text message content |
+
+**Example**
+
+```redscript
+dialog_broadcast("Server restart in 60 seconds")
+```
+
+---
+
+## `dialog_say_color` <Badge type="info" text="v1.0.0" />
+
+Sends a colored chat message to a player or selector.
+
+Color mapping: `0=white`, `1=red`, `2=green`, `3=gold`, `4=aqua`.
+Any other value falls back to white.
+
+```redscript
+fn dialog_say_color(p: selector, msg: string, color: int)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `p` | Recipient selector |
+| `msg` | Plain text message content |
+| `color` | Color selector integer (0=white, 1=red, 2=green, 3=gold, 4=aqua) |
+
+**Example**
+
+```redscript
+dialog_say_color(@s, "You died!", 1)
+```
+
+---
+
+## `dialog_title` <Badge type="info" text="v1.0.0" />
+
+Displays a title and subtitle on a player's screen.
+
+```redscript
+fn dialog_title(p: selector, title: string, subtitle: string)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `p` | Recipient selector |
+| `title` | Large title text |
+| `subtitle` | Subtitle text shown below the title |
+
+**Example**
+
+```redscript
+dialog_title(@s, "Stage 2", "Defeat the boss")
+```
+
+---
+
+## `dialog_title_clear` <Badge type="info" text="v1.0.0" />
+
+Clears any currently displayed title for the target selector.
+
+```redscript
+fn dialog_title_clear(p: selector)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `p` | Recipient selector |
+
+**Example**
+
+```redscript
+dialog_title_clear(@s)
+```
+
+---
+
+## `dialog_actionbar` <Badge type="info" text="v1.0.0" />
+
+Displays a short message in the player's actionbar.
+
+```redscript
+fn dialog_actionbar(p: selector, msg: string)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `p` | Recipient selector |
+| `msg` | Plain text message content |
+
+**Example**
+
+```redscript
+dialog_actionbar(@s, "Mana: 80/100")
+```
+
+---