常见问题

LyGalaxyMapped 是一个基于装备物品、玩家状态、权限、PlaceholderAPI 条件和临时标签的动态构筑插件。插件先通过 tag-check 计算标签层数，再按照 mapped 的需求、排斥条件和同组优先级激活属性与药水效果。

基本信息

插件支持哪些 Minecraft 版本？

项目提供以下服务端版本适配：

Minecraft 版本
1.7.10
1.8.8
1.11.2
1.12.2
1.13.2
1.14.4
1.15.2
1.16.5
1.17.1
1.18.2
1.19.2
1.19.4
1.20.1
1.20.2
1.20.3

项目文件没有提供其它 Minecraft 版本的适配信息。

PlaceholderAPI 是必需的吗？

不是所有功能都需要 PlaceholderAPI。

使用以下功能时需要安装并启用 PlaceholderAPI：

papi(...) 标签条件。
属性文本中的 PlaceholderAPI 占位符。
需要通过 PlaceholderAPI 获取玩家数据的计算内容。

PlaceholderAPI 未启用时，papi(...) 条件不会命中，属性文本中的 PlaceholderAPI 占位符也不会展开。如果占位符位于尖括号公式中，公式可能因此无法计算，该属性行会被跳过。

插件支持哪些属性插件？

config.yml 的 attribute-plugin 支持以下值：

配置值	用途
`AttributePlus`	使用 AttributePlus 写入映射属性
`AttributeSystem`	使用 AttributeSystem 写入映射属性
`SX-Attribute`	使用 SX-Attribute 写入映射属性
`ItemLoreOrigin`	使用 ItemLoreOrigin 写入映射属性

要让 mapped.attribute 生效，必须配置并启用对应的属性插件。配置了未支持的值，插件无法按该适配方式写入属性。

选择 ItemLoreOrigin 时，插件会使用固定的 20 tick 同步间隔。thread-running-interval 不会改变 ItemLoreOrigin 的同步间隔。

插件有哪些外部插件依赖？

依赖取决于实际使用的功能：

使用功能	要求
`papi(...)` 条件或属性中的 PlaceholderAPI 占位符	安装并启用 PlaceholderAPI
`mapped.attribute`	安装并启用 `attribute-plugin` 配置中选择的属性插件
`plugin-slot` 外部槽位	对应插件及其槽位 API 必须可用

plugin.yml 声明的软依赖包括 PlaceholderAPI、DZ_Status、AttributePlus、SX-Attribute、ItemLoreOrigin、APInventory、LyInventory 和 GermPlugin。

使用外部背包槽位时为什么读取不到物品？

plugin-slot 会直接调用对应外部插件的槽位 API，并保存物品快照。配置了外部槽位但对应 API 不可用时，该槽位会被跳过，相关物品条件和 Lore 动态变量也不会读取到该物品。

单个槽位或外部 API 出错时，插件只跳过当前槽位，不会因此停止其它槽位的检测。

指令

插件有哪些指令？

指令	说明	限制
`/lgm`	显示帮助	无额外限制
`/lgm help`	显示帮助	无额外限制
`/lgm active [玩家]`	查询自己或指定在线玩家当前激活的映射	查询其他玩家仅限 OP
`/lgm tag [玩家]`	查询自己或指定在线玩家当前的标签及层数	查询其他玩家仅限 OP
`/lgm reload`	重载主配置和 `mapped` 目录中的映射文件	仅限 OP

插件没有在 plugin.yml 中声明独立的命令权限节点。权限判断使用执行者的 OP 状态。

控制台为什么不能直接执行 `active` 或 `tag`？

不指定玩家时，指令默认查询执行者自己的数据。控制台不是玩家，因此必须指定在线玩家名称：

text

/lgm active 玩家名
/lgm tag 玩家名

指定目标玩家时，执行者必须是 OP，目标玩家必须在线。

为什么普通玩家不能查询其他玩家？

active 和 tag 的第二个参数用于查询指定在线玩家，仅 OP 可以使用。普通玩家只能查询自己的数据。

`/lgm reload` 为什么提示没有权限？

该指令只允许 OP 执行。插件没有提供可替代的命名权限节点。

指令补全为什么不显示玩家名称？

只有 OP 在输入 active 或 tag 的第二个参数时，才会补全在线玩家名称。普通玩家不会看到目标玩家补全。

查询指令显示的数据为什么不是刚刚放入的物品？

active 和 tag 读取玩家最近一次计算后保存的缓存，不会在执行指令时重新扫描物品。

进服、关闭背包、快捷栏切换、主副手交换以及周期性快照更新会触发后续计算。事件触发后需要等待下一次计算完成，查询结果才会更新。

标签计算

`condition` 下的数字是条件编号吗？

不是。数字是每次命中条件时增加的层数权重。

yaml

tag-check:
  '火焰':
    condition:
      1:
        - "lore('元素：火焰')"
      2:
        - "permission('lgm.先天霜火圣体')"
    max-point: -1

上例中，Lore 条件每命中一个扫描槽位增加 1 层，权限条件命中一次增加 2 层。

同一权重下配置多条条件时，是多行 AND 吗？

不是。同一权重下的每一条字符串条件都会独立统计命中次数。

同一件物品同时满足多条条件时，各条条件分别累计，不进行物品去重。单条条件中的顶层 || 才表示 OR。

例如：

yaml

condition:
  1:
    - "lore('元素：火焰')"
    - "nbt('lgm.element', 'fire')"

同一件物品同时满足 Lore 和 NBT 条件时，会分别为两条条件计数。

`max-point` 什么时候生效？

所有条件累计完成后，插件才会使用 max-point 限制最终标签层数。

-1：不限制最大层数。
非负数：最终层数不能超过该值。

玩家状态条件会按装备槽位重复计算吗？

不会。world(...)、time(...)、gamemode(...) 和 weather(...) 属于玩家状态条件，每次只命中一次，不会按物品槽位重复累计。

物品名称、Lore 和 NBT 条件则按照配置的扫描槽位统计命中次数。

为什么标签没有达到需求？

可以依次检查：

tag-check 是否使用新版函数式条件写法。
condition 权重是否符合预期。
物品是否位于 plugin-slot 配置的扫描槽位中。
多个 require 标签是否全部达到要求。
max-point 是否限制了最终层数。
是否有 exclude 标签达到排斥层数。
是否刚修改配置但还没有执行 /lgm reload。
如果使用 papi(...)，PlaceholderAPI 是否已安装并启用。

插件不再兼容旧版的 check、attribute-group、lore:{...}、nbt:{...} 和 permission:{...} 格式。

条件表达式

条件表达式支持哪些函数？

函数	说明
`name('文本')`	物品名称包含文本
`name('文本', contains)`	物品名称包含文本
`name('文本', equals)`	物品名称完整匹配文本，忽略大小写
`lore('文本')`	任意一行 Lore 包含文本
`lore('文本', contains)`	任意一行 Lore 包含文本
`lore('文本', equals)`	任意一行 Lore 完整匹配文本，忽略大小写
`nbt('路径', '值')`	NBT 标量值完整匹配
`permission('权限')`	玩家拥有权限时命中
`nopermission('权限')`	玩家没有权限时命中
`papi(比较表达式)`	使用 PlaceholderAPI 占位符进行比较
`world('世界名')`	当前世界名称匹配
`time('day/night')`	当前世界时间处于白天或夜晚
`gamemode('模式')`	当前游戏模式匹配
`weather('clear/rain/thunder')`	当前天气状态匹配

weather('storm') 是 weather('thunder') 的同义写法。

名称和 Lore 条件中的文本参数会先将 & 转换为 Minecraft 颜色码。默认匹配方式是包含匹配，equals 使用完整文本比较并忽略大小写。

条件中的 `!` 和 `||` 怎么处理？

单条条件中的顶层 || 表示 OR，任意一侧成立即可。
函数前添加 ! 表示取反。
同一权重下的多条字符串仍然独立累计，不会因为处于同一权重就自动变成 AND。

例如：

yaml

condition:
  1:
    - "lore('火焰') || nbt('lgm.element', 'fire')"
    - "!lore('已绑定')"

第一条条件中任意一侧成立即可；第二条条件表示 Lore 不包含“已绑定”。两条字符串条件仍然分别统计。

`papi(...)` 支持哪些比较符号？

PlaceholderAPI 条件支持：

==
!=
>
>=
<
<=
&&
||

数字比较支持四则运算。字符串比较值需要使用单引号包裹。

例如：

yaml

condition:
  1:
    - "papi(%player_level% >= 5 && %player_level% <= 10)"
    - "papi(%player_class% == '战士' || %player_class% == '骑士')"

NBT 条件支持哪些值和比较方式？

nbt 条件读取字符串和数值等标量 NBT 值，不用于直接匹配列表、复合对象或数组。

写法	说明
`nbt('路径', '文本值')`	字符串完整匹配
`nbt('路径', 5)`	数值完整匹配
`nbt('路径', '文本值', equals)`	字符串完整匹配
`nbt('路径', '文本值', !=)`	不等于
`nbt('路径', '文本值', contains)`	字符串包含
`nbt('路径', '文本值', startsWith)`	字符串以目标值开头
`nbt('路径', '文本值', endsWith)`	字符串以目标值结尾
`nbt('路径', 5, >)`	数值大于目标值
`nbt('路径', 5, >=)`	数值大于等于目标值
`nbt('路径', 5, <)`	数值小于目标值
`nbt('路径', 5, <=)`	数值小于等于目标值
`nbt('路径', 'TEXT', ignoreCase)`	忽略英文大小写完整匹配
`nbt('路径', 'TEXT', equals, ignoreCase)`	忽略英文大小写完整匹配

数值比较要求 NBT 实际值和配置目标值都能转换为数字。ignoreCase 可以与其它匹配方式组合使用。

映射选择

`require` 中的多个标签是 AND 还是 OR？

默认是 AND。映射的所有 require 标签都达到配置层数后，映射才满足需求。

yaml

require:
  '火焰': 1
  '冰霜': 1

上例要求“火焰”至少 1 层且“冰霜”至少 1 层。

同一个 `group-id` 的多个映射会同时生效吗？

不会。同一个 group-id 中，插件只选择满足需求且 group-priority 最高的一条映射。

不同 group-id 的映射可以同时生效。

为什么低等级映射没有和高等级映射叠加？

相同 group-id 的映射属于同一个优先级组。高优先级映射生效后，同组低优先级映射不会继续写入属性或药水效果。

`exclude` 的优先级是什么？

exclude 高于 require。只要 exclude 中任意标签达到配置层数，即使 require 全部满足，该映射也不会生效。

yaml

exclude:
  '夜间': 1

上例表示“夜间”标签达到 1 层时，该映射被排斥。

`start-message` 和 `end-message` 什么时候发送？

start-message：映射进入生效状态时发送。
end-message：映射离开生效状态时发送。

消息按 group-id 的状态变化处理，只在进入、离开或同组映射切换时发送。空消息列表不会发送消息。

物品槽位和动态变量

`plugin-slot` 支持哪些槽位格式？

槽位格式	说明
`Minecraft#槽位ID`	原版背包数字槽位
`Origin#MainHand`	原版主手
`Origin#OffHand`	原版副手
`Origin#Helmet`	头盔
`Origin#ChestPlate`	胸甲
`Origin#Legging`	护腿
`Origin#Boots`	鞋子
`DragonCore#槽位名`	DragonCore 槽位
`GermPlugin#槽位名`	GermPlugin 槽位
`APInventory#分页ID#槽位ID`	APInventory 分页和槽位
`LyInventory#背包ID#槽位名`	LyInventory 背包和槽位
`LyInventoryReload#背包ID#槽位名`	LyInventoryReload 背包和槽位
`YeeJewelry#背包ID#槽位ID`	YeeJewelry 背包和槽位

槽位配置必须使用完整字符串。物品条件和 Lore 动态变量都从插件保存的物品快照中读取。

为什么 1.7.10 或 1.8.8 读取不到副手？

这些版本没有可用的原版副手读取方法。Origin#OffHand 在这些版本会返回空值，不能用于读取副手物品。

`lore-get-placeholder` 如何提取数值？

该节点将变量名映射到 Lore 模板，模板必须包含 <value>。<value> 代表待提取的数字，模板两侧的文本用于定位数字。

yaml

lore-get-placeholder:
  '变量id': '获得 <value>x玩家 等级点攻击力'
attribute:
  - '火属性伤害: {var.变量id}'

例如 Lore 为“获得 12x玩家等级点攻击力”时，变量值为 12。同一个变量在多个物品或多行 Lore 中命中时会累加。未命中变量或无法转换为数字时，变量值按 0 处理。

`{var.xxx}` 和 `{tag.xxx}` 有什么区别？

变量格式	数据来源
`{var.变量id}`	当前映射的 `lore-get-placeholder` 从物品 Lore 提取的数值
`{tag.标签}`	本次计算得到的装备标签和临时标签合并层数

引用不存在的变量或标签时，替换结果为 0。

属性公式支持什么写法？

属性文本中的每个 <...> 片段都会单独计算。公式支持数字、小数、括号和四则运算 +、-、*、/。PlaceholderAPI 占位符会在公式计算前展开。

yaml

attribute:
  - '火焰层数伤害: <{tag.火焰}*2>'
  - '火属性伤害: <%player_level%*2>'

公式不合法时，该属性行不会提交给属性插件。属性文本中的 & 会在输出时转换为 Minecraft 颜色码。

PlaceholderAPI 变量

插件提供哪些 PlaceholderAPI 变量？

插件当前使用以下 lgm 占位符：

占位符	说明
`%lgm_tag-标签%`	查询指定标签最近一次计算的层数
`%lgm_active-组ID%`	查询指定映射组当前的激活状态
`%lgm_mapped-映射ID:序号%`	读取指定映射的最近一次已计算属性缓存

映射属性查询前缀同时接受 mapped- 和 Mapped- 写法。项目不再使用旧版占位符。

这些变量读取插件最近一次计算结果，不会在占位符被请求时重新扫描物品。

临时标签和 API

外部插件添加的临时标签会参与映射计算吗？

会。插件提供公开的 LyGalaxyMappedAPI，外部插件添加的临时标签会与装备标签合并后参与映射计算，也可以被 {tag.xxx} 属性变量读取。

同一玩家同一标签的多次添加会独立叠加，并按各自的 tick 时间分别过期。玩家退出或插件停止时，临时标签会被清理。

临时标签会覆盖装备标签吗？

不会。临时标签和装备条件得到的标签层数会合并计算，不会覆盖已有的装备标签层数。

临时标签过期后映射为什么消失了？

临时标签按配置的 tick 时间独立过期。标签层数减少后，相关映射可能不再满足 require，或者触发 exclude，插件会移除对应属性和药水效果，并在状态变化时发送 end-message。

配置与重载

配置文件放在哪里？

插件主配置位于：

text

plugins/LyGalaxyMapped/config.yml

映射数据位于：

text

plugins/LyGalaxyMapped/mapped/

mapped 文件夹中的 YAML 文件读取 tag-check 和 mapped 节点。主 config.yml 不读取这两个节点。

`config.yml` 中有哪些配置项？

配置项	说明
`attribute-plugin`	选择属性插件，支持 `AttributePlus`、`AttributeSystem`、`SX-Attribute` 和 `ItemLoreOrigin`
`thread-running-interval`	映射检测线程运行间隔，示例值为 `20`
`plugin-slot`	指定需要保存和检测的物品槽位列表

示例主配置中的 plugin-slot 默认扫描原版主手、副手和四个装备槽位。

`mapped` 文件中的节点如何分组？

映射文件使用以下顶层节点：

顶层节点	作用
`tag-check`	定义条件如何转换为标签层数
`mapped`	根据标签需求选择属性和药水效果

单个 mapped 映射可以包含：

配置项	作用
`group-id`	指定映射所属的优先级组
`group-priority`	指定同组优先级
`require`	定义必须达到的标签层数
`exclude`	定义达到后禁止映射生效的标签层数
`lore-get-placeholder`	从物品 Lore 提取动态数值
`attribute`	映射生效时提交的属性文本列表
`potion`	映射生效时添加的药水效果列表
`start-message`	映射进入生效状态时发送的消息列表
`end-message`	映射离开生效状态时发送的消息列表

修改配置后为什么没有立即生效？

配置修改后需要由 OP 执行：

text

/lgm reload

重载会重新读取主配置和 mapped 文件夹中的映射数据，并重新安排在线玩家的快照计算。

重载后旧配置为什么不再生效？

当前版本只读取新版配置节点：

tag-check
mapped

旧版 check 和 attribute-group 不再兼容。条件也必须改为新版函数式写法，例如 lore('文本')、nbt('路径', '值') 和 permission('权限')。

属性和药水现在直接写在对应的 mapped 映射节点中，不再使用旧版独立效果配置结构。

修改 `thread-running-interval` 后，ItemLoreOrigin 的同步间隔会改变吗？

不会。ItemLoreOrigin 的同步任务间隔固定为 20 tick，没有单独的同步间隔配置项。

药水效果

`potion` 应该怎么填写？

potion 使用列表配置，格式为 效果名:数值：

yaml

potion:
  - 'SPEED:1'

项目示例中列出的效果名包括：

SPEED、FAST_DIGGING、SLOW_DIGGING、INCREASE_DAMAGE、HEAL、HARM、JUMP、CONFUSION、REGENERATION、DAMAGE_RESISTANCE、FIRE_RESISTANCE、WATER_BREATHING、INVISIBILITY、BLINDNESS、NIGHT_VISION、HUNGER、WEAKNESS、POISON、WITHER、HEALTH_BOOST、ABSORPTION、SATURATION 和 FIRE。

为什么映射激活了但药水没有生效？

请检查：

映射是否真的满足 require 且没有被 exclude 排斥。
potion 是否位于当前生效的映射节点下。
效果名和数值格式是否符合项目示例。
映射是否因同组更高优先级映射切换而失效。
是否配置并启用了正确的属性插件。映射选择和药水刷新由同一套生效状态处理。

映射失效后旧属性或药水为什么还在？

插件会根据当前计算结果清理本插件此前写入的属性和药水来源。配置重载、玩家退出和插件停止时也会执行对应清理流程。

常见问题 ​

基本信息 ​

插件支持哪些 Minecraft 版本？ ​

PlaceholderAPI 是必需的吗？ ​

插件支持哪些属性插件？ ​

插件有哪些外部插件依赖？ ​

使用外部背包槽位时为什么读取不到物品？ ​

指令 ​

插件有哪些指令？ ​

控制台为什么不能直接执行 active 或 tag？ ​

为什么普通玩家不能查询其他玩家？ ​

/lgm reload 为什么提示没有权限？ ​

指令补全为什么不显示玩家名称？ ​

查询指令显示的数据为什么不是刚刚放入的物品？ ​

标签计算 ​

condition 下的数字是条件编号吗？ ​

同一权重下配置多条条件时，是多行 AND 吗？ ​

max-point 什么时候生效？ ​

玩家状态条件会按装备槽位重复计算吗？ ​

为什么标签没有达到需求？ ​

条件表达式 ​

条件表达式支持哪些函数？ ​

条件中的 ! 和 || 怎么处理？ ​

papi(...) 支持哪些比较符号？ ​

NBT 条件支持哪些值和比较方式？ ​

映射选择 ​

require 中的多个标签是 AND 还是 OR？ ​

同一个 group-id 的多个映射会同时生效吗？ ​

为什么低等级映射没有和高等级映射叠加？ ​

exclude 的优先级是什么？ ​

start-message 和 end-message 什么时候发送？ ​

物品槽位和动态变量 ​

plugin-slot 支持哪些槽位格式？ ​

为什么 1.7.10 或 1.8.8 读取不到副手？ ​

lore-get-placeholder 如何提取数值？ ​

{var.xxx} 和 {tag.xxx} 有什么区别？ ​

属性公式支持什么写法？ ​

PlaceholderAPI 变量 ​

插件提供哪些 PlaceholderAPI 变量？ ​

临时标签和 API ​

外部插件添加的临时标签会参与映射计算吗？ ​

临时标签会覆盖装备标签吗？ ​

临时标签过期后映射为什么消失了？ ​

配置与重载 ​

配置文件放在哪里？ ​

config.yml 中有哪些配置项？ ​

mapped 文件中的节点如何分组？ ​

修改配置后为什么没有立即生效？ ​

重载后旧配置为什么不再生效？ ​

修改 thread-running-interval 后，ItemLoreOrigin 的同步间隔会改变吗？ ​

药水效果 ​

potion 应该怎么填写？ ​

为什么映射激活了但药水没有生效？ ​

映射失效后旧属性或药水为什么还在？ ​

常见问题

基本信息

插件支持哪些 Minecraft 版本？

PlaceholderAPI 是必需的吗？

插件支持哪些属性插件？

插件有哪些外部插件依赖？

使用外部背包槽位时为什么读取不到物品？

指令

插件有哪些指令？

控制台为什么不能直接执行 `active` 或 `tag`？

为什么普通玩家不能查询其他玩家？

`/lgm reload` 为什么提示没有权限？

指令补全为什么不显示玩家名称？

查询指令显示的数据为什么不是刚刚放入的物品？

标签计算

`condition` 下的数字是条件编号吗？

同一权重下配置多条条件时，是多行 AND 吗？

`max-point` 什么时候生效？

玩家状态条件会按装备槽位重复计算吗？

为什么标签没有达到需求？

条件表达式

条件表达式支持哪些函数？

条件中的 `!` 和 `||` 怎么处理？

`papi(...)` 支持哪些比较符号？

NBT 条件支持哪些值和比较方式？

映射选择

`require` 中的多个标签是 AND 还是 OR？

同一个 `group-id` 的多个映射会同时生效吗？

为什么低等级映射没有和高等级映射叠加？

`exclude` 的优先级是什么？

`start-message` 和 `end-message` 什么时候发送？

物品槽位和动态变量

`plugin-slot` 支持哪些槽位格式？

为什么 1.7.10 或 1.8.8 读取不到副手？

`lore-get-placeholder` 如何提取数值？

`{var.xxx}` 和 `{tag.xxx}` 有什么区别？

属性公式支持什么写法？

PlaceholderAPI 变量

插件提供哪些 PlaceholderAPI 变量？

临时标签和 API

外部插件添加的临时标签会参与映射计算吗？

临时标签会覆盖装备标签吗？

临时标签过期后映射为什么消失了？

配置与重载

配置文件放在哪里？

`config.yml` 中有哪些配置项？

`mapped` 文件中的节点如何分组？

修改配置后为什么没有立即生效？

重载后旧配置为什么不再生效？

修改 `thread-running-interval` 后，ItemLoreOrigin 的同步间隔会改变吗？

药水效果

`potion` 应该怎么填写？

为什么映射激活了但药水没有生效？

映射失效后旧属性或药水为什么还在？