常见问题
界面与分类
分类菜单打不开或分类没有内容
检查 config.yml 中的 forge-menu：
- 确认菜单使用的分类 ID 已在
forge-menu中定义。 - 确认分类内填写的是图纸 ID，不是图纸显示名。
- 确认对应图纸配置已经正常加载。
- 检查分类 ID、图纸 ID 的大小写和空格，引用值必须与配置中的实际 ID 一致。
点击界面物品没有反应
插件的菜单、制作界面和返回操作由不同的界面状态处理。出现点击无反应时，依次检查：
- 当前打开的是否为 LyGalaxyForge 创建的界面。
- 对应 GUI 配置是否存在并已正常加载。
- 图纸引用的界面 ID 是否正确。
- 控制台是否出现 GUI 配置、物品解析或图纸读取异常。
- 是否有其他背包菜单插件拦截了点击事件。
如果只有某一个图纸无法操作，应优先检查该图纸配置，而不是全局菜单配置。
返回按钮无法回到上一级菜单
确认当前图纸是从正确的分类菜单打开，并检查对应 GUI 配置中的返回组件。插件内部区分菜单界面、锻造界面、制作中界面和返回操作，错误的界面引用可能导致返回目标不存在。
图纸获取与显示
玩家看不到图纸
玩家必须先拥有图纸。检查以下内容：
- 图纸 ID 是否正确。
- 图纸是否已被正常加载。
how-to-get-it设置的获取条件是否满足。- 分类菜单中填写的是否为图纸 ID。
- 玩家数据是否已从数据库正常读取。
可使用以下指令手动发放图纸进行测试：
text
/lgf give 玩家 图纸ID如果手动发放后可以显示，问题通常位于图纸获取条件或自动解锁流程。
满足条件后仍未解锁图纸
插件具有图纸解锁监听逻辑。检查：
how-to-get-it的条件内容是否正确。- 条件引用的物品、权限或变量能否正常解析。
- 玩家数据和数据库连接是否正常。
- 控制台是否出现条件计算或物品识别错误。
修改获取条件后，应重新触发对应的获取行为。已经执行过的行为不会因为配置改变而自动重新判定。
使用 /lgf give 后图纸仍未出现
确认指令中的最后一个参数是图纸 ID，而不是图纸名称或成品名称。同时检查目标玩家的数据是否正常加载，以及该图纸是否被分类菜单引用。
数据库不可用时，即使指令执行过程没有明显报错，玩家图纸数据也可能无法正常读取或持久化。
必需材料
图纸界面提示材料不足
检查图纸的 need-item 配置：
| 检查项 | 说明 |
|---|---|
| 物品库前缀 | 必须使用插件能够识别的物品来源前缀 |
| 物品 ID | 必须与对应物品库中的实际 ID 一致 |
| 数量公式 | 必须能够计算出有效数字 |
| 玩家物品 | 必须与配置要求的物品匹配 |
| 物品数量 | 实际数量必须达到公式计算后的需求量 |
材料数量支持公式，最终需求数量会向上取整。例如公式结果为 2.1 时，实际需要 3 个物品。
背包里有同名物品，但仍提示材料不足
插件按配置的物品来源和物品 ID 查找物品，不应只根据显示名称判断。两个显示名称相同的物品，仍可能具有不同的来源、NBT 或内部数据。
检查 need-item 使用的物品库前缀和物品 ID，并使用对应物品库实际生成的物品测试。
材料数量计算结果比预期多一个
need-item 的数量公式会向上取整。只要计算结果包含小数部分，就会取下一个整数。
如果不希望出现向上取整后的差异，应调整公式，使最终结果直接得到整数。
材料没有被正确识别
依次检查：
- 物品来源前缀是否正确。
- 物品 ID 是否存在。
- 物品是否经过其他插件修改。
- 物品 NBT 是否与原始物品一致。
- 当前服务端版本是否具有对应的 NMS 适配。
LyGalaxyForge 包含跨版本 NBT 处理。服务端版本不在现有 NMS 适配范围内时，依赖 NBT 的物品匹配可能无法正常工作。
可选材料
可选材料放不进去
确认材料匹配当前图纸的 optional-item，并检查：
| 配置项 | 检查内容 |
|---|---|
| 物品来源与 ID | 必须与放入的物品一致 |
max | 当前放入数量不能超过允许上限 |
mutex-group | 同一互斥组不能同时使用不同材料 |
如果材料属于互斥组，应先取出同组的其他材料，再放入当前材料。
两种可选材料不能同时放入
检查它们的 mutex-group。同一互斥组中的不同材料不能同时使用，这是正常限制，不是界面故障。
如需允许同时使用，应在图纸配置中调整互斥组，但不要让本应互斥的材料错误地使用不同分组。
可选材料效果没有应用
检查以下内容：
- 材料是否被插件识别为当前图纸的可选材料。
- 材料数量是否超过
max。 - 是否与其他材料发生
mutex-group冲突。 - 可选材料对应的条件或函数是否执行成功。
- 控制台是否出现表达式、物品或 NBT 处理异常。
插件提供 ForgeOptionalApplyEvent 供其他插件监听。若服务器安装了基于该事件开发的扩展，也应检查扩展插件是否影响了可选材料处理。
制作时间与加速
制作时间没有被权限缩短
检查 permission-upspeed 中的权限节点和 time-formula。玩家需要实际拥有配置中的权限，权限节点必须完全一致。
建议按以下顺序排查：
- 使用权限插件确认玩家实际拥有该节点。
- 检查权限节点是否存在多余空格或大小写差异。
- 检查
time-formula是否能计算出有效结果。 - 检查玩家是否同时匹配了多个加速配置。
- 重新打开图纸界面后再查看制作时间。
权限已经添加，但旧任务时间没有变化
制作任务可能已经按开始制作时的条件生成。权限或公式修改通常应在开始新的制作任务时重新验证，不能假定已经开始的任务会自动重新计算。
可使用一个新的制作任务测试权限加速是否生效。
制作时间公式报错
检查公式中的数字、括号、变量和函数调用。不要让公式返回空文本、非数字文本或无法转换的值。
如果公式使用 PlaceholderAPI 数据，还需要确认 PlaceholderAPI 已安装，并且相关变量能够为该玩家返回有效内容。
制作任务与结果
制作任务重启后丢失或无法读取
LyGalaxyForge 项目包含 MySQL 数据管理和数据库监听逻辑。涉及数据库存储的功能，必须安装 LyMySQLCore，并确保 LyMySQLCore 已成功连接数据库后才会生效。
排查时检查：
- LyMySQLCore 是否已安装并正常启用。
- 数据库地址、端口、库名和账号是否由 LyMySQLCore 正确配置。
- 控制台是否显示数据库连接成功。
- 玩家进入服务器时是否成功加载数据。
- 数据库连接中断后是否已经恢复。
数据库未连接时，图纸持有状态、锻造次数、制作任务等相关数据可能无法正常读取或保存。
数据库连接成功前可以正常使用吗
依赖 MySQL 数据的功能不会完整生效。必须先安装 LyMySQLCore，并确保它成功连接数据库，再测试玩家图纸、锻造次数和制作数据。
不要在数据库尚未连接时使用管理指令批量修改玩家数据，否则无法确认修改是否已经持久化。
制作完成后没有获得结果物品
检查：
- 图纸的结果物品配置是否能够正常解析。
- 结果物品使用的物品来源和 ID 是否存在。
- 玩家数据与制作任务是否正常读取。
- 控制台是否出现物品生成、NBT 或表达式异常。
- 是否有其他插件监听并修改了锻造结果。
插件提供 ForgeResultEvent 供其他插件监听。安装了相关扩展时，需要同时检查扩展插件的处理逻辑。
制作概率与预期不一致
项目包含增加、减少和直接设置锻造概率的函数。若图纸或可选材料同时调用多个概率函数，应检查它们的执行顺序以及最终概率值。
重点检查：
- 是否同时使用了增加概率和减少概率的逻辑。
- 是否有逻辑直接覆盖了之前计算的概率。
- 可选材料是否成功应用。
- 条件表达式是否进入了预期分支。
- 随机或权重结果是否被误认为固定结果。
词条与表达式
词条不生效
先执行：
text
/lgf entry-debug再检查 entry/ 目录中的方法名是否与图纸中使用的 {方法名} 一致。
同时检查：
- 词条配置是否已被正常加载。
- 方法名是否存在空格或大小写差异。
- 参数数量和参数类型是否正确。
- 方法返回值是否适用于当前配置位置。
- 控制台是否输出词条计算异常。
开启 entry-debug 后仍没有调试信息
确认当前操作确实触发了包含词条的图纸逻辑。仅打开调试功能不会主动执行词条。
如果只有某个词条没有输出，检查图纸中是否正确引用了对应方法，以及触发条件是否已经满足。
词条方法名相同但仍无法调用
方法引用必须与已注册的方法名一致。除名称外，还应检查：
- 方法是否已成功注册。
- 词条文件是否存在格式错误。
- 方法参数是否完整。
- 当前调用位置是否提供了所需的玩家或图纸上下文。
插件具有独立的词条方法注册机制。自定义词条扩展应通过项目提供的 API 注册，不能仅添加一个同名类文件。
条件判断结果与预期不一致
项目包含权限、包含、相等、开头匹配、结尾匹配、条件选择等词条方法。排查时先确认参与比较的数据类型和值。
常见问题包括：
- 数字被当作文本比较。
- PlaceholderAPI 返回了空文本。
- 字符串包含颜色代码或多余空格。
- 权限节点填写错误。
- 随机或权重方法每次都可能返回不同结果。
- 取整方法改变了原始小数。
可先使用 entry-debug 查看实际参与计算的内容。
PlaceholderAPI 内容没有被替换
项目具有 PlaceholderAPI 挂钩和 PAPI 词条方法。出现变量未替换时，检查：
- PlaceholderAPI 是否已安装并正常启用。
- 对应变量扩展是否已安装。
- 变量对当前玩家是否能返回内容。
- 变量是否写在支持 PlaceholderAPI 解析的位置。
- 返回内容是否符合后续公式要求的数据类型。
PlaceholderAPI 未安装时，仅影响依赖其解析的内容，不代表所有图纸功能都无法使用。
锻造次数
图纸次数变量不对
变量 %lgf_forge_count_图纸ID% 读取玩家该图纸的已锻造次数。
检查：
- 变量中的图纸 ID 是否正确。
- 玩家数据是否已经从数据库加载。
- 数据库连接是否正常。
- 使用的是否为图纸 ID，而不是显示名称。
- PlaceholderAPI 是否正常解析该变量。
可使用以下管理指令修正次数：
| 指令 | 用途 |
|---|---|
/lgf setcount | 设置玩家的图纸锻造次数 |
/lgf givecount | 增加玩家的图纸锻造次数 |
/lgf takecount | 减少玩家的图纸锻造次数 |
具体参数应以服务器内的指令帮助为准。
修改次数后变量没有立即变化
先确认管理指令修改的是同一名玩家和同一个图纸 ID，再重新解析变量。
如果重新解析后仍未变化，应检查数据库连接和玩家数据状态。必须安装 LyMySQLCore，并确保数据库已经成功连接，相关次数数据才能正常读取和保存。
不同图纸显示了相同次数
检查变量最后一段是否分别填写了正确的图纸 ID。变量按图纸 ID 查询，不按图纸显示名称查询。
如果两个图纸错误地使用了相同 ID，也会导致数据无法按预期区分。
指令与数据修改
管理指令执行后没有效果
依次确认：
- 玩家名称和图纸 ID 是否正确。
- 使用的是图纸 ID，而不是显示名称。
- 目标玩家数据是否已经加载。
- LyMySQLCore 是否已安装并成功连接数据库。
- 控制台是否出现数据库写入或图纸查找异常。
修改后应使用对应界面或变量重新读取数据，不要只根据旧界面中的文本判断。
指令中的图纸参数应该填写什么
填写图纸配置使用的图纸 ID。以下内容不能替代图纸 ID：
- 图纸显示名称。
- 结果物品名称。
- 分类名称。
- GUI 文件名，除非它本身就是配置引用的图纸 ID。
版本与兼容
启动时提示 NMS 或版本不支持
项目中存在以下服务端 NMS 适配：
1.7 R4、1.8 R3、1.11 R1、1.12 R1、1.13 R2、1.14 R1、1.15 R1、1.16 R3、1.17 R1、1.18 R2、1.19 R1、1.19 R3、1.20 R1、1.20 R2、1.20 R3。
如果服务端使用其他 NMS 映射，依赖 NBT 的物品识别和修改功能可能无法正常工作。不要仅根据 Minecraft 大版本判断兼容性，应同时确认服务端实际使用的 NMS 映射。
服务端可以启动，但物品匹配或 NBT 修改异常
这通常需要检查服务端分支和 NMS 映射。插件的 NBT 功能按服务端内部版本适配，兼容层未匹配时，普通界面可能仍能打开，但物品 NBT 读取、写入或匹配可能异常。
同时检查其他物品插件是否在物品生成后再次修改 NBT。
配置排查
修改 YAML 后配置没有生效
检查：
- YAML 缩进是否正确。
- 是否使用了 Tab 制表符。
- ID 引用是否与实际配置一致。
- 列表和对象层级是否写在正确位置。
- 控制台是否出现 YAML 解析错误。
- 修改的是否为当前正在使用的配置文件。
插件包含 YAML 配置监听和安全写入逻辑，但格式错误的配置仍无法正常加载。
控制台没有报错，但配置仍不生效
没有语法错误不代表引用关系正确。继续检查：
- 分类 ID 是否存在。
- 图纸 ID 是否存在。
- GUI ID 是否存在。
- 物品库前缀和物品 ID 是否正确。
- 词条方法名是否已经注册。
- 条件是否实际满足。
- 玩家数据库数据是否正常加载。
建议先使用一个已确认正常的图纸配置进行对照，只修改一个配置项后测试，避免同时修改多个条件导致无法定位问题。