redscript-mc 3.0.1 → 3.0.2

package/redscript-docs/docs/zh/stdlib/world.md

@@ -0,0 +1,289 @@
+# World
+
+> 本文档由 `src/stdlib/world.mcrs` 自动生成，请勿手动编辑。
+
+## API 列表
+
+- [set_day](#set-day)
+- [set_night](#set-night)
+- [set_noon](#set-noon)
+- [set_midnight](#set-midnight)
+- [weather_clear](#weather-clear)
+- [weather_rain](#weather-rain)
+- [weather_thunder](#weather-thunder)
+- [enable_keep_inventory](#enable-keep-inventory)
+- [disable_keep_inventory](#disable-keep-inventory)
+- [disable_mob_griefing](#disable-mob-griefing)
+- [disable_fire_spread](#disable-fire-spread)
+- [set_peaceful](#set-peaceful)
+- [set_easy](#set-easy)
+- [set_normal](#set-normal)
+- [set_hard](#set-hard)
+- [barrier_wall](#barrier-wall)
+- [clear_area](#clear-area)
+- [glass_box](#glass-box)
+- [sun_altitude](#sun-altitude)
+- [sun_azimuth](#sun-azimuth)
+
+---
+
+## `set_day`
+
+将世界时间设置为白天（tick 1000）
+
+```redscript
+fn set_day()
+```
+
+---
+
+## `set_night`
+
+将世界时间设置为夜晚（tick 13000）
+
+```redscript
+fn set_night()
+```
+
+---
+
+## `set_noon`
+
+将世界时间设置为正午（tick 6000）
+
+```redscript
+fn set_noon()
+```
+
+---
+
+## `set_midnight`
+
+将世界时间设置为午夜（tick 18000）
+
+```redscript
+fn set_midnight()
+```
+
+---
+
+## `weather_clear`
+
+将天气设置为晴天
+
+```redscript
+fn weather_clear()
+```
+
+---
+
+## `weather_rain`
+
+将天气设置为下雨
+
+```redscript
+fn weather_rain()
+```
+
+---
+
+## `weather_thunder`
+
+将天气设置为雷暴
+
+```redscript
+fn weather_thunder()
+```
+
+---
+
+## `enable_keep_inventory`
+
+启用 `keepInventory` 游戏规则
+
+```redscript
+fn enable_keep_inventory()
+```
+
+---
+
+## `disable_keep_inventory`
+
+关闭 `keepInventory` 游戏规则
+
+```redscript
+fn disable_keep_inventory()
+```
+
+---
+
+## `disable_mob_griefing`
+
+将 `mobGriefing` 设为 false，禁止生物破坏方块
+
+```redscript
+fn disable_mob_griefing()
+```
+
+---
+
+## `disable_fire_spread`
+
+将 `doFireTick` 设为 false，禁止火焰蔓延
+
+```redscript
+fn disable_fire_spread()
+```
+
+---
+
+## `set_peaceful`
+
+将难度设置为和平
+
+```redscript
+fn set_peaceful()
+```
+
+---
+
+## `set_easy`
+
+将难度设置为简单
+
+```redscript
+fn set_easy()
+```
+
+---
+
+## `set_normal`
+
+将难度设置为普通
+
+```redscript
+fn set_normal()
+```
+
+---
+
+## `set_hard`
+
+将难度设置为困难
+
+```redscript
+fn set_hard()
+```
+
+---
+
+## `barrier_wall`
+
+用屏障方块填充一个长方体区域
+
+```redscript
+fn barrier_wall(x1: int, y1: int, z1: int, x2: int, y2: int, z2: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x1` | 第一个角点 X 坐标 |
+| `y1` | 第一个角点 Y 坐标 |
+| `z1` | 第一个角点 Z 坐标 |
+| `x2` | 对角点 X 坐标 |
+| `y2` | 对角点 Y 坐标 |
+| `z2` | 对角点 Z 坐标 |
+
+---
+
+## `clear_area`
+
+用空气填充一个长方体区域，以清空该区域
+
+```redscript
+fn clear_area(x1: int, y1: int, z1: int, x2: int, y2: int, z2: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x1` | 第一个角点 X 坐标 |
+| `y1` | 第一个角点 Y 坐标 |
+| `z1` | 第一个角点 Z 坐标 |
+| `x2` | 对角点 X 坐标 |
+| `y2` | 对角点 Y 坐标 |
+| `z2` | 对角点 Z 坐标 |
+
+---
+
+## `glass_box`
+
+构建一个中空玻璃盒，先填满外壳再挖空内部
+
+```redscript
+fn glass_box(x1: int, y1: int, z1: int, x2: int, y2: int, z2: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x1` | 第一个角点 X 坐标 |
+| `y1` | 第一个角点 Y 坐标 |
+| `z1` | 第一个角点 Z 坐标 |
+| `x2` | 对角点 X 坐标 |
+| `y2` | 对角点 Y 坐标 |
+| `z2` | 对角点 Z 坐标 |
+
+---
+
+## `sun_altitude`
+
+根据世界时间计算太阳高度角，结果为角度 ×10000 定点数
+
+```redscript
+fn sun_altitude(ticks: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `ticks` | Minecraft 世界时间（游戏刻） |
+
+**返回：** 太阳高度角，单位为角度 ×10000
+
+**示例**
+
+```redscript
+let alt = sun_altitude(6000)  // 900000
+```
+
+---
+
+## `sun_azimuth`
+
+根据世界时间计算太阳方位角，结果为角度 ×10000 定点数
+
+```redscript
+fn sun_azimuth(ticks: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `ticks` | Minecraft 世界时间（游戏刻） |
+
+**返回：** 方位角，范围为 `[0, 3600000)`
+
+**示例**
+
+```redscript
+let az = sun_azimuth(6000)  // 900000
+```
+
+---

package/src/__tests__/formatter-extra.test.ts

@@ -0,0 +1,139 @@
+/**
+ * Additional coverage for src/formatter/index.ts
+ *
+ * Targets uncovered branches: string handling, long line wrapping,
+ * comment preservation, CRLF normalization, multiple blank line collapsing.
+ */
+
+import { format } from '../formatter'
+
+describe('formatter — string literal preservation', () => {
+  it('does not reindent content inside string literals', () => {
+    const input = 'fn test(): void {\nlet s: string = "{ not a block }";\n}'
+    const result = format(input)
+    expect(result).toContain('"{ not a block }"')
+  })
+
+  it('handles multiline strings spanning multiple lines', () => {
+    // A string that contains a newline escape
+    const input = 'fn test(): void {\nlet s: string = "line1\\nline2";\n}'
+    const result = format(input)
+    expect(result).toContain('"line1\\nline2"')
+  })
+
+  it('handles escaped quotes inside strings', () => {
+    const input = 'fn test(): void {\nlet s: string = "say \\"hello\\"";\n}'
+    const result = format(input)
+    expect(result).toContain('"say \\"hello\\""')
+  })
+
+  it('handles string with braces that should not affect indentation', () => {
+    const input = 'fn test(): void {\nlet s: string = "{{{}}} more";\nlet x: int = 1;\n}'
+    const result = format(input)
+    // x should be indented at 1 level (inside fn), not affected by string braces
+    expect(result).toMatch(/^ {2}let x: int = 1;$/m)
+  })
+})
+
+describe('formatter — comment handling', () => {
+  it('preserves inline comments', () => {
+    const input = 'fn test(): void {\nlet x: int = 1; // important\n}'
+    const result = format(input)
+    expect(result).toContain('// important')
+  })
+
+  it('does not treat braces in comments as code', () => {
+    const input = 'fn test(): void {\n// { this is a comment\nlet x: int = 1;\n}'
+    const result = format(input)
+    expect(result).toMatch(/^ {2}let x: int = 1;$/m)
+  })
+})
+
+describe('formatter — CRLF normalization', () => {
+  it('normalizes CRLF to LF', () => {
+    const input = 'fn test(): void {\r\nlet x: int = 1;\r\n}'
+    const result = format(input)
+    expect(result).not.toContain('\r')
+    expect(result).toBe('fn test(): void {\n  let x: int = 1;\n}\n')
+  })
+})
+
+describe('formatter — blank line collapsing', () => {
+  it('collapses more than 2 consecutive blank lines', () => {
+    const input = 'fn a(): void {\n}\n\n\n\n\nfn b(): void {\n}'
+    const result = format(input)
+    // Should have at most 2 blank lines between functions
+    expect(result).not.toMatch(/\n\n\n\n/)
+  })
+
+  it('strips leading blank lines', () => {
+    const input = '\n\n\nfn test(): void {\n}'
+    const result = format(input)
+    expect(result).toMatch(/^fn test/)
+  })
+})
+
+describe('formatter — long line wrapping', () => {
+  it('wraps function calls longer than 80 characters', () => {
+    const inner = 'fn test(): void {\n  some_function(argument_one, argument_two, argument_three, argument_four, argument_five);\n}'
+    const result = format(inner)
+    // Should be wrapped since the line is > 80 chars
+    const lines = result.split('\n')
+    // After wrapping, should produce more lines than original 3
+    expect(lines.length).toBeGreaterThan(3)
+  })
+
+  it('does not wrap short function calls', () => {
+    const input = 'fn test(): void {\n  foo(a, b);\n}'
+    const result = format(input)
+    expect(result).toContain('foo(a, b)')
+  })
+
+  it('does not wrap lines with comments even if long', () => {
+    const longComment = 'fn test(): void {\n  let x: int = 1; // this is a very long comment that makes the line exceed 80 characters easily\n}'
+    const result = format(longComment)
+    // Should keep comment line as-is (no wrapping)
+    expect(result).toContain('// this is a very long comment')
+  })
+})
+
+describe('formatter — brace collapsing', () => {
+  it('puts opening brace on same line as preceding statement', () => {
+    const input = 'if true\n{\nlet x: int = 1;\n}'
+    const result = format(input)
+    expect(result).toContain('if true {')
+  })
+
+  it('handles else brace normalization', () => {
+    const input = 'fn test(): void {\nif true {\nlet x: int = 1;\n}else{\nlet y: int = 2;\n}\n}'
+    const result = format(input)
+    expect(result).toContain('} else {')
+  })
+})
+
+describe('formatter — deeply nested code', () => {
+  it('indents 3 levels deep correctly', () => {
+    const input = 'fn test(): void {\nif true {\nif false {\nlet x: int = 1;\n}\n}\n}'
+    const result = format(input)
+    expect(result).toMatch(/^ {6}let x: int = 1;$/m)
+  })
+})
+
+describe('formatter — edge cases', () => {
+  it('handles single line code', () => {
+    const result = format('let x: int = 1;')
+    expect(result).toBe('let x: int = 1;\n')
+  })
+
+  it('handles code with only braces', () => {
+    const result = format('{}')
+    expect(result).toContain('{')
+    expect(result).toContain('}')
+  })
+
+  it('handles closing brace followed by opening brace', () => {
+    const input = 'fn a(): void {\n}\nfn b(): void {\n}'
+    const result = format(input)
+    expect(result).toContain('fn a(): void {\n}\nfn b(): void {\n}\n')
+  })
+})

package/src/__tests__/global-vars.test.ts

@@ -0,0 +1,171 @@
+/**
+ * Integration tests for module-level global variables.
+ *
+ * Covers:
+ * - Global variable assignment and read (score_write / score_read)
+ * - Global variable increment in a loop
+ * - Global variable visible across functions
+ * - Global variable in f-string interpolation (no stray "~")
+ *
+ * These tests compile RedScript source and inspect the generated .mcfunction
+ * content to verify correct scoreboard-based code generation.
+ */
+
+import { compile } from '../emit/compile'
+
+// Helper: find a function's body by name
+function getFunctionBody(
+  files: { path: string; content: string }[],
+  fnName: string,
+  ns = 'test'
+): string {
+  const target = `data/${ns}/function/${fnName}.mcfunction`
+  const f = files.find(f => f.path === target || f.path.endsWith(`/${fnName}.mcfunction`))
+  if (!f) {
+    const paths = files.map(f => f.path).join('\n')
+    throw new Error(`Function '${fnName}' not found in output. Files:\n${paths}`)
+  }
+  return f.content
+}
+
+// ──────────────────────────────────────────────────────────────
+// Test 1: global variable assignment and read
+// ──────────────────────────────────────────────────────────────
+describe('Global variable: assignment and read', () => {
+  const src = `
+    let counter: int = 0;
+
+    @keep
+    fn set_counter() {
+      counter = 42;
+    }
+
+    @keep
+    fn get_counter() {
+      scoreboard_set("#result", "rs", counter);
+    }
+  `
+
+  it('set_counter uses scoreboard players set to write global', () => {
+    const { files } = compile(src, { namespace: 'test' })
+    const body = getFunctionBody(files, 'set_counter')
+    // Should write 42 to the scoreboard for the global variable
+    expect(body).toContain('scoreboard players set')
+    expect(body).toContain('42')
+  })
+
+  it('get_counter reads global via score_read (not hardcoded 0)', () => {
+    const { files } = compile(src, { namespace: 'test' })
+    const body = getFunctionBody(files, 'get_counter')
+    // Should contain a scoreboard read for the counter variable,
+    // not a hardcoded literal "0" assignment
+    expect(body).toContain('scoreboard players')
+    // The result should not be a constant "0" — it must read the scoreboard
+    // (hardcoded copy t = 0 was the old bug)
+    expect(body).not.toMatch(/scoreboard players set #result rs 0\s*$/)
+  })
+})
+
+// ──────────────────────────────────────────────────────────────
+// Test 2: global variable increment in a loop
+// ──────────────────────────────────────────────────────────────
+describe('Global variable: increment in a loop', () => {
+  const src = `
+    let running: int = 0;
+
+    @keep
+    fn count_up() {
+      let i: int = 0;
+      while i < 5 {
+        running = running + 1;
+        i = i + 1;
+      }
+    }
+  `
+
+  it('count_up reads and writes running (not a no-op)', () => {
+    const { files } = compile(src, { namespace: 'test' })
+    const body = getFunctionBody(files, 'count_up')
+    // Should contain scoreboard operations (not an empty function)
+    expect(body.trim().length).toBeGreaterThan(0)
+    expect(body).toContain('scoreboard players')
+  })
+
+  it('DCE does not eliminate running = running + 1', () => {
+    const { files } = compile(src, { namespace: 'test' })
+    // The while loop generates sub-functions; check all files
+    const allContent = files.map(f => f.content).join('\n')
+    // There must be a scoreboard add or operation for running
+    const hasAdd = allContent.includes('scoreboard players add') ||
+      allContent.includes('scoreboard players operation')
+    expect(hasAdd).toBe(true)
+  })
+})
+
+// ──────────────────────────────────────────────────────────────
+// Test 3: global variable visible across functions
+// ──────────────────────────────────────────────────────────────
+describe('Global variable: cross-function visibility', () => {
+  const src = `
+    let x: int = 0;
+
+    @keep
+    fn set_x() {
+      x = 42;
+    }
+
+    @keep
+    fn get_x() {
+      scoreboard_set("#out", "rs", x);
+    }
+  `
+
+  it('set_x writes to x (not just a local temp)', () => {
+    const { files } = compile(src, { namespace: 'test' })
+    const body = getFunctionBody(files, 'set_x')
+    expect(body).toContain('scoreboard players set')
+    expect(body).toContain('42')
+    // The write must target the persistent scoreboard name for x, not a temp
+    expect(body).toContain('x')
+  })
+
+  it('get_x reads x from scoreboard', () => {
+    const { files } = compile(src, { namespace: 'test' })
+    const body = getFunctionBody(files, 'get_x')
+    // Must contain a scoreboard get / operation to read x
+    expect(body).toContain('scoreboard players')
+    expect(body).toContain('x')
+  })
+})
+
+// ──────────────────────────────────────────────────────────────
+// Test 4: global variable in f-string interpolation
+// ──────────────────────────────────────────────────────────────
+describe('Global variable: f-string interpolation', () => {
+  const src = `
+    let score_val: int = 0;
+
+    @keep
+    fn announce() {
+      say(f"Score: {score_val}");
+    }
+  `
+
+  it('announce does not contain stray ~ in tellraw', () => {
+    const { files } = compile(src, { namespace: 'test' })
+    const body = getFunctionBody(files, 'announce')
+    // The generated tellraw must not fall back to "~" (the old default bug)
+    expect(body).not.toContain('"text":"~"')
+    expect(body).not.toContain('"~"')
+  })
+
+  it('announce reads score_val from scoreboard (not hardcoded)', () => {
+    const { files } = compile(src, { namespace: 'test' })
+    const body = getFunctionBody(files, 'announce')
+    // f-string int interpolation uses macro pattern:
+    // execute store result storage ... run scoreboard players get score_val __test
+    expect(body).toContain('score_val')
+    // Must be a dynamic read, not a constant
+    expect(body).not.toMatch(/say Score: \d+/)
+  })
+})