redscript-mc 2.5.0 → 2.6.0

package/docs/stdlib/teams.md

@@ -0,0 +1,87 @@
+# `teams` — Team management
+
+Import: `import teams;`
+
+Team management helpers for common multi-team game setups. Provides named team creation with colour and friendly-fire settings, player assignment/removal, and full 2- and 4-team game setup/cleanup helpers.
+
+## Functions
+
+### `create_team(name: string, color: string)`
+
+Create a team with the given name and color using `team_add` and `team_option`.
+
+**Example:**
+```rs
+import teams;
+create_team("purple", "dark_purple");
+```
+
+---
+
+### `create_red_team()`
+
+Create the `red` team with red colour and friendly fire disabled.
+
+---
+
+### `create_blue_team()`
+
+Create the `blue` team with blue colour and friendly fire disabled.
+
+---
+
+### `create_green_team()`
+
+Create the `green` team with green colour and friendly fire disabled.
+
+---
+
+### `create_yellow_team()`
+
+Create the `yellow` team with yellow colour and friendly fire disabled.
+
+---
+
+### `add_to_team(target: selector, team_name: string)`
+
+Add entities to a team.
+
+**Example:**
+```rs
+import teams;
+add_to_team(@s, "red");
+```
+
+---
+
+### `remove_from_teams(target: selector)`
+
+Remove entities from all teams.
+
+---
+
+### `setup_two_teams()`
+
+Create red and blue teams. Convenience wrapper for 1v1 or 2-team games.
+
+**Example:**
+```rs
+import teams;
+
+@load
+fn init() {
+    setup_two_teams();
+}
+```
+
+---
+
+### `setup_four_teams()`
+
+Create red, blue, green, and yellow teams.
+
+---
+
+### `cleanup_teams()`
+
+Remove red, blue, green, and yellow teams.

package/docs/stdlib/timer.md

@@ -0,0 +1,126 @@
+# `timer` — Countdown timers
+
+Import: `import timer;`
+
+Timer struct with OOP-style API for countdown/stopwatch functionality, plus tick/time conversion helpers. Each `Timer::new()` is statically allocated a unique compile-time ID; the compiler inlines scoreboard operations per instance. `Timer::new()` must be called at the top level of a function (not inside loops or if/else bodies).
+
+## Struct: `Timer`
+
+```rs
+struct Timer {
+    _id: int,
+    _duration: int
+}
+```
+
+### `Timer::new(duration: int): Timer`
+
+Create a new timer with the given duration in ticks. Initialises scoreboard slots to 0 (inactive).
+
+**Example:**
+```rs
+import timer;
+
+fn start_round() {
+    let t: Timer = Timer::new(600);  // 30-second timer
+    t.start();
+}
+```
+
+---
+
+### `Timer.start(self)`
+
+Start or resume the timer (sets active = 1).
+
+---
+
+### `Timer.pause(self)`
+
+Pause the timer (sets active = 0).
+
+---
+
+### `Timer.reset(self)`
+
+Reset elapsed ticks to zero.
+
+---
+
+### `Timer.done(self): bool`
+
+Returns true if elapsed ticks ≥ duration.
+
+**Example:**
+```rs
+import timer;
+
+@tick
+fn check_timer() {
+    if (my_timer.done()) {
+        end_round();
+    }
+}
+```
+
+---
+
+### `Timer.elapsed(self): int`
+
+Get elapsed ticks.
+
+---
+
+### `Timer.remaining(self): int`
+
+Get remaining ticks, clamped at zero.
+
+---
+
+### `Timer.tick(self)`
+
+Manually advance the timer by one tick when active. Call from a `@tick` function.
+
+## Conversion functions
+
+### `tick_to_seconds(ticks: int): int`
+
+Convert MC ticks to seconds (20 ticks = 1 second).
+
+---
+
+### `tick_to_ms(ticks: int): int`
+
+Convert ticks to milliseconds (1 tick = 50ms).
+
+---
+
+### `seconds_to_ticks(s: int): int`
+
+Convert seconds to ticks (`s × 20`).
+
+---
+
+### `format_time_s(ticks: int): int`
+
+Seconds component of tick count (mod 60).
+
+---
+
+### `format_time_m(ticks: int): int`
+
+Minutes component of tick count (mod 60).
+
+---
+
+### `format_time_h(ticks: int): int`
+
+Hours component of tick count.
+
+**Example:**
+```rs
+import timer;
+let elapsed: int = 1500;  // ticks
+let mins: int = format_time_m(elapsed);  // 1
+let secs: int = format_time_s(elapsed);  // 15
+```

package/docs/stdlib/vec.md

@@ -0,0 +1,193 @@
+# `vec` — 2D and 3D vectors
+
+Import: `import vec;`
+
+2D and 3D vector math with fixed-point scale=1000 (same as `math`). A unit vector has components in `[-1000, 1000]`. Provides dot product, cross product, Euclidean/Manhattan/Chebyshev distance, normalisation, linear interpolation, 2D rotation, `atan2` lookup, and 3D component-wise arithmetic. Requires `math` for `abs`, `sqrt_fixed`, `sin_fixed`, `cos_fixed`, `lerp`, `mulfix`.
+
+## Functions
+
+### `dot2d(ax: int, ay: int, bx: int, by: int): int`
+
+2D dot product of integer vectors. `dot2d(3, 4, 3, 4)` → 25.
+
+---
+
+### `cross2d(ax: int, ay: int, bx: int, by: int): int`
+
+Z-component of the 3D cross product: `ax×by − ay×bx`. Positive means b is counter-clockwise from a.
+
+---
+
+### `length2d_fixed(x: int, y: int): int`
+
+Euclidean length ×1000. `length2d_fixed(3, 4)` → 5000. Input components safe up to ~1000.
+
+---
+
+### `distance2d_fixed(x1: int, y1: int, x2: int, y2: int): int`
+
+Euclidean distance between two points ×1000. `distance2d_fixed(0, 0, 3, 4)` → 5000.
+
+---
+
+### `manhattan(x1: int, y1: int, x2: int, y2: int): int`
+
+Manhattan (taxicab) distance: `|dx| + |dy|`.
+
+---
+
+### `chebyshev(x1: int, y1: int, x2: int, y2: int): int`
+
+Chebyshev (chess-king) distance: `max(|dx|, |dy|)`.
+
+---
+
+### `normalize2d_x(x: int, y: int): int`
+
+X component of unit vector ×1000. Returns 0 for zero vector.
+
+**Example:**
+```rs
+import vec;
+let ux: int = normalize2d_x(3, 4);  // 600  (3/5 × 1000)
+```
+
+---
+
+### `normalize2d_y(x: int, y: int): int`
+
+Y component of unit vector ×1000. `normalize2d_y(3, 4)` → 800.
+
+---
+
+### `lerp2d_x(ax: int, ay: int, bx: int, by: int, t: int): int`
+
+X component of linear interpolation between vectors a and b. `t ∈ [0, 1000]`.
+
+---
+
+### `lerp2d_y(ax: int, ay: int, bx: int, by: int, t: int): int`
+
+Y component of linear interpolation. `lerp2d_y(0, 0, 100, 200, 500)` → 100.
+
+---
+
+### `atan2_fixed(y: int, x: int): int`
+
+> **Cost:** O(log 46) — binary search on 46-entry tan table  
+> **Requires:** `math:tables` NBT storage must be pre-loaded (auto-loaded via `@require_on_load(_atan_init)`)
+
+Angle of vector `(y, x)` in integer degrees `[0, 359]`. Inputs clamped to ≤46340 to avoid overflow.
+
+**Example:**
+```rs
+import vec;
+let angle: int = atan2_fixed(1, 1);  // 45
+```
+
+---
+
+### `rotate2d_x(x: int, y: int, deg: int): int`
+
+> **Requires:** `math:tables` NBT storage must be pre-loaded
+
+X component after 2D rotation by `deg` degrees (integer degrees, not ×10000). `rotate2d_x(1000, 0, 90)` → 0.
+
+---
+
+### `rotate2d_y(x: int, y: int, deg: int): int`
+
+> **Requires:** `math:tables` NBT storage must be pre-loaded
+
+Y component after 2D rotation. `rotate2d_y(1000, 0, 90)` → 1000.
+
+---
+
+### `dot3d(ax: int, ay: int, az: int, bx: int, by: int, bz: int): int`
+
+3D dot product.
+
+---
+
+### `cross3d_x(ax: int, ay: int, az: int, bx: int, by: int, bz: int): int`
+
+X component of 3D cross product: `ay×bz − az×by`.
+
+---
+
+### `cross3d_y(ax: int, ay: int, az: int, bx: int, by: int, bz: int): int`
+
+Y component of 3D cross product: `az×bx − ax×bz`.
+
+---
+
+### `cross3d_z(ax: int, ay: int, az: int, bx: int, by: int, bz: int): int`
+
+Z component of 3D cross product: `ax×by − ay×bx`.
+
+---
+
+### `length3d_fixed(x: int, y: int, z: int): int`
+
+Euclidean length ×1000. `length3d_fixed(1, 1, 1)` → 1732. Input components safe up to ~800.
+
+---
+
+### `distance3d_fixed(x1: int, y1: int, z1: int, x2: int, y2: int, z2: int): int`
+
+3D Euclidean distance ×1000.
+
+---
+
+### `manhattan3d(x1: int, y1: int, z1: int, x2: int, y2: int, z2: int): int`
+
+3D Manhattan distance.
+
+---
+
+### `chebyshev3d(x1: int, y1: int, z1: int, x2: int, y2: int, z2: int): int`
+
+3D Chebyshev distance.
+
+---
+
+### 2D arithmetic helpers
+
+| Function | Description |
+|:--|:--|
+| `add2d_x(ax, bx)` | ax + bx |
+| `add2d_y(ay, by)` | ay + by |
+| `sub2d_x(ax, bx)` | ax - bx |
+| `sub2d_y(ay, by)` | ay - by |
+| `scale2d_x(x, s)` | x × s / 1000 |
+| `scale2d_y(y, s)` | y × s / 1000 |
+| `neg2d_x(x)` | -x |
+| `neg2d_y(y)` | -y |
+
+---
+
+### 3D arithmetic helpers
+
+| Function | Description |
+|:--|:--|
+| `add3d_x(ax, bx)` | ax + bx |
+| `add3d_y(ay, by)` | ay + by |
+| `add3d_z(az, bz)` | az + bz |
+| `sub3d_x(ax, bx)` | ax - bx |
+| `sub3d_y(ay, by)` | ay - by |
+| `sub3d_z(az, bz)` | az - bz |
+| `scale3d_x(x, s)` | x × s / 1000 |
+| `scale3d_y(y, s)` | y × s / 1000 |
+| `scale3d_z(z, s)` | z × s / 1000 |
+| `neg3d_x(x)` | -x |
+| `neg3d_y(y)` | -y |
+| `neg3d_z(z)` | -z |
+
+**Example:**
+```rs
+import vec;
+// Normalize a 2D direction and scale to speed 300
+let dx: int = 3; let dy: int = 4;
+let vx: int = scale2d_x(normalize2d_x(dx, dy), 300);  // 180
+let vy: int = scale2d_y(normalize2d_y(dx, dy), 300);  // 240
+```

package/docs/stdlib/world.md

@@ -0,0 +1,151 @@
+# `world` — World queries and manipulation
+
+Import: `import world;`
+
+World manipulation helpers: time control, weather, gamerules, difficulty, fill helpers, and sun angle calculations. Sun angle functions use `×10000` scale and require `math` for `sin_fixed`.
+
+## Functions
+
+### `set_day()`
+
+Set world time to day (tick 1000).
+
+---
+
+### `set_night()`
+
+Set world time to night (tick 13000).
+
+---
+
+### `set_noon()`
+
+Set world time to noon (tick 6000).
+
+---
+
+### `set_midnight()`
+
+Set world time to midnight (tick 18000).
+
+---
+
+### `weather_clear()`
+
+Set weather to clear.
+
+---
+
+### `weather_rain()`
+
+Set weather to rain.
+
+---
+
+### `weather_thunder()`
+
+Set weather to thunder.
+
+---
+
+### `enable_keep_inventory()`
+
+Set `keepInventory` gamerule to true.
+
+---
+
+### `disable_keep_inventory()`
+
+Set `keepInventory` gamerule to false.
+
+---
+
+### `disable_mob_griefing()`
+
+Set `mobGriefing` gamerule to false.
+
+---
+
+### `disable_fire_spread()`
+
+Set `doFireTick` gamerule to false.
+
+---
+
+### `set_peaceful()`
+
+Set difficulty to peaceful.
+
+---
+
+### `set_easy()`
+
+Set difficulty to easy.
+
+---
+
+### `set_normal()`
+
+Set difficulty to normal.
+
+---
+
+### `set_hard()`
+
+Set difficulty to hard.
+
+---
+
+### `barrier_wall(x1: int, y1: int, z1: int, x2: int, y2: int, z2: int)`
+
+Fill region with `minecraft:barrier` blocks.
+
+**Example:**
+```rs
+import world;
+barrier_wall(-50, 0, -50, 50, 256, -50);
+```
+
+---
+
+### `clear_area(x1: int, y1: int, z1: int, x2: int, y2: int, z2: int)`
+
+Fill region with `minecraft:air`.
+
+---
+
+### `glass_box(x1: int, y1: int, z1: int, x2: int, y2: int, z2: int)`
+
+Create a hollow glass box: fills outer shell with glass, clears interior with air.
+
+**Example:**
+```rs
+import world;
+glass_box(0, 64, 0, 10, 74, 10);
+```
+
+---
+
+### `sun_altitude(ticks: int): int`
+
+> **Requires:** `math:tables` NBT storage must be pre-loaded (uses `sin_fixed`)
+
+Sun elevation above the horizon ×10000. Noon (tick 6000) → 900000 (+90°); midnight (tick 18000) → -900000 (-90°). Uses `sin_fixed`.
+
+**Example:**
+```rs
+import world;
+let alt: int = sun_altitude(6000);  // 900000 (directly overhead)
+```
+
+---
+
+### `sun_azimuth(ticks: int): int`
+
+Compass angle of the sun ×10000. Tick 0 = 0° (east), increases linearly to 3600000 over 24000 ticks.
+
+**Example:**
+```rs
+import world;
+let az: int = sun_azimuth(12000);  // 1800000 (180°, west)
+```

package/editors/vscode/build.mjs

@@ -1,28 +1,47 @@
 import esbuild from 'esbuild'
+import path from 'path'
+import { fileURLToPath } from 'url'
 
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const watch = process.argv.includes('--watch')
 
-/** @type {import('esbuild').BuildOptions} */
-const config = {
-  entryPoints: ['src/extension.ts'],
+const common = {
   bundle: true,
-  outfile: 'out/extension.js',
-  external: ['vscode'],   // vscode is provided by the host, never bundle it
   format: 'cjs',
   platform: 'node',
   target: 'node18',
   sourcemap: false,
   minify: false,
-  // Stub out Node builtins that the compiler might use
-  // (they're fine in the extension since it runs in Node)
-  // The compiler uses fs/path, which are available in the extension host
+}
+
+// Extension host bundle
+const extensionConfig = {
+  ...common,
+  entryPoints: ['src/extension.ts'],
+  outfile: 'out/extension.js',
+  external: ['vscode'],
+}
+
+// LSP server bundle — bundled separately so it runs in a clean Node process.
+// The server is located in the monorepo root (../../src/lsp/main.ts).
+const lspServerConfig = {
+  ...common,
+  entryPoints: [path.join(__dirname, '../../src/lsp/main.ts')],
+  outfile: 'out/lsp-server.js',
+  // No 'vscode' external — LSP server doesn't use vscode API
 }
 
 if (watch) {
-  const ctx = await esbuild.context(config)
-  await ctx.watch()
+  const [extCtx, lspCtx] = await Promise.all([
+    esbuild.context(extensionConfig),
+    esbuild.context(lspServerConfig),
+  ])
+  await Promise.all([extCtx.watch(), lspCtx.watch()])
   console.log('Watching for changes...')
 } else {
-  await esbuild.build(config)
-  console.log('Built out/extension.js')
+  await Promise.all([
+    esbuild.build(extensionConfig),
+    esbuild.build(lspServerConfig),
+  ])
+  console.log('Built out/extension.js + out/lsp-server.js')
 }