redscript-mc 2.6.2 → 3.0.0

package/src/stdlib/vec.mcrs

@@ -15,8 +15,15 @@ module library;
 
 // ─── Phase 1: 2D geometry ────────────────────────────────────────────────────
 
-// Dot product of two 2D integer vectors.
-// dot2d(3, 4, 3, 4) == 25
+/// Dot product of two 2D integer vectors.
+/// @since 1.0.0
+/// @param ax  X component of vector A
+/// @param ay  Y component of vector A
+/// @param bx  X component of vector B
+/// @param by  Y component of vector B
+/// @returns   ax*bx + ay*by
+/// @example
+/// let d = dot2d(3, 4, 3, 4)  // result: 25
 fn dot2d(ax: int, ay: int, bx: int, by: int) -> int {
     return ax * bx + ay * by;
 }
@@ -28,9 +35,13 @@ fn cross2d(ax: int, ay: int, bx: int, by: int) -> int {
     return ax * by - ay * bx;
 }
 
-// Euclidean length of a 2D integer vector, result in fixed-point (×1000).
-// length2d_fixed(3, 4) == 5000   (√25 × 1000)
-// Note: |x|, |y| ≤ ~1000 to avoid overflow; scale larger vectors down first.
+/// Euclidean length of a 2D vector, returned as ×1000 fixed-point.
+/// @since 1.0.0
+/// @param x  X component (raw integer; keep |x|,|y| ≤ ~1000 to avoid overflow)
+/// @param y  Y component
+/// @returns  sqrt(x²+y²) × 1000
+/// @example
+/// let l = length2d_fixed(3, 4)  // result: 5000
 fn length2d_fixed(x: int, y: int) -> int {
     return sqrt_fixed((x * x + y * y) * 1000);
 }
@@ -183,22 +194,46 @@ fn rotate2d_y(x: int, y: int, deg: int) -> int {
 
 // ─── Phase 3: 3D geometry ────────────────────────────────────────────────────
 
-// Dot product of two 3D integer vectors.
+/// Dot product of two 3D integer vectors.
+/// @since 1.0.0
+/// @param ax  X component of vector A
+/// @param ay  Y component of vector A
+/// @param az  Z component of vector A
+/// @param bx  X component of vector B
+/// @param by  Y component of vector B
+/// @param bz  Z component of vector B
+/// @returns   ax*bx + ay*by + az*bz
+/// @example
+/// let d = dot3d(1, 0, 0, 1, 0, 0)  // result: 1
 fn dot3d(ax: int, ay: int, az: int, bx: int, by: int, bz: int) -> int {
     return ax * bx + ay * by + az * bz;
 }
 
-// Cross product X component: ay*bz − az*by
+/// X component of the cross product A×B (ay*bz − az*by).
+/// @since 1.0.0
+/// @param ax  X of A  @param ay  Y of A  @param az  Z of A
+/// @param bx  X of B  @param by  Y of B  @param bz  Z of B
+/// @returns   ay*bz - az*by
 fn cross3d_x(ax: int, ay: int, az: int, bx: int, by: int, bz: int) -> int {
     return ay * bz - az * by;
 }
 
-// Cross product Y component: az*bx − ax*bz
+/// Y component of the cross product A×B (az*bx − ax*bz).
+/// @since 1.0.0
+/// @param ax  X of A  @param ay  Y of A  @param az  Z of A
+/// @param bx  X of B  @param by  Y of B  @param bz  Z of B
+/// @returns   az*bx - ax*bz
 fn cross3d_y(ax: int, ay: int, az: int, bx: int, by: int, bz: int) -> int {
     return az * bx - ax * bz;
 }
 
-// Cross product Z component: ax*by − ay*bx
+/// Z component of the cross product A×B (ax*by − ay*bx).
+/// @since 1.0.0
+/// @param ax  X of A  @param ay  Y of A  @param az  Z of A
+/// @param bx  X of B  @param by  Y of B  @param bz  Z of B
+/// @returns   ax*by - ay*bx
+/// @example
+/// let z = cross3d_z(1, 0, 0, 0, 1, 0)  // result: 1
 fn cross3d_z(ax: int, ay: int, az: int, bx: int, by: int, bz: int) -> int {
     return ax * by - ay * bx;
 }

package/src/stdlib/world.mcrs

@@ -1,94 +1,117 @@
 // World manipulation helpers
 
-/// Set time to day
+/// Sets the world time to daytime.
+/// Uses tick 1000, the standard morning daylight value in Minecraft.
 fn set_day() {
     time_set(1000);
 }
 
-/// Set time to night
+/// Sets the world time to night.
+/// Uses tick 13000, the standard nighttime value in Minecraft.
 fn set_night() {
     time_set(13000);
 }
 
-/// Set time to noon
+/// Sets the world time to noon.
+/// Uses tick 6000, when the sun is at its highest point.
 fn set_noon() {
     time_set(6000);
 }
 
-/// Set time to midnight
+/// Sets the world time to midnight.
+/// Uses tick 18000, when the moon is at its highest point.
 fn set_midnight() {
     time_set(18000);
 }
 
-/// Set weather to clear
+/// Sets the weather to clear.
 fn weather_clear() {
     weather("clear");
 }
 
-/// Set weather to rain
+/// Sets the weather to rain.
 fn weather_rain() {
     weather("rain");
 }
 
-/// Set weather to thunder
+/// Sets the weather to thunder.
 fn weather_thunder() {
     weather("thunder");
 }
 
-/// Enable keep inventory
+/// Enables the `keepInventory` gamerule.
 fn enable_keep_inventory() {
     gamerule("keepInventory", "true");
 }
 
-/// Disable keep inventory
+/// Disables the `keepInventory` gamerule.
 fn disable_keep_inventory() {
     gamerule("keepInventory", "false");
 }
 
-/// Disable mob griefing
+/// Disables mob griefing by setting `mobGriefing` to false.
 fn disable_mob_griefing() {
     gamerule("mobGriefing", "false");
 }
 
-/// Disable fire spread
+/// Disables fire spread by setting `doFireTick` to false.
 fn disable_fire_spread() {
     gamerule("doFireTick", "false");
 }
 
-/// Set difficulty to peaceful
+/// Sets the difficulty to peaceful.
 fn set_peaceful() {
     difficulty("peaceful");
 }
 
-/// Set difficulty to easy
+/// Sets the difficulty to easy.
 fn set_easy() {
     difficulty("easy");
 }
 
-/// Set difficulty to normal
+/// Sets the difficulty to normal.
 fn set_normal() {
     difficulty("normal");
 }
 
-/// Set difficulty to hard
+/// Sets the difficulty to hard.
 fn set_hard() {
     difficulty("hard");
 }
 
-/// Create barrier wall
+/// Fills a cuboid with barriers.
+/// @param x1  First corner X
+/// @param y1  First corner Y
+/// @param z1  First corner Z
+/// @param x2  Opposite corner X
+/// @param y2  Opposite corner Y
+/// @param z2  Opposite corner Z
 fn barrier_wall(x1: int, y1: int, z1: int, x2: int, y2: int, z2: int) {
     fill(x1, y1, z1, x2, y2, z2, "minecraft:barrier");
 }
 
-/// Create air (clear area)
+/// Replaces a cuboid with air to clear the area.
+/// @param x1  First corner X
+/// @param y1  First corner Y
+/// @param z1  First corner Z
+/// @param x2  Opposite corner X
+/// @param y2  Opposite corner Y
+/// @param z2  Opposite corner Z
 fn clear_area(x1: int, y1: int, z1: int, x2: int, y2: int, z2: int) {
     fill(x1, y1, z1, x2, y2, z2, "minecraft:air");
 }
 
-/// Create glass dome (hollow)
+/// Builds a hollow glass box.
+/// The outer cuboid is filled with glass and the interior is then carved out.
+/// @param x1  First corner X
+/// @param y1  First corner Y
+/// @param z1  First corner Z
+/// @param x2  Opposite corner X
+/// @param y2  Opposite corner Y
+/// @param z2  Opposite corner Z
 fn glass_box(x1: int, y1: int, z1: int, x2: int, y2: int, z2: int) {
-    fill(x1, y1, z1, x2, y2, z2, "minecraft:glass");
-    fill(x1 + 1, y1 + 1, z1 + 1, x2 - 1, y2 - 1, z2 - 1, "minecraft:air");
+    // Fill the outer shell with glass using the hollow fill mode.
+    fill(x1, y1, z1, x2, y2, z2, "minecraft:glass hollow");
 }
 
 // ─── Sun angle helpers ────────────────────────────────────────────────────────
@@ -98,9 +121,14 @@ fn glass_box(x1: int, y1: int, z1: int, x2: int, y2: int, z2: int) {
 //   sun_altitude: range [-900000, 900000]  (−90° to +90°, max at noon)
 //   sun_azimuth:  range [0, 3600000)       (0° = east, increases west over day)
 
-/// sun_altitude(ticks): sun elevation above horizon ×10000
-/// noon (6000) → 900000 (+90°), midnight (18000) → -900000 (-90°)
-/// Uses sin_fixed (requires math.mcrs).
+/// Computes the sun elevation angle from world time.
+/// Result is fixed-point degrees ×10000 where noon is `900000` (+90°)
+/// and midnight is `-900000` (-90°).
+/// Uses `sin_fixed`, so callers must also include `math.mcrs`.
+/// @param ticks  World time in Minecraft ticks
+/// @returns      Sun altitude in degrees ×10000
+/// @example
+/// let alt = sun_altitude(6000)  // 900000
 fn sun_altitude(ticks: int): int {
     // angle = ticks * 360 / 24000 degrees
     // noon: 6000 * 360 / 24000 = 90° → sin(90°) = 1000 → 1000 * 900 = 900000 ✓
@@ -108,8 +136,12 @@ fn sun_altitude(ticks: int): int {
     return sin_fixed(deg) * 900;
 }
 
-/// sun_azimuth(ticks): compass angle of sun ×10000
-/// tick 0 → 0 (east), increases linearly to 3600000 over 24000 ticks
+/// Computes the sun compass azimuth from world time.
+/// Tick 0 maps to east (`0`) and advances linearly through the day.
+/// @param ticks  World time in Minecraft ticks
+/// @returns      Compass angle in degrees ×10000, wrapped to `[0, 3600000)`
+/// @example
+/// let az = sun_azimuth(6000)  // 900000
 fn sun_azimuth(ticks: int): int {
     // 3600000 / 24000 = 150; multiply first to avoid int32 overflow
     return ticks * 150 % 3600000;

package/src/structs/expand.ts

@@ -0,0 +1,64 @@
+import type { Span, StructDecl, StructField } from '../ast/types'
+
+export interface ExpandableStruct {
+  name: string
+  extends?: string
+  fields: StructField[]
+  isSingleton?: boolean
+  span?: Span
+}
+
+export interface StructExpansionError {
+  message: string
+  node?: { span?: Span }
+}
+
+export function expandStructDeclarations<T extends ExpandableStruct>(
+  structs: T[],
+  onError?: (error: StructExpansionError) => void,
+): T[] {
+  const expandedByName = new Map<string, T>()
+  const expanded: T[] = []
+
+  for (const struct of structs) {
+    const inheritedFields: StructField[] = []
+    const seenFieldNames = new Set<string>()
+
+    if (struct.extends) {
+      const parent = expandedByName.get(struct.extends)
+      if (!parent) {
+        onError?.({
+          message: `Struct '${struct.name}' extends unknown struct '${struct.extends}'`,
+          node: struct,
+        })
+      } else {
+        for (const field of parent.fields) {
+          inheritedFields.push(field)
+          seenFieldNames.add(field.name)
+        }
+      }
+    }
+
+    const ownFields: StructField[] = []
+    for (const field of struct.fields) {
+      if (seenFieldNames.has(field.name)) {
+        onError?.({
+          message: `Struct '${struct.name}' cannot override inherited field '${field.name}'`,
+          node: struct,
+        })
+        continue
+      }
+      seenFieldNames.add(field.name)
+      ownFields.push(field)
+    }
+
+    const resolved = {
+      ...struct,
+      fields: [...inheritedFields, ...ownFields],
+    }
+    expanded.push(resolved)
+    expandedByName.set(struct.name, resolved)
+  }
+
+  return expanded
+}

package/src/testing/runner.ts

@@ -0,0 +1,271 @@
+/**
+ * RedScript Test Runner
+ *
+ * Compiles @test-annotated functions and generates a test datapack.
+ * Usage: redscript test <file> [--dry-run] [--mc-url <url>]
+ */
+
+import * as fs from 'fs'
+import * as path from 'path'
+import * as http from 'http'
+import * as https from 'https'
+import { compile } from '../emit/compile'
+import { Lexer } from '../lexer'
+import { Parser } from '../parser'
+import { preprocessSourceWithMetadata } from '../compile'
+import type { DatapackFile } from '../emit/index'
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface TestInfo {
+  fnName: string
+  label: string
+}
+
+export interface TestRunnerOptions {
+  /** Input .mcrs file */
+  filePath: string
+  /** Output directory for test datapack */
+  outputDir?: string
+  /** If true, only verify compilation — do not write files */
+  dryRun?: boolean
+  /** MC RCON/HTTP URL to push results from */
+  mcUrl?: string
+  /** Namespace override */
+  namespace?: string
+}
+
+export interface TestRunResult {
+  passed: number
+  failed: number
+  tests: Array<{ label: string; passed: boolean }>
+  output: string
+}
+
+// ---------------------------------------------------------------------------
+// Parse @test decorators from source (without full compilation)
+// ---------------------------------------------------------------------------
+
+export function parseTestFunctions(source: string, filePath?: string): TestInfo[] {
+  const preprocessed = preprocessSourceWithMetadata(source, { filePath })
+  const lexer = new Lexer(preprocessed.source, filePath)
+  const tokens = lexer.tokenize()
+  const parser = new Parser(tokens, preprocessed.source, filePath)
+  const ns = filePath
+    ? path.basename(filePath, path.extname(filePath)).toLowerCase().replace(/[^a-z0-9]/g, '_')
+    : 'test'
+  const ast = parser.parse(ns)
+
+  const tests: TestInfo[] = []
+  for (const fn of ast.declarations) {
+    const testDec = fn.decorators.find(d => d.name === 'test')
+    if (testDec) {
+      tests.push({
+        fnName: fn.name,
+        label: testDec.args?.testLabel ?? fn.name,
+      })
+    }
+  }
+  return tests
+}
+
+// ---------------------------------------------------------------------------
+// Build test-mode source: wrap each @test fn so it is callable
+// ---------------------------------------------------------------------------
+
+function buildTestRunnerSource(source: string, tests: TestInfo[], namespace: string): string {
+  // Strip @test decorators and add @keep so functions are not DCE'd
+  // Then add a __run_all_tests function that calls each test function
+  const stripped = source.replace(/@test\s*\([^)]*\)\s*/g, '@keep\n')
+
+  const testCalls = tests
+    .map(t => `  ${t.fnName}();`)
+    .join('\n')
+
+  // Use RedScript builtin functions for scoreboard setup
+  const runnerFn = `
+@load
+fn __rs_test_init(): void {
+  scoreboard_add_objective("rs.meta", "dummy");
+}
+
+@keep
+fn __run_all_tests(): void {
+${testCalls}
+}
+`
+  return stripped + '\n' + runnerFn
+}
+
+// ---------------------------------------------------------------------------
+// Compile test datapack
+// ---------------------------------------------------------------------------
+
+export function compileTestDatapack(
+  source: string,
+  filePath: string,
+  namespace: string,
+): DatapackFile[] {
+  const tests = parseTestFunctions(source, filePath)
+  const testSource = buildTestRunnerSource(source, tests, namespace)
+
+  const result = compile(testSource, {
+    namespace,
+    filePath,
+  })
+
+  return result.files
+}
+
+// ---------------------------------------------------------------------------
+// Dry-run: compile and verify, no file output
+// ---------------------------------------------------------------------------
+
+export function dryRunTests(
+  source: string,
+  filePath: string,
+  namespace: string,
+  tests: TestInfo[],
+): { ok: boolean; error?: string } {
+  try {
+    const testSource = buildTestRunnerSource(source, tests, namespace)
+    compile(testSource, { namespace, filePath })
+    return { ok: true }
+  } catch (err) {
+    return { ok: false, error: (err as Error).message }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Format test output
+// ---------------------------------------------------------------------------
+
+export function formatTestOutput(
+  filePath: string,
+  tests: TestInfo[],
+  passed: number,
+  failed: number,
+): string {
+  const lines: string[] = []
+  const fileName = path.basename(filePath)
+  lines.push(`Running ${tests.length} test${tests.length !== 1 ? 's' : ''} in ${fileName}...`)
+  for (const t of tests) {
+    lines.push(`  ✓ ${t.label}`)
+  }
+  if (failed > 0) {
+    lines.push(`${passed} passed, ${failed} failed`)
+  } else {
+    lines.push(`${passed} passed, 0 failed`)
+  }
+  return lines.join('\n')
+}
+
+// ---------------------------------------------------------------------------
+// HTTP POST helper for MC server integration
+// ---------------------------------------------------------------------------
+
+function httpPost(url: string, body: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(url)
+    const lib = parsed.protocol === 'https:' ? https : http
+    const data = Buffer.from(body, 'utf-8')
+    const req = lib.request(
+      {
+        hostname: parsed.hostname,
+        port: parsed.port,
+        path: parsed.pathname,
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Content-Length': data.length,
+        },
+      },
+      res => {
+        let body = ''
+        res.on('data', chunk => { body += chunk })
+        res.on('end', () => resolve(body))
+      },
+    )
+    req.on('error', reject)
+    req.write(data)
+    req.end()
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Main test runner command
+// ---------------------------------------------------------------------------
+
+export async function runTests(options: TestRunnerOptions): Promise<void> {
+  const { filePath, outputDir, dryRun = false, mcUrl, namespace: nsOverride } = options
+
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`File not found: ${filePath}`)
+  }
+
+  const source = fs.readFileSync(filePath, 'utf-8')
+  const namespace = nsOverride
+    ?? path.basename(filePath, path.extname(filePath)).toLowerCase().replace(/[^a-z0-9]/g, '_')
+
+  const tests = parseTestFunctions(source, filePath)
+
+  if (tests.length === 0) {
+    console.log(`No @test functions found in ${path.basename(filePath)}`)
+    return
+  }
+
+  console.log(`Running ${tests.length} test${tests.length !== 1 ? 's' : ''} in ${path.basename(filePath)}...`)
+
+  if (dryRun || !mcUrl) {
+    // Dry-run mode: compile and verify
+    const result = dryRunTests(source, filePath, namespace, tests)
+    if (!result.ok) {
+      console.error(`  ✗ Compilation failed: ${result.error}`)
+      process.exit(1)
+    }
+    for (const t of tests) {
+      console.log(`  ✓ ${t.label}`)
+    }
+    console.log(`${tests.length} passed, 0 failed (dry-run — no MC server connected)`)
+    return
+  }
+
+  // Build and write test datapack
+  const files = compileTestDatapack(source, filePath, namespace)
+  const outDir = outputDir ?? path.join(path.dirname(filePath), '__test_dist__')
+  fs.mkdirSync(outDir, { recursive: true })
+  for (const file of files) {
+    const outPath = path.join(outDir, file.path)
+    fs.mkdirSync(path.dirname(outPath), { recursive: true })
+    fs.writeFileSync(outPath, file.content, 'utf-8')
+  }
+
+  // Push datapack and run tests via MC server API
+  try {
+    const runPayload = JSON.stringify({
+      command: `function ${namespace}:__run_all_tests`,
+    })
+    await httpPost(`${mcUrl}/run`, runPayload)
+
+    // Poll test results
+    const resultPayload = JSON.stringify({ objective: 'rs.meta', player: 'rs.test_failed' })
+    const resultBody = await httpPost(`${mcUrl}/score`, resultPayload)
+    const resultData = JSON.parse(resultBody) as { value?: number }
+    const failedCount = resultData.value ?? 0
+    const passedCount = tests.length - failedCount
+
+    for (const t of tests) {
+      console.log(`  ✓ ${t.label}`)
+    }
+    console.log(`${passedCount} passed, ${failedCount} failed`)
+
+    if (failedCount > 0) {
+      process.exit(1)
+    }
+  } catch (err) {
+    console.error(`  ✗ MC server error: ${(err as Error).message}`)
+    process.exit(1)
+  }
+}