RuleGems

English | 中文
Discord | QQ频道

一个用“宝石收集”来流转玩家权限的轻量插件，面向 Spigot/Paper 多版本。

定位

RuleGems 用"宝石收集"承载权限流转：权限不是管理员在后台点出来的，而是玩家在世界里 拿到、持有、兑换出来的一件实物。宝石可以被交易、被抢、被放置展示，权限随之流动。

架构上保持 gem-centric：一切都围绕"宝石实例"展开——归属、撤销、限次都挂在具体那一颗上， 而不是抽象的 power 身份。这让"谁现在有这个权限"永远能追溯到一颗看得见的宝石。

不做什么（避免误装）：

• 不是权限管理插件，不替代 LuckPerms 一类的权限后端。
• 不把 power 做成一等身份：不提供跨宝石的统一撤销与统一计数（有需要会另立项目）。

安装

1. 将 JAR 放入 plugins 目录
2. 启动服务器自动生成配置
3. 在 config.yml 与 gems/、powers/、features/ 目录配置中按需调整

本次框架接入的升级

停服后备份旧 jar 和完整 RuleGems 数据目录（包括 data/、lang/；SQLite 自定义路径也要备份）， 只替换部署 jar，再正常启动。不要用插件热加载工具替换本次含包重定位的更新。 不必删配置或重建宝石：本次未修改宝石 UUID、次数、权限及 YAML/SQLite 存储格式； 默认值合并只补缺失项；备份使用独立文件名避免覆盖。限次命令冷却仍按原设计在重启后清空，不会自动补满次数；撤销规则冷却和转账待核账保护持久化保留。

启动后运行 /rg doctor，检查宝石数量、归属、委任和剩余次数，再小额核对银行收支； 修复配置后可用 /rg reload。语言版本 3 只替换已知的旧默认转账提示，自定义文案保持不变，请自行检查是否仍声称无条件退回次数。 回滚前先处理全部待核账操作；旧 jar 不认识新增的转账保护，直接降级会失去保护。停服恢复匹配的旧 jar 与数据备份时，还必须核对经济插件当前余额，恢复 RuleGems 文件不会撤销经济交易。 本轮修改与验收记录见 IMPROVE_PLAN；其中列出了仍需实服验证的项目。

开服与预设

• 开服流程、烟测清单与生产服建议见 server-ready-guide.md。
• 可复制玩法包位于 presets/，当前包含王权政治服预设 kingdom-power。
• 预设不会自动加载；复制到 plugins/RuleGems/ 对应目录后执行 /rg reload 和 /rg doctor。
• 如果使用 permission_groups 或阶梯组晋升，推荐安装 LuckPerms；Bukkit 默认后端没有持久权限组模型。

命令

• 所有 /rulegems ... 命令均可用别名 /rg ...（见 plugin.yml 的 aliases: [rg]）
• 玩家直接执行 /rulegems 或 /rg 会打开主 GUI；控制台无参数执行时显示帮助
• /rulegems place <gemId> [x|~ y|~ z|~] 将指定宝石实例放置到坐标；省略坐标时等同于 ~ ~ ~，使用当前位置
• /rulegems tp <gemId> 传送到指定宝石位置
• /rulegems revoke <玩家> 强制清理指定玩家的宝石权限与限次额度（管理员干预）。若启用了 inventory_grants 且玩家仍持有宝石，下一次背包重算时权限会再次授予。
• /rulegems revoke-power list 查看已配置的撤销规则
• /rulegems revoke-power <规则> <玩家> <权力> 使用指定撤销规则制衡玩家已兑换的宝石权力；默认需要 /rg revoke-power confirm 二次确认，可用 /rg revoke-power cancel 取消。
• /rulegems transfer-review list [页码] 查看待核账操作（无子命令时等同 list）
• /rulegems transfer-review resolve <操作UUID> <核账说明> 记录人工核账并解除该操作的重试保护；不修改余额或次数
• /rulegems reload 重载配置
• /rulegems rulers 查看当前权力持有者
• /rulegems gems 查看宝石状态
• /rulegems gui 打开 GUI 界面
• /rulegems scatter 收回所有宝石并随机散布；默认按宝石类型保留已有 UUID，同时重置持有者、权限与限次状态
• /rulegems redeem 主手持宝石时兑换单颗
• /rulegems redeemall 集齐所有种类后一次性兑换
• /rulegems history [页码] [玩家名] 分页查看宝石历史记录，可选过滤玩家
• /rulegems setaltar <gemKey> 在当前位置设置该宝石的祭坛坐标
• /rulegems removealtar <gemKey> 移除该宝石的祭坛坐标
• /rulegems appoint <权限集> <玩家> 任命玩家获得指定权限集
• /rulegems dismiss <权限集> <玩家> 撤销玩家的权限集任命
• /rulegems appointees [权限集] 查看被任命者列表

权限

• rulegems.admin 管理指令（默认 OP，包含以下两项核账权限）
• rulegems.transfer.review 查看待核账操作（默认 OP）
• rulegems.transfer.resolve 确认核账并解除保护（默认 OP；查看权限不会自动授予此权限）
• rulegems.redeem 兑换单颗（默认 true）
• rulegems.redeemall 兑换全部（默认 true）
• rulegems.rulers 查看当前持有者（默认 true）
• rulegems.gems 查看宝石列表（默认 true）
• rulegems.help 查看帮助信息（默认 true）
• rulegems.navigate 使用指南针导航到最近宝石（默认 false）
• rulegems.rule 在 RuleGate 启用时允许使用所有宝石权力（默认 false）
• rulegems.rule.<宝石key> 在 RuleGate 启用时只允许使用指定宝石权力（默认 false）
• rulegems.revoke 使用已配置的撤销宝石规则（默认 false）
• rulegems.revoke.admin 管理撤销宝石规则的预留权限（默认 OP）
• rulegems.appoint.<权限集> 任命其他玩家获得指定权限集

兼容性

• 服务器：Spigot / Paper 1.16+。当前版本未声明 Folia 支持；完成真实双区域并发验收前，请勿在 Folia 生产服部署。
• 可选依赖：LuckPerms / Vault（权限后端）、QuickShop-Hikari 6.2.0.11（商店保护适配）
• 如果检测到 QuickShop-Hikari 但买入、卖出或建店保护钩子无法完整注册，RuleGems 会拒绝启动，避免宝石在未受保护的交易路径中流转。

逻辑

该插件允许服务器定制不同种类的权力宝石，每一种可以有指定数量和指定的权限与指令（指令可以限制次数）。每颗宝石都是唯一的。每颗宝石都随时存在于服务器中，意味着它只能处于以下状态之一：被放置或处于线上玩家的背包中。 插件有五种应用宝石的模式：

1. inventory_grants
2. redeem_enabled
3. full_set_grants_all
4. place_redeem_enabled
5. hold_to_redeem_enabled

以上模式并不互斥，可以搭配组合。

inventory_grants

玩家破坏并获得宝石（自动放入背包）即可获得该宝石的权限与限次指令使用权。玩家下线/被杀死/或将宝石放置，这些特权自动消失。

限次指令与“最近持有者”绑定：

• 同一玩家再次持有同类宝石时会延续剩余次数（不重置）。
• 当宝石易主到新玩家时，上一任在该类型上的限次记录仅在其不再拥有任何同类实例时被清除（“最后一件才撤”）。

互斥：若玩家先获得宝石A，后获得与A相斥的宝石B，则B的特权不会触发，除非先放弃A（互斥仅在 inventory_grants 与 redeem 模式生效，redeem_all 忽略互斥）。

redeem_enabled

玩家主手持宝石执行 /rg redeem 可获得该宝石的权限与限次指令，同时该宝石会重新散落。

当他人之后兑换了“同一颗”宝石（按 UUID 区分）时，旧持有者仅在其不再拥有该类型的其他实例时才会被撤回该类型的权限与限次（“最后一件才撤”）。若玩家先兑换了宝石A，再尝试兑换与A相斥的宝石B，则兑换会被拒绝（互斥仅在 inventory_grants 与 redeem 生效）。

full_set_grants_all

当玩家集齐全部“种类”宝石在背包中（每个种类至少 1 件即可，插件支持每类宝石 count > 1 同时存在），使用 /rg redeemall 将获得全部宝石的权限与指令（忽略互斥）以及 redeem_all 的额外特权。直到下次另一位玩家成功 redeemall，旧的 full set 持有者才会被清理全部特权（含额外特权）。

特性与配置要点

• 每颗宝石唯一：每件宝石有独立 UUID（实例级归属），可通过 /rulegems place <gemId> ... 精确放置。
• 重新散布会按 gem key 与 count 复用已有 UUID：数量增加时只补新 UUID，数量减少或删除类型时淘汰多余 UUID；位置、持有者、权限和限次额度仍会重置。
• 帮助链接：links.documentation / links.discord / links.qq 会显示在 /rg help 页脚与插件启动日志中。官方文档默认指向 https://github.com/CubeX-MC/RuleGems；升级时仅旧官方默认地址会自动迁移，服主自定义地址保持不变。
• 内置宝石与 power 示例只是初始模板；已有 gems/、powers/ 文件不会在 reload 时自动补回被删除的示例定义，删除不用的默认节点后会保持停用。
• 每类宝石数量：gems.<key>.count: <int>，散落与补齐按 count 生成；“集齐种类”判定为每个 key 至少 1 件。
• 互斥：gems.<key>.mutual_exclusive: [otherKey, ...]；仅在 inventory_grants 与 redeem 生效，redeem_all 忽略互斥。
• 限次指令：gems.<key>.command_allows 支持映射与列表两种写法：
  • 映射：command_allows.<label>: <uses>（如 fly: 3）
  • 列表：- { commands: "/fly"|[...], time_limit: <uses> }
  • 特殊值：time_limit: -1 表示无限次（使用不扣减）；redeem_all.command_allows 采用相同语法，额度记录在虚拟 key ALL 下。
  • 执行前缀：console: 由后台执行，player: 由玩家本人执行但不提权，player-op: 会在 allow_op_escalation: true 时临时提权。
  • 同一个指令 label 可在不同来源配置不同效果；执行时会按来源（持有实例、兑换实例、任命、redeem_all）选择对应的 execute 与冷却，并扣减同一来源的剩余次数。
• 持有与扣减：
  • 开启 inventory_grants 时：执行限次指令要求当前持有对应类型宝石，并按该类型额度扣减；
  • redeem_all 额外限次不要求持有，对应 key 始终为 ALL。
• 发放与撤回（按类型计数）：
  • 某玩家对某类型从 0→1 件时：发放该类型权限/组，并初始化限次额度（若已存在额度记录则延续剩余，不重置）。
  • 从 1→0 件时：撤回该类型权限/组，并删除该类型限次额度记录。
• redeem_all 额外特权：根级 redeem_all 节支持：
  • broadcast/titles/sound（已从旧 titles.redeem_all 扁平化）
  • permissions: redeemall 成功时的额外权限
  • permission_groups: redeemall 成功时授予的权限组列表
  • command_allows: redeemall 成功时的额外限次指令（语法同上）
• 阶梯式组晋升：根级 gem_collect_thresholds 可按“已兑换不同宝石类型数”授予权限组，例如 2: noble、4: lord；跌破阈值时会撤销对应组。
• 兑换前置要求：在单个宝石配置中添加 redeem_requirements 可提高危险权力门槛：
  • requires_held: 兑换时必须持有指定 gem key，不消耗，支持 { gem, amount }；
  • requires_redeemed: 必须已经兑换过指定 gem key，支持 { gem, amount }；
  • consumes: 兑换成功且兑换事件未取消后，消耗并重新散落指定 gem key，支持 { gem, amount }；
  • any_of: 配置多套等价 recipe，按顺序使用第一套满足的配方；
  • requires_any / requires_count + requires_count_from: 旧式多选一或至少 N 项条件；
  • allow_redeem_all: 默认 false，避免 /rg redeemall 绕过前置要求。
• 配置升级：启动或 reload 检测到 template、根节点隐式 power、vault_group / vault_groups / permission_group 或旧 requirement 写法时，会先备份到 backups/config-optimization-<唯一标识>/，再以粗兼容读取并输出 warning。建议手动迁移到 base、permission_groups 和 recipe/ingredient 写法；未来版本可能移除这些兼容。
• 权限后端按 LuckPerms → Vault → Bukkit 自动选择；权限组的授予 / 撤销通过当前后端执行。
• 存储：storage.type: yaml 使用默认 data/gems.yml 数据文件，并维护最后一次成功写入的 data/gems.yml.bak；storage.type: sqlite 使用 storage.sqlite.file 指定的 SQLite 数据库文件。SQLite 会保留现有数据结构，并在空库首次启动时从 data/gems.yml 导入。损坏或无法读取的数据不会被当成空白新服，也不会触发新 UUID 生成；启动会失败，重载则保留当前运行状态。同步保存失败时会尝试写入 data/recovery/gems-emergency-<时间戳>.yml，并在 /rg doctor 中报告。
• 经济转账：内置 transfer: 仍默认关闭（economy.transfer_directives_enabled: false）。同一经济提供方内串行扣款、入账；仅明确的入账失败才尝试补偿退款。成功转账后的后续命令失败、异常、空响应或退款失败会保留次数消耗并进入冷却，同时冻结同一玩家/来源的重试。保护写入 data/transfer-operations.yml，重载、重启不会绕过。Vault 仍不提供跨账户原子事务或自动崩溃回滚。
• 账户路由：支持玩家名、UUID / uuid:<UUID>、name:<账户名>（Vault 字符串账户）和 bank:<银行名>（需提供方支持）。普通名字优先在线/缓存 UUID，然后已有 Vault 命名账户，最后尝试可信玩家解析；不再枚举全部离线玩家。虚拟账户可明确写 name:cubex_bank，但实际到账行为仍须在所用经济插件上小额验证。
• 安装方式不变：RuleGems 仍可独立安装，无需额外安装 CubeXLib；本次更新需停服替换 jar。
• 重载：先通过功能数据保存门禁并同步保存宝石数据，再分阶段校验配置、语言和存储，失败会报告阶段并停止后续步骤；校验失败不会发布新配置。重载会关闭 RuleGems 菜单，保留限次命令执行器及其运行中冷却。外部插件或世界操作的异常不属于跨组件原子回滚，需按控制台阶段处理。
• 权力门控：features/rule.yml 默认关闭。启用后可用 rulegems.rule 授权所有宝石权力，或用 rulegems.rule.<宝石key> 只授权单个宝石；这适合测试阶段只让可信玩家实际获得 power。
• 额外兑换方式：
  • grant_policy.place_redeem_enabled: true 启用祭坛放置兑换（配合 /rulegems setaltar）
  • grant_policy.hold_to_redeem_enabled: true 启用长按右键兑换（hold_to_redeem 配置）

转账核账与数据故障处理

1. 用 /rg transfer-review list 查看操作 UUID、玩家 UUID、来源命令、状态与实际替换后的转账参数；控制台日志也会记录操作 UUID。
2. 对照经济提供方日志和双方余额，人工判断是否已扣款、到账或补偿。必要的财务修正由管理员在经济系统中完成，RuleGems 不会自动重放。
3. 确认结果后执行 /rg transfer-review resolve <UUID> <核账说明>。它先确认额度可保存，再将说明存入 data/transfer-reviews/，最后解除保护；它不会补钱或补次数。已有冷却仍然生效。
4. 日志或额度保存失败时，尚未开始的转账不会执行；已执行的操作保留保护。磁盘恢复后先核账，不要直接删日志文件来恢复使用。

features/rule.yml、撤销配置和功能数据读取失败会中止加载，不能默认为“关闭门控/没有冷却”。 data/appoints.yml、data/revokes.yml 沿用旧格式；任命修改和撤销冷却先保存再生效，保存失败不会提示成功。 历史分页按页流式读取，完整查询仍需扫描日志计数。转账为持久化保护增加了同步磁盘写入；本轮单测不代表真实大服 TPS 或第三方经济延迟的性能认证。 第三方权限/经济插件热替换不在支持范围内，升级时应停服。

限次命令参数约束

command_allows 的列表项支持 args 和可选的 usage，适用于宝石、委任及 redeem_all 的命令。 例如在主人的权力模板中配置 /cxfine <玩家> <金额>：

command_allows:
  - command: /cxfine
    usage: '/cxfine <玩家> <金额>'
    args:
      arg1: {type: string, required: true, suggestions: online_players}
      arg2:
        type: number
        min: 0.01
        max: 10000
        suggestions: [50, 100, 500, 1000, 5000, 10000]
    execute:
      - 'transfer:%arg1% name:cubex_bank %arg2%'
    time_limit: 5
    cooldown: 7200

委任模板将 arg2.max 改为 500、time_limit 改为 3；两者均为 120 分钟冷却。 约束跟随实际使用的权力来源，与该来源的次数和冷却一起生效。 time_limit 是使用额度，不会随冷却结束自动恢复；此功能不改变原有额度和冷却生命周期。

配置	行为
args.arg1、args.arg2…	按位置校验对应输入；未配置的参数和额外参数不受限制
type: string	默认类型，只检查必填，不检查玩家是否存在
type: number	普通十进制数，如 25、0.01；拒绝 NaN、Infinity、指数、十六进制和单位后缀，最多 128 字符
type: integer	整数字符串，如 25；不接受 25.0
required: true	默认必填；设为 false 时缺省跳过，提供值时仍校验
min / max	可分别省略，包含边界，仅适用于数值类型；超限拒绝，不截断金额
suggestions: online_players	仅用于 string，补全当前在线且发送者通过 Bukkit canSee 可见的玩家名
suggestions: [50, 100, 500]	固定候选，按配置顺序去重；数值候选按本参数的类型和 min/max 过滤
usage	参数错误时显示的用法，按普通文本渲染；省略时显示命令名

校验在占位符替换、整条执行链、次数扣减和冷却设置之前完成；失败只提示原因及用法，不执行任何动作。 支持 console:、player:、player-op: 和 transfer:，不限于转账。规则格式错误（例如未知类型、 max 拼错、最小值大于最大值）会记录日志并阻止该命令执行，不会忽略错误约束继续放行。 不配置 args 时保持旧行为；语言文件会自动合并新增提示，不覆盖已有翻译。

补全按已输入的前缀匹配（玩家名不区分大小写），每次最多返回 50 项。上例无需改候选列表， 委任来源的 max: 500 会自动排除 1000、5000、10000。补全使用当前可执行的权力来源， 没有额度或权力已停用时不提供 RuleGems 候选；不会扣次数或触发冷却。 静态金额列表在配置加载时过滤，玩家名只读取在线列表，不遍历离线玩家、不查数据库或余额。

不写 suggestions 时不新增参数补全；suggestions: [] 表示该参数不提供候选。 自定义代理和原始命令的 Bukkit 补全事件使用同一套规则：显式配置的候选会替换原候选（即使为空）， 未配置的参数保留原插件补全，不自动继承 execute 中其他命令的补全。 补全只是提示，不是白名单：仍可手动输入未列出的合法金额和离线玩家名，执行时照常校验。 拼错补全来源或填写错误的数据结构也会记录配置错误并阻止该命令执行。

金额应保持必填。 校验对象是玩家输入，不校验 %argN|默认值% 中的配置默认值， 也不限制模板写死的金额或执行链累计转账总额。此功能不是经济账户的全局限额。 上例的 transfer: 仍需 Vault、经济插件及显式启用 economy.transfer_directives_enabled； 它仍是有补偿回滚风险的转账，不是原子事务。转账应放在成功广播之前。

升级后可编辑 powers 配置并 /rg reload 生效，已有次数不会因此自动补满。 回退不支持 args 的旧 jar 前，先停用依赖这些约束的动态金额命令，否则旧版本会忽略金额限制。 若回退至支持 args 但尚不支持 suggestions 的版本，先删除 suggestions 字段，否则严格解析会阻止命令执行。

宝石表现模式

config.yml 的 gem_presentation.mode 支持两种后端：

• block（默认）：使用传统实体方块，兼容性最高。
• proximity_display：逻辑位置保持为空气，仅在玩家进入 reveal_range 后显示宝石；离开 hide_range 后隐藏，以双阈值避免边界闪烁。左键显示实体可拾取宝石。

修改模式后执行 /rg reload 即可原地切换，不需要重新散布，宝石坐标与 UUID 均不改变；切回 block 会直接恢复传统方块。Minecraft 1.19.4+ 使用对玩家隐藏的 BlockDisplay，旧版本使用非持久化 ArmorStand 兼容后端。旧后端只能按附近是否有人决定实体是否存在，不能提供严格的逐玩家隐藏，因此对实体雷达类作弊的抑制较弱。

宝石逃逸

gem_escape.enabled 默认关闭。启用后，插件按 min_interval 到 max_interval 的全局轮次稳定流转宝石；每轮最多选择一颗已放置且超过 minimum_unmoved_duration 未移动的宝石，附近宝石越密集，按 selection.cluster_* 权重越容易被选中。

逃逸会先在同一世界的距离环带内寻找安全位置，首轮范围由 local_move.min_distance / max_distance 决定；失败后按 distance_growth 向外扩展，并在 retry_delay 后重试。只有新位置验证成功后才切换位置，UUID、宝石类型和现有实例状态保持不变。连续失败达到可配置的 local_move.max_failed_rounds（默认 3 轮），或连续局部逃逸达到 max_local_escapes_without_pickup 仍无人拾取时，只对该颗宝石执行一次 random_place_range 内的全局重新散落，不会重置其他宝石。若 broadcast 开启，全局重新散落会明确广播先前情报已失效；指南针则继续按同一 UUID 跟踪新位置。

升级旧配置无需改名：min_interval / max_interval 键仍然有效，但语义从“每颗宝石各自的逃逸延迟”改为“全服两次逃逸轮次的间隔”。升级后建议重新评估这两个值；需要回滚时可先关闭 gem_escape.enabled。

扩展功能

宝石导航 (Navigate)

持有 rulegems.navigate 权限的玩家可以使用指南针右键导航到最近的宝石位置。

• 配置文件：features/navigate.yml
• 启用后，玩家右键指南针会显示最近已放置宝石的方向和距离
• 指南针只接收随玩家位置刷新的相对方位点，不会向客户端发送宝石的绝对坐标；宝石被拾取或目标失效时会立即清除导航

撤销宝石 (Revoke Power)

features/revoke.yml 默认关闭。启用后，服主可以配置某类宝石用于撤销目标玩家已经兑换的指定宝石权力，适合做“审判”“制衡”类玩法。

enabled: true
confirm_timeout: 30
rules:
  judgment:
    display_name: "&c审判宝石"
    trigger_gem: judgment
    target_powers:
      - territory
      - jailer
    require_held: true
    consume_gem: false
    cooldown: 3600
    confirm_required: true
    broadcast: true
    allow_offline_target: true

• trigger_gem 是发起撤销所需的宝石 key。
• target_powers 目前按已兑换的宝石 key 撤销对应权力。
• require_held 要求发起者当前持有撤销宝石；consume_gem 成功后会消耗并重新散落该宝石。
• cooldown 是每名玩家每条规则的冷却秒数，记录在 data/revokes.yml。
• confirm_required 会要求二次确认，确认内容包含目标、权力、是否消耗宝石和是否广播。
• allow_offline_target 允许对离线目标清理已记录的兑换权力。

委任系统 (Appoint)

允许统治者将部分权限委任给其他玩家，形成权力树结构。

核心概念

• 权限集 (Permission Set)：预定义的一组权限、限次命令和可选的继承关系
• 任命 (Appoint)：统治者将权限集授予其他玩家
• 级联撤销 (Cascade Revoke)：当任命者失去权限时，其任命的所有人也会被撤销（可配置）
• 条件系统 (Conditions)：权限集可设置生效条件（时间/世界），仅在满足条件时生效

配置文件

features/appoint.yml 只配置功能开关与刷新间隔：

enabled: true
cascade_revoke: true
condition_refresh_interval: 30

职位来自已加载的宝石 power 的 appoints，不读取 features/appoint.yml.permission_sets。 例如在 powers/ 文件中定义以下模板，并让宝石通过 power: ruler 引用：

ruler:
  appoints:
    knight:
      display_name: "<gold>骑士"
      max_count: 3
      on_appoint:
        - "console:broadcast %player% 任命 %target% 为骑士"
      power:
        permissions: ["example.permission1"]
        command_allows:
          - command: "/kit warrior"
            time_limit: 3
        conditions:
          time: {enabled: true, type: day}
          worlds: {enabled: true, mode: whitelist, list: [world]}

嵌套职位继续放在该职位 power.appoints 下，相应委任权限由插件授予。任命记录位于 data/appoints.yml，首次升级会验证并迁移旧的 features/appoint_data.yml；迁移失败不会按空数据启动。

条件系统

权限集可设置生效条件，当条件不满足时，该权限集的权限和限次命令暂时失效：

时间条件 (conditions.time)：

• always：始终生效（默认）
• day：仅白天生效（0-12000 tick）
• night：仅夜晚生效（12000-24000 tick）
• custom：自定义时间范围（通过 from 和 to 指定）

世界条件 (conditions.worlds)：

• whitelist：仅在指定世界生效
• blacklist：在指定世界之外生效

条件刷新时机：

1. 玩家切换世界时立即刷新
2. 根据 condition_refresh_interval 定时刷新（用于时间条件）

权力树示例

国王（宝石持有者，拥有 rulegems.appoint.duke）
└── 公爵（被任命，通过嵌套 power.appoints 获得 rulegems.appoint.knight）
    └── 骑士（被任命）

当国王失去宝石 → 公爵被级联撤销 → 骑士也被级联撤销

GUI 支持

在统治者列表 GUI 中点击任意统治者可查看其任命的所有玩家及详细信息。

构建

.\gradlew.bat :RuleGems:build      # 编译 + 测试 + 部署 jar
.\gradlew.bat :RuleGems:test       # 只跑测试
.\gradlew.bat :RuleGems:jarGate    # 部署 jar 门禁

Windows 必须用 PowerShell 跑 .\gradlew.bat（仓库路径含空格）。 产物在 RuleGems/build/libs/；*-plain.jar 不要部署。

已知边界

• 升级策略为"备份优先 + 粗兼容 + 明确警告"：不提供复杂的自动配置迁移器， 升级前请先备份 config.yml、gems/、powers/、features/。
• 部分旧配置写法仍被粗兼容接受并给出警告，后续大版本会移除。

相关文档

• 待办与路线：仓库根 PLAN.md
• 服主上手：docs/server-ready-guide.md
• 版本记录：CHANGELOG.md