Flame Jenny 引擎的local命令节点级局部变量的声明、类型注解与作用域实战【免费下载链接】flameA Flutter based game engine.项目地址: https://gitcode.com/GitHub_Trending/fl/flamelocal是 JennyFlame 游戏引擎内置的 YarnSpinner 方言实现位于packages/flame_jenny中用于声明节点级局部变量的内置命令。它允许你在单个对话节点内部创建临时变量并赋予初始值从而在骰子点数、关卡内计时、单次对话临时状态等场景中避免污染全局命名空间。读完本文你将掌握local的两种声明语法、as TYPE类型注解的作用、它与全局变量declare的边界划分以及隐藏在源码与测试用例背后的作用域与生命周期机制。什么是local与declare的分工在 Jenny 的 YarnSpinner 语言中所有变量名都以$符号开头如$roll、$money每个变量同时具有名称、值、类型、作用域四个属性其中作用域分为两类全局变量通过 declare 命令在脚本根层级node 之外声明一旦创建即可在整个项目中任意位置访问所有全局变量名全局唯一局部变量通过 local 命令在节点内部声明只能在声明它的那一个节点内使用。local与declare的核心区别在于可见范围前者创建的变量只存在于当前节点后者创建的变量对整个项目可见。正因如此language 文档明确说明允许出现在文件根层级的命令只有declare与characterlocal必须书写在 node 内部——它和set、if、jump一样属于运行时指令在对话执行到该行时才生效而declare则在编译期YarnProject解析 yarn 脚本时即完成变量注册。local的两种声明语法local的完整语法如下local $VARIABLE EXPRESSION local $VARIABLE EXPRESSION as TYPE第一种形式创建一个名为$VARIABLE的局部变量并将EXPRESSION的值赋给它。变量的类型由EXPRESSION的类型自动推导无需显式声明。第二种形式在第一种形式基础上附加as TYPE显式类型注解。编译器会校验EXPRESSION的类型是否与TYPE一致若不一致则抛出编译期错误。因此第二种形式既是对读者和代码审查者的意图声明也是编译期的类型护栏。其中TYPE可取值为Bool、Number、String三者之一分别对应布尔、数字、字符串三种基础类型。EXPRESSION可以是字面量、变量、操作符表达式或函数调用例如内置的dice(n)、randomRange(a, b)等随机数函数。例如下面的写法把$roll显式声明为 Number 类型并赋予掷骰结果local $roll dice(6) as Number如果dice(6)的返回值不是数字类型编译器会直接报错从源头拦截类型漂移。两条必须遵守的限制原文档强调local在使用中有两条硬性限制违反任意一条都会导致编译期错误在源码测试中被实现为NameError见下文每个局部变量在一个节点内只能声明一次。同一个节点内出现两次local $x ...即视为重复声明。若确需在节点内复用同一变量应先local声明一次之后用 set 更新其值。局部变量名不能与任何全局变量重名。这是为了杜绝局部变量遮蔽全局变量的隐晦行为保证变量解析永远无歧义。但需要注意不同节点之间可以各自声明同名的局部变量它们是完全独立的两个变量互不影响。实战示例节点内的临时掷骰逻辑原文档给出了一个非常典型的使用场景——骰子点数只在当前节点内临时需要没必要占用全局命名空间title: a_dice_roll --- local $roll dice(6) if $roll 1 Youve rolled 1, rotten luck... elseif $roll 2 Youve rolled 2, which is still below the average. Try harder! elseif $roll 3 Youve rolled 3.14159265 (well, almost). elseif $roll 4 Your roll is an unlucky number. Please roll again else Youve rolled 10 (when rounded to the nearest ten). Good job! endif 这个示例同时展示了local与 if 条件分支的联动$roll只在本节点内参与判断与文本渲染节点结束后即失去意义因此作为局部变量是语义上最贴切的选择。dice(6)是 Jenny 内置的随机数函数源码位于packages/flame_jenny/jenny/lib/src/structure/expressions/functions/dice.dart每次执行节点时都会产生新的随机值。进一步地局部变量同样支持在内联表达式中渲染以及与set的复合赋值联动title: Counter --- local $i 3 Value of $i {$i} set $i 10 Value of $i {$i} 运行结果依次输出Value of $i 3与Value of $i 13——局部变量在节点内的读取、渲染、修改链路与全局变量完全一致。源码级剖析局部变量到底存在哪里要理解local的生命周期最直接的方式是阅读它的实现。命令本体在 local_command.dart 中仅有 20 行class LocalCommand extends Command { const LocalCommand(this.variable, this.expression, this.storage); final String variable; final Expression expression; final VariableStorage storage; override String get name local; override void execute(DialogueRunner dialogue) { storage.setVariable(variable, expression.value); } }从源码结构可以看出两个关键设计每个LocalCommand持有独立的VariableStorage实例。它不是写入项目级全局存储而是写入当前节点专属的变量存储对应Node内部的variables字段。这正是节点内可见这一语义的直接实现——局部变量的作用域边界就是Node对象本身。执行语义就是一次赋值execute调用storage.setVariable(variable, expression.value)把表达式求值结果写入局部存储。再来看 variable_storage.dart 中setVariable的类型约束void setVariable(String name, dynamic value) { final dynamic oldValue variables[name]; if (!(value is String || value is num || value is bool)) { throw DialogueError(Cannot set variable $name to a value with type ...); } if (oldValue ! null !(value is String oldValue is String) !(value is num oldValue is num) !(value is bool oldValue is bool)) { throw DialogueError(Redefinition of variable $name from type ... is not allowed); } variables[name] value; }这意味着局部变量的类型在首次写入后就被钉死后续若试图用不同类型的值覆盖会抛出DialogueError。这与文档中类型在变量首次声明时确定、之后永不变更的规则完全吻合参见 variables.md。用测试用例验证作用域与边界行为Jenny 为local编写了完整的单元测试位于 local_command_test.dart它们恰好逐条印证了文档的每一条规则1. 局部变量与全局变量存储分离parse 测试final command node.lines[0] as LocalCommand; expect(command.storage yarn.variables, false); expect(command.storage node.variables, true); expect(yarn.variables.hasVariable(r$x), false); expect(node.variables!.hasVariable(r$x), true);测试断言LocalCommand写入的是node.variables而非yarn.variables从而验证local $x声明的变量不会出现在全局存储中二者是物理隔离的两套存储。2. 节点重复执行时局部变量可重新初始化local command executed multiple times 测试declare $counter 0 --- title: Start --- local $i 5 - $counter Countdown ...{$i} set $counter 1 if $counter 5 jump Start else GO! endif 期望输出Countdown ...5、4、3、2、1然后GO!。虽然Start节点被jump反复进入但每次进入都重新执行local $i ...因此局部变量每次都被重新初始化——局部变量的生命周期跟随节点的一次执行而非整个对话会话。这也解释了为何每节点只能声明一次而不会与节点多次执行冲突限制的是文本中的声明次数而不是运行时的初始化次数。3. 未执行到的local分支visibility 测试title: Start --- First line if false local $x 137 else Value of x is {$x} set $x 5 endif Now x {$x} 期望输出First line、Value of x is 0、Now x 5。即便local $x 137位于永假分支而从未执行$x仍以类型默认值 0存在于节点存储中对应Number类型的零值内联表达式{$x}可以正常读取随后set $x 5将其更新为 5。这一行为揭示了局部变量在编译期即完成注册并赋予类型默认值false、0、LocalCommand.execute只是在实际执行到该行时用表达式结果覆盖默认值。4. 两条限制的编译期报错errors 测试组同节点重复声明local $x两次报错NameError: redeclaration of local variable $x局部变量与全局变量同名报错NameError: variable $x shadows a global variable with the same name若对local使用as String而缺少赋值local $x as String则报SyntaxError: assignment operator is expected——说明local必须携带初始赋值表达式不存在只声明类型不赋初值的写法这一点与declare的declare $name as String形式不同。local与相关命令的完整关系在 命令总览 中local归属于变量类内置命令与它协同工作的命令包括命令作用与local的关系declare声明全局变量编译期、根层级局部变量的对立面二者命名空间互斥set更新已有变量值含、-等复合赋值局部变量声明后靠它修改且类型必须一致if条件分支局部变量常在分支内参与条件判断jump跳转到另一节点跳转后局部变量随之失效生命周期终止内联表达式{...}将变量值插入对话文本可读取当前节点的局部变量值得注意的联动细节是local声明的变量在声明行之后的同节点代码中即可被set修改、被内联表达式读取这与全局变量的用法完全一致差别只在于跳出节点后局部变量便不再存在任何对该名称的引用都会在编译期被判定为未声明。实践建议何时用local何时用declare综合文档与实现可以给出清晰的选型准则只在一个节点内部使用、且不跨节点保留的临时状态如骰子点数、本次对话中的临时计数、局部分支结果→ 用local。它的好处是命名空间干净不会污染全局变量表也不会在存档系统保存全局变量值中留下无意义的条目。需要跨节点共享、参与存档、或由游戏逻辑如DialogueRunner之外的代码读取的状态如主角金币、剧情标志位、好感度→ 必须用declare声明为全局变量。避免临时变量与全局变量重名因为规则明确禁止遮蔽如果你的项目已有大量全局变量为局部变量约定前缀如$_或$tmp_是降低冲突概率的实用做法。善用as TYPE注解在表达式类型不直观时例如randomRange(1, 365)、自定义函数返回值显式标注类型既能自文档化又能获得编译期类型校验把错误提前到解析阶段而非运行时。关于运行与调试local的行为可以在packages/flame_jenny包中通过dart test test/structure/commands/local_command_test.dart独立验证更完整的 Jenny 运行时DialogueRunner、VariableStorage的对外 API可参考 runtime 文档 与 jenny.md。在实际 Flame 游戏中只需在pubspec.yaml引入flame_jenny依赖并创建YarnProject解析.yarn文件即可享受这套严谨的变量作用域体系带来的可维护性。【免费下载链接】flameA Flutter based game engine.项目地址: https://gitcode.com/GitHub_Trending/fl/flame创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Flame Jenny 引擎的 `＜＜local＞＞` 命令：节点级局部变量的声明、类型注解与作用域实战
Flame Jenny 引擎的local命令节点级局部变量的声明、类型注解与作用域实战【免费下载链接】flameA Flutter based game engine.项目地址: https://gitcode.com/GitHub_Trending/fl/flamelocal是 JennyFlame 游戏引擎内置的 YarnSpinner 方言实现位于packages/flame_jenny中用于声明节点级局部变量的内置命令。它允许你在单个对话节点内部创建临时变量并赋予初始值从而在骰子点数、关卡内计时、单次对话临时状态等场景中避免污染全局命名空间。读完本文你将掌握local的两种声明语法、as TYPE类型注解的作用、它与全局变量declare的边界划分以及隐藏在源码与测试用例背后的作用域与生命周期机制。什么是local与declare的分工在 Jenny 的 YarnSpinner 语言中所有变量名都以$符号开头如$roll、$money每个变量同时具有名称、值、类型、作用域四个属性其中作用域分为两类全局变量通过 declare 命令在脚本根层级node 之外声明一旦创建即可在整个项目中任意位置访问所有全局变量名全局唯一局部变量通过 local 命令在节点内部声明只能在声明它的那一个节点内使用。local与declare的核心区别在于可见范围前者创建的变量只存在于当前节点后者创建的变量对整个项目可见。正因如此language 文档明确说明允许出现在文件根层级的命令只有declare与characterlocal必须书写在 node 内部——它和set、if、jump一样属于运行时指令在对话执行到该行时才生效而declare则在编译期YarnProject解析 yarn 脚本时即完成变量注册。local的两种声明语法local的完整语法如下local $VARIABLE EXPRESSION local $VARIABLE EXPRESSION as TYPE第一种形式创建一个名为$VARIABLE的局部变量并将EXPRESSION的值赋给它。变量的类型由EXPRESSION的类型自动推导无需显式声明。第二种形式在第一种形式基础上附加as TYPE显式类型注解。编译器会校验EXPRESSION的类型是否与TYPE一致若不一致则抛出编译期错误。因此第二种形式既是对读者和代码审查者的意图声明也是编译期的类型护栏。其中TYPE可取值为Bool、Number、String三者之一分别对应布尔、数字、字符串三种基础类型。EXPRESSION可以是字面量、变量、操作符表达式或函数调用例如内置的dice(n)、randomRange(a, b)等随机数函数。例如下面的写法把$roll显式声明为 Number 类型并赋予掷骰结果local $roll dice(6) as Number如果dice(6)的返回值不是数字类型编译器会直接报错从源头拦截类型漂移。两条必须遵守的限制原文档强调local在使用中有两条硬性限制违反任意一条都会导致编译期错误在源码测试中被实现为NameError见下文每个局部变量在一个节点内只能声明一次。同一个节点内出现两次local $x ...即视为重复声明。若确需在节点内复用同一变量应先local声明一次之后用 set 更新其值。局部变量名不能与任何全局变量重名。这是为了杜绝局部变量遮蔽全局变量的隐晦行为保证变量解析永远无歧义。但需要注意不同节点之间可以各自声明同名的局部变量它们是完全独立的两个变量互不影响。实战示例节点内的临时掷骰逻辑原文档给出了一个非常典型的使用场景——骰子点数只在当前节点内临时需要没必要占用全局命名空间title: a_dice_roll --- local $roll dice(6) if $roll 1 Youve rolled 1, rotten luck... elseif $roll 2 Youve rolled 2, which is still below the average. Try harder! elseif $roll 3 Youve rolled 3.14159265 (well, almost). elseif $roll 4 Your roll is an unlucky number. Please roll again else Youve rolled 10 (when rounded to the nearest ten). Good job! endif 这个示例同时展示了local与 if 条件分支的联动$roll只在本节点内参与判断与文本渲染节点结束后即失去意义因此作为局部变量是语义上最贴切的选择。dice(6)是 Jenny 内置的随机数函数源码位于packages/flame_jenny/jenny/lib/src/structure/expressions/functions/dice.dart每次执行节点时都会产生新的随机值。进一步地局部变量同样支持在内联表达式中渲染以及与set的复合赋值联动title: Counter --- local $i 3 Value of $i {$i} set $i 10 Value of $i {$i} 运行结果依次输出Value of $i 3与Value of $i 13——局部变量在节点内的读取、渲染、修改链路与全局变量完全一致。源码级剖析局部变量到底存在哪里要理解local的生命周期最直接的方式是阅读它的实现。命令本体在 local_command.dart 中仅有 20 行class LocalCommand extends Command { const LocalCommand(this.variable, this.expression, this.storage); final String variable; final Expression expression; final VariableStorage storage; override String get name local; override void execute(DialogueRunner dialogue) { storage.setVariable(variable, expression.value); } }从源码结构可以看出两个关键设计每个LocalCommand持有独立的VariableStorage实例。它不是写入项目级全局存储而是写入当前节点专属的变量存储对应Node内部的variables字段。这正是节点内可见这一语义的直接实现——局部变量的作用域边界就是Node对象本身。执行语义就是一次赋值execute调用storage.setVariable(variable, expression.value)把表达式求值结果写入局部存储。再来看 variable_storage.dart 中setVariable的类型约束void setVariable(String name, dynamic value) { final dynamic oldValue variables[name]; if (!(value is String || value is num || value is bool)) { throw DialogueError(Cannot set variable $name to a value with type ...); } if (oldValue ! null !(value is String oldValue is String) !(value is num oldValue is num) !(value is bool oldValue is bool)) { throw DialogueError(Redefinition of variable $name from type ... is not allowed); } variables[name] value; }这意味着局部变量的类型在首次写入后就被钉死后续若试图用不同类型的值覆盖会抛出DialogueError。这与文档中类型在变量首次声明时确定、之后永不变更的规则完全吻合参见 variables.md。用测试用例验证作用域与边界行为Jenny 为local编写了完整的单元测试位于 local_command_test.dart它们恰好逐条印证了文档的每一条规则1. 局部变量与全局变量存储分离parse 测试final command node.lines[0] as LocalCommand; expect(command.storage yarn.variables, false); expect(command.storage node.variables, true); expect(yarn.variables.hasVariable(r$x), false); expect(node.variables!.hasVariable(r$x), true);测试断言LocalCommand写入的是node.variables而非yarn.variables从而验证local $x声明的变量不会出现在全局存储中二者是物理隔离的两套存储。2. 节点重复执行时局部变量可重新初始化local command executed multiple times 测试declare $counter 0 --- title: Start --- local $i 5 - $counter Countdown ...{$i} set $counter 1 if $counter 5 jump Start else GO! endif 期望输出Countdown ...5、4、3、2、1然后GO!。虽然Start节点被jump反复进入但每次进入都重新执行local $i ...因此局部变量每次都被重新初始化——局部变量的生命周期跟随节点的一次执行而非整个对话会话。这也解释了为何每节点只能声明一次而不会与节点多次执行冲突限制的是文本中的声明次数而不是运行时的初始化次数。3. 未执行到的local分支visibility 测试title: Start --- First line if false local $x 137 else Value of x is {$x} set $x 5 endif Now x {$x} 期望输出First line、Value of x is 0、Now x 5。即便local $x 137位于永假分支而从未执行$x仍以类型默认值 0存在于节点存储中对应Number类型的零值内联表达式{$x}可以正常读取随后set $x 5将其更新为 5。这一行为揭示了局部变量在编译期即完成注册并赋予类型默认值false、0、LocalCommand.execute只是在实际执行到该行时用表达式结果覆盖默认值。4. 两条限制的编译期报错errors 测试组同节点重复声明local $x两次报错NameError: redeclaration of local variable $x局部变量与全局变量同名报错NameError: variable $x shadows a global variable with the same name若对local使用as String而缺少赋值local $x as String则报SyntaxError: assignment operator is expected——说明local必须携带初始赋值表达式不存在只声明类型不赋初值的写法这一点与declare的declare $name as String形式不同。local与相关命令的完整关系在 命令总览 中local归属于变量类内置命令与它协同工作的命令包括命令作用与local的关系declare声明全局变量编译期、根层级局部变量的对立面二者命名空间互斥set更新已有变量值含、-等复合赋值局部变量声明后靠它修改且类型必须一致if条件分支局部变量常在分支内参与条件判断jump跳转到另一节点跳转后局部变量随之失效生命周期终止内联表达式{...}将变量值插入对话文本可读取当前节点的局部变量值得注意的联动细节是local声明的变量在声明行之后的同节点代码中即可被set修改、被内联表达式读取这与全局变量的用法完全一致差别只在于跳出节点后局部变量便不再存在任何对该名称的引用都会在编译期被判定为未声明。实践建议何时用local何时用declare综合文档与实现可以给出清晰的选型准则只在一个节点内部使用、且不跨节点保留的临时状态如骰子点数、本次对话中的临时计数、局部分支结果→ 用local。它的好处是命名空间干净不会污染全局变量表也不会在存档系统保存全局变量值中留下无意义的条目。需要跨节点共享、参与存档、或由游戏逻辑如DialogueRunner之外的代码读取的状态如主角金币、剧情标志位、好感度→ 必须用declare声明为全局变量。避免临时变量与全局变量重名因为规则明确禁止遮蔽如果你的项目已有大量全局变量为局部变量约定前缀如$_或$tmp_是降低冲突概率的实用做法。善用as TYPE注解在表达式类型不直观时例如randomRange(1, 365)、自定义函数返回值显式标注类型既能自文档化又能获得编译期类型校验把错误提前到解析阶段而非运行时。关于运行与调试local的行为可以在packages/flame_jenny包中通过dart test test/structure/commands/local_command_test.dart独立验证更完整的 Jenny 运行时DialogueRunner、VariableStorage的对外 API可参考 runtime 文档 与 jenny.md。在实际 Flame 游戏中只需在pubspec.yaml引入flame_jenny依赖并创建YarnProject解析.yarn文件即可享受这套严谨的变量作用域体系带来的可维护性。【免费下载链接】flameA Flutter based game engine.项目地址: https://gitcode.com/GitHub_Trending/fl/flame创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考