redscript-mc 3.0.1 → 3.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (225) hide show
  1. package/.github/workflows/ci.yml +1 -0
  2. package/README.md +119 -313
  3. package/README.zh.md +118 -314
  4. package/ROADMAP.md +5 -5
  5. package/dist/data/impl_test/function/counter/get.mcfunction +5 -0
  6. package/dist/data/impl_test/function/counter/inc.mcfunction +7 -0
  7. package/dist/data/impl_test/function/counter/new.mcfunction +4 -0
  8. package/dist/data/impl_test/function/load.mcfunction +1 -0
  9. package/dist/data/impl_test/function/test_impl.mcfunction +10 -0
  10. package/dist/data/minecraft/tags/function/load.json +5 -0
  11. package/dist/data/playground/function/load.mcfunction +1 -0
  12. package/dist/data/playground/function/start.mcfunction +4 -0
  13. package/dist/data/playground/function/start__say_macro_t1.mcfunction +1 -0
  14. package/dist/data/playground/function/stop.mcfunction +5 -0
  15. package/dist/data/playground/function/stop__say_macro_t0.mcfunction +1 -0
  16. package/dist/data/stdlib_queue8_test/function/__queue_append_apply.mcfunction +4 -0
  17. package/dist/data/stdlib_queue8_test/function/__queue_peek_apply.mcfunction +4 -0
  18. package/dist/data/stdlib_queue8_test/function/__queue_size_raw_apply.mcfunction +4 -0
  19. package/dist/data/stdlib_queue8_test/function/load.mcfunction +1 -0
  20. package/dist/data/stdlib_queue8_test/function/queue_clear.mcfunction +6 -0
  21. package/dist/data/stdlib_queue8_test/function/queue_empty__merge_1.mcfunction +5 -0
  22. package/dist/data/stdlib_queue8_test/function/queue_empty__then_0.mcfunction +5 -0
  23. package/dist/data/stdlib_queue8_test/function/queue_peek__merge_1.mcfunction +13 -0
  24. package/dist/data/stdlib_queue8_test/function/queue_peek__then_0.mcfunction +5 -0
  25. package/dist/data/stdlib_queue8_test/function/queue_pop__merge_1.mcfunction +15 -0
  26. package/dist/data/stdlib_queue8_test/function/queue_pop__then_0.mcfunction +5 -0
  27. package/dist/data/stdlib_queue8_test/function/queue_push__const_11.mcfunction +6 -0
  28. package/dist/data/stdlib_queue8_test/function/queue_push__const_22.mcfunction +6 -0
  29. package/dist/data/stdlib_queue8_test/function/queue_size.mcfunction +13 -0
  30. package/dist/data/stdlib_queue8_test/function/test_queue_push_and_size.mcfunction +13 -0
  31. package/dist/data/test/function/load.mcfunction +1 -0
  32. package/dist/data/test/function/say_at.mcfunction +6 -0
  33. package/dist/data/test/function/test.mcfunction +4 -0
  34. package/dist/pack.mcmeta +6 -0
  35. package/dist/package.json +1 -1
  36. package/dist/src/__tests__/formatter-extra.test.d.ts +7 -0
  37. package/dist/src/__tests__/formatter-extra.test.js +123 -0
  38. package/dist/src/__tests__/global-vars.test.d.ts +13 -0
  39. package/dist/src/__tests__/global-vars.test.js +156 -0
  40. package/dist/src/__tests__/lint/new-rules.test.d.ts +9 -0
  41. package/dist/src/__tests__/lint/new-rules.test.js +402 -0
  42. package/dist/src/__tests__/lsp-rename.test.d.ts +8 -0
  43. package/dist/src/__tests__/lsp-rename.test.js +157 -0
  44. package/dist/src/__tests__/mc-integration/say-fstring.test.d.ts +11 -0
  45. package/dist/src/__tests__/mc-integration/say-fstring.test.js +220 -0
  46. package/dist/src/__tests__/mc-integration/stdlib-coverage-2.test.js +1 -1
  47. package/dist/src/__tests__/mc-integration/stdlib-coverage-3.test.js +1 -1
  48. package/dist/src/__tests__/mc-integration/stdlib-coverage-4.test.js +1 -1
  49. package/dist/src/__tests__/mc-integration/stdlib-coverage-5.test.js +1 -1
  50. package/dist/src/__tests__/mc-integration/stdlib-coverage-6.test.js +1 -1
  51. package/dist/src/__tests__/mc-integration/stdlib-coverage-7.test.js +1 -1
  52. package/dist/src/__tests__/mc-integration/stdlib-coverage-8.test.js +1 -1
  53. package/dist/src/__tests__/mc-syntax.test.js +4 -1
  54. package/dist/src/__tests__/monomorphize-coverage.test.d.ts +9 -0
  55. package/dist/src/__tests__/monomorphize-coverage.test.js +204 -0
  56. package/dist/src/__tests__/optimizer-cse.test.d.ts +7 -0
  57. package/dist/src/__tests__/optimizer-cse.test.js +226 -0
  58. package/dist/src/__tests__/parser.test.js +4 -13
  59. package/dist/src/__tests__/repl-server-extra.test.js +6 -7
  60. package/dist/src/__tests__/repl-server.test.js +5 -7
  61. package/dist/src/__tests__/stdlib/queue.test.js +6 -6
  62. package/dist/src/cli.js +0 -0
  63. package/dist/src/lexer/index.js +2 -1
  64. package/dist/src/lint/index.d.ts +12 -5
  65. package/dist/src/lint/index.js +730 -5
  66. package/dist/src/lsp/main.js +0 -0
  67. package/dist/src/mc-test/client.d.ts +21 -0
  68. package/dist/src/mc-test/client.js +34 -0
  69. package/dist/src/mir/lower.js +108 -6
  70. package/dist/src/optimizer/interprocedural.js +37 -2
  71. package/dist/src/parser/decl-parser.d.ts +19 -0
  72. package/dist/src/parser/decl-parser.js +323 -0
  73. package/dist/src/parser/expr-parser.d.ts +46 -0
  74. package/dist/src/parser/expr-parser.js +759 -0
  75. package/dist/src/parser/index.d.ts +8 -129
  76. package/dist/src/parser/index.js +13 -2262
  77. package/dist/src/parser/stmt-parser.d.ts +28 -0
  78. package/dist/src/parser/stmt-parser.js +577 -0
  79. package/dist/src/parser/type-parser.d.ts +20 -0
  80. package/dist/src/parser/type-parser.js +257 -0
  81. package/dist/src/parser/utils.d.ts +34 -0
  82. package/dist/src/parser/utils.js +141 -0
  83. package/docs/dev/README-mc-integration-tests.md +141 -0
  84. package/docs/lint-rules.md +162 -0
  85. package/docs/stdlib/bigint.md +2 -0
  86. package/editors/vscode/README.md +63 -41
  87. package/editors/vscode/out/extension.js +1881 -1776
  88. package/editors/vscode/out/lsp-server.js +4257 -3651
  89. package/editors/vscode/package-lock.json +3 -3
  90. package/editors/vscode/package.json +1 -1
  91. package/examples/loops-demo.mcrs +87 -0
  92. package/package.json +1 -1
  93. package/redscript-docs/docs/en/stdlib/advanced.md +629 -0
  94. package/redscript-docs/docs/en/stdlib/bigint.md +316 -0
  95. package/redscript-docs/docs/en/stdlib/bits.md +292 -0
  96. package/redscript-docs/docs/en/stdlib/bossbar.md +177 -0
  97. package/redscript-docs/docs/en/stdlib/calculus.md +289 -0
  98. package/redscript-docs/docs/en/stdlib/color.md +353 -0
  99. package/redscript-docs/docs/en/stdlib/combat.md +88 -0
  100. package/redscript-docs/docs/en/stdlib/cooldown.md +82 -0
  101. package/redscript-docs/docs/en/stdlib/dialog.md +155 -0
  102. package/redscript-docs/docs/en/stdlib/easing.md +558 -0
  103. package/redscript-docs/docs/en/stdlib/ecs.md +475 -0
  104. package/redscript-docs/docs/en/stdlib/effects.md +324 -0
  105. package/redscript-docs/docs/en/stdlib/events.md +3 -0
  106. package/redscript-docs/docs/en/stdlib/expr.md +45 -0
  107. package/redscript-docs/docs/en/stdlib/fft.md +141 -0
  108. package/redscript-docs/docs/en/stdlib/geometry.md +430 -0
  109. package/redscript-docs/docs/en/stdlib/graph.md +259 -0
  110. package/redscript-docs/docs/en/stdlib/heap.md +185 -0
  111. package/redscript-docs/docs/en/stdlib/interactions.md +179 -0
  112. package/redscript-docs/docs/en/stdlib/inventory.md +97 -0
  113. package/redscript-docs/docs/en/stdlib/linalg.md +557 -0
  114. package/redscript-docs/docs/en/stdlib/list.md +559 -0
  115. package/redscript-docs/docs/en/stdlib/map.md +140 -0
  116. package/redscript-docs/docs/en/stdlib/math.md +193 -0
  117. package/redscript-docs/docs/en/stdlib/math_hp.md +149 -0
  118. package/redscript-docs/docs/en/stdlib/matrix.md +403 -0
  119. package/redscript-docs/docs/en/stdlib/mobs.md +965 -0
  120. package/redscript-docs/docs/en/stdlib/noise.md +244 -0
  121. package/redscript-docs/docs/en/stdlib/ode.md +253 -0
  122. package/redscript-docs/docs/en/stdlib/parabola.md +342 -0
  123. package/redscript-docs/docs/en/stdlib/particles.md +311 -0
  124. package/redscript-docs/docs/en/stdlib/pathfind.md +255 -0
  125. package/redscript-docs/docs/en/stdlib/physics.md +493 -0
  126. package/redscript-docs/docs/en/stdlib/player.md +78 -0
  127. package/redscript-docs/docs/en/stdlib/quaternion.md +673 -0
  128. package/redscript-docs/docs/en/stdlib/queue.md +134 -0
  129. package/redscript-docs/docs/en/stdlib/random.md +223 -0
  130. package/redscript-docs/docs/en/stdlib/result.md +143 -0
  131. package/redscript-docs/docs/en/stdlib/scheduler.md +183 -0
  132. package/redscript-docs/docs/en/stdlib/set_int.md +190 -0
  133. package/redscript-docs/docs/en/stdlib/sets.md +101 -0
  134. package/redscript-docs/docs/en/stdlib/signal.md +400 -0
  135. package/redscript-docs/docs/en/stdlib/sort.md +104 -0
  136. package/redscript-docs/docs/en/stdlib/spawn.md +147 -0
  137. package/redscript-docs/docs/en/stdlib/state.md +142 -0
  138. package/redscript-docs/docs/en/stdlib/strings.md +154 -0
  139. package/redscript-docs/docs/en/stdlib/tags.md +3451 -0
  140. package/redscript-docs/docs/en/stdlib/teams.md +153 -0
  141. package/redscript-docs/docs/en/stdlib/timer.md +246 -0
  142. package/redscript-docs/docs/en/stdlib/vec.md +158 -0
  143. package/redscript-docs/docs/en/stdlib/world.md +298 -0
  144. package/redscript-docs/docs/zh/stdlib/advanced.md +615 -0
  145. package/redscript-docs/docs/zh/stdlib/bigint.md +316 -0
  146. package/redscript-docs/docs/zh/stdlib/bits.md +292 -0
  147. package/redscript-docs/docs/zh/stdlib/bossbar.md +170 -0
  148. package/redscript-docs/docs/zh/stdlib/calculus.md +287 -0
  149. package/redscript-docs/docs/zh/stdlib/color.md +353 -0
  150. package/redscript-docs/docs/zh/stdlib/combat.md +88 -0
  151. package/redscript-docs/docs/zh/stdlib/cooldown.md +84 -0
  152. package/redscript-docs/docs/zh/stdlib/dialog.md +152 -0
  153. package/redscript-docs/docs/zh/stdlib/easing.md +558 -0
  154. package/redscript-docs/docs/zh/stdlib/ecs.md +472 -0
  155. package/redscript-docs/docs/zh/stdlib/effects.md +324 -0
  156. package/redscript-docs/docs/zh/stdlib/events.md +3 -0
  157. package/redscript-docs/docs/zh/stdlib/expr.md +37 -0
  158. package/redscript-docs/docs/zh/stdlib/fft.md +128 -0
  159. package/redscript-docs/docs/zh/stdlib/geometry.md +430 -0
  160. package/redscript-docs/docs/zh/stdlib/graph.md +259 -0
  161. package/redscript-docs/docs/zh/stdlib/heap.md +185 -0
  162. package/redscript-docs/docs/zh/stdlib/interactions.md +160 -0
  163. package/redscript-docs/docs/zh/stdlib/inventory.md +94 -0
  164. package/redscript-docs/docs/zh/stdlib/linalg.md +543 -0
  165. package/redscript-docs/docs/zh/stdlib/list.md +561 -0
  166. package/redscript-docs/docs/zh/stdlib/map.md +132 -0
  167. package/redscript-docs/docs/zh/stdlib/math.md +193 -0
  168. package/redscript-docs/docs/zh/stdlib/math_hp.md +143 -0
  169. package/redscript-docs/docs/zh/stdlib/matrix.md +396 -0
  170. package/redscript-docs/docs/zh/stdlib/mobs.md +965 -0
  171. package/redscript-docs/docs/zh/stdlib/noise.md +244 -0
  172. package/redscript-docs/docs/zh/stdlib/ode.md +243 -0
  173. package/redscript-docs/docs/zh/stdlib/parabola.md +337 -0
  174. package/redscript-docs/docs/zh/stdlib/particles.md +307 -0
  175. package/redscript-docs/docs/zh/stdlib/pathfind.md +255 -0
  176. package/redscript-docs/docs/zh/stdlib/physics.md +493 -0
  177. package/redscript-docs/docs/zh/stdlib/player.md +78 -0
  178. package/redscript-docs/docs/zh/stdlib/quaternion.md +669 -0
  179. package/redscript-docs/docs/zh/stdlib/queue.md +124 -0
  180. package/redscript-docs/docs/zh/stdlib/random.md +222 -0
  181. package/redscript-docs/docs/zh/stdlib/result.md +147 -0
  182. package/redscript-docs/docs/zh/stdlib/scheduler.md +173 -0
  183. package/redscript-docs/docs/zh/stdlib/set_int.md +180 -0
  184. package/redscript-docs/docs/zh/stdlib/sets.md +107 -0
  185. package/redscript-docs/docs/zh/stdlib/signal.md +373 -0
  186. package/redscript-docs/docs/zh/stdlib/sort.md +104 -0
  187. package/redscript-docs/docs/zh/stdlib/spawn.md +142 -0
  188. package/redscript-docs/docs/zh/stdlib/state.md +134 -0
  189. package/redscript-docs/docs/zh/stdlib/strings.md +107 -0
  190. package/redscript-docs/docs/zh/stdlib/tags.md +3451 -0
  191. package/redscript-docs/docs/zh/stdlib/teams.md +150 -0
  192. package/redscript-docs/docs/zh/stdlib/timer.md +254 -0
  193. package/redscript-docs/docs/zh/stdlib/vec.md +158 -0
  194. package/redscript-docs/docs/zh/stdlib/world.md +289 -0
  195. package/src/__tests__/formatter-extra.test.ts +139 -0
  196. package/src/__tests__/global-vars.test.ts +171 -0
  197. package/src/__tests__/lint/new-rules.test.ts +437 -0
  198. package/src/__tests__/lsp-rename.test.ts +171 -0
  199. package/src/__tests__/mc-integration/say-fstring.test.ts +211 -0
  200. package/src/__tests__/mc-integration/stdlib-coverage-2.test.ts +1 -1
  201. package/src/__tests__/mc-integration/stdlib-coverage-3.test.ts +1 -1
  202. package/src/__tests__/mc-integration/stdlib-coverage-4.test.ts +1 -1
  203. package/src/__tests__/mc-integration/stdlib-coverage-5.test.ts +1 -1
  204. package/src/__tests__/mc-integration/stdlib-coverage-6.test.ts +1 -1
  205. package/src/__tests__/mc-integration/stdlib-coverage-7.test.ts +1 -1
  206. package/src/__tests__/mc-integration/stdlib-coverage-8.test.ts +1 -1
  207. package/src/__tests__/mc-syntax.test.ts +3 -0
  208. package/src/__tests__/monomorphize-coverage.test.ts +220 -0
  209. package/src/__tests__/optimizer-cse.test.ts +250 -0
  210. package/src/__tests__/parser.test.ts +4 -13
  211. package/src/__tests__/repl-server-extra.test.ts +6 -6
  212. package/src/__tests__/repl-server.test.ts +5 -6
  213. package/src/__tests__/stdlib/queue.test.ts +6 -6
  214. package/src/lexer/index.ts +2 -1
  215. package/src/lint/index.ts +713 -5
  216. package/src/mc-test/client.ts +40 -0
  217. package/src/mir/lower.ts +111 -2
  218. package/src/optimizer/interprocedural.ts +40 -2
  219. package/src/parser/decl-parser.ts +349 -0
  220. package/src/parser/expr-parser.ts +838 -0
  221. package/src/parser/index.ts +17 -2558
  222. package/src/parser/stmt-parser.ts +585 -0
  223. package/src/parser/type-parser.ts +276 -0
  224. package/src/parser/utils.ts +173 -0
  225. package/src/stdlib/queue.mcrs +19 -6
package/README.zh.md CHANGED
@@ -2,400 +2,204 @@
2
2
 
3
3
  <img src="./logo.png" alt="RedScript Logo" width="64" />
4
4
 
5
- <img src="https://img.shields.io/badge/RedScript-2.6.1-red?style=for-the-badge&logo=minecraft&logoColor=white" alt="RedScript" />
5
+ # RedScript
6
6
 
7
- **一个编译为 Minecraft datapacks 的类型化脚本语言。**
7
+ **编译到 Minecraft 数据包的类型化语言**
8
8
 
9
- 编写干净的游戏逻辑。RedScript 负责处理 scoreboard 的 spaghetti
9
+ 写干净的代码,生成原版数据包。无需 Mod
10
10
 
11
- [![CI](https://github.com/bkmashiro/redscript/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/bkmashiro/redscript/actions/workflows/ci.yml)
12
- [![Tests](https://img.shields.io/badge/tests-1901%20passing-brightgreen)](https://github.com/bkmashiro/redscript)
13
- [![npm](https://img.shields.io/npm/v/redscript-mc?color=cb3837)](https://www.npmjs.com/package/redscript-mc)
14
- [![npm downloads](https://img.shields.io/npm/dm/redscript-mc?color=cb3837)](https://www.npmjs.com/package/redscript-mc)
11
+ [![npm](https://img.shields.io/npm/v/redscript-mc?color=cb3837&label=npm)](https://www.npmjs.com/package/redscript-mc)
12
+ [![CI](https://github.com/bkmashiro/redscript/actions/workflows/ci.yml/badge.svg)](https://github.com/bkmashiro/redscript/actions/workflows/ci.yml)
13
+ [![Tests](https://img.shields.io/badge/tests-3886%20passing-brightgreen)](https://github.com/bkmashiro/redscript)
15
14
  [![VSCode](https://img.shields.io/badge/VSCode-Extension-007ACC?logo=visualstudiocode)](https://marketplace.visualstudio.com/items?itemName=bkmashiro.redscript-vscode)
16
- [![Online IDE](https://img.shields.io/badge/Try-Online%20IDE-orange)](https://redscript-ide.pages.dev)
17
- [![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
18
15
 
19
- [English](./README.md) · [快速开始](#快速开始) · [文档](https://redscript-docs.pages.dev) · [贡献](./CONTRIBUTING.md)
20
-
21
- ### 🚀 [在线试用,无需安装](https://redscript-ide.pages.dev)
22
-
23
- <img src="./demo.gif" alt="RedScript Demo — 在 Minecraft 中用粒子绘制数学曲线" width="520" />
24
-
25
- *↑ 五条数学曲线以粒子实时渲染,100% 原版,无需 mod!*
26
- *`y = x·sin(x)` · `y = sin(x) + ½sin(2x)` · `y = e⁻ˣsin(4x)` · `y = tanh(2x)` · `r = cos(2θ)` 玫瑰线*
27
- *每条曲线都由 RedScript 的 fixed-point math stdlib 逐 tick 计算。*
16
+ [English](./README.md) · [文档](https://redscript-docs.pages.dev) · [在线编辑器](https://redscript-ide.pages.dev)
28
17
 
29
18
  </div>
30
19
 
31
20
  ---
32
21
 
33
- ### 什么是 RedScript?
22
+ ## 为什么用 RedScript?
34
23
 
35
- RedScript 是一种会编译为原版 Minecraft datapacks 的类型化脚本语言。你可以用变量、函数、循环和事件编写清晰的代码,RedScript 会替你处理 scoreboard 命令和 `.mcfunction` 文件。
24
+ Minecraft 数据包很强大,但写起来很痛苦:
36
25
 
37
- **上面的演示是什么?** 五条数学曲线,每条各有 64 个采样点。核心逻辑如下:
26
+ ```mcfunction
27
+ # 原版:检查玩家分数 >= 100 并给奖励
28
+ execute as @a[scores={points=100..}] run scoreboard players add @s rewards 1
29
+ execute as @a[scores={points=100..}] run scoreboard players set @s points 0
30
+ execute as @a[scores={points=100..}] run give @s minecraft:diamond 1
31
+ execute as @a[scores={points=100..}] run tellraw @s {"text":"领取成功!"}
32
+ ```
38
33
 
39
34
  ```rs
40
- import "stdlib/math"
41
-
42
- let phase: int = 0;
43
- let frame: int = 0;
44
-
45
- // 5 curves cycle every 128 ticks (~6.5 s each)
46
- @tick fn _wave_tick() {
47
- phase = (phase + 4) % 360;
48
- frame = frame + 1;
49
-
50
- let curve_id: int = (frame / 128) % 5;
51
-
52
- // Compute sin at 9 column offsets (40° apart = full sine wave span)
53
- let s0: int = sin_fixed((phase + 0) % 360);
54
- let s1: int = sin_fixed((phase + 40) % 360);
55
- // ... s2 through s8 ...
56
-
57
- // Draw bar chart: each column height = sin value
58
- // (64 fixed particle positions per curve, all respawned each tick)
59
- if (curve_id == 0) { _draw_xsinx(); }
60
- if (curve_id == 1) { _draw_harmonic(); }
61
- // ...
62
-
63
- actionbar(@a, f"§e y = x·sin(x) phase: {phase}° center: {s0}‰");
35
+ // RedScript:同样的逻辑,更易读
36
+ @tick fn check_rewards() {
37
+ foreach (p in @a) {
38
+ if (scoreboard_get(p, #points) >= 100) {
39
+ scoreboard_add(p, #rewards, 1);
40
+ scoreboard_set(p, #points, 0);
41
+ give(p, "minecraft:diamond", 1);
42
+ tell(p, "领取成功!");
43
+ }
44
+ }
64
45
  }
65
46
  ```
66
47
 
67
- **你将获得:**
68
- - ✅ `let` / `const` 变量(不用再写 `scoreboard players set`)
69
- - ✅ `if` / `else` / `for` / `foreach` / `break` / `continue` 控制流
70
- - ✅ `@tick` / `@load` / `@on(Event)` decorators
71
- - ✅ `foreach (p in @a) at @s positioned ~ ~1 ~` 以及完整的 `execute` subcommand 支持
72
- - ✅ 支持 `70..79` 这类范围模式的 `match`
73
- - ✅ Builtins 在任意参数位置都接受 runtime macro variables
74
- - ✅ 像 `f"Score: {points}"` 这样的 f-strings 用于动态输出
75
- - ✅ public functions 会自动保留;`_privateFn()` 会保持 private
76
- - ✅ `enum` 类型配合 `match` dispatch(零 runtime 开销)
77
- - ✅ 多返回值:`fn divmod(a: int, b: int): (int, int)`
78
- - ✅ Generics:`fn max<T>(a: T, b: T): T`(monomorphized)
79
- - ✅ `Option<T>` 空值安全:`Some(x)` / `None` / `if let Some(x) = opt`
80
- - ✅ `@coroutine(batch=N)` 用于把循环分摊到多个 tick(不用再担心 maxCommandChain)
81
- - ✅ `@schedule(ticks=N)` 用于延迟函数执行
82
- - ✅ 模块系统:`module math; import math::sin;`
83
- - ✅ 多版本目标:`--mc-version 1.20.2`
84
- - ✅ Source maps:`--source-map` 方便调试
85
- - ✅ Language Server Protocol:diagnostics、hover、go-to-def、completion
86
- - ✅ 一个文件直接编译成可用的 datapack
48
+ ## 快速开始
87
49
 
88
- ---
50
+ ### 在线体验(无需安装)
89
51
 
90
- ### 快速开始
52
+ **[→ redscript-ide.pages.dev](https://redscript-ide.pages.dev)** — 写代码,下载数据包。
91
53
 
92
- #### 方式 1:Online IDE(无需安装)
54
+ ### 安装 CLI
93
55
 
94
- **[→ redscript-ide.pages.dev](https://redscript-ide.pages.dev)** 直接写代码,立刻看输出。
95
-
96
- #### 方式 2:VSCode Extension
97
-
98
- 1. 安装 [RedScript for VSCode](https://marketplace.visualstudio.com/items?itemName=bkmashiro.redscript-vscode)
99
- 2. 获得语法高亮、自动补全、hover docs 等功能
100
-
101
- #### 方式 3:CLI
102
-
103
- ```mcrs
104
- struct Timer { _id: int; duration: int; }
56
+ ```bash
57
+ npm install -g redscript-mc
58
+ ```
105
59
 
106
- impl Timer {
107
- fn new(duration: int): Timer {
108
- return Timer { _id: 0, duration: duration };
109
- }
110
- fn done(self): bool { return true; }
111
- }
60
+ ### Hello World
112
61
 
113
- @on(PlayerJoin)
114
- fn welcome(player: Player) {
115
- say(f"Welcome {player}!");
62
+ ```rs
63
+ // hello.mcrs
64
+ @load fn init() {
65
+ say("Hello from RedScript!");
116
66
  }
117
67
 
118
68
  @tick fn game_loop() {
119
- let timer = Timer::new(100);
120
- setTimeout(200, () => { say("Delayed!"); });
69
+ foreach (p in @a[tag=playing]) {
70
+ effect(p, "minecraft:speed", 1, 0, true);
71
+ }
121
72
  }
122
73
  ```
123
74
 
124
75
  ```bash
125
- npm install -g redscript-mc
126
- redscript compile game.mcrs -o ./my-datapack
76
+ redscript build hello.mcrs -o ./my-datapack
127
77
  ```
128
78
 
129
- #### 部署
130
-
131
- 把输出目录放进世界存档的 `datapacks/` 目录,然后运行 `/reload`。完成。
79
+ `my-datapack/` 放到世界的 `datapacks/` 文件夹,运行 `/reload`。完成。
132
80
 
133
81
  ---
134
82
 
135
- ### 语言
136
-
137
- #### Variables & Types
138
-
139
- ```rs
140
- let x: int = 42;
141
- let name: string = "Steve";
142
- let spawn: BlockPos = (0, 64, 0);
143
- let nearby: BlockPos = (~5, ~0, ~5); // relative coords
144
- const MAX: int = 100; // compile-time constant
145
- ```
146
-
147
- #### MC Names(Objectives、Tags、Teams)
148
-
149
- 用 `#name` 表示 Minecraft 标识符,不需要引号:
150
-
151
- ```rs
152
- // Objectives, fake players, tags, teams — write without quotes
153
- let hp: int = scoreboard_get(@s, #health);
154
- scoreboard_set(#game, #timer, 300); // fake player #game, objective timer
155
- tag_add(@s, #hasKey);
156
- team_join(#red, @s);
157
- gamerule(#keepInventory, true);
158
-
159
- // String literals still work (backward compatible)
160
- scoreboard_get(@s, "health") // same output as #health
161
- ```
83
+ ## 功能特性
162
84
 
163
- #### Functions & Defaults
164
-
165
- ```rs
166
- fn greet(player: selector, msg: string = "Welcome!") {
167
- tell(player, msg);
168
- }
85
+ ### 语言
169
86
 
170
- greet(@s); // uses default message
171
- greet(@a, "Hello!"); // override
172
- ```
87
+ | 特性 | 示例 |
88
+ |------|------|
89
+ | 变量 | `let x: int = 42;` |
90
+ | 函数 | `fn damage(target: selector, amount: int) { ... }` |
91
+ | 控制流 | `if`, `else`, `for`, `while`, `foreach`, `match` |
92
+ | 结构体 | `struct Player { score: int, alive: bool }` |
93
+ | 枚举 | `enum State { Lobby, Playing, Ended }` |
94
+ | Option 类型 | `let item: Option<int> = Some(5);` |
95
+ | Result 类型 | `let r: Result<int, string> = Ok(42);` |
96
+ | 格式字符串 | `say(f"分数: {points}");` |
97
+ | 模块 | `import math; math::sin(45);` |
173
98
 
174
- #### Decorators
99
+ ### Minecraft 集成
175
100
 
176
101
  ```rs
177
- @tick // every tick
178
- fn heartbeat() { ... }
179
-
180
- @tick(rate=20) // every second
181
- fn every_second() { ... }
102
+ // 游戏事件装饰器
103
+ @tick fn every_tick() { }
104
+ @tick(rate=20) fn every_second() { }
105
+ @load fn on_datapack_load() { }
106
+ @on(PlayerJoin) fn welcome(p: Player) { }
182
107
 
183
- @on_advancement("story/mine_diamond")
184
- fn on_diamond() {
185
- give(@s, "minecraft:diamond", 5);
108
+ // 实体选择器自然使用
109
+ foreach (zombie in @e[type=zombie, distance=..10]) {
110
+ kill(zombie);
186
111
  }
187
112
 
188
- @on_death
189
- fn on_death() {
190
- scoreboard_add(@s, #deaths, 1);
113
+ // execute 子命令
114
+ foreach (p in @a) at @s positioned ~ ~2 ~ {
115
+ particle("minecraft:flame", ~0, ~0, ~0, 0.1, 0.1, 0.1, 0.01, 10);
191
116
  }
192
117
 
193
- // Delay execution by N ticks (20t = 1 second)
194
- @schedule(ticks=20)
195
- fn after_one_second(): void {
196
- title(@a, "One second later!");
197
- }
198
-
199
- // Spread a heavy loop across multiple ticks (batch=N iterations/tick)
200
- @coroutine(batch=50, onDone=all_done)
201
- fn process_all(): void {
202
- let i: int = 0;
203
- while (i < 1000) {
204
- // work spread over ~20 ticks instead of lagging one tick
205
- i = i + 1;
118
+ // 协程分散计算(跨 tick 执行)
119
+ @coroutine(batch=100)
120
+ fn process_all() {
121
+ for (let i = 0; i < 10000; i = i + 1) {
122
+ // 不会卡顿 — 每 tick 只执行 100 次迭代
206
123
  }
207
124
  }
208
125
  ```
209
126
 
210
- #### Control Flow
127
+ ### 工具链
211
128
 
212
- ```rs
213
- if (hp <= 0) {
214
- respawn();
215
- } else if (hp < 5) {
216
- warn_player();
217
- }
218
-
219
- for (let i: int = 0; i < 10; i = i + 1) {
220
- say(f"Spawning wave {i}");
221
- summon("minecraft:zombie", ~0, ~0, ~0);
222
- }
223
-
224
- foreach (player in @a) {
225
- heal(player, 2);
226
- }
227
- ```
228
-
229
- #### Structs & Enums
230
-
231
- ```rs
232
- enum Phase { Lobby, Playing, Ended }
233
-
234
- struct Player {
235
- score: int,
236
- alive: bool,
237
- }
238
-
239
- match (phase) {
240
- Phase::Lobby => { announce("Waiting..."); }
241
- Phase::Playing => { every_second(); }
242
- Phase::Ended => { show_scoreboard(); }
243
- }
244
- ```
245
-
246
- #### Lambdas
247
-
248
- ```rs
249
- fn apply(f: (int) -> int, x: int) -> int {
250
- return f(x);
251
- }
252
-
253
- let double = (x: int) -> int { return x * 2; };
254
- apply(double, 5); // 10
255
- ```
256
-
257
- #### Arrays
258
-
259
- ```rs
260
- let scores: int[] = [];
261
- push(scores, 42);
262
-
263
- foreach (s in scores) {
264
- announce("Score: ${s}");
265
- }
266
- ```
129
+ - **15 个优化 pass** — 死代码消除、常量折叠、内联等
130
+ - **LSP** 悬停文档、跳转定义、自动补全、诊断
131
+ - **VSCode 扩展** — 完整语法高亮和代码片段
132
+ - **50 个标准库模块** 数学、向量、寻路、粒子等
267
133
 
268
134
  ---
269
135
 
270
- ### CLI Reference
136
+ ## CLI 命令
271
137
 
272
- ```
273
- redscript compile <file> Compile to datapack (default) or structure
274
- -o, --output <dir> Output directory [default: ./out]
275
- --target datapack|structure Output format [default: datapack]
276
- --namespace <ns> Datapack namespace [default: filename]
277
- --mc-version <ver> Target MC version [default: 1.21]
278
- --include <dir> Extra library search path (repeatable)
279
- --source-map Emit .mcrs.map source map for debugging
280
- --no-optimize Skip optimizer passes
281
- --stats Print optimizer statistics
282
-
283
- redscript repl Interactive REPL
284
- redscript validate <file> Validate MC commands
138
+ ```bash
139
+ redscript build <file> # 带优化编译
140
+ redscript compile <file> # 不带优化编译
141
+ redscript check <file> # 仅类型检查
142
+ redscript fmt <file> # 格式化代码
143
+ redscript lint <file> # 静态分析
144
+ redscript test <file> # 运行 @test 函数
145
+ redscript watch <dir> # 监听模式,热重载
146
+ redscript docs [module] # 打开标准库文档
285
147
  ```
286
148
 
287
149
  ---
288
150
 
289
- ### Stdlib
151
+ ## 标准库
290
152
 
291
- RedScript 内置 standard library。使用短路径即可,不需要写完整路径:
153
+ 50 个模块,覆盖数学、数据结构、游戏系统和 MC 特定功能:
292
154
 
293
155
  ```rs
294
- import "stdlib/math" // fixed-point math: ln, sqrt_fx, exp_fx, sin_fixed, cos_fixed...
295
- import "stdlib/math_hp" // high-precision trig via entity rotation (init_trig required)
296
- import "stdlib/vec" // 2D/3D vector: dot, cross, length, distance, atan2, rotate...
297
- import "stdlib/random" // LCG & PCG random number generators
298
- import "stdlib/color" // RGB/HSL color packing, blending, conversion
299
- import "stdlib/bits" // bitwise AND/OR/XOR/NOT/shift/popcount (integer-simulated)
300
- import "stdlib/list" // sort3, min/max/avg, weighted utilities
301
- import "stdlib/geometry" // AABB/sphere contains, parabola physics, angle helpers
302
- import "stdlib/signal" // normal/exponential distributions, bernoulli, weighted choice
303
- import "stdlib/bigint" // 96-bit base-10000 arithmetic (add/sub/mul/div/cmp)
304
- import "stdlib/easing" // 12 easing functions: quad/cubic/sine/bounce/back/smooth
305
- import "stdlib/noise" // value noise, fractal Brownian motion, terrain height
306
- import "stdlib/calculus" // numerical differentiation, trapezoid/Simpson integration, curve length, online statistics
307
- import "stdlib/matrix" // 2D/3D rotation, Display Entity quaternion helpers
308
- import "stdlib/combat" // damage, kill-check helpers
309
- import "stdlib/player" // health, alive check, range
310
- import "stdlib/cooldown" // per-player cooldown tracking
156
+ import math; // sin, cos, sqrt, pow, abs
157
+ import vec; // 2D/3D 向量, dot, cross, normalize
158
+ import random; // LCG/PCG 随机数生成器
159
+ import pathfind; // A* 寻路
160
+ import particles; // 粒子辅助
161
+ import inventory; // 物品栏操作
162
+ import scheduler; // 延迟执行
163
+ import ecs; // 实体组件系统
164
+ // ... 还有 42
311
165
  ```
312
166
 
313
- 所有 stdlib 文件都使用 `module library;`,因此只有你实际调用到的函数才会被编译进去。
314
-
315
- > standard library 的一部分灵感来自 [kaer-3058/large_number](https://github.com/kaer-3058/large_number),这是一个面向 Minecraft datapacks 的完整数学库。
316
-
317
- 你也可以通过 `--include <dir>` 添加自定义 library 路径,让自己的 modules 以同样方式工作。
318
-
319
- **示例:在游戏内计算 Fibonacci(50):**
320
-
321
- ```rs
322
- import "stdlib/bigint"
323
-
324
- fn show_fib() {
325
- bigint_fib(50);
326
- // F(50) = 12,586,269,025 — too big for int32, stored across 3 limbs:
327
- let l0: int = bigint_get_a(0); // 9025
328
- let l1: int = bigint_get_a(1); // 8626
329
- let l2: int = bigint_get_a(2); // 125
330
- say(f"F(50) limbs: {l2} {l1} {l0}");
331
- }
332
- ```
167
+ 完整列表:[标准库文档](https://redscript-docs.pages.dev/en/stdlib/)
333
168
 
334
169
  ---
335
170
 
336
- ### 示例
337
-
338
- `examples/` 目录里提供了可直接编译的 demos:
171
+ ## 示例
339
172
 
340
- | File | 展示内容 |
341
- |---|---|
342
- | `readme-demo.mcrs` | 实时正弦波粒子效果:`@tick`、`foreach`、f-strings、math stdlib |
343
- | `math-showcase.mcrs` | 全套 stdlib math modules:trig、vectors、BigInt、fractals |
344
- | `showcase.mcrs` | 完整功能展示:structs、enums、`match`、lambdas、`@tick`/`@load` |
345
- | `coroutine-demo.mcrs` | `@coroutine(batch=50)`:把 1000 次迭代分散到约 20 个 ticks |
346
- | `enum-demo.mcrs` | enum 状态机:NPC AI 通过 `match` 在 Idle → Moving → Attacking 之间切换 |
347
- | `scheduler-demo.mcrs` | `@schedule(ticks=20)`:延迟事件与链式调度 |
173
+ | 文件 | 描述 |
174
+ |------|------|
175
+ | [`loops-demo.mcrs`](./examples/loops-demo.mcrs) | 所有循环结构 |
176
+ | [`showcase.mcrs`](./examples/showcase.mcrs) | 完整功能展示 |
348
177
 
349
- 编译任意示例:
350
- ```bash
351
- node dist/cli.js compile examples/coroutine-demo.mcrs -o ~/mc-server/datapacks/demo --namespace demo
352
- ```
178
+ 更多示例在 [`examples/`](./examples/) 目录。
353
179
 
354
180
  ---
355
181
 
356
- ### Changelog Highlights
357
-
358
- #### v1.2.27 (2026-03-14)
359
-
360
- - **BigInt real-MC fix**:`storage_set_int` macro 现在使用 `execute store result storage`,而不是 `data modify set value $(n)`;这可以绕过 Minecraft 在整数 macro substitution 上的一个 bug。BigInt 已在 Paper 1.21.4 上确认可用
361
- - **showcase**:`atan2_fixed` 返回的是 degrees(0–360),不是 millidegrees;修复了示例中过度除法的问题;`mod_pow` 测试样例改为使用安全的小模数范围,避免 INT32 overflow
362
-
363
- #### v1.2.26 (2026-03-14)
364
-
365
- - 完整的 math/vector/advanced/bigint standard library(见上)
366
- - `module library;` pragma,实现零成本 tree-shaking
367
- - `storage_get_int` / `storage_set_int` dynamic NBT array builtins
368
- - 编译器 bug 修复:`isqrt` 收敛、copy propagation、变量作用域
182
+ ## 文档
369
183
 
370
- #### v1.2.25 (2026-03-13)
371
-
372
- - Entity type hierarchy,带 `W_IMPOSSIBLE_AS` warnings
373
- - 变量名混淆为 `$a`、`$b`、`$c` 等,以尽量缩小 scoreboard footprint
374
- - 自动化 CI/CD:每次 push 都会发布 npm 包和 VSCode extension
375
-
376
- #### v1.2.0
377
-
378
- - `impl` blocks、methods 和 static constructors
379
- - `is` 类型收窄,用于 entity-safe 控制流
380
- - `@on(Event)` 静态事件与 callback scheduling builtins
381
- - 用于输出函数的 runtime f-strings
382
- - 扩展后的 stdlib,包含 Timer OOP APIs 与 313 个 MC tag 常量
383
- - Dead code elimination
384
-
385
- 完整版本说明见 [CHANGELOG.md](./CHANGELOG.md)。
184
+ - **[入门指南](https://redscript-docs.pages.dev/en/guide/)** — 安装和第一个项目
185
+ - **[语言参考](https://redscript-docs.pages.dev/en/reference/)** — 完整语法指南
186
+ - **[标准库参考](https://redscript-docs.pages.dev/en/stdlib/)** 50 个模块文档
187
+ - **[CLI 参考](https://redscript-docs.pages.dev/en/cli/)** 命令行选项
386
188
 
387
189
  ---
388
190
 
389
- ## 致谢
191
+ ## 链接
390
192
 
391
- standard library 的一部分灵感来自 [kaer-3058/large_number](https://github.com/kaer-3058/large_number),这是一个面向 Minecraft datapacks 的完整数学库。RedScript 在类似算法之上提供了更高层、更类型安全的 API。
193
+ - [在线编辑器](https://redscript-ide.pages.dev)
194
+ - [VSCode 扩展](https://marketplace.visualstudio.com/items?itemName=bkmashiro.redscript-vscode)
195
+ - [npm 包](https://www.npmjs.com/package/redscript-mc)
196
+ - [更新日志](./CHANGELOG.md)
197
+ - [贡献指南](./CONTRIBUTING.md)
392
198
 
393
199
  ---
394
200
 
395
201
  <div align="center">
396
202
 
397
- MIT License · Copyright © 2026 [bkmashiro](https://github.com/bkmashiro)
398
-
399
- *少写一点。多构建一些。更快交付。*
203
+ MIT License · [bkmashiro](https://github.com/bkmashiro)
400
204
 
401
205
  </div>
package/ROADMAP.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # RedScript ROADMAP
2
2
 
3
- > Last updated: 2026-03-22
3
+ > Last updated: 2026-03-23
4
4
  > Current version: 3.0.0
5
5
 
6
6
  ## Legend
@@ -145,7 +145,7 @@ All 50 modules documented with `///` annotations and en+zh generated docs.
145
145
  | Type system reference | ✅ |
146
146
  | Error reference | ✅ |
147
147
  | Blog posts (3) | ✅ |
148
- | Tutorials | 📋 |
148
+ | Tutorials (23 en + 23 zh) | |
149
149
 
150
150
  ---
151
151
 
@@ -154,6 +154,6 @@ All 50 modules documented with `///` annotations and en+zh generated docs.
154
154
  | Item | Status |
155
155
  |------|--------|
156
156
  | redscript-mc v3.0.0 npm publish | ✅ |
157
- | VSCode marketplace v3.0.0 description update | 📋 |
158
- | nest-faster-crud npm publish | 📋 |
159
- | GitHub Release notes | 📋 |
157
+ | VSCode marketplace v3.0.0 description update | |
158
+ | nest-faster-crud npm publish | |
159
+ | GitHub Release notes | |
@@ -0,0 +1,5 @@
1
+ # Generated from: /tmp/impl_test.mcrs:8 (fn get)
2
+ # Source: fn get(self: Counter) -> int
3
+ scoreboard players operation $Counter::get_t0 __impl_test = $p0 __impl_test
4
+ # src: /tmp/impl_test.mcrs:8
5
+ scoreboard players operation $ret __impl_test = $Counter::get_t0 __impl_test
@@ -0,0 +1,7 @@
1
+ # Generated from: /tmp/impl_test.mcrs:7 (fn inc)
2
+ # Source: fn inc(self: Counter) -> Counter
3
+ scoreboard players operation $Counter::inc_t0 __impl_test = $p0 __impl_test
4
+ # src: /tmp/impl_test.mcrs:7
5
+ scoreboard players operation $Counter::inc_t1 __impl_test = $Counter::inc_t0 __impl_test
6
+ scoreboard players add $Counter::inc_t1 __impl_test 1
7
+ scoreboard players operation $ret_val __impl_test = $Counter::inc_t1 __impl_test
@@ -0,0 +1,4 @@
1
+ # Generated from: /tmp/impl_test.mcrs:6 (fn new)
2
+ # Source: fn new() -> Counter
3
+ # src: /tmp/impl_test.mcrs:6
4
+ scoreboard players set $ret_val __impl_test 0
@@ -0,0 +1 @@
1
+ scoreboard objectives add __impl_test dummy
@@ -0,0 +1,10 @@
1
+ # Generated from: /tmp/impl_test.mcrs:11 (fn test_impl)
2
+ # Source: fn test_impl() -> void
3
+ # src: /tmp/impl_test.mcrs:6
4
+ scoreboard players set $ret_val __impl_test 0
5
+ # src: /tmp/impl_test.mcrs:7
6
+ scoreboard players set $ret_val __impl_test 1
7
+ scoreboard players set $ret_val __impl_test 2
8
+ scoreboard players set $ret_val __impl_test 3
9
+ # src: /tmp/impl_test.mcrs:16
10
+ scoreboard players set #impl_out sc_out 3
@@ -0,0 +1,5 @@
1
+ {
2
+ "values": [
3
+ "impl_test:load"
4
+ ]
5
+ }
@@ -0,0 +1 @@
1
+ scoreboard objectives add __playground dummy
@@ -0,0 +1,4 @@
1
+ # Generated from: /tmp/test_say_fstr.mcrs:3 (fn start)
2
+ # Source: fn start() -> void
3
+ # src: /tmp/test_say_fstr.mcrs:5
4
+ function playground:start__say_macro_t1 with storage rs:macro_args
@@ -0,0 +1 @@
1
+ $say Demo started!
@@ -0,0 +1,5 @@
1
+ # Generated from: /tmp/test_say_fstr.mcrs:8 (fn stop)
2
+ # Source: fn stop() -> void
3
+ # src: /tmp/test_say_fstr.mcrs:9
4
+ execute store result storage rs:macro_args counter int 1 run scoreboard players get counter __playground
5
+ function playground:stop__say_macro_t0 with storage rs:macro_args
@@ -0,0 +1 @@
1
+ $say Demo stopped at $(counter) ticks.
@@ -0,0 +1,4 @@
1
+ # Generated from: /Users/yuzhe/projects/redscript/src/stdlib/queue.mcrs:16 (fn __queue_append_apply)
2
+ # Source: fn __queue_append_apply() -> void
3
+ # src: /Users/yuzhe/projects/redscript/src/stdlib/queue.mcrs:17
4
+ $data modify storage rs:arrays Queue append value $(val)
@@ -0,0 +1,4 @@
1
+ # Generated from: /Users/yuzhe/projects/redscript/src/stdlib/queue.mcrs:20 (fn __queue_peek_apply)
2
+ # Source: fn __queue_peek_apply() -> void
3
+ # src: /Users/yuzhe/projects/redscript/src/stdlib/queue.mcrs:21
4
+ $execute store result score $ret __stdlib_queue8_test run data get storage rs:arrays Queue[$(idx)]
@@ -0,0 +1,4 @@
1
+ # Generated from: /Users/yuzhe/projects/redscript/src/stdlib/queue.mcrs:24 (fn __queue_size_raw_apply)
2
+ # Source: fn __queue_size_raw_apply() -> void
3
+ # src: /Users/yuzhe/projects/redscript/src/stdlib/queue.mcrs:25
4
+ $execute store result score $ret __stdlib_queue8_test run data get storage rs:arrays Queue
@@ -0,0 +1 @@
1
+ scoreboard objectives add __stdlib_queue8_test dummy
@@ -0,0 +1,6 @@
1
+ # Generated from: /Users/yuzhe/projects/redscript/src/stdlib/queue.mcrs:120 (fn queue_clear)
2
+ # Source: fn queue_clear() -> void
3
+ # src: /Users/yuzhe/projects/redscript/src/stdlib/queue.mcrs:121
4
+ data modify storage rs:arrays Queue set value []
5
+ # src: /Users/yuzhe/projects/redscript/src/stdlib/queue.mcrs:122
6
+ scoreboard players set rs.q_head __RS__ 0
@@ -0,0 +1,5 @@
1
+ # Generated from: /Users/yuzhe/projects/redscript/src/stdlib/queue.mcrs:107 (fn queue_empty)
2
+ # Source: fn queue_empty() -> int
3
+ # src: /Users/yuzhe/projects/redscript/src/stdlib/queue.mcrs:110
4
+ scoreboard players set $__const_0 __stdlib_queue8_test 0
5
+ scoreboard players operation $ret __stdlib_queue8_test = $__const_0 __stdlib_queue8_test