SnowyGems
安装与快速上手
SnowyGems 的安装步骤、目录结构、命令与权限，以及第一次配置需要知道的事。
安装与快速上手
SnowyGems 是一个宝石镶嵌插件：玩家把「宝石」镶嵌到装备上，装备获得属性、附魔或常驻 BUFF；宝石还能带主动技能，右键、攻击、挖矿时触发。
环境要求
| 项目 | 要求 |
|---|---|
| 服务端 | Paper / Spigot 及其衍生（Leaves、Purpur 等），支持 Folia |
| 版本 | 1.21.4 及以上，含 1.21.5 ~ 1.21.11、26.x |
| 依赖 | 无硬依赖 |
| 可选 | Vault（金币奖励）、PlayerPoints（点券后端） |
插件不按版本号写死功能，而是启动时读服务端注册表。高版本新增的属性、附魔、药水效果、物品会自动可用；低版本没有的内容会跳过并在控制台说明，不影响其他宝石。详见多版本兼容。
安装
- 把
SnowyGems-1.0-Dev.jar放进plugins/ - 启动服务器，插件会在
plugins/SnowyGems/下释放默认配置 - 控制台出现启动横幅与加载统计后即安装完成
目录结构
plugins/SnowyGems/
├── config.yml # 全局设置：调试、点券后端、版本兼容模块
├── lang.yml # 玩家能看到的所有文字（唯一修改入口）
├── gems/ # 宝石定义
│ ├── AttributeGem.yml # 属性类
│ ├── EnchantGem.yml # 附魔类
│ ├── FunctionGem.yml # 功能类（无限耐久、隐藏粉尘等）
│ ├── PotionGem.yml # BUFF 药水类
│ ├── PlayerGem.yml # 玩家类（兑换券、饮品）
│ └── ModernGem.yml # 新版本内容示例（矛/铜装/锤/新属性）
├── skills/ # 技能与 BUFF 定义
│ ├── DefaultSkills.yml # 主动技能示例
│ ├── DefaultBuffs.yml # 常驻 BUFF 定义
│ ├── ExampleSkills.yml # 进阶技能示例（条件/概率/连招）
│ └── ModernBuffs.yml # 新版本 BUFF 示例
├── gui/ # 工作台菜单布局
│ ├── gui.yml
│ └── rune.yml
└── data/
└── points.yml # 内置点券账户（用 PlayerPoints 时不使用）
gems/ 与 skills/ 下的文件名可以任意起，插件会加载目录里所有 .yml。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 open <菜单名> | 打开 gui/ 里定义的工作台菜单 | snowygems.open |
管理指令（snowygems.admin，默认 OP）：
| 命令 | 作用 | 权限 |
|---|---|---|
/sgem view | 分类浏览全部宝石，点击免费领取 | snowygems.view |
/sgem give <玩家> <宝石ID> [数量] | 发放宝石 | snowygems.give |
/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
看清自己这个版本有什么、没有什么。比如 1.21.4 上没有矛（SPEAR）和铜装备，那么 ModernGem.yml 里相关宝石就会被跳过——这是正常的，不是报错。
打开 /sgem embed 试一次镶嵌
用 /sgem give 你自己 生命宝石 拿一颗，配一件盔甲，走一遍完整流程，确认插件工作正常。
改 lang.yml 而不是改代码
玩家能看到的每一句话都在 lang.yml 里。改完保存即生效，不需要重载。
照抄示例改宝石
gems/ 下的文件都带完整中文注释，从最接近你需求的那颗开始复制修改。字段含义见宝石配置。
遇到不生效就开 debug
/sgem debug Reward,GemManager 只看镶嵌相关日志，能直接看到每条 Rewards 的执行结果。见排错。
config.yml 速览
# 调试模式：把插件全部交互逻辑输出到控制台
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 的意义是「绝对不会被忽略的醒目报错」。