安装与快速上手
安装与快速上手
SnowyGems 是一个宝石镶嵌插件：玩家把「宝石」镶嵌到装备上，装备获得属性、附魔或常驻 BUFF；宝石还能带主动技能，右键、攻击、挖矿时触发。
环境要求
| 项目 | 要求 |
|---|---|
| Java | 插件编译目标为 Java 21；同时满足所用服务端自身的 Java 要求 |
| 服务端 | 使用 Bukkit API，优先在你的 Paper 服务端测试 |
| 版本 | 源码提供现代注册表与旧名兼容逻辑，当前编译依赖为 26.1 API；具体版本须实服验证 |
| Folia | 当前没有完整的实体 / 区域调度适配验证，不承诺支持 |
| 依赖 | 无硬依赖 |
| 可选 | Vault + 经济插件（金币收支）、PlayerPoints（点券后端） |
插件启动时读取服务端注册表。不存在或被模块禁用的内容会在自检中提示，相关奖励无法生效。注册表探测不能替代不同服务端版本的运行验证。详见多版本兼容。
安装
- 把
SnowyGems.jar放进plugins/ - 启动服务器，插件会在
plugins/SnowyGems/下释放默认配置 - 控制台出现启动横幅与加载统计后即安装完成
从旧版本升级时的配置自检
0.0.4 起，插件启动和 /sgem reload 后会检查 config.yml、三种语言文件、菜单、宝石和符文配方文件。缺失文件会自动以不覆盖模式重新释放；已有文件和自定义值不会被替换。config.yml 与语言配置还启用了 TabooLib 的迁移机制，新版本新增的节点会尽量补入旧文件。
如果控制台仍列出缺失文件，请检查文件权限或部署脚本是否在启动后删除了它，然后恢复该文件并再次执行 /sgem reload。菜单布局和已有宝石文件中的新条目不会强行合并，升级前应备份并手动对照示例。
目录结构
plugins/SnowyGems/
├── config.yml # 全局设置：调试、点券后端、版本兼容模块
├── lang/ # config.yml 的 Lang 选择的语言文件
│ ├── zh_CN.yml # 简体中文
│ ├── zh_TW.yml # 繁体中文
│ └── en_US.yml # 英文
├── gems/ # 宝石定义
│ ├── AttributeGem.yml # 属性类
│ ├── EnchantGem.yml # 附魔类
│ ├── FunctionGem.yml # 功能类（无限耐久、隐藏粉尘等）
│ ├── PotionGem.yml # BUFF 药水类
│ ├── PlayerGem.yml # 玩家类（兑换券、饮品）
│ ├── ModernGem.yml # 新版本内容示例
│ └── RuneGem.yml # 符文、符文碎片与分解券
├── skills/ # 技能与 BUFF 定义
│ ├── DefaultSkills.yml # 主动技能示例
│ ├── DefaultBuffs.yml # 常驻 BUFF 定义
│ ├── ExampleSkills.yml # 进阶技能示例（条件/概率/连招）
│ └── ModernBuffs.yml # 新版本 BUFF 示例
├── gui/ # 工作台菜单布局
│ ├── gui.yml
│ └── rune.yml
├── MarkedBlocks.yml # /sgem mark 保存的实体镶嵌台坐标
└── data/
└── points.yml # 内置点券账户（用 PlayerPoints 时不使用）
gems/ 与 skills/ 下的文件名可以任意起，插件会加载目录第一层的 .yml 与 .yaml。gems/ 的文件名会成为 /sgem view 里的分类名。
命令
主命令 /sgem，基础权限 snowygems.command。
snowygems.user（普通玩家常用指令，默认所有人可用）与 snowygems.admin（管理指令 + 包含全部 user 权限，默认 OP）。大多数服务器不需要动权限插件。详见权限节点。普通玩家指令（snowygems.user，默认可用）：
| 命令 | 作用 | 权限 |
|---|---|---|
/sgem embed | 打开通用宝石镶嵌台 | snowygems.embed |
/sgem inspect | 只读查看手持装备上已镶嵌的宝石 | snowygems.inspect |
/sgem dismantle | 拆卸宝石（扣费 + 损坏概率） | snowygems.dismantle |
/sgem use | 直接使用手持的兑换券/饮品类宝石 | snowygems.use |
/sgem rune | 消耗碎片合成、升级或回收符文，详见符文锻造 | snowygems.rune |
/sgem open <菜单名> | 打开 gui/ 里定义的工作台菜单 | snowygems.open |
管理指令（snowygems.admin，默认 OP）：
| 命令 | 作用 | 权限 |
|---|---|---|
/sgem view | 分类浏览全部宝石，点击免费领取 | snowygems.view |
/sgem give <玩家> <宝石ID> [数量] | 发放宝石 | snowygems.give |
/sgem mark | 标记视线内白名单方块为通用镶嵌台 | snowygems.mark |
/sgem compat [all] | 查看当前服务端支持哪些版本能力 | snowygems.compat |
/sgem skills [关键字] | 列出可用技能函数与用法 | snowygems.skills |
/sgem triggers | 列出可用触发标记 | snowygems.triggers |
/sgem debug [tag,...] | 开关调试输出，可只看指定 tag | snowygems.debug |
/sgem reload | 重载全部配置 | snowygems.reload |
/sgem view 是管理指令——那个界面可以无限量免费领取任何宝石。名字看着无害，别发给玩家。第一次配置：建议顺序
先跑 /sgem compat
查看当前服务端实际支持的属性、附魔、效果和材质。ModernGem.yml 中使用缺失内容的要求与奖励无法使用；配置自检会给出明细。
打开 /sgem embed 试一次镶嵌
用 /sgem give 你自己 生命宝石 拿一颗，配一件盔甲，走一遍完整流程，确认插件工作正常。
选择语言并修改文案
在 config.yml 设置 Lang: zh_CN，修改 lang/zh_CN.yml。切换语言后执行 /sgem reload。宝石名称、菜单标题、技能文本仍在对应配置中，见语言配置。
体验符文镶嵌台
执行 /sgem open 符文镶嵌台，放入一件装备与对应颜色的符文，查看确认按钮上的预检结果。默认符文与分解流程见菜单配置。
照抄示例改宝石
gems/ 下的文件都带完整中文注释，从最接近你需求的那颗开始复制修改。字段含义见宝石配置。
遇到不生效就开 debug
先执行 /sgem debug Reward,GemManager 选择日志范围，再用 /sgem debug 将总开关切换到开启，观察每条奖励的执行结果。见排错。
config.yml 速览
# 统一使用的语言：zh_CN / zh_TW / en_US
Lang: zh_CN
# 调试模式：把插件全部交互逻辑输出到控制台
Debug: false
# 调试 tag 白名单，留空表示全部
# 可用：Registry Compat Command Menu Workbench Embed GUI GemUse
# Protect GemManager ItemFactory Reward Skill SkillExec Buff
# Points Money PlayerPoints Update Dismantle
DebugTags: []
# 点券后端：Internal（内置 data/points.yml）或 PlayerPoints
Points:
Provider: Internal
# 拆卸宝石的费用与损坏概率
Dismantle:
Cost:
Enabled: true
Type: money # money 金币 / points 点券 / exp 经验等级
Amount: 100
BreakChance: 20 # 0~100，0 = 拆下必返还
# 版本更新检测与公告（服务器启动完成后静默检测一次）
UpdateChecker:
Enabled: true
Announcement: true
AdminPermission: snowygems.admin
NotifyAdminOnJoin: true
Timeout: 8
Compat:
# 配置用到当前版本不存在的内容时如何处理
# skip 跳过并记日志（默认）
# warn 用警告级别输出，排查配置时用
# strict 用醒目错误级别输出，上线前自检用
OnMissingFeature: skip
# 启动时是否打印版本能力简报
ReportOnStartup: true
# 按版本自动启停的功能模块，auto = 由服务端注册表决定
Modules:
Mace: auto # 1.21+ 锤及其专属附魔
Spear: auto # 1.21.11+ 矛分类及其专属附魔「突进」
CopperEquipment: auto # 1.21.9+ 铜装备
ModernAttributes: auto # 1.20.5+ scale / 交互距离 等
MiningAttributes: auto # 1.21.2+ 挖掘与移动类属性
TrialEffects: auto # 1.21+ 试炼密室药水效果
WaypointAttributes: auto # 26.x 路径点属性
三种 OnMissingFeature 级别都不会阻止插件启动。宝石配置通常很大，一条写错就拒绝启动会让整个服进不去，代价远高于收益；strict 的意义是「绝对不会被忽略的醒目报错」。