iPlugin | 持久数据

范围与键名

persist 省略 by 时默认操作全局数据。 个人数据明确填写 by player name；这里的玩家名称表达式属于通用 Kether，语法见 TabooLib Kether 列表。

ctx 的持久前缀区分大小写，应写小写的 player@、global@。persist 会自动加前缀，传入的键名不要再带前缀。保存值会转成文字；不要期待 List、Map 或物品对象保存后仍保留原类型。保存空文字会删除对应存储项。

在已有图标的动作中保存：

action: "persist set theme to green by player name icons update"

在图标名称或 Lore 中读取：

lore:
  - '&7主题：{{ctx get player@theme}}'

如果仍在活动菜单内，也可写 ctx set 'player@theme' to green；普通键 theme 则只是当前会话状态。持久设置可在下次打开菜单时重新载入，不需要在打开事件中无条件重设。

persist 操作键 [to 值] [by 处理对象]。参数按此顺序写：先值，后处理对象。

字段	类型	必填	省略行为	说明
操作	固定名称	是	无法解析	下表列出全部操作
键	可求值文字	是	无法解析	不带 `player@` / `global@`
`to`（`of`）后的值	可求值参数	`inc` / `dec` 必填，`set` 应填写	`set` 不写入；增减报无有效值	增减也用 `to` / `of`，不能用 `by` 传增量
`by`（`handler`）后的处理对象	可求值文字	否	全局数据	`global` 不区分大小写；其他文字作为在线玩家名查找

语句	操作别名	返回或可见效果
`persist get theme by player name`	—	返回保存的文字，缺失时为空
`persist set theme to green by player name`	—	保存值，返回保存后的值
`persist del theme by player name`	`delete`、`remove`	从存储缓存与数据库删除，返回为空
`persist inc visits to 1 by global`	`increase`、`+=`	原值不存在时从 0 起算，返回增加后的存储值
`persist dec visits to 1 by global`	`decrease`、`-=`	原值不存在时从 0 起算，返回减少后的存储值

需要有效的数据存储配置；后端见主配置。指定玩家名必须在线，找不到名字时会回退操作执行者的数据，不是离线玩家读写接口。不要用拼错或离线名字测试另一个人的数据。

ctx set、ctx inc、ctx dec 遇到持久前缀时同时写入存储，并更新当前会话及当前脚本变量。
persist 直接操作所选存储；写入后会合并更新当前活动会话中的持久数据。读取其他玩家的数据不等于把其他玩家的全部数据载入本会话。
ctx update 重新合并存储值，但不重绘图标、不清理已经删除的旧键。
ctx del player@theme / ctx del global@season 只移除当前缓存，没有删除数据库记录。 永久删除应使用 persist del。

永久删除并立即从当前界面隐藏时，可以顺序执行：

action: |-
  persist del theme by player name
  ctx del player@theme
  icons update

第一行删存储，第二行清理当前会话与脚本仍保留的旧值，第三行更新文字。其他已打开的会话可能仍持有旧值，重新打开后才建立新的数据视图。

安装并启用 PlaceholderAPI 后，可使用：

占位符	内容
`%invero_data_player_theme%`	当前玩家的 `theme`
`%invero_data_global_season%`	全局的 `season`

菜单内部不必为了读取这些数据额外套 PlaceholderAPI，直接使用 ctx 或 persist 的内联求值即可。