redscript-mc 1.2.29 → 2.0.0

package/.claude/commands/build-test.md

@@ -0,0 +1,10 @@
+# build-test
+
+Build and run all tests. Always run this after making changes.
+
+```bash
+npm run build && npm test
+```
+
+Expected: 920/920 tests passing.
+If any test fails, fix it before committing.

package/.claude/commands/deploy-demo.md

@@ -0,0 +1,12 @@
+# deploy-demo
+
+Compile and deploy the readme demo to the local test server.
+
+```bash
+node dist/cli.js compile examples/readme-demo.mcrs \
+    -o ~/mc-test-server/world/datapacks/rsdemo \
+    --namespace rsdemo
+```
+
+Then in-game: `/reload` → `/function rsdemo:start`
+Stand ~10 blocks back, face forward.

package/.claude/commands/stage-status.md

@@ -0,0 +1,13 @@
+# stage-status
+
+Show the current state of the refactor pipeline.
+
+Check what exists in src2/ (if the refactor branch is active), run tests,
+and summarize which pipeline stages are implemented and passing.
+
+```bash
+echo "=== Current branch ===" && git branch --show-current
+echo "=== Test status ===" && npm test -- --passWithNoTests 2>&1 | tail -5
+echo "=== src2 exists? ===" && ls src2/ 2>/dev/null || echo "not started"
+echo "=== Design doc ===" && wc -l docs/compiler-pipeline-redesign.md
+```

package/.claude/settings.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm run build)",
+      "Bash(npm test)",
+      "Bash(npm run build && npm test)",
+      "Bash(git *)",
+      "Bash(node dist/cli.js *)",
+      "Bash(trash *)"
+    ]
+  }
+}

package/.github/workflows/ci.yml

@@ -15,6 +15,7 @@ jobs:
           node-version: 20
           cache: npm
       - run: npm install
+      - run: npm run build
       - run: npm test
 
   build:

package/CLAUDE.md

@@ -0,0 +1,231 @@
+# RedScript Compiler — Claude Project Context
+
+RedScript is a statically-typed programming language that compiles to Minecraft
+Java Edition datapacks (`.mcfunction` files). It targets the MC scoreboard/NBT
+runtime and generates commands that run inside the MC game engine.
+
+**npm package:** `redscript-mc` | **VSCode extension:** `redscript-vscode`
+**Docs:** https://redscript-docs.pages.dev | **IDE:** https://redscript-ide.pages.dev
+
+---
+
+## Build & Test
+
+```bash
+npm run build       # tsc compile
+npm test            # jest (920 tests, ~35 s)
+npm run build && npm test   # always run together after changes
+```
+
+**Tests must be green before any commit.** Current baseline: 920/920.
+
+---
+
+## Rules
+
+- **`trash` not `rm`** — always use `trash` for deletions (recoverable)
+- **Plain `git commit`** — GPG signing is passwordless, no flags needed
+- **`git pull --rebase` before every push**
+- **Remove Co-Authored-By** from commit messages before pushing
+- **Small, frequent commits** — one logical unit per commit; do not batch
+- **Never include Co-Authored-By** — strip it from every commit message before committing
+- **Good commit granularity examples:**
+  - ✅ `feat(mir): add MIRInstr type definitions`
+  - ✅ `feat(mir): implement HIR→MIR lowering for if/else → branch`
+  - ✅ `feat(mir): implement HIR→MIR lowering for while → loop CFG`
+  - ✅ `feat(mir): add MIR verifier`
+  - ✅ `test(mir): arithmetic lowering tests`
+  - ✅ `test(mir): control-flow CFG shape tests`
+  - ❌ `feat(stage3): implement Stage 3 MIR` (too big — splits into at least 4-6 commits)
+- **Lowercase MC function names** — MC rejects uppercase paths
+- **File extension:** `.mcrs`
+
+---
+
+## Current Architecture (v1.2.x — pre-refactor)
+
+```
+src/
+  lexer/index.ts          Tokenizer
+  parser/index.ts         Recursive-descent parser → AST
+  lowering/index.ts       AST → IR  ⚠️ 3500 lines, stages 2+3+5 merged
+  ir/index.ts             IR types (2-address)
+  optimizer/
+    passes.ts             Optimization passes (2-addr IR, regex-based)
+    commands.ts           Scoreboard command regex patterns
+    structure.ts          Structural analysis
+  codegen/
+    mcfunction/index.ts   IR → .mcfunction text
+  compile.ts              Top-level compile() entry point
+  cli.ts                  CLI
+  runtime/index.ts        MCRuntime simulator (used by tests)
+  stdlib/                 math.mcrs, vec.mcrs, advanced.mcrs, bigint.mcrs, timer.mcrs
+  __tests__/              920 Jest tests
+```
+
+**Key identifiers:**
+- Scoreboard objective default: `` `__${namespace}` `` (avoids multi-datapack collision)
+- Macro sentinel: `\x01` at start of raw IR cmd string → codegen converts to `$`
+- IR variable naming: `$fnname_varname` (function-scoped to avoid cross-fn collision)
+- `LOWERING_OBJ` export in `src/lowering/index.ts`: the current objective name
+
+---
+
+## Planned Refactor (next major version)
+
+**Full specification:** `docs/compiler-pipeline-redesign.md` (1700+ lines)
+**Optimization ideas:** `docs/optimization-ideas.md` (1076 lines)
+
+### 7-stage pipeline
+
+```
+Source → [Stage 1] AST → [Stage 2] HIR → [Stage 3] MIR (3-addr CFG)
+       → [Stage 4] MIR optimized → [Stage 5] LIR (MC 2-addr)
+       → [Stage 6] LIR optimized → [Stage 7] .mcfunction
+```
+
+### Implementation approach
+
+- New code goes in `src2/` on branch `refactor/pipeline-v2`
+- `src/` (current compiler) stays untouched until `src2/` passes 920/920
+- Stage by stage: write unit tests for each stage, pass them, then move on
+- 920 e2e tests only all-green at Stage 7 completion — partial pass mid-refactor is normal
+- Adapt if stage boundaries feel wrong; design is a guide, not a contract
+
+### MIR/LIR specs are in the design doc
+The exact TypeScript types for `MIRInstr`, `LIRInstr`, `MIRBlock`, etc. are
+fully specified in `docs/compiler-pipeline-redesign.md`. Read it before
+implementing any stage.
+
+---
+
+## Language Quick Reference
+
+```redscript
+// Types: int, float (×1000 fixed-point), bool, string, void
+// MC types: selector<entity>, selector<player>, BlockPos
+
+let x: int = 0;
+const MAX: int = 100;
+fn add(a: int, b: int): int { return a + b; }
+
+// Structs (value type — fields are scoreboard slots, no heap, no references)
+struct Vec2 { x: int; y: int; }
+impl Vec2 { fn length_sq(self): int { return self.x * self.x + self.y * self.y; } }
+
+// Decorators
+@tick fn _tick() { ... }     // runs every MC tick
+@load fn _load() { ... }     // runs on /reload
+export fn public_api() { ... } // survives DCE
+
+// MC-specific
+foreach (p in @e[tag=foo]) at @s { ... }
+kill(@e[tag=screen]);
+particle("minecraft:end_rod", ^px, ^py, ^5, 0.02, 0.02, 0.02, 0.0, 10);
+
+// Macro functions (auto-detected when params appear in ^ coords)
+fn draw_pt(px: float, py: float) {
+    particle("minecraft:end_rod", ^px, ^py, ^5, 0.02, 0.02, 0.02, 0.0, 10);
+}
+// Compiles to: function ns:draw_pt with storage rs:macro_args
+
+// Math stdlib (fixed-point ×1000)
+let s: int = sin_fixed(45);  // = 707  (sin(45°) × 1000)
+let r: int = sqrt_fixed(2000); // = 1414 (√2 × 1000)
+let m: int = mulfix(a, b);   // = (a × b) / 1000
+```
+
+---
+
+## Known Bugs / Technical Debt
+
+- `redscript check` hardcodes `namespace = 'redscript'`; doesn't run TypeChecker
+- TypeChecker is "warn mode" — type errors don't block compilation
+- `watch` mode recompiles all files on any change (no incremental)
+- Timer stdlib is single-instance only (shared fake player names)
+- Optimizer passes use regex on raw command strings — fragile
+- All of the above are addressed in the refactor plan
+
+---
+
+## Test Server
+
+```bash
+# Server: Paper 1.21.4, port 25561
+cd ~/mc-test-server
+/opt/homebrew/opt/openjdk@21/bin/java -jar paper.jar --nogui
+
+# Deploy
+node dist/cli.js compile examples/readme-demo.mcrs \
+    -o ~/mc-test-server/world/datapacks/rsdemo --namespace rsdemo
+# then in-game: /reload && /function rsdemo:start
+```
+
+---
+
+## Useful Files
+
+| File | Purpose |
+|---|---|
+| `docs/compiler-pipeline-redesign.md` | Full refactor spec (read this first) |
+| `docs/optimization-ideas.md` | Optimization pass catalogue |
+| `examples/readme-demo.mcrs` | Sine wave particle demo |
+| `examples/math-showcase.mcrs` | Math stdlib showcase |
+| `src/stdlib/math.mcrs` | sin/cos/sqrt/mulfix/divfix |
+| `src/__tests__/` | 920 Jest tests — do not break these |
+| `src/runtime/index.ts` | MCRuntime (scoreboard + NBT simulator) |
+
+---
+
+## Profiler (planned)
+
+`MCRuntime` will gain a profiling mode (`{ profiling: { enabled: true } }`):
+- Per-function command counts
+- Error analysis vs JS float ground truth for math functions
+- Coroutine BATCH auto-calibration
+
+See `docs/compiler-pipeline-redesign.md` → "MCRuntime Profiler" section.
+
+---
+
+## VSCode Extension & npm Package Maintenance
+
+### npm package (`redscript-mc`)
+
+Claude can maintain fully:
+- Version bumps via `npm version patch/minor/major` in root `package.json`
+- Publishing: push to main → CI handles it automatically
+- The 920 tests verify CLI behavior end-to-end
+
+### VSCode extension (`editors/vscode/`)
+
+**What Claude can verify automatically:**
+```bash
+cd editors/vscode
+npm run build      # esbuild bundle must succeed
+vsce package       # .vsix must build without errors
+```
+
+Grammar unit tests (if set up with `vscode-tmgrammar-test`):
+```bash
+# Tests that specific source lines tokenize as expected
+# e.g. "fn foo(x: int): int" → keyword.fn, entity.function, etc.
+npm test
+```
+
+**What Claude cannot verify:** visual rendering, hover UI, color themes,
+real-time IntelliSense behavior. These require a running VS Code instance.
+
+**Division of labor:**
+- Claude: grammar files, manifest, version sync, CI publish, update tokens on syntax changes
+- You: visual check before major releases (`code --install-extension *.vsix`)
+
+**When syntax changes (e.g. `->` → `:`, `@keep` → `export`):**
+Claude must update `editors/vscode/syntaxes/redscript.tmLanguage.json`
+to match the new grammar, then rebuild and repackage.
+
+**CI publish flow:**
+Push to main → `publish-extension-on-ci.yml` auto-bumps patch version and
+publishes via `VSCE_PAT` secret. Manual minor/major bump: edit
+`editors/vscode/package.json` version directly before pushing.
+

package/README.md

@@ -2,14 +2,14 @@
 
 <img src="./logo.png" alt="RedScript Logo" width="64" />
 
-<img src="https://img.shields.io/badge/RedScript-1.2.27-red?style=for-the-badge&logo=minecraft&logoColor=white" alt="RedScript" />
+<img src="https://img.shields.io/badge/RedScript-1.2.29-red?style=for-the-badge&logo=minecraft&logoColor=white" alt="RedScript" />
 
 **A typed scripting language that compiles to Minecraft datapacks.**
 
 Write clean game logic. RedScript handles the scoreboard spaghetti.
 
 [![CI](https://github.com/bkmashiro/redscript/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/bkmashiro/redscript/actions/workflows/ci.yml)
-[![Tests](https://img.shields.io/badge/tests-918%20passing-brightgreen)](https://github.com/bkmashiro/redscript)
+[![Tests](https://img.shields.io/badge/tests-920%20passing-brightgreen)](https://github.com/bkmashiro/redscript)
 [![npm](https://img.shields.io/npm/v/redscript-mc?color=cb3837)](https://www.npmjs.com/package/redscript-mc)
 [![npm downloads](https://img.shields.io/npm/dm/redscript-mc?color=cb3837)](https://www.npmjs.com/package/redscript-mc)
 [![VSCode](https://img.shields.io/badge/VSCode-Extension-007ACC?logo=visualstudiocode)](https://marketplace.visualstudio.com/items?itemName=bkmashiro.redscript-vscode)
@@ -20,9 +20,11 @@ Write clean game logic. RedScript handles the scoreboard spaghetti.
 
 ### 🚀 [Try it online — no install needed!](https://redscript-ide.pages.dev)
 
-<img src="./demo.gif" alt="RedScript Demo" width="400" />
+<img src="./demo.gif" alt="RedScript Demo — math curves drawn with particles in Minecraft" width="520" />
 
-*↑ Particles spawning at player position every tick — 100% vanilla, no mods! Just 30 lines of RedScript with full control flow: `if`, `foreach`, `@tick`, f-strings, and more.*
+*↑ Five mathematical curves rendered in real-time with particles — 100% vanilla, no mods!*
+*`y = x·sin(x)` · `y = sin(x) + ½sin(2x)` · `y = e⁻ˣsin(4x)` · `y = tanh(2x)` · `r = cos(2θ)` rose curve*
+*Each curve is computed tick-by-tick using RedScript's fixed-point math stdlib.*
 
 </div>
 
@@ -32,34 +34,33 @@ Write clean game logic. RedScript handles the scoreboard spaghetti.
 
 RedScript is a typed scripting language that compiles to vanilla Minecraft datapacks. Write clean code with variables, functions, loops, and events — RedScript handles the scoreboard commands and `.mcfunction` files for you.
 
-**The demo above?** Just 30 lines:
+**The demo above?** Five math curves drawn with 64 sample points each. The core logic:
 
 ```rs
-let counter: int = 0;
-let running: bool = false;
-
-@tick fn demo_tick() {
-    if (!running) { return; }
-    counter = counter + 1;
-    
-    foreach (p in @a) at @s {
-        particle("minecraft:end_rod", ~0, ~1, ~0, 0.5, 0.5, 0.5, 0.1, 5);
-    }
-    
-    if (counter % 20 == 0) {
-        say(f"Running for {counter} ticks");
-    }
-}
+import "stdlib/math.mcrs"
 
-fn start() {
-    running = true;
-    counter = 0;
-    say(f"Demo started!");
-}
+let phase: int = 0;
+let frame: int = 0;
+
+// 5 curves cycle every 128 ticks (~6.5 s each)
+@tick fn _wave_tick() {
+    phase = (phase + 4) % 360;
+    frame = frame + 1;
+
+    let curve_id: int = (frame / 128) % 5;
+
+    // Compute sin at 9 column offsets (40° apart = full sine wave span)
+    let s0: int = sin_fixed((phase +   0) % 360);
+    let s1: int = sin_fixed((phase +  40) % 360);
+    // ... s2 through s8 ...
+
+    // Draw bar chart: each column height = sin value
+    // (64 fixed particle positions per curve, all respawned each tick)
+    if (curve_id == 0) { _draw_xsinx(); }
+    if (curve_id == 1) { _draw_harmonic(); }
+    // ...
 
-fn stop() {
-    running = false;
-    say(f"Demo stopped at {counter} ticks.");
+    actionbar(@a, f"§e  y = x·sin(x)   phase: {phase}°  center: {s0}‰");
 }
 ```
 

package/README.zh.md

@@ -2,14 +2,14 @@
 
 <img src="./logo.png" alt="RedScript Logo" width="64" />
 
-<img src="https://img.shields.io/badge/RedScript-1.2.27-red?style=for-the-badge&logo=minecraft&logoColor=white" alt="RedScript" />
+<img src="https://img.shields.io/badge/RedScript-1.2.29-red?style=for-the-badge&logo=minecraft&logoColor=white" alt="RedScript" />
 
 **一个编译到 Minecraft Datapack 的类型化脚本语言。**
 
 写干净的游戏逻辑，把记分板的面条代码交给 RedScript 处理。
 
 [![CI](https://github.com/bkmashiro/redscript/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/bkmashiro/redscript/actions/workflows/ci.yml)
-[![Tests](https://img.shields.io/badge/tests-918%20passing-brightgreen)](https://github.com/bkmashiro/redscript)
+[![Tests](https://img.shields.io/badge/tests-920%20passing-brightgreen)](https://github.com/bkmashiro/redscript)
 [![npm](https://img.shields.io/npm/v/redscript-mc?color=cb3837)](https://www.npmjs.com/package/redscript-mc)
 [![npm downloads](https://img.shields.io/npm/dm/redscript-mc?color=cb3837)](https://www.npmjs.com/package/redscript-mc)
 [![VSCode](https://img.shields.io/badge/VSCode-插件-007ACC?logo=visualstudiocode)](https://marketplace.visualstudio.com/items?itemName=bkmashiro.redscript-vscode)
@@ -20,9 +20,11 @@
 
 ### 🚀 [在线试用 — 无需安装！](https://redscript-ide.pages.dev)
 
-<img src="./demo.gif" alt="RedScript Demo" width="400" />
+<img src="./demo.gif" alt="RedScript Demo — 用粒子在 Minecraft 中绘制数学曲线" width="520" />
 
-*↑ 每 tick 在玩家位置生成粒子 — 纯原版，无需 MOD！仅 30 行 RedScript，包含完整控制流：`if`、`foreach`、`@tick`、f-strings 等。*
+*↑ 五条数学函数图像实时粒子渲染 — 纯原版，无需 MOD！*
+*`y = x·sin(x)` · `y = sin(x) + ½sin(2x)` · `y = e⁻ˣsin(4x)` · `y = tanh(2x)` · 玫瑰曲线 `r = cos(2θ)`*
+*每条曲线由 RedScript 定点数学库逐 tick 计算，64 个采样点动态绘制。*
 
 </div>
 
@@ -32,34 +34,32 @@
 
 RedScript 是一门编译到原版 Minecraft 数据包的脚本语言。用变量、函数、循环、事件写代码，RedScript 帮你生成记分板命令和 `.mcfunction` 文件。
 
-**上面的演示？** 只有 30 行：
+**上面的演示？** 五条数学曲线，每条 64 个采样点，核心逻辑：
 
 ```rs
-let counter: int = 0;
-let running: bool = false;
-
-@tick fn demo_tick() {
-    if (!running) { return; }
-    counter = counter + 1;
-    
-    foreach (p in @a) at @s {
-        particle("minecraft:end_rod", ~0, ~1, ~0, 0.5, 0.5, 0.5, 0.1, 5);
-    }
-    
-    if (counter % 20 == 0) {
-        say(f"已运行 {counter} ticks");
-    }
-}
+import "stdlib/math.mcrs"
 
-@keep fn start() {
-    running = true;
-    counter = 0;
-    say(f"Demo 已启动！");
-}
+let phase: int = 0;
+let frame: int = 0;
+
+// 5 条曲线每 128 tick (~6.5 秒) 自动切换
+@tick fn _wave_tick() {
+    phase = (phase + 4) % 360;
+    frame = frame + 1;
+
+    let curve_id: int = (frame / 128) % 5;
+
+    // 计算 9 列的 sin 值（每列相差 40°，刚好覆盖完整周期）
+    let s0: int = sin_fixed((phase +   0) % 360);
+    let s1: int = sin_fixed((phase +  40) % 360);
+    // ... s2 到 s8 ...
+
+    // 绘制图像：每条曲线有 64 个固定坐标粒子，每 tick 全部重绘
+    if (curve_id == 0) { _draw_xsinx(); }
+    if (curve_id == 1) { _draw_harmonic(); }
+    // ...
 
-@keep fn stop() {
-    running = false;
-    say(f"Demo 已停止，共运行 {counter} ticks。");
+    actionbar(@a, f"§e  y = x·sin(x)   phase: {phase}°  center: {s0}‰");
 }
 ```