redscript-mc 2.1.0 → 2.2.1

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to RedScript will be documented in this file.
 
+## [2.1.1] - 2026-03-16
+
+### Added
+- stdlib include path: `import "stdlib/math"` without specifying full path
+- `--include <dir>` CLI flag for custom library paths
+- LSP hover for 50+ builtin functions and all decorators (@tick/@load/@coroutine/@schedule/@on_trigger)
+- f-string syntax highlighting in VSCode extension
+
+### Changed
+- Example files cleaned up: removed stale/redundant examples, added coroutine/enum/scheduler demos
+
 ## [1.2.15] - 2026-03-13
 
 ### Changed

package/README.md

@@ -2,14 +2,14 @@
 
 <img src="./logo.png" alt="RedScript Logo" width="64" />
 
-<img src="https://img.shields.io/badge/RedScript-2.0.0-red?style=for-the-badge&logo=minecraft&logoColor=white" alt="RedScript" />
+<img src="https://img.shields.io/badge/RedScript-2.1.1-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-857%20passing-brightgreen)](https://github.com/bkmashiro/redscript)
+[![Tests](https://img.shields.io/badge/tests-1123%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)
@@ -37,7 +37,7 @@ RedScript is a typed scripting language that compiles to vanilla Minecraft datap
 **The demo above?** Five math curves drawn with 64 sample points each. The core logic:
 
 ```rs
-import "stdlib/math.mcrs"
+import "stdlib/math"
 
 let phase: int = 0;
 let frame: int = 0;
@@ -73,20 +73,32 @@ let frame: int = 0;
 - ✅ Builtins accept runtime macro variables in any argument position
 - ✅ f-strings like `f"Score: {points}"` for dynamic output
 - ✅ Public functions are preserved automatically; `_privateFn()` stays private
+- ✅ `enum` types with `match` dispatch (zero-runtime overhead)
+- ✅ Multi-return values: `fn divmod(a: int, b: int): (int, int)`
+- ✅ Generics: `fn max<T>(a: T, b: T): T` (monomorphized)
+- ✅ `Option<T>` null safety: `Some(x)` / `None` / `if let Some(x) = opt`
+- ✅ `@coroutine(batch=N)` for tick-spread loops (no more maxCommandChain hits)
+- ✅ `@schedule(ticks=N)` to delay function execution
+- ✅ Module system: `module math; import math::sin;`
+- ✅ Multi-version targets: `--mc-version 1.20.2`
+- ✅ Source maps: `--source-map` for debugging
+- ✅ Language Server Protocol: diagnostics, hover, go-to-def, completion
 - ✅ One file -> ready-to-use datapack
 
 ---
 
-### What's New in v2.0.0
+### What's New in v2.1.x
 
-- New compiler pipeline: **AST → HIR → MIR → LIR → emit**
-- New LIR optimizer passes (dead slot elimination + constant immediate folding)
-- CLI `compile` now runs on the v2 pipeline by default
-- `use "..."` import resolution fully supported in v2 (including library modules)
-- Macro calls (`^var`/`~var`) supported end-to-end in v2 emitter
-- Struct/impl lowering completed in v2 (field slots + method dispatch)
-- Unified source tree: old `src2/` merged back into `src/`
-- Published as **redscript-mc@2.0.0**
+- **`enum` + `match` dispatch** — zero-runtime-overhead state machines; the compiler folds enum variants to integer constants and uses `execute if score` dispatch with no heap allocation
+- **Multi-return values** — `fn divmod(a: int, b: int): (int, int)` unpacks to separate scoreboard slots; no struct wrapper needed
+- **Generics** — `fn max<T>(a: T, b: T): T` is fully monomorphized at compile time; no boxing, no indirection
+- **`Option<T>` null safety** — `Some(x)` / `None` with `if let Some(x) = opt` pattern binding; safe access to optional values without sentinel integers
+- **`@coroutine(batch=N)`** — spreads a heavy loop across multiple ticks (`batch=50` means 50 iterations/tick), avoiding `maxCommandChainLength` hits on large workloads
+- **`@schedule(ticks=N)`** — delays a function call by N game ticks; compiles to `schedule function` with automatic namespace scoping
+- **Module system** — `module math;` declares a named module; consumers `import math::sin` to tree-shake individual symbols
+- **Multi-version targets** — `--mc-version 1.20.2` switches emit strategy (macro sub-functions vs. legacy scoreboards) for the target server version
+- **Source maps** — `--source-map` emits a `.mcrs.map` sidecar that maps each `.mcfunction` line back to the original source; enables in-editor debugging
+- **LSP: hover + completion for builtins & decorators** — 50+ builtin functions and all decorators (`@tick`/`@load`/`@coroutine`/`@schedule`/`@on_trigger`) now show inline docs on hover
 
 ---
 
@@ -192,6 +204,22 @@ fn on_diamond() {
 fn on_death() {
     scoreboard_add(@s, #deaths, 1);
 }
+
+// Delay execution by N ticks (20t = 1 second)
+@schedule(ticks=20)
+fn after_one_second(): void {
+    title(@a, "One second later!");
+}
+
+// Spread a heavy loop across multiple ticks (batch=N iterations/tick)
+@coroutine(batch=50, onDone=all_done)
+fn process_all(): void {
+    let i: int = 0;
+    while (i < 1000) {
+        // work spread over ~20 ticks instead of lagging one tick
+        i = i + 1;
+    }
+}
 ```
 
 #### Control Flow
@@ -261,6 +289,9 @@ redscript compile <file>       Compile to datapack (default) or structure
   -o, --output <dir>           Output directory         [default: ./out]
   --target datapack|structure  Output format            [default: datapack]
   --namespace <ns>             Datapack namespace       [default: filename]
+  --mc-version <ver>           Target MC version        [default: 1.21]
+  --include <dir>              Extra library search path (repeatable)
+  --source-map                 Emit .mcrs.map source map for debugging
   --no-optimize                Skip optimizer passes
   --stats                      Print optimizer statistics
 
@@ -270,39 +301,53 @@ redscript validate <file>      Validate MC commands
 
 ---
 
+### Stdlib
+
+RedScript ships a built-in standard library. Use the short form — no path needed:
+
+```rs
+import "stdlib/math"      // fixed-point math
+import "stdlib/vec"       // 2D/3D vector geometry
+import "stdlib/combat"    // damage, kill-check helpers
+import "stdlib/player"    // health, alive check, range
+import "stdlib/cooldown"  // per-player cooldown tracking
+```
+
+Custom library paths can be added with `--include <dir>` so your own modules work the same way.
+
 ### Standard Library
 
 All stdlib files use `module library;` — only the functions you actually call are compiled in.
 
 ```rs
-import "stdlib/math.mcrs"       // abs, sign, min, max, clamp, lerp, isqrt, sqrt_fixed,
+import "stdlib/math"            // abs, sign, min, max, clamp, lerp, isqrt, sqrt_fixed,
                                 // pow_int, gcd, lcm, sin_fixed, cos_fixed, map, ceil_div,
                                 // log2_int, mulfix, divfix, smoothstep, smootherstep
 
-import "stdlib/vec.mcrs"        // dot2d, cross2d, length2d_fixed, distance2d_fixed,
+import "stdlib/vec"             // dot2d, cross2d, length2d_fixed, distance2d_fixed,
                                 // manhattan, chebyshev, atan2_fixed, normalize2d_x/y,
                                 // rotate2d_x/y, lerp2d_x/y, dot3d, cross3d_x/y/z,
                                 // length3d_fixed
 
-import "stdlib/advanced.mcrs"   // fib, is_prime, collatz_steps, digit_sum, reverse_int,
+import "stdlib/advanced"        // fib, is_prime, collatz_steps, digit_sum, reverse_int,
                                 // mod_pow, hash_int, noise1d, bezier_quad,
                                 // mandelbrot_iter, julia_iter, angle_between,
                                 // clamp_circle_x/y, newton_sqrt, digital_root
 
-import "stdlib/bigint.mcrs"     // bigint_init, bigint_from_int_a/b, bigint_add/sub/mul,
+import "stdlib/bigint"          // bigint_init, bigint_from_int_a/b, bigint_add/sub/mul,
                                 // bigint_compare, bigint_mul_small, bigint_fib
                                 // — up to 32 decimal digits, runs on MC scoreboard
 
-import "stdlib/player.mcrs"     // is_alive, in_range, get_health
-import "stdlib/timer.mcrs"      // start_timer, tick_timer, has_elapsed
-import "stdlib/cooldown.mcrs"   // set_cooldown, check_cooldown
-import "stdlib/mobs.mcrs"       // ZOMBIE, SKELETON, CREEPER, ... (60+ constants)
+import "stdlib/player"          // is_alive, in_range, get_health
+import "stdlib/timer"           // start_timer, tick_timer, has_elapsed
+import "stdlib/cooldown"        // set_cooldown, check_cooldown
+import "stdlib/mobs"            // ZOMBIE, SKELETON, CREEPER, ... (60+ constants)
 ```
 
 **Example — computing Fibonacci(50) in-game:**
 
 ```rs
-import "stdlib/bigint.mcrs"
+import "stdlib/bigint"
 
 fn show_fib() {
     bigint_fib(50);
@@ -316,6 +361,26 @@ fn show_fib() {
 
 ---
 
+### Examples
+
+The `examples/` directory contains ready-to-compile demos:
+
+| File | What it shows |
+|---|---|
+| `readme-demo.mcrs` | Real-time sine wave particles — `@tick`, `foreach`, f-strings, math stdlib |
+| `math-showcase.mcrs` | All stdlib math modules: trig, vectors, BigInt, fractals |
+| `showcase.mcrs` | Full feature tour: structs, enums, `match`, lambdas, `@tick`/`@load` |
+| `coroutine-demo.mcrs` | `@coroutine(batch=50)` — spread 1000 iterations across ~20 ticks |
+| `enum-demo.mcrs` | Enum state machine: NPC AI cycling Idle → Moving → Attacking with `match` |
+| `scheduler-demo.mcrs` | `@schedule(ticks=20)` — delayed events, chained schedules |
+
+Compile any example:
+```bash
+node dist/cli.js compile examples/coroutine-demo.mcrs -o ~/mc-server/datapacks/demo --namespace demo
+```
+
+---
+
 ### Further Reading
 
 | | |

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-2.0.0-red?style=for-the-badge&logo=minecraft&logoColor=white" alt="RedScript" />
+<img src="https://img.shields.io/badge/RedScript-2.1.1-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-857%20passing-brightgreen)](https://github.com/bkmashiro/redscript)
+[![Tests](https://img.shields.io/badge/tests-1123%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)
@@ -37,7 +37,7 @@ RedScript 是一门编译到原版 Minecraft 数据包的脚本语言。用变
 **上面的演示？** 五条数学曲线，每条 64 个采样点，核心逻辑：
 
 ```rs
-import "stdlib/math.mcrs"
+import "stdlib/math"
 
 let phase: int = 0;
 let frame: int = 0;
@@ -65,40 +65,36 @@ let frame: int = 0;
 
 **你得到：**
 - ✅ `let` / `const` 变量（告别 `scoreboard players set`）
-- ✅ `if` / `else` / `for` / `foreach` 完整控制流
+- ✅ `if` / `else` / `for` / `foreach` / `break` / `continue` 完整控制流
 - ✅ `@tick` / `@load` / `@on(Event)` 装饰器
 - ✅ `foreach (p in @a) at @s` — 遍历实体并设置执行上下文
 - ✅ f-strings 如 `f"分数: {points}"` 动态输出
+- ✅ `enum` 类型 + `match` 分发（零运行时开销）
+- ✅ 多返回值：`fn divmod(a: int, b: int): (int, int)`
+- ✅ 泛型：`fn max<T>(a: T, b: T): T`（单态化）
+- ✅ `Option<T>` 空值安全：`Some(x)` / `None` / `if let Some(x) = opt`
+- ✅ `@coroutine(batch=N)` 将循环分散到多个 tick（不再触发 maxCommandChain 限制）
+- ✅ `@schedule(ticks=N)` 延迟执行函数
+- ✅ 模块系统：`module math; import math::sin;`
+- ✅ 多版本目标：`--mc-version 1.20.2`
+- ✅ 源码映射：`--source-map` 支持调试
+- ✅ 语言服务协议（LSP）：诊断、悬停提示、跳转定义、代码补全
 - ✅ 一个文件 → 可直接使用的 datapack
 
 ---
 
-### v1.2.27 新增内容
+### v2.1.x 新增内容
 
-- **BigInt 实机验证通过** (`bigint.mcrs`)：任意精度整数在 MC 记分板 + NBT 上完整运行 — base 10000 × 8 limbs = 最多 32 位十进制数；`bigint_fib(50)` = 12,586,269,025 在 Paper 1.21.4 实机验证正确
-- **`storage_set_int` 宏修复**：动态 NBT 数组写入改用 `execute store result storage` 而非 `data modify set value $(n)` — 规避 Minecraft 宏机制对整数值的静默替换 bug
-- **完整标准库** (`math.mcrs`、`vec.mcrs`、`advanced.mcrs`、`bigint.mcrs`、`showcase.mcrs`)：18 个数学函数、14 个向量几何函数、20+ 数论与分形函数
-- **`module library;` pragma**：库文件零成本树摇 — 标准库永远不会撑大你的数据包
-- **`@require_on_load(fn)` 装饰器**：sin/cos/atan 查找表初始化器的声明式加载依赖跟踪
-
-### v1.2.26 新增内容
-
-- **数学标准库** (`math.mcrs`)：18 个定点数函数 — `abs`、`sign`、`min`、`max`、`clamp`、`lerp`、`isqrt`、`sqrt_fixed`、`pow_int`、`gcd`、`lcm`、`sin_fixed`、`cos_fixed`、`map`、`ceil_div`、`log2_int`、`mulfix`、`divfix`、`smoothstep`、`smootherstep`
-- **向量标准库** (`vec.mcrs`)：2D / 3D 几何 — 点积/叉积、`length2d_fixed`、`atan2_fixed`（二分搜索正切表，O(log 46)）、`normalize2d`、`rotate2d`、`lerp2d`、完整 3D 叉积
-- **高级标准库** (`advanced.mcrs`)：数论（`fib`、`is_prime`、`collatz_steps`、`mod_pow`）、哈希/噪声（splitmix32 `hash_int`、`noise1d`）、曲线（`bezier_quad`）、分形（`mandelbrot_iter`、`julia_iter`）、几何实验
-- **BigInt** (`bigint.mcrs`)：任意精度整数架构设计 — base 10000 × 8 limbs = 最多 32 位十进制数
-- **编译器修复**：`isqrt` 大数收敛、优化器拷贝传播别名失效、跨函数变量命名冲突、MCRuntime 数组索引正则
-
-### v1.2.25 新增内容
-
-- `impl` 块与方法，支持围绕结构体构建面向对象风格 API
-- `is` 类型收窄，实体判断更安全
-- 使用 `@on(Event)` 的静态事件系统
-- 面向运行时输出的 f-string
-- `Timer::new(...)` 与实例方法组成的 Timer OOP API
-- `setTimeout(...)` 与 `setInterval(...)` 调度辅助函数
-- 优化器中的死代码消除
-- 标准库新增 313 个 Minecraft 标签常量
+- **`enum` + `match` 分发** — 零运行时开销的状态机；编译器将枚举变体折叠为整数常量，用 `execute if score` 分发，无堆分配
+- **多返回值** — `fn divmod(a: int, b: int): (int, int)` 解包到独立记分板槽位，不需要结构体包装
+- **泛型** — `fn max<T>(a: T, b: T): T` 在编译期完整单态化，无装箱无间接引用
+- **`Option<T>` 空值安全** — `Some(x)` / `None` 与 `if let Some(x) = opt` 模式绑定，不再依赖哨兵整数
+- **`@coroutine(batch=N)`** — 将繁重循环分散到多个 tick（`batch=50` 表示每 tick 执行 50 次迭代），避免触发 `maxCommandChainLength` 限制
+- **`@schedule(ticks=N)`** — 延迟 N 个游戏 tick 后执行函数，编译为带自动命名空间前缀的 `schedule function`
+- **模块系统** — `module math;` 声明命名模块；调用方 `import math::sin` 可按符号树摇
+- **多版本目标** — `--mc-version 1.20.2` 针对目标服务器版本切换发射策略（宏子函数 vs 传统记分板）
+- **源码映射** — `--source-map` 生成 `.mcrs.map` 附属文件，将每行 `.mcfunction` 映射回原始源码，支持编辑器内调试
+- **LSP 悬停 + 补全** — 50+ 内置函数及所有装饰器（`@tick`/`@load`/`@coroutine`/`@schedule`/`@on_trigger`）均支持悬停内联文档
 
 ---
 
@@ -273,6 +269,9 @@ redscript compile <file>       编译为 datapack（默认）或 structure
   -o, --output <dir>           输出目录              [默认: ./out]
   --target datapack|structure  输出格式              [默认: datapack]
   --namespace <ns>             Datapack 命名空间     [默认: 文件名]
+  --mc-version <ver>           目标 MC 版本          [默认: 1.21]
+  --include <dir>              额外库搜索路径（可重复）
+  --source-map                 生成 .mcrs.map 源码映射文件
   --no-optimize                禁用优化器
   --stats                      输出优化器统计信息
 
@@ -284,37 +283,49 @@ redscript validate <file>      验证 MC 命令语法
 
 ### 标准库
 
+RedScript 内置标准库，使用短路径直接导入，无需指定完整文件路径：
+
+```rs
+import "stdlib/math"      // 定点数学
+import "stdlib/vec"       // 2D/3D 向量几何
+import "stdlib/combat"    // 伤害、击杀检测辅助函数
+import "stdlib/player"    // 血量、存活检测、范围判断
+import "stdlib/cooldown"  // 每玩家冷却时间管理
+```
+
+通过 `--include <dir>` 可添加自定义库路径，自有模块也能用同样的短路径导入。
+
 所有标准库文件都使用 `module library;` —— 只有你实际调用的函数才会编译进去。
 
 ```rs
-import "stdlib/math.mcrs"       // abs, sign, min, max, clamp, lerp, isqrt, sqrt_fixed,
+import "stdlib/math"            // abs, sign, min, max, clamp, lerp, isqrt, sqrt_fixed,
                                 // pow_int, gcd, lcm, sin_fixed, cos_fixed, map, ceil_div,
                                 // log2_int, mulfix, divfix, smoothstep, smootherstep
 
-import "stdlib/vec.mcrs"        // dot2d, cross2d, length2d_fixed, distance2d_fixed,
+import "stdlib/vec"             // dot2d, cross2d, length2d_fixed, distance2d_fixed,
                                 // manhattan, chebyshev, atan2_fixed, normalize2d_x/y,
                                 // rotate2d_x/y, lerp2d_x/y, dot3d, cross3d_x/y/z,
                                 // length3d_fixed
 
-import "stdlib/advanced.mcrs"   // fib, is_prime, collatz_steps, digit_sum, reverse_int,
+import "stdlib/advanced"        // fib, is_prime, collatz_steps, digit_sum, reverse_int,
                                 // mod_pow, hash_int, noise1d, bezier_quad,
                                 // mandelbrot_iter, julia_iter, angle_between,
                                 // clamp_circle_x/y, newton_sqrt, digital_root
 
-import "stdlib/bigint.mcrs"     // bigint_init, bigint_from_int_a/b, bigint_add/sub/mul,
+import "stdlib/bigint"          // bigint_init, bigint_from_int_a/b, bigint_add/sub/mul,
                                 // bigint_compare, bigint_mul_small, bigint_fib
                                 // — 最多 32 位十进制数，纯记分板运行
 
-import "stdlib/player.mcrs"     // is_alive, in_range, get_health
-import "stdlib/timer.mcrs"      // start_timer, tick_timer, has_elapsed
-import "stdlib/cooldown.mcrs"   // set_cooldown, check_cooldown
-import "stdlib/mobs.mcrs"       // ZOMBIE, SKELETON, CREEPER ... (60+ 实体常量)
+import "stdlib/player"     // is_alive, in_range, get_health
+import "stdlib/timer"      // start_timer, tick_timer, has_elapsed
+import "stdlib/cooldown"   // set_cooldown, check_cooldown
+import "stdlib/mobs"       // ZOMBIE, SKELETON, CREEPER ... (60+ 实体常量)
 ```
 
 **示例 — 游戏内计算斐波那契数列第 50 项：**
 
 ```rs
-import "stdlib/bigint.mcrs"
+import "stdlib/bigint"
 
 fn show_fib() {
     bigint_fib(50);
@@ -343,32 +354,21 @@ fn show_fib() {
 
 ### 更新日志亮点
 
-#### v1.2.27（2026-03-14）
-
-- **BigInt 实机修复**：`storage_set_int` 宏改用 `execute store result storage`，规避 MC 宏整数替换 bug；BigInt 在 Paper 1.21.4 实机验证通过
-- showcase 示例修复：`atan2_fixed` 返回度数（0–360），更正不必要的除以 1000；`mod_pow` 测试改用小 modulus 避免 INT32 溢出
-
-#### v1.2.26（2026-03-14）
-
-- 完整的数学/向量/高级/BigInt 标准库（详见上方）
-- `module library;` pragma，实现零成本树摇
-- `storage_get_int` / `storage_set_int` 动态 NBT 数组内置函数
-- 编译器修复：`isqrt` 收敛、拷贝传播、变量作用域命名
-
-#### v1.2.25（2026-03-13）
+#### v2.1.1（2026-03-16）
 
-- 实体类型层级与 `W_IMPOSSIBLE_AS` 警告
-- 变量名混淆（`$a`、`$b`、`$c` ...），最小化记分板占用
-- CI/CD 自动化：每次推送自动发布 npm + VSCode 插件
+- stdlib 包含路径支持：`import "stdlib/math"` 无需指定完整路径
+- `--include <dir>` CLI 参数，支持自定义库路径
+- LSP 悬停支持 50+ 内置函数及全部装饰器
+- VSCode 插件支持 f-string 语法高亮
 
-#### v1.2.0
+#### v2.0.0
 
-- 新增 `impl` 块、实例方法与静态构造函数
-- 新增 `is` 类型收窄，提升实体相关控制流的类型安全
-- 新增 `@on(Event)` 静态事件与回调调度内置函数
-- 新增运行时输出用 f-string
-- 标准库补充 Timer OOP API 与 313 个 MC 标签常量
-- 优化器支持死代码消除
+- 新编译器管线：**AST → HIR → MIR → LIR → emit**
+- 新 LIR 优化器（死槽位消除 + 常量立即数折叠）
+- CLI `compile` 默认使用 v2 管线
+- 完整 `use "..."` 导入解析（含库模块）
+- 宏调用（`^var`/`~var`）在 v2 发射器中端到端支持
+- v2 中完成结构体/impl 降级（字段槽位 + 方法分发）
 
 完整发布说明见 [CHANGELOG.md](./CHANGELOG.md)。
 

package/dist/src/__tests__/e2e/basic.test.js

@@ -136,5 +136,30 @@ describe('e2e: basic compilation', () => {
         const tickJson = getFile(result.files, 'tick.json');
         expect(tickJson).toBeUndefined();
     });
+    test('array literal emits data modify storage command', () => {
+        const source = `
+      fn test_arrays(): void {
+        let nums: int[] = [10, 20, 30, 40, 50];
+      }
+    `;
+        const result = (0, compile_1.compile)(source, { namespace: 'array_test' });
+        const fn = getFile(result.files, 'test_arrays.mcfunction');
+        expect(fn).toBeDefined();
+        expect(fn).toContain('data modify storage array_test:arrays nums set value [10, 20, 30, 40, 50]');
+    });
+    test('array index access emits data get storage command', () => {
+        const source = `
+      fn test_arrays(): void {
+        let nums: int[] = [10, 20, 30, 40, 50];
+        scoreboard_set("#arr_0", #rs, nums[0]);
+      }
+    `;
+        const result = (0, compile_1.compile)(source, { namespace: 'array_test' });
+        const fn = getFile(result.files, 'test_arrays.mcfunction');
+        expect(fn).toBeDefined();
+        expect(fn).toContain('data modify storage array_test:arrays nums set value [10, 20, 30, 40, 50]');
+        expect(fn).toContain('data get storage array_test:arrays nums[0]');
+        expect(fn).toContain('#arr_0');
+    });
 });
 //# sourceMappingURL=basic.test.js.map

package/dist/src/__tests__/e2e/coroutine.test.js

@@ -109,6 +109,28 @@ describe('e2e: @coroutine', () => {
         const helperFn = getFile(result.files, 'helper.mcfunction');
         expect(helperFn).toBeDefined();
     });
+    test('@coroutine with macro call_macro is skipped with warning', () => {
+        // call_macro: a function that has isMacro params will be called via call_macro
+        // We simulate this with raw() containing ${var} which generates __raw:\x01 in MIR
+        const source = `
+      @coroutine(batch=10)
+      fn with_macro_raw(): void {
+        let i: int = 0;
+        while (i < 100) {
+          let x: int = i;
+          raw("particle minecraft:end_rod ^$\{x} ^0 ^0 0 0 0 0 1 force @a");
+          i = i + 1;
+        }
+      }
+    `;
+        const result = (0, compile_1.compile)(source, { namespace: 'corotest' });
+        // Should emit a warning about skipping
+        expect(result.warnings.some(w => w.includes('@coroutine cannot be applied') && w.includes('with_macro_raw'))).toBe(true);
+        // Should NOT generate continuation files — function kept as-is
+        const paths = getFileNames(result.files);
+        const contFiles = paths.filter(p => p.includes('_coro_'));
+        expect(contFiles.length).toBe(0);
+    });
     test('default batch value is 10 when not specified', () => {
         // @coroutine without batch should default to batch=10
         // We test by ensuring compilation succeeds

package/dist/src/__tests__/lsp.test.js

@@ -10,6 +10,7 @@ const lexer_1 = require("../lexer");
 const parser_1 = require("../parser");
 const typechecker_1 = require("../typechecker");
 const diagnostics_1 = require("../diagnostics");
+const metadata_1 = require("../builtins/metadata");
 // ---------------------------------------------------------------------------
 // Helpers mirrored from lsp/server.ts (tested independently)
 // ---------------------------------------------------------------------------
@@ -231,6 +232,81 @@ fn anotherFn(x: int): int { return x; }
     });
 });
 // ---------------------------------------------------------------------------
+// Hover — builtin functions
+// ---------------------------------------------------------------------------
+const DECORATOR_DOCS = {
+    tick: 'Runs every MC game tick (~20 Hz). No arguments.',
+    load: 'Runs on `/reload`. Use for initialization logic.',
+    coroutine: 'Splits loops into tick-spread continuations. Arg: `batch=N` (steps per tick, default 1).',
+    schedule: 'Schedules the function to run after N ticks. Arg: `ticks=N`.',
+    on_trigger: 'Runs when a trigger scoreboard objective is set by a player. Arg: trigger name.',
+    keep: 'Prevents the compiler from dead-code-eliminating this function.',
+    on: 'Generic event handler decorator.',
+    on_advancement: 'Runs when a player earns an advancement. Arg: advancement id.',
+    on_craft: 'Runs when a player crafts an item. Arg: item id.',
+    on_death: 'Runs when a player dies.',
+    on_join_team: 'Runs when a player joins a team. Arg: team name.',
+    on_login: 'Runs when a player logs in.',
+};
+describe('LSP hover — builtin functions', () => {
+    it('has metadata for say', () => {
+        const b = metadata_1.BUILTIN_METADATA['say'];
+        expect(b).toBeDefined();
+        expect(b.params.length).toBeGreaterThan(0);
+        expect(b.returns).toBe('void');
+        expect(b.doc).toBeTruthy();
+    });
+    it('has metadata for kill', () => {
+        const b = metadata_1.BUILTIN_METADATA['kill'];
+        expect(b).toBeDefined();
+        expect(b.returns).toBe('void');
+    });
+    it('has metadata for tellraw', () => {
+        const b = metadata_1.BUILTIN_METADATA['tellraw'];
+        expect(b).toBeDefined();
+        const paramStr = b.params.map(p => `${p.name}: ${p.type}${p.required ? '' : '?'}`).join(', ');
+        const sig = `fn ${b.name}(${paramStr}): ${b.returns}`;
+        expect(sig).toMatch(/^fn tellraw/);
+        expect(sig).toContain('target');
+    });
+    it('formats builtin hover markdown', () => {
+        const b = metadata_1.BUILTIN_METADATA['particle'];
+        expect(b).toBeDefined();
+        const paramStr = b.params.map(p => `${p.name}: ${p.type}${p.required ? '' : '?'}`).join(', ');
+        const sig = `fn ${b.name}(${paramStr}): ${b.returns}`;
+        const markdown = `\`\`\`redscript\n${sig}\n\`\`\`\n${b.doc}`;
+        expect(markdown).toContain('```redscript');
+        expect(markdown).toContain('fn particle');
+        expect(markdown).toContain(b.doc);
+    });
+});
+// ---------------------------------------------------------------------------
+// Hover — decorators
+// ---------------------------------------------------------------------------
+describe('LSP hover — decorators', () => {
+    it('has docs for @tick', () => {
+        expect(DECORATOR_DOCS['tick']).toContain('tick');
+    });
+    it('has docs for @load', () => {
+        expect(DECORATOR_DOCS['load']).toContain('reload');
+    });
+    it('has docs for @coroutine', () => {
+        expect(DECORATOR_DOCS['coroutine']).toContain('batch');
+    });
+    it('has docs for @schedule', () => {
+        expect(DECORATOR_DOCS['schedule']).toContain('ticks');
+    });
+    it('has docs for @on_trigger', () => {
+        expect(DECORATOR_DOCS['on_trigger']).toContain('trigger');
+    });
+    it('formats decorator hover markdown', () => {
+        const name = 'tick';
+        const doc = DECORATOR_DOCS[name];
+        const markdown = `**@${name}** — ${doc}`;
+        expect(markdown).toBe(`**@tick** — ${DECORATOR_DOCS['tick']}`);
+    });
+});
+// ---------------------------------------------------------------------------
 // Server module import (smoke test — does not start stdio)
 // ---------------------------------------------------------------------------
 describe('LSP server module', () => {

package/dist/src/__tests__/mc-integration.test.js

@@ -105,13 +105,25 @@ beforeAll(async () => {
         console.warn(`  Then restart the MC server and re-run tests.`);
         return;
     }
-    // ── Write fixtures + use safe reloadData (no /reload confirm) ───────
-    // counter.mcrs
-    if (fs.existsSync(path.join(__dirname, '../examples/counter.mcrs'))) {
-        writeFixture(fs.readFileSync(path.join(__dirname, '../examples/counter.mcrs'), 'utf-8'), 'counter');
+    // ── Clear stale minecraft tag files before writing fixtures ──────────
+    for (const tagFile of ['data/minecraft/tags/function/tick.json', 'data/minecraft/tags/function/load.json',
+        'data/minecraft/tags/functions/tick.json', 'data/minecraft/tags/functions/load.json']) {
+        const p = path.join(DATAPACK_DIR, tagFile);
+        if (fs.existsSync(p))
+            fs.writeFileSync(p, JSON.stringify({ values: [] }, null, 2));
     }
-    if (fs.existsSync(path.join(__dirname, '../examples/world_manager.mcrs'))) {
-        writeFixture(fs.readFileSync(path.join(__dirname, '../examples/world_manager.mcrs'), 'utf-8'), 'world_manager');
+    // ── Write fixtures + use safe reloadData (no /reload confirm) ───────
+    // counter.mcrs (use fixtures if examples was removed)
+    const counterSrc = fs.existsSync(path.join(__dirname, '../examples/counter.mcrs'))
+        ? fs.readFileSync(path.join(__dirname, '../examples/counter.mcrs'), 'utf-8')
+        : fs.readFileSync(path.join(__dirname, 'fixtures/counter.mcrs'), 'utf-8');
+    writeFixture(counterSrc, 'counter');
+    // world_manager.mcrs
+    const wmPath = fs.existsSync(path.join(__dirname, '../examples/world_manager.mcrs'))
+        ? path.join(__dirname, '../examples/world_manager.mcrs')
+        : path.join(__dirname, '../src/examples/world_manager.mcrs');
+    if (fs.existsSync(wmPath)) {
+        writeFixture(fs.readFileSync(wmPath, 'utf-8'), 'world_manager');
     }
     writeFixture(`
     @tick
@@ -394,9 +406,9 @@ describe('MC Integration Tests', () => {
         if (!serverOnline)
             return;
         await mc.fullReset({ clearArea: false, killEntities: true, resetScoreboards: false });
-        await mc.command('/summon minecraft:armor_stand 0 65 0');
-        await mc.command('/summon minecraft:armor_stand 2 65 0');
-        await mc.command('/summon minecraft:armor_stand 4 65 0');
+        await mc.command('/summon minecraft:armor_stand 0 65 0 {NoGravity:1b}');
+        await mc.command('/summon minecraft:armor_stand 2 65 0 {NoGravity:1b}');
+        await mc.command('/summon minecraft:armor_stand 4 65 0 {NoGravity:1b}');
         await mc.ticks(5);
         const stands = await mc.entities('@e[type=minecraft:armor_stand]');
         expect(stands.length).toBe(3);
@@ -538,21 +550,21 @@ describe('E2E Scenario Tests', () => {
             return;
         await mc.command('/function match_test:__load');
         // Test match on value 2
-        await mc.command('/scoreboard players set $p0 rs 2');
+        await mc.command('/scoreboard players set $p0 __match_test 2');
         await mc.command('/function match_test:classify');
         await mc.ticks(5);
         let out = await mc.scoreboard('#match', 'out');
         expect(out).toBe(20);
         console.log(`  match(2) → out=${out} (expect 20) ✓`);
         // Test match on value 3
-        await mc.command('/scoreboard players set $p0 rs 3');
+        await mc.command('/scoreboard players set $p0 __match_test 3');
         await mc.command('/function match_test:classify');
         await mc.ticks(5);
         out = await mc.scoreboard('#match', 'out');
         expect(out).toBe(30);
         console.log(`  match(3) → out=${out} (expect 30) ✓`);
         // Test default branch (value 99)
-        await mc.command('/scoreboard players set $p0 rs 99');
+        await mc.command('/scoreboard players set $p0 __match_test 99');
         await mc.command('/function match_test:classify');
         await mc.ticks(5);
         out = await mc.scoreboard('#match', 'out');
@@ -714,7 +726,7 @@ describe('MC Integration - New Features', () => {
         expect(armorStands).toBe(2); // 2 armor_stands matched
         expect(items).toBe(1); // 1 item matched
         await mc.command('/function is_check_test:cleanup').catch(() => { });
-    });
+    }, 30000); // extended timeout: entity spawn + reload can take >5 s
     test('event-test.mcrs: @on(PlayerDeath) compiles and loads', async () => {
         if (!serverOnline)
             return;