redscript-mc 2.2.1 → 2.3.0

package/docs/STDLIB_ROADMAP.md

@@ -0,0 +1,142 @@
+# RedScript Standard Library Roadmap
+
+> 目标：覆盖卡儿数学库（large_number）的所有核心功能，但以 RedScript 语言提供干净的 API。
+> 参考分析：`docs/LARGE_NUMBER_ANALYSIS.md`（本地，不追踪到 git）
+
+---
+
+## 当前 stdlib 状态（2026-03-17）
+
+| 文件 | 内容 | 状态 |
+|------|------|------|
+| `math.mcrs` | abs/sign/clamp/lerp/ln/sqrt_fx/exp_fx/sin_fixed/cos_fixed/isqrt/gcd/lcm... | ✅ |
+| `math_hp.mcrs` | sin_hp/cos_hp（实体旋转，高精度），init_trig | ✅框架/⚠️return值待修 |
+| `random.mcrs` | LCG: next_lcg/random_range/random_bool; PCG: pcg_next/pcg_output | ✅ |
+| `vec.mcrs` | 2D/3D dot/cross/length/distance/normalize/lerp/atan2/rotate/add/sub/scale | ✅ |
+| `color.mcrs` | rgb_pack/unpack, rgb_lerp, hsl_to_r/g/b, rgb_to_h/s/l | ✅ |
+| `bits.mcrs` | bit_and/or/xor/not, bit_shl/shr, bit_get/set/clear/toggle, popcount | ✅ |
+| `list.mcrs` | sort3, min/max/avg (3/5), weighted utilities | ✅ |
+| `geometry.mcrs` | AABB/sphere/cylinder contains, parabola, angle helpers, MC sun angle | ✅ |
+| `signal.mcrs` | uniform, normal_approx12, exp_dist, bernoulli, weighted2/3 | ✅ |
+| `bigint.mcrs` | 96-bit base-10000: add/sub/mul/div/cmp, int32↔bigint3 conversion | ✅ |
+| `combat.mcrs` | damage/kill-check | ✅（原有） |
+| `player.mcrs` | health/alive/range | ✅（原有） |
+| `cooldown.mcrs` | per-player cooldown tracking | ✅（原有） |
+| `timer.mcrs` | Timer static allocation | ✅（原有） |
+| `strings.mcrs` | string utilities | ✅（原有） |
+
+---
+
+## Batch 1 — 纯整数，无需新语言特性（当前可做）
+
+### `stdlib/math.mcrs` 补充
+- [x] `abs`, `sign`, `clamp`, `lerp`, `pow2`
+- [x] `ln(x: int): int` — SA-tuned atanh 级数，max_error 0.000557
+- [x] `sqrt_fx(x: int): int` — 基于 isqrt，固定点 ×10000
+- [x] `exp_fx(x: int): int` — Horner-form Taylor + 2^k 缩放，固定点 ×10000
+
+### `stdlib/math_hp.mcrs`（新建，框架就绪）
+- [x] `init_trig()` — 初始化 Marker 实体（用户在 `@load` 里调用）
+- [x] `sin_hp`, `cos_hp` — 框架 + `@require_on_load(init_trig)` 就绪
+- [ ] 真正实现 — 需要 `@raw` / `@builtin` 语言特性（emit 层内嵌 mcfunction）
+
+### `stdlib/random.mcrs`
+- [x] `next_lcg(seed: int): int`
+- [x] `random_range(seed, lo, hi)`
+- [x] `random_bool(seed: int): int`
+
+### `stdlib/random.mcrs`（已完成）
+- [x] `next_lcg(seed: int): int`
+- [x] `random_range(seed, lo, hi)`
+- [x] `random_bool(seed: int): int`
+
+### `stdlib/vec.mcrs` 补充
+- [x] `Vec2`, `Vec3`, `dot2`, `dot3`, `dist2_sq`, `dist3_sq`
+- [ ] `add2`, `sub2`, `scale2`（Vec2 加减缩放）
+- [ ] `add3`, `sub3`, `scale3`（Vec3 加减缩放）
+- [ ] `cross3(a, b: Vec3): Vec3` — 叉积
+
+### `stdlib/color.mcrs`（新建）
+- [ ] `rgb_to_int(r, g, b: int): int` — 打包成单个 int
+- [ ] `int_to_r/g/b(c: int): int` — 解包
+- [ ] `hsl_to_rgb(h, s, l: int): (int, int, int)` — 需要元组返回值
+
+---
+
+## Batch 2 — 需要位运算支持（语言特性 PR 先）
+
+> 依赖：编译器支持 `^`、`>>`、`<<` 运算符（目前 scoreboard 没有原生位运算，需要编译器层模拟或降级）
+
+### `stdlib/random.mcrs` 升级
+- [ ] `next_pcg(state: int): int` — PCG 算法（比 LCG 质量好，需要 `^` 和 `>>` ）
+- [ ] `next_xorshift(x: int): int` — Xorshift（仅需 `^`、`>>`、`<<`）
+
+### `stdlib/bits.mcrs`（新建）
+- [ ] `bit_and(a, b: int): int` — 用加法模拟（慢但正确）
+- [ ] `bit_or(a, b: int): int`
+- [ ] `bit_xor(a, b: int): int`
+- [ ] `bit_shift_left(x, n: int): int` — 乘以 2^n
+- [ ] `bit_shift_right(x, n: int): int` — 除以 2^n
+
+---
+
+## Batch 3 — 需要数组完整支持
+
+> 依赖：数组 literal 初始化完整实现（目前只有读取，写入走 workaround）
+
+### `stdlib/list.mcrs`（新建）
+- [ ] 基于 NBT list 的动态数组
+- [ ] `list_push`, `list_pop`, `list_get`, `list_set`, `list_len`
+- [ ] `list_sort_int` — 冒泡排序（整数）
+- [ ] `list_sum`, `list_min`, `list_max`
+
+### `stdlib/math.mcrs` — 查表升级
+- [ ] `ln` 升级为查表 + 插值（需要 `@precompute` 或 `@load` 初始化 NBT list）
+- [ ] `sin`/`cos` 高精度版（查表 + 和角公式）
+
+---
+
+## Batch 4 — 高级数学（长期）
+
+### `stdlib/bigint.mcrs`
+- [ ] 万进制 int 数组大数（基于 NBT int array）
+- [ ] 大数加减乘
+- [ ] 大数除以整数（竖式法）
+
+### `stdlib/geometry.mcrs`
+- [ ] `parabola_shoot` — 抛物线弹道（给定目标点和时间计算初速度）
+- [ ] `cone_select` — 圆锥选区
+- [ ] `midpoint3` — 三维中点
+
+### `stdlib/signal.mcrs`
+- [ ] `normal_dist_approx` — 正态分布近似（12个均匀分布相加）
+- [ ] `exponential_dist` — 指数分布随机变量
+
+---
+
+## Tuner 覆盖计划
+
+以下函数需要 `redscript tune` 生成最优系数：
+
+| 函数 | Adapter | 目标精度 |
+|------|---------|---------|
+| `ln` | `ln-polynomial`（已有） | < 0.001 |
+| `sqrt` | `sqrt-newton`（待写） | < 0.001 |
+| `exp` | `exp-polynomial`（待写） | < 0.001 |
+| `sin`/`cos` | `sincos-table`（待写） | < 0.0001 |
+
+---
+
+## 语言特性依赖清单
+
+| 特性 | 依赖的 stdlib | 难度 | 状态 |
+|------|-------------|------|------|
+| `@raw` / `@builtin` 内嵌 mcfunction | `sin_hp`/`cos_hp` 实现 | 中 | ❌ TODO |
+| 位运算 `^>><< ` | random PCG, bits | 中 | ❌ TODO |
+| 数组 literal 初始化 | list, bigint | 中 | ❌ TODO（读取已修，写入待做） |
+| 元组返回值 | color（hsl_to_rgb）| 中 | ❌ TODO |
+| `@precompute` 装饰器 | 高精度 sin/cos/ln | 高 | ❌ 长期 |
+
+---
+
+*生成于 2026-03-17 · 奇尔沙治*

package/editors/vscode/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "redscript-vscode",
-  "version": "1.2.17",
+  "version": "1.2.26",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "redscript-vscode",
-      "version": "1.2.17",
+      "version": "1.2.26",
       "license": "MIT",
       "dependencies": {
         "redscript": "file:../../",
@@ -24,7 +24,7 @@
     },
     "../..": {
       "name": "redscript-mc",
-      "version": "2.2.1",
+      "version": "2.3.0",
       "license": "MIT",
       "dependencies": {
         "vscode-languageserver": "^9.0.1",

package/editors/vscode/package.json

@@ -2,7 +2,7 @@
   "name": "redscript-vscode",
   "displayName": "RedScript for Minecraft",
   "description": "Syntax highlighting, error diagnostics, and language support for RedScript — a compiler targeting Minecraft Java Edition",
-  "version": "1.2.17",
+  "version": "1.2.26",
   "publisher": "bkmashiro",
   "icon": "icon.png",
   "license": "MIT",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "redscript-mc",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "description": "A high-level programming language that compiles to Minecraft datapacks",
   "main": "dist/src/index.js",
   "bin": {

package/src/__tests__/tuner/engine.test.ts

@@ -0,0 +1,260 @@
+/**
+ * Tests for the redscript tuner engine, simulator, and ln-polynomial adapter.
+ */
+
+import { search, searchSA } from '../../tuner/engine';
+import { i32, fixedMul, isOverflow } from '../../tuner/simulator';
+import { evaluate } from '../../tuner/metrics';
+import { lnPolynomialAdapter, defaultParams as lnDefaultParams } from '../../tuner/adapters/ln-polynomial';
+import { sqrtNewtonAdapter, defaultParams as sqrtDefaultParams } from '../../tuner/adapters/sqrt-newton';
+import { TunerAdapter, ParamSpec } from '../../tuner/types';
+
+// ─── simulator tests ──────────────────────────────────────────────────────────
+
+describe('simulator', () => {
+  test('i32 truncates to int32', () => {
+    expect(i32(3.7)).toBe(3);
+    expect(i32(-3.7)).toBe(-3);
+    expect(i32(2147483648)).toBe(-2147483648); // overflow wraps
+    expect(i32(0)).toBe(0);
+  });
+
+  test('fixedMul basic', () => {
+    // 10000 * 10000 / 10000 = 10000
+    expect(fixedMul(10000, 10000, 10000)).toBe(10000);
+    // 5000 * 2 / 10000 = 1
+    expect(fixedMul(5000, 2, 10000)).toBe(1);
+  });
+
+  test('fixedMul returns Infinity on overflow', () => {
+    expect(fixedMul(2147483647, 2147483647, 1)).toBe(Infinity);
+  });
+
+  test('isOverflow detects out-of-range', () => {
+    expect(isOverflow(2147483648)).toBe(true);
+    expect(isOverflow(-2147483649)).toBe(true);
+    expect(isOverflow(Infinity)).toBe(true);
+    expect(isOverflow(NaN)).toBe(true);
+    expect(isOverflow(0)).toBe(false);
+    expect(isOverflow(2147483647)).toBe(false);
+  });
+});
+
+// ─── Nelder-Mead convergence test ────────────────────────────────────────────
+
+describe('Nelder-Mead engine', () => {
+  test('converges to minimum of (x-3)^2', () => {
+    // Simple 1D minimization: minimize (x-3)^2
+    const mockAdapter: TunerAdapter = {
+      name: 'test-quadratic',
+      description: 'Minimize (x-3)^2',
+      params: [
+        { name: 'x', range: [-10, 10], integer: false } as ParamSpec,
+      ],
+      simulate(input: number, params: Record<string, number>): number {
+        // Return the residual as a scaled integer
+        const x = params['x'];
+        return Math.round(x * 10000);
+      },
+      reference(_input: number): number {
+        // Target: x = 3 → value 30000
+        return 30000;
+      },
+      sampleInputs(): number[] {
+        return [1]; // single input, target value is 3.0 (×10000 = 30000)
+      },
+      generateCode(params: Record<string, number>): string {
+        return `// x = ${params['x']}`;
+      },
+    };
+
+    const result = search(mockAdapter, 5000);
+    // Should converge close to x=3
+    expect(result.params['x']).toBeCloseTo(3.0, 1);
+    expect(result.maxError).toBeLessThan(0.1);
+  });
+
+  test('handles integer constraints', () => {
+    const mockAdapter: TunerAdapter = {
+      name: 'test-integer',
+      description: 'Integer parameter test',
+      params: [
+        { name: 'n', range: [0, 10], integer: true } as ParamSpec,
+      ],
+      simulate(input: number, params: Record<string, number>): number {
+        // Should snap to integer 7
+        return Math.round(params['n'] * 10000);
+      },
+      reference(_input: number): number {
+        return 70000; // 7.0 × 10000
+      },
+      sampleInputs(): number[] {
+        return [1];
+      },
+      generateCode(): string {
+        return '';
+      },
+    };
+
+    const result = search(mockAdapter, 2000);
+    // Should find n close to 7
+    expect(Math.round(result.params['n'])).toBe(7);
+  });
+
+  test('i32 overflow penalization', () => {
+    const mockAdapter: TunerAdapter = {
+      name: 'test-overflow',
+      description: 'Test overflow penalization',
+      params: [
+        { name: 'scale', range: [1, 1000], integer: true } as ParamSpec,
+      ],
+      simulate(_input: number, params: Record<string, number>): number {
+        // Always overflow for any scale >= 500
+        if (params['scale'] >= 500) return Infinity;
+        return params['scale'] * 10000;
+      },
+      reference(_input: number): number {
+        return 2000000; // target: scale=200 → 2000000
+      },
+      sampleInputs(): number[] {
+        return [1];
+      },
+      generateCode(): string {
+        return '';
+      },
+    };
+
+    const { maxError, mae, rmse } = evaluate(mockAdapter, { scale: 2147483647 });
+    expect(maxError).toBe(Infinity);
+    expect(mae).toBe(Infinity);
+    expect(rmse).toBe(Infinity);
+  });
+});
+
+// ─── ln-polynomial adapter tests ─────────────────────────────────────────────
+
+describe('ln-polynomial adapter', () => {
+  const defaultParams = lnDefaultParams; // { A1: 20000, A3: 6667, A5: 4000 }
+
+  test('sample inputs cover the valid range', () => {
+    const inputs = lnPolynomialAdapter.sampleInputs();
+    expect(inputs.length).toBeGreaterThan(50);
+    // All inputs should be positive
+    expect(inputs.every(x => x > 0)).toBe(true);
+  });
+
+  test('reference matches Math.log', () => {
+    const SCALE = 10000;
+    // ln(1.0) = 0
+    expect(lnPolynomialAdapter.reference(SCALE)).toBeCloseTo(0, 5);
+    // ln(2.0) ≈ 0.6931 → 6931
+    expect(lnPolynomialAdapter.reference(2 * SCALE)).toBeCloseTo(6931.47, 0);
+    // ln(0.5) ≈ -0.6931 → -6931
+    expect(lnPolynomialAdapter.reference(5000)).toBeCloseTo(-6931.47, 0);
+  });
+
+  test('simulate produces reasonable output for x=1 (no error)', () => {
+    const result = lnPolynomialAdapter.simulate(10000, defaultParams);
+    // ln(1.0) = 0; allow some approximation error
+    expect(Math.abs(result)).toBeLessThan(500); // within 0.05
+  });
+
+  test('simulate returns Infinity for invalid input', () => {
+    const result = lnPolynomialAdapter.simulate(0, defaultParams);
+    expect(result).toBeLessThan(0); // negative sentinel or -MAX_INT
+  });
+
+  test('max_error < 0.001 with default atanh coefficients', () => {
+    const metrics = evaluate(lnPolynomialAdapter, defaultParams);
+    expect(metrics.maxError).toBeLessThan(0.001);
+  }, 10000);
+
+  test('search improves over default params', () => {
+    // Run a short search and confirm it doesn't get worse
+    const baseMetrics = evaluate(lnPolynomialAdapter, defaultParams);
+    const result = search(lnPolynomialAdapter, 500); // short budget for test speed
+    // Either same or better
+    expect(result.maxError).toBeLessThanOrEqual(baseMetrics.maxError * 2);
+    expect(result.maxError).toBeLessThan(0.01);
+  }, 30000);
+
+  test('generateCode produces valid output', () => {
+    const meta = {
+      maxError: 0.00003,
+      mae: 0.000012,
+      rmse: 0.000015,
+      estimatedCmds: 38,
+      tuneDate: '2026-03-17',
+      budgetUsed: 5000,
+    };
+    const code = lnPolynomialAdapter.generateCode(defaultParams, meta);
+    expect(code).toContain('AUTO-GENERATED');
+    expect(code).toContain('ln-polynomial');
+    expect(code).toContain('fn ln');
+    expect(code).toContain('A1');
+    expect(code).toContain('A3');
+    expect(code).toContain('A5');
+    expect(code).toContain('2026-03-17');
+  });
+
+  test('searchSA achieves max_error < 0.001 on ln-polynomial', () => {
+    const result = searchSA(lnPolynomialAdapter, 3000);
+    expect(result.maxError).toBeLessThan(0.001);
+  }, 30000);
+});
+
+// ─── sqrt-newton adapter tests ────────────────────────────────────────────────
+
+describe('sqrt-newton adapter', () => {
+  test('simulate(10000, defaultParams) ≈ 10000 (sqrt(1.0)=1.0)', () => {
+    const result = sqrtNewtonAdapter.simulate(10000, sqrtDefaultParams);
+    // sqrt(1.0) * 10000 = 10000
+    expect(Math.abs(result - 10000)).toBeLessThan(10);
+  });
+
+  test('simulate(40000, defaultParams) ≈ 20000 (sqrt(4.0)=2.0)', () => {
+    const result = sqrtNewtonAdapter.simulate(40000, sqrtDefaultParams);
+    // sqrt(4.0) * 10000 = 20000
+    expect(Math.abs(result - 20000)).toBeLessThan(10);
+  });
+
+  test('simulate(0) returns 0', () => {
+    expect(sqrtNewtonAdapter.simulate(0, sqrtDefaultParams)).toBe(0);
+    expect(sqrtNewtonAdapter.simulate(-1, sqrtDefaultParams)).toBe(0);
+  });
+
+  test('simulate(250000, defaultParams) ≈ 50000 (sqrt(25.0)=5.0)', () => {
+    const result = sqrtNewtonAdapter.simulate(250000, sqrtDefaultParams);
+    expect(Math.abs(result - 50000)).toBeLessThan(10);
+  });
+
+  test('sample inputs are all positive', () => {
+    const inputs = sqrtNewtonAdapter.sampleInputs();
+    expect(inputs.length).toBeGreaterThan(50);
+    expect(inputs.every(x => x > 0)).toBe(true);
+  });
+
+  test('reference matches Math.sqrt', () => {
+    const SCALE = 10000;
+    expect(sqrtNewtonAdapter.reference(SCALE)).toBe(SCALE);          // sqrt(1.0)
+    expect(sqrtNewtonAdapter.reference(4 * SCALE)).toBe(2 * SCALE);  // sqrt(4.0)
+    expect(sqrtNewtonAdapter.reference(9 * SCALE)).toBe(3 * SCALE);  // sqrt(9.0)
+    expect(sqrtNewtonAdapter.reference(0)).toBe(0);
+  });
+
+  test('generateCode contains fn sqrt_fx', () => {
+    const meta = {
+      maxError: 1.5,
+      mae: 0.5,
+      rmse: 0.8,
+      estimatedCmds: 30,
+      tuneDate: '2026-03-17',
+      budgetUsed: 3000,
+    };
+    const code = sqrtNewtonAdapter.generateCode(sqrtDefaultParams, meta);
+    expect(code).toContain('AUTO-GENERATED');
+    expect(code).toContain('sqrt-newton');
+    expect(code).toContain('fn sqrt_fx');
+    expect(code).toContain('2026-03-17');
+  });
+});