RuleGems

English | 中文
Discord | QQ频道

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

安装

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

开服与预设

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

命令

• 所有 /rulegems ... 命令均可用别名 /rg ...（见 plugin.yml 的 aliases: [rg]）
• /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 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.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 页脚与插件启动日志中。
• 内置宝石与 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-<yyyyMMdd-HHmmss>/，再以粗兼容读取并输出 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 禁用。Vault 只提供分开的扣款与入账调用，并不保证跨账户事务；生产服应保持关闭，优先在 command_allows 中调用经济插件自己的转账命令。若明确启用，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 配置）

宝石表现模式

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  # 条件刷新间隔（秒），设为0禁用定时刷新

permission_sets:
  knight:  # 权限集 key，对应权限节点 rulegems.appoint.knight
    display_name: "&6骑士"
    description: "拥有基础战斗相关权限"
    max_appointments: 3  # 每个任命者最多任命人数，-1为无限
    permissions:
      - example.permission1
    command_allows:  # 限次命令（语法同宝石；额度按该任命来源独立保存）
      - command: "/kit warrior"
        time_limit: 3
    delegate_permissions:  # 可再次委任的权限
      - rulegems.appoint.squire
    inherits:  # 继承其他权限集
      - squire
    on_appoint:  # 任命时执行的命令
      - "console: broadcast %player% 任命 %target% 为骑士"
    on_revoke:  # 撤销时执行的命令
      - "console: broadcast %target% 的骑士头衔被撤销"
    
    # 条件配置（可选）
    conditions:
      time:
        enabled: true
        type: day  # always / day / night / custom
        from: 0    # 自定义时间范围（仅type=custom时生效）
        to: 12000  # Minecraft时间: 0=日出, 6000=正午, 12000=日落
      worlds:
        enabled: true
        mode: whitelist  # whitelist / blacklist
        list:
          - world
          - world_nether

条件系统

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

时间条件 (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）
└── 公爵（被任命，通过 delegate_permissions 拥有 rulegems.appoint.knight）
    └── 骑士（被任命）

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

GUI 支持

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