积木文本语法

积木页文本、命令行（gandi）、本机 MCP 和积木注释里的 gandi-dsl 片段，都用同一种文本来描述积木。 控制、运算、变量和列表写成 JavaScript 的样子，其余积木写成 分类.积木名(...)。文本从不执行， 只是积木的另一种写法：积木打印成文本、文本编回积木，结构完全一致。

const score = stage.variable("score", 0);
const items = sprite.list("items", []);

when.flagclicked(() => {
    score = 0;
    for (let i = 1; i <= 10; i++) {
        items.push(i * 2);
        if (i % 3 == 0 && !sensing.mousedown()) {
            score += 1;
        } else if (i > 8) {
            looks.say(`第 ${i} 个`);
        }
    }
    repeat(3, () => { motion.movesteps(10); });
});

旧的块式写法（control.if(operator.gt(a, 1), () => { ... })、data.set(x, 1)）一直可用， 编出的积木相同。读回积木时，能写成 JavaScript 的地方都写成 JavaScript；写不成的保持块式（见细节）。

声明#

要新建变量、列表或广播，在文件开头声明，const 和 let 等价：

项目里已有的变量和列表不用声明，直接按名字写（x = 1;、L.push(v);）。只有三种情况要声明：新建一个； 角色变量和全局变量同名（不声明会报 E_AMBIGUOUS_VAR，声明时选 sprite.variable 还是 stage.variable）； 同名的变量和列表要用列表写法（L.push(...)）。引用从不新建变量，名字不存在报 E_UNKNOWN_VAR。 for 的循环变量也一样：要么项目里已有，要么先声明，例如 const i = sprite.variable("i", 0);。

读回积木时只声明这一页用到的变量，声明里的字符串是变量的真名，标识符可以不同：名字写不成标识符 （my score、☁ x、_）叫 _variable；和积木分类同名（data、motion……）、和这一页任何自制积木的形参同名的， 标识符加数字后缀（p → p2），重名的往后编号。例如变量 p 和自制积木形参 p 同名时：

const p2 = sprite.variable("p", 0);          // 真名还是 "p"
define("f %n", (p) => { p2 = p; });          // 形参 p 和变量 p2 不会混

控制#

while (true) 的循环体里有 break; 时，它是「当 真 重复执行」而不是「重复执行」： 「重复执行」是终结积木，后面不能再接积木，会结束的循环可以。break; 和 continue; 只能写在 while、for 语句里；repeat、repeatUntil 的回调里写 control.break()、 control.continue()。

定义之外孤立的「返回」积木在运行时合法（相当于停止这个脚本，TurboWarp 作品里有），读回时写成块式 procedures.return(值)，编译只给 W_RETURN_OUTSIDE 警告；要停止脚本写 stop("this script")。

for 的语义#

for (let i = 1; i <= n; i++) 编成「对于每个 i（1 到 n）」积木，和 JavaScript 的 for 不一样（VM 实测，解释器和编译执行一致）：

起点只能写 1，步长只能是 ++ 或 += 1，条件只能是 i <= n，别的写法报 E_UNSUPPORTED_FOR。

运算#

运算符的优先级与 JavaScript 相同，a + b * 2 是 a + (b * 2)，积木是嵌套的两个运算积木。

&&、||、! 和 if、while 的条件必须是布尔积木：比较、true / false、侦测里的判断等。 变量不是布尔值，要写成 x != 0。

变量与列表#

显示、隐藏变量仍写 data.showvariable(x)、data.hidevariable(x)。运动、外观、声音、事件、侦测等 其余积木都写成 分类.积木名(...)，需要的积木名用 gandi blocks 关键词 查。

和 JavaScript 不同的地方#

不支持函数表达式、new、typeof、??、switch、do...while、async。对象和数组只能写在其他写法 列出的位置（可增减的参数组、命名参数），不能当值用。作品装了「高级数据结构」时，对象和数组字面量、typeof、new Set(...) 是它的积木，见高级数据结构的文本写法。

Gandi 专有积木#

===、!==、**（Math.pow）、条件 ? a : b、break、continue 编成 Gandi 才有的积木 （operator_strictequals、operator_power、operator_ternary、control_break、control_continue）。 原版 Scratch 没有这些操作码，含有它们的作品导出到原版 Scratch 后打不开。check 和写入时编译会给 W_GANDI_ONLY 警告，列出用到的积木，不阻断写入；作品要在原版 Scratch 里打开就别用： === 换 ==，break / continue 换条件变量加 while / repeatUntil，**、三元换乘法和 if。

其他写法#

• 命名参数：looks.say({MESSAGE: "hi"})，键是积木的输入名或字段名，写了不存在的键报 E_UNKNOWN_ARG， 新积木缺必填字段报 E_MISSING_ARG。命名参数和位置参数不能混用；有回调时回调是第二个参数。
• 可增减的参数组（扩展积木的 ➕➖ 参数）：固定参数照常写，后面每个组写成数组或对象： gandiScene.switchToWithParams("main", {关卡: 1, 难度: 2})（键 = 值 两格一组写成对象）、 ext.block(a, [x, y, z])（一格一组写成数组）、[[键, 值], ...]（键写不成属性名时）。数字样的键、 typed / reference / opcode 等保留名不能当对象键，会退回 [[键, 值], ...]。核心积木的多操作数写成 operator.add(a, b, c)、混合运算符写成 operator.arithmetic(a, "+", b, "-", c)。 扩展声明了「逐槽选类型」（types）的组，每个槽放什么由槽里的值定：布尔积木是布尔槽（槽里没有文字框），数字是数字槽， 文字是文字槽；类型存在积木的 argtypes 里，带底写回原样保留，纯文本重编会按槽里的值重新写出。 超过个数上限报一条 E_VARIADIC_LIMIT（不是每个多出来的槽一条未知输入），积木上带着 items="2" 这类和槽数一致的旧属性，写回时原样保留。
• 阈值型 hat：when.greaterthan("LOUDNESS", 10, () => { ... }) 的阈值是数字框，可以换成报告器 （when.greaterthan("TIMER", sensing.answer(), ...)）；它没有参数椭圆，写回调形参报 E_HAT_PARAMS。
• hat 回调的形参：带参数椭圆的 hat 把椭圆名写成回调形参，体内直接用： gandiScene.whenSceneStartsWithParams((level, 难度) => { looks.say(level); })。形参只在这个回调里有效， 不能赋值；椭圆名写不成标识符或和变量重名时退回 ["名字", ...] 加 ccw.hat_parameter("名字")。 hat 没有参数椭圆却写了形参报 E_HAT_PARAMS。回调形参 _ 表示「不要这个参数」，参数名真叫 _ 时退回字符串位置写法。
• 自制积木：define("go %n", (steps) => { ... }); 和 call["go %n"](10);，形参 %n 数字、%s 文字、 %b 布尔、%c 积木堆（体内 body() 调用）。变量和形参同名时形参优先，读回时变量会改名（见声明）。
• 积木注释：积木前写 /** 文字 */，多行用每行 * 开头的 JSDoc 样式；文字有首尾空白、*/、\r 时写成精确 写法 /** @text "..." */。空注释写 /** */。挂在 reporter 上的注释写成 (/** 文字 */ 表达式)，括号让 注释挂在这一整块上。普通注释（//、/* */）不会存进积木，会给 W_COMMENT_DROPPED 警告； else /** 注释 */ if 这种不在语句或表达式前面的注释同样被丢并警告。
• 装饰器：@at(x, y)、@warp、@global、@reporter、@boolean、@collapsed、@id("...")、@size、@color、 @locked、@note(...) 只能写在顶层语句或 frame() 前面（中间只隔空白和注释）；写在回调里、或后面没有语句， 报 E_DECORATOR。
• 深度上限：语句和表达式嵌套超过 400 层报 E_TOO_DEEP（带上限数），长链（几百项的 +、&&、模板） 拆成几条语句。读回积木时嵌套超过 180 层也会拒绝打印并报同一个错，不会截断。

回调形参#

积木上有「参数槽」时，参数槽写成回调的形参。参数槽是积木上一个只能放自己那块参数积木的输入：遍历积木的「键」「值」、 map 积木的「项」「序号」、reduce 的「累积值」……（hat 积木的参数椭圆是同一类，见上面的 hat 回调）。

ext.each(list, (key, value) => { looks.say(value); });   // C 形积木：回调体是积木堆
r = ext.map(list, (item, index) => item * 2);             // 回调体是一个表达式（lambda 积木）

• 回调永远是最后一个参数，前面是积木上其余的固定参数（按积木上的顺序）。具名写法把回调放在回调体输入的键里 （{LIST: list, SUBSTACK: (key, value) => {...}}）或者作第二个参数。没有形参的 () => { ... } 也认。
• 形参依次绑定参数槽，个数不能超过槽数（E_HAT_PARAMS），少写的槽照样在积木上；形参名只是文字里的写法。体里用形参就是 引用槽里那块参数积木，所以形参只在这个回调体里有效，不能赋值（E_ASSIGN_PARAM），回调外面再用报 E_UNKNOWN_VAR。
• 回调体的种类要对：C 形口写 { ... }，lambda 写表达式，写反了报 E_SLOT_TYPE。lambda 体里的 true / false、字面量照常编。
• 参数槽的名字：槽里是自己的可再生积木的（item、key……），打印时取槽名的小写（IDX 写 index）；槽里是默认名的参数椭圆的，取椭圆名。 重名或和变量冲突就加数字（item2）。
• 里层回调盖住外层的同一块参数积木：两个回调积木用的是同一块参数积木（例如都有 item）时，运行时读最近一层的值。 在里层体里写外层的形参报 E_PARAM_SHADOWED，要用就先放进变量；这包括里层没写形参的槽。
• 参数槽被别的积木盖住、缺输入、体不是标准形状的积木，读回时保持位置参数写法（参数槽里的标准影子写成它自己的调用， ext.forEachKey()），编译回去是同一块积木。
• 老的「每个槽都写出来」的位置写法（ext.each(list, "ITEM", "POS", () => {...})、参数槽里写参数积木的调用）照常可用。

带点和特殊字符的扩展 id#

积木写成 扩展id.积木名(...)。扩展 id 不一定是单个标识符，写法按 id 的样子定，打印和解析互逆（积木 → 文本 → 积木结构一致）：

• 积木的操作码是 扩展id_积木名；解析成积木后和普通扩展没有区别，E_UNKNOWN_BLOCK 的报错里是完整的操作码， 没装的扩展（test.moreDataTypes.getNewSet(...)）报「积木不存在」并带上完整 id，宿主据此去装扩展。
• 分类名、带点 id 的第一段（test）和 ext 在文本里是前缀：变量、形参不能叫这些名字（读回积木时同名的变量会改名， 如 test2，声明里的字符串真名不变）。文件里声明了同名变量时，那个名字就是变量，不再当扩展前缀。
• 装了「高级数据结构」时，没对上已装扩展 id 的成员链（o.a.b.push(v)）是对象属性路径，不是积木调用。

细节#

下列积木打印时保持块式，因为写成 JavaScript 读回来会变样：

• 在比较下拉里选了 ≠、≥、≤、≡ 的紧凑比较积木，以及带可增减参数的算术、逻辑、连接、三元积木： operator.compare(...)、operator.arithmetic(...)、operator.logic(...)、operator.join(...)、 operator.ternary({...})。
• 带 else if 分支的「如果」积木（多条件的紧凑形态）。
• 「否则」槽里的内层「如果」带注释、或下面还有别的积木时，写成 else { ... }，不写成 else if。
• 嵌套在左边的连接积木 连接(连接(a, b), c)；只有嵌套在右边的链才写成模板字符串。
• 条件恰好是 true 而循环体里没有 break 的「当…重复执行」：写成 control.while(true, ...)。
• 循环体里有 break 的「重复执行」：写成 control.forever(...)。
• repeat、repeatUntil 回调里的「跳出循环」：写成 control.break()。
• 名字和积木分类同名的变量（data、motion……）、和自制积木形参同名的变量、写不成标识符的名字（含 _）： 打印时改标识符（加后缀，如 data2、p2；写不成标识符的叫 _variable），声明里的字符串真名不变。
• 定义之外的「返回」积木：写成 procedures.return(值)，不写成 return。
• 带注释的 reporter：写成 (/** 注释 */ 表达式)。

没装扩展的积木页是只读的#

作品用了还没装的扩展时，读这一页会先自动装上它（和写入同一套：协作中要有 edit.project、要用户同意，已授权的设备不再逐次确认； 装第三方代码，所以这是读取会改动环境的一处，结果里带 installedExtensions）。装不上的页（扩展库里没有、没权限、不同意、超时） 退回只读预览：扩展积木写成 扩展.积木({ 输入名: 值 })，结果带 degraded: true 和 missingExtensions。

预览看不到积木上的隐藏结构（mutation、菜单影子、布尔槽的空位），写回会悄悄改掉它们，所以含预览的页一律不能写： write_file、edit_file、apply_patch、transaction 都报 E_DEGRADED_WRITE（check 也报，details.missingExtensions 列出缺的扩展）， 页和积木表原样不动。先装好扩展，重新读这一页拿到正式写法，再改。

• 扩展 id 带下划线（my_ext）时，按已知的扩展 id（已装的、扩展库里的）取最长前缀还原，不会当成 my。
• search_files 先在预览上搜，只为命中的缺扩展页装扩展，再重新打印命中页；大列表折叠成占位的页搜不到列表里的内容， 结果带 folded: true、totalExact: false。
• 多场景：积木页按角色所在场景的舞台解析变量和广播，那个舞台取不到时读、检查、写入都报 E_STAGE_CONTEXT，不会悄悄换成入口场景的舞台。 页面里指向看不见的变量（别的场景舞台上的、已删除的）的旧引用，写回时沿用原来的 id，不新建变量，给 W_VARIABLE_NOT_VISIBLE 警告。 场景在读和写之间改过名，写入会因为修订号变了报 E_CONFLICT；文本里的场景名和积木原来指向的场景对不上时给 W_SCENE_RENAMED。

报错#

警告（warnings，不阻断写入）：

相关#

• 本机 MCP：用命令行或 AI 工具读写作品
• 积木注释：注释里可拖出的 gandi-dsl 片段
• 补全的积木：break、continue、三元、≠ 等积木