常见问题

插件的作用是什么？

LySell 提供一个 GUI 出售界面。玩家可以将物品放入界面，插件根据物品 Lore 或 sell-preset 中的固定售价计算可获得的货币，点击出售按钮后移除可出售物品并发放对应收益。

插件同时提供：

• 多种货币分别统计和发放。
• 通过正则表达式从物品 Lore 中提取价格。
• 为没有 Lore 的原版物品配置固定售价。
• 根据 Lore 或原版物品 ID 快速放入物品。
• 一键取回界面中的全部物品。
• 可选的 Shift + 右键清空功能。
• 通过 API 尝试出售指定物品。

如何打开出售界面？

使用：

/lsell open

该指令只能由玩家执行。执行后会打开 LySell 的出售界面。

/lsell reload 谁可以使用？

/lsell reload 只允许服务器管理员执行。代码使用 Bukkit 的 sender.isOp() 判断权限，没有注册独立的权限节点。

/lsell reload

重载时会重新读取配置，并重新加载以下内容：

• prohibit-sell-lore
• economy
• extra-button
• sell-preset

为什么 /lsell 没有显示完整帮助？

客户端部分在授权验证通过前，只显示重载指令，并提示更多指令需要验证通过后显示。授权验证通过后，服务端部分会注册 open 和 reload 两个子指令。

如果授权验证没有完成，出售界面和服务端指令不会正常初始化。

为什么物品放进去没有价格？

LySell 只会识别两类售价：

1. 物品 Lore 被 economy.<货币>.key 中的正则表达式匹配。
2. 没有物品元数据的物品匹配 sell-preset 中的物品键。

请按以下顺序检查：

• Lore 中是否包含正则表达式能够匹配的数字。
• Lore 颜色代码是否影响了匹配。插件会过滤常见颜色代码后再匹配。
• economy 下的货币配置是否完整。
• 没有 Lore 的物品是否配置了 sell-preset。
• 物品是否包含 prohibit-sell-lore 中的禁止关键词。

Lore 价格匹配示例：

economy:
  金币:
    key:
      - '(?<=出售可获得)[0-9]*(?=金币)'

该正则表达式可以从类似 出售可获得25金币 的 Lore 行中提取 25。

为什么配置了 sell-preset 仍然没有价格？

sell-preset 只用于没有物品元数据的物品。代码判断到物品存在元数据时，不会使用固定售价预设。

因此，带有 Lore、展示名称或其他物品元数据的物品，需要通过 economy.<货币>.key 匹配 Lore 价格。

配置键还必须使用插件能够识别的格式：

sell-preset:
  '160:0':
    金币: 1

物品键由原版材质名称或数字物品 ID 加子 ID 组成。代码会尝试按材质名称和数字 ID 查找物品。

为什么某些物品不能出售？

检查配置中的 prohibit-sell-lore。

只要物品任意一行 Lore 包含其中一个关键词，物品就会被排除，不会计入出售金额，也不会在出售时被移除。

例如：

prohibit-sell-lore:
  - '已绑定'

如果物品 Lore 中包含 已绑定，该物品不会被统计和出售。

被禁止出售的物品会显示在预览金额中吗？

不会。

GUI 会在计算出售按钮 Lore 前检查 prohibit-sell-lore。匹配禁止关键词的物品不会计入预览金额。点击出售时也会再次检查，因此不会被出售。

多个物品的价格如何计算？

物品数量会参与计算。

• Lore 价格：匹配到的单个物品价格乘以物品堆叠数量。
• sell-preset 价格：配置的单个物品价格乘以物品堆叠数量。
• 相同货币的结果会累加。
• 不同货币会分别计算和发放。

例如，某物品 Lore 匹配到单价 25，物品数量为 4，则该物品计入的基础金额为 100，之后还会按照对应货币的 formula 和 round 处理。

economy 中的 formula 有什么作用？

formula 用于计算 Lore 匹配到的基础价格。{value} 会被替换为匹配数字乘以物品数量后的结果。

支持整数、浮点数以及以下四则运算符：

• +
• -
• *
• /
• ( 和 )

示例：

economy:
  金币:
    formula: '{value}*1'

如果将公式设置为 {value}*2，则匹配到的基础价格会乘以 2。

round 会影响什么？

round 决定最终显示和发放金额的格式。

round: '%.2f'

其中：

• %.2f：保留两位小数。
• %.0f：按格式取整显示和发放。

最终金额会先按照该格式转换，再用于发放货币。因此，使用点券时应确保结果能够转换为整数。

为什么预览金额和最终到账金额看起来不同？

预览金额和最终发放金额都使用对应货币的 round 格式，但计算时机不同：

• 预览金额会根据界面当前物品重新计算，并写入出售按钮 Lore。
• 点击出售后会再次计算实际出售结果。
• 物品数量、Lore、禁止关键词和配置变化都会影响结果。

配置重载后，打开中的界面不会作为固定结果保存；按钮会继续按照当前界面物品和已重载的配置计算。

Vault 或点券没有到账怎么办？

先确认对应前置已经安装并成功加载。插件启动时会检查 Vault 和 PlayerPoints 是否可用，但配置中的货币发放方式仍需与前置对应。

默认配置中的发放方式如下：

give-from	发放方式	需要的前置
Vault	通过 Vault 经济服务发放金币	Vault 以及实际的经济插件
PlayerPoints	通过 PlayerPoints API 发放点券	PlayerPoints
其他文本	作为控制台指令执行	PlaceholderAPI 用于解析变量

如果使用 Vault：

• 检查 Vault 是否正常加载。
• 检查服务器是否有可用的 Vault 经济服务。
• 确认对应货币的 give-from 为 Vault。

如果使用 PlayerPoints：

• 检查 PlayerPoints 是否正常加载。
• 确认对应货币的 give-from 为 PlayerPoints。
• 确认最终金额经过 round 后是整数。

如果使用自定义指令：

give-from: 'lshop give %player_name% nb {value}'

插件会以控制台身份执行该指令，并在执行前使用 PlaceholderAPI 解析玩家变量，同时替换 {value}。

使用自定义指令发放货币时需要注意什么？

自定义 give-from 不会调用 Vault 或 PlayerPoints，而是直接执行控制台指令。

配置中可以使用：

• {value}：替换为最终金额。
• PlaceholderAPI 支持的玩家变量，例如 %player_name%。

示例：

economy:
  其他:
    give-from: 'lshop give %player_name% nb {value}'

使用该方式时，需要确保：

• 指令本身可以由控制台执行。
• 指令参数顺序正确。
• PlaceholderAPI 已安装并正常工作。
• 最终金额格式符合目标插件要求。

为什么使用 Vault 时提示没有连接到 Vault？

插件需要从 Bukkit 服务管理器中找到 Vault 提供的经济服务。如果 Vault 未安装、未加载，或没有任何经济插件注册经济服务，插件无法发放金币。

仅安装 Vault 不一定能够提供经济服务，还需要服务器中存在实际提供经济服务的插件。

一键放入按钮没有效果怎么办？

检查 extra-button.<槽位>.type。

额外按钮只会读取第 0 到 8 个槽位，并显示在出售界面底部。当前代码支持以下类型：

类型	作用
put:<关键词>	将背包中 Lore 任意一行包含关键词的物品放入界面
put:not-lore	将背包中没有物品元数据的物品放入界面
putid:<物品列表>	按原版物品 ID、材质名称和可选子 ID筛选并放入界面
get	将界面中的物品取回背包

示例：

extra-button:
  0:
    type: 'put:&7品质: &a一般'
    item: '160:5'
    name: '&7一键放入&a一般&7品质的装备'
    lore:
      - '[点我]'

put:<关键词> 是包含匹配，不要求整行完全相同。颜色代码会按配置中的内容转换后进行匹配。

putid 应该怎样填写？

putid 后面使用逗号分隔多个物品条件，每个条件可以写物品 ID，也可以写 物品 ID:子 ID。

示例：

type: 'putid:1,2,3,4:0,5:0'

该配置会尝试放入：

• ID 为 1 的物品。
• ID 为 2 的物品。
• ID 为 3 的物品。
• 子 ID 为 0 的 ID 4 物品。
• 子 ID 为 0 的 ID 5 物品。

带有子 ID 的条件会同时检查物品材质和耐久值。物品材质可以使用原版数字 ID 或材质名称。

一键取回按钮为什么没有取回全部物品？

get 按钮会按照界面物品槽位顺序将物品加入玩家背包。如果背包空间不足，剩余物品会保留在对应的界面槽位中。

关闭界面时，界面前 36 个槽位中的物品也会自动返还玩家背包。背包已满时，Bukkit 的物品加入规则可能导致物品无法完全放入，因此取回前应确认背包有足够空间。

Shift + 右键为什么不能清空？

需要开启：

clear-item-button: true

开启后，玩家在出售按钮上执行 Shift + 右键，插件会清空界面前 36 个物品槽位，并发送“清空成功”提示。

该操作不会发放收益，也不会执行出售流程。清空前请确认玩家确实要移除界面中的物品。

点击出售按钮没有出售物品怎么办？

请检查以下内容：

• 物品是否匹配 Lore 价格正则表达式。
• 物品是否匹配 sell-preset。
• 物品是否被 prohibit-sell-lore 排除。
• 对应的 economy 配置是否成功加载。
• 是否在点击后的一秒冷却时间内重复操作。

出售按钮存在一秒操作冷却。冷却期间重复点击会提示稍后再试。

点击出售按钮后物品被移除了，但没有收到货币怎么办？

插件会先计算并移除可出售物品，再按照每种货币的 give-from 发放收益。请检查：

• Vault 是否存在可用经济服务。
• PlayerPoints 是否正常加载。
• 自定义发放指令是否可以由控制台执行。
• 自定义指令中的 {value} 是否处于正确位置。
• round 是否生成了目标发放插件接受的金额格式。
• 控制台是否有发放失败或配置解析错误。

使用自定义指令时，实际执行的指令会受到 PlaceholderAPI 解析结果影响，建议同时查看服务器控制台日志。

关闭出售界面后物品会丢失吗？

正常关闭界面时，插件会遍历界面前 36 个槽位，并将物品加入玩家背包。

如果玩家背包空间不足，物品可能无法全部返还。关闭界面前应预留足够的背包空间。

为什么出售按钮上的金额不会立即变化？

出售按钮金额每秒刷新一次。代码使用每 20 个游戏刻刷新一次，通常约为一秒。

如果刚放入物品后金额暂未变化，请等待下一次刷新。

为什么额外按钮最多只能配置到 8？

插件只处理 extra-button 下的 0 到 8 槽位，并将其显示在界面底部的 9 个槽位中。其他编号不会被载入。

为什么配置的物品显示成了错误材质？

界面物品和额外按钮物品支持数字 ID、数字 ID 加子 ID，以及部分英文材质名称。插件还包含旧版数字 ID 和英文材质 ID 的兼容处理。

建议保持以下格式：

gui:
  fill-item: '160:0'
  button-item: '355:0'

extra-button:
  0:
    item: '160:5'

如果物品 ID、子 ID 或材质名称不存在，插件无法正确构造目标物品。

插件支持哪些服务器版本？

项目的 plugin.yml 声明 api-version: 1.13。代码中包含低于 1.13 的旧版材质和数字 ID 兼容逻辑，但项目文件没有声明更详细的服务器版本范围。

实际使用时，还需要确认当前服务器及其前置插件能够正常加载 Bukkit API、Vault、PlayerPoints 或 PlaceholderAPI 等所需组件。

插件需要哪些前置？

项目声明的软依赖为：

• PlaceholderAPI
• PlayerPoints
• Vault

其中具体作用取决于配置：

前置	使用场景
Vault	give-from: 'Vault' 时发放经济余额
PlayerPoints	give-from: 'PlayerPoints' 时发放点券
PlaceholderAPI	自定义 give-from 指令中解析玩家变量

如果只使用自定义指令，仍需确认该指令及其目标插件正常工作。

重载配置后哪些内容会生效？

执行 /lsell reload 后，插件会重新读取配置并清空旧的内存数据，然后重新载入：

• 禁售 Lore 关键词。
• 货币匹配规则、公式、格式、发放方式和消息。
• 额外按钮。
• 出售预设。

重载只重新读取配置，不会替玩家处理已经关闭或正在操作中的界面物品。修改配置后，建议重新打开出售界面确认显示效果。

API 能否直接出售物品？

可以。插件提供 LySellAPI 接口中的方法：

boolean trySell(Player player, ItemStack item, int amount)

该方法会按照与 GUI 出售相同的主要规则处理物品：

• 检查 sell-preset。
• 检查 Lore 价格规则。
• 检查 prohibit-sell-lore。
• 按 amount 计算收益。
• 按货币配置发放收益并发送消息。

返回值表示是否识别到可出售价格。API 方法只负责出售计算和发放，不会自动从调用方背包中移除物品；调用方需要自行处理物品数量变化。

为什么 API 调用后物品没有被自动扣除？

trySell 的实现只接收玩家、物品和数量，并执行价格计算、收益发放及消息发送。代码没有修改调用方背包，也没有修改传入物品的数量。

如果其他插件通过 API 出售物品，需要自行确认出售成功后再扣除对应数量。

为什么自定义货币没有到账？

自定义货币的名称只是 economy 下的配置键。真正的发放方式由该货币的 give-from 决定。

例如：

economy:
  牛币:
    key:
      - '(?<=出售可获得)[0-9]*(?=牛币)'
    formula: '{value}*1'
    round: '%.0f'
    format: '&d{value}牛币'
    give-from: 'lshop give %player_name% nb {value}'
    message: '&7本次出售物品, 获得了&d{value}牛币!'

请确认：

• Lore 正则表达式能够匹配到数字。
• give-from 是有效的控制台指令。
• PlaceholderAPI 能够解析其中的玩家变量。
• 目标货币插件接受 round 生成的数值格式。

为什么配置文件修改后没有生效？

配置修改后需要执行：

/lsell reload

只有管理员可以执行该指令。YAML 缩进、配置键拼写、正则表达式和货币名称错误，都可能导致对应内容无法正确载入。重载时请同时查看服务器控制台是否出现配置载入失败信息。