会话变量
查询 ctx、context、meta 的全部操作、可见范围与刷新规则。
变量在哪一层
| 变量 | 可见范围 | 适合用途 |
|---|---|---|
| 普通 Kether 脚本临时变量 | 当前这段脚本及其执行上下文 | 一段计算的中间值；不是跨点击状态 |
ctx 普通键 | 当前玩家的当前菜单会话 | 分类、计数、按钮状态 |
输入 catch 的结果 | 输入回调；成功重开时传入新会话 | 搜索词、多步输入的答案 |
meta | 玩家在线期间的 Bukkit 临时元数据 | 跨菜单的临时标记，不保证重启保留 |
player@... / global@... | 持久数据，并载入会话 | 个人设置、全局数据，见持久数据 |
{{&key}} 从文字的当前求值上下文读取变量；{{ctx get key}} 明确读取当前活动菜单会话。这两种方式在普通图标文字中常有相同结果，在菜单已关闭的输入回调中则不等价。
ctx / context
语法：ctx 操作 [键] [to 值]。context 是根语句别名；数值修改中的连接词也可以用 by。操作名按表中大小写填写。
| 语句 | 别名或参数 | 返回或可见效果 |
|---|---|---|
ctx get key | 需要键 | 返回会话中的值；不存在时为空 |
ctx has key | 需要键 | 返回是否存在且文字非空白；0、false 都属于有值 |
ctx without key | no | 返回是否没有有效值，正好与 has 相反 |
ctx set key to value | to 可用 by | 设置会话及当前脚本中的值；值不能为 null |
ctx del key | rem、delete | 删除当前脚本与会话里的键；持久键删除有区别，见持久数据页 |
ctx inc key by 1 | increase、+=；by 可用 to | 按数值增加，原键不存在时从 0 起算 |
ctx dec key by 1 | decrease、-=；by 可用 to | 按数值减少，原键不存在时从 0 起算 |
ctx update | 不填写键 | 合并载入当前玩家与全局的持久数据，不刷新图标 |
解析时键名可省略，但任意操作省略键名都会转为 update，不是读取或删除全部变量；meta 也采用这一规则。
这些操作依赖当前活动会话；关闭菜单后不要用 ctx 保存输入回调的状态。get 不会回退读取普通脚本变量。set / inc / dec 的值是可求值的 Kether 参数，使用能立即返回的值。
数值增减会转换数值；负的小数结果目前可能被截成整数。如果需要精确的小数计算，先用适合的计算语句取得结果，再 ctx set 写入。
ctx update 只合并已有数据，不会删除会话里已经缓存、而存储中已被删除的旧键，也不会刷新正在运行脚本的一切临时变量。重新打开菜单可建立新的数据视图。
点击计数
在菜单顶层初始化：
events:
pre_open: 'ctx set clicks to 0 true'在现有面板的 icons 下加入按钮，并在该面板布局中安排 A：
A:
material: PAPER
name: '&f点击次数: {{&clicks}}'
action: 'ctx inc clicks by 1 icon update'每次打开从 0 开始，点击增加 1，然后更新当前图标文字。只改变量不会自动重绘图标。
选择刷新方式
| 状态变化 | 使用方式 |
|---|---|
| 仅名称、Lore、数量等文字或物品显示变化 | icon update / icons update |
| 子图标条件变化 | icon refresh，或 icons relocate 后 icons update |
| 生成器筛选、排序变化 | regenerate，再单独刷新固定导航和状态按钮 |
| 要重建现有生成器显示缓存 | icons refresh；生成器回第一页，不等于重新请求数据源 |
全部刷新、暂停和恢复操作见语句参考。操作闭环见权限按钮和搜索列表。
切换菜单
menu open help 创建新会话，不带普通临时状态；menu switch help（menu open_ctx help）把当前会话变量传给目标菜单。目标菜单的初始化事件仍然执行，可能覆盖传入值。持久数据在新会话中会重新载入。
meta
语法：meta 操作 [键] [to 值]，to 也可用 by。需要玩家，不需要仍然打开菜单；不会自动加入 {{&key}} 的会话变量中，读取时使用 {{meta get key}}。
| 语句 | 别名 | 返回或可见效果 |
|---|---|---|
meta get key | — | 返回该键的第一个 Bukkit 元数据值，可能来自其他插件 |
meta has key | — | 返回是否存在元数据 |
meta no key / meta without key | — | 目前同样返回“是否存在”，不能当作不存在判断 |
meta set key to value | by 替代 to | 写入本插件的元数据；没有有效值时不写入 |
meta del key | rem、delete | 删除本插件的该键元数据 |
meta inc key by 1 | increase、+= | 增加数值，缺失值从 0 起算 |
meta dec key by 1 | decrease、-= | 减少数值，缺失值从 0 起算 |
meta update | 不填写键 | 目前与 ctx update 一样刷新会话的持久数据，不是元数据刷新 |
未知 meta 操作会返回提示文字，而不是执行写入；普通 ctx 的未知操作则会失败。
对不存在条件进行判断时，不依赖 meta no / meta without 的名称。临时标记不等于持久存储；保存后重启仍需保留的内容使用 persist。
Last updated on