Lore Template Engine
一个 Paper 插件,通过配置文件定义自定义物品描述文本和工具提示布局。
为物品标记一个模板,每当物品发生变化时(如合成、附魔、管理员命令等),其描述文本就会根据该模板生成。


工作原理
配置文件使用 KDL 格式,包含四个部分:
- 变量 (Variables):从物品读取的单个值(
rarity、item_level)
- 组 (Groups):从物品读取的值列表(
enchantments、attributes、tags)
- 转换器 (Transformers):将值映射到
color、icon 和 label 字段
- 模板 (Templates):将变量、组和转换器输出排列成描述文本布局
示例
一个转换器:
transformer "rarity_lookup" {
entry "common" {
color "<gray>"
label "普通"
}
entry "uncommon" {
color "<green>"
label "稀有"
}
entry "rare" {
color "<blue>"
label "史诗"
}
entry "epic" {
color "<light_purple><bold>"
label "传说"
}
entry "legendary" {
color "<gold><bold>"
label "传奇"
}
fallback {
color "<gray>"
label "未知"
}
}
使用转换器的变量:
variable "rarity" {
source "pdc" key="rarity" type="string" default="common"
transformer "rarity_lookup"
}
当变量使用转换器时,必须在模板中指定其 display,否则原始值不会显示:
var "rarity" display="<color><label>"
一个模板:
template "weapon_default" {
var "rarity" display="<color><label>"
blank collapse-if-empty="enchantments"
group "enchantments" each="<gray><ench_name> <ench_level_roman>" empty="skip"
text "<red>Hello, World"
}
标记了 collapse-if-empty 的行在其所属组没有内容时会消失,因此没有附魔的物品不会出现空白间隙。
扩展模板并添加工具提示样式(资源包):
template "vanilla_extended" extends="vanilla" tooltip-style="simple" {
group "description" each="<gray><line>" empty="skip"
var "rarity" display="<color><label>"
}
转换器也可以绑定到组上。内置组使用 key 来命名正在转换的字段,而 PDC 组则直接转换其存储的值:
group "styled_enchantments" {
builtin "enchantments"
transformer "ench_style" key="ench_id"
// 暴露字段:<color>, <icon>, <ench_name>, <ench_level>, <ench_level_roman>
}
没有对应条目的值会使用转换器的 fallback。如果没有 fallback,则该变量或组的条目会被省略。
错误信息
配置文件由 kidl 解析,它将配置错误转换为编译器风格的诊断信息,而不是在启动时仅显示通用的“无效配置”:
- 精确的文件、行号和列号
- 出错的源代码行
- 对确切节点的-caret 下划线标注
- 解释预期内容的简短标签
- 可选的说明和用于修复的
help: 行
例如,拼写错误的源文件会产生如下报错:
error: unknown variable source `config`
--> plugins/LTE/variables.kdl:2:2
|
2 | source "config" key="rarity"
| ^^^^^^^^^^^^^^^ use `pdc` or `computed`
重复定义、缺失的组源、未知的区块以及无效的转换器键都会以相同的方式报告,并在服务器控制台中显示 ANSI 颜色。无效的配置会在任何描述文本渲染之前失败,以便你立即发现问题。
命令
/lte set template weapon_default
/lte set variable rarity epic
/lte group set description Hello World\nThis is second line
文档
完整的配置参考(变量、组、转换器、模板、扩展、工具提示样式)请查看 wiki。
面向开发者
其他插件可以通过开发者 API 应用模板并读取物品数据。设置和依赖说明请参阅 wiki。
Lore Template Engine
A Paper plugin for defining custom item lore and tooltip layouts through config.
Tag an item with a template, and its lore is generated from that template whenever the item changes (crafting, enchanting, admin commands, ...).


How it works
The config uses KDL and has four parts:
- Variables: single values read from an item (
rarity, item_level)
- Groups: lists of values read from an item (
enchantments, attributes, tags)
- Transformers: map values to
color, icon, and label fields
- Templates: arrange variables, groups, and transformer output into a lore layout
Examples
A transformer:
transformer "rarity_lookup" {
entry "common" {
color "<gray>"
label "Common"
}
entry "uncommon" {
color "<green>"
label "Uncommon"
}
entry "rare" {
color "<blue>"
label "Rare"
}
entry "epic" {
color "<light_purple><bold>"
label "Epic"
}
entry "legendary" {
color "<gold><bold>"
label "Legendary"
}
fallback {
color "<gray>"
label "Unknown"
}
}
A variable using a transformer:
variable "rarity" {
source "pdc" key="rarity" type="string" default="common"
transformer "rarity_lookup"
}
When a variable uses a transformer, its display is required in the template because the raw value is otherwise not shown:
var "rarity" display="<color><label>"
A template:
template "weapon_default" {
var "rarity" display="<color><label>"
blank collapse-if-empty="enchantments"
group "enchantments" each="<gray><ench_name> <ench_level_roman>" empty="skip"
text "<red>Hello, World"
}
Lines marked with collapse-if-empty disappear when their group has nothing to show, so an item without enchantments has no leftover gaps.
Extending a template and adding a tooltip style (resource pack):
template "vanilla_extended" extends="vanilla" tooltip-style="simple" {
group "description" each="<gray><line>" empty="skip"
var "rarity" display="<color><label>"
}
Transformers can also be bound to groups. Builtin groups use key to name the field being transformed, while PDC groups transform their stored values directly:
group "styled_enchantments" {
builtin "enchantments"
transformer "ench_style" key="ench_id"
// exposes: <color>, <icon>, <ench_name>, <ench_level>, <ench_level_roman>
}
Values without an entry use the transformer's fallback. If there is no fallback, the variable or group entry is omitted.
Error messages
Config is parsed with kidl, which turns config mistakes into compiler-style diagnostics instead of a generic "invalid config" at startup:
- the exact file, line, and column
- the offending source line
- a caret underline on the exact node
- a short label explaining what was expected
- optional notes and a
help: line for fixes
For example, a misspelled source produces:
error: unknown variable source `config`
--> plugins/LTE/variables.kdl:2:2
|
2 | source "config" key="rarity"
| ^^^^^^^^^^^^^^^ use `pdc` or `computed`
Duplicate definitions, missing group sources, unknown sections, and invalid transformer keys are reported the same way, with ANSI colors in the server console. Invalid config fails before any lore is rendered, so you see the problem immediately.
Commands
/lte set template weapon_default
/lte set variable rarity epic
/lte group set description Hello World\nThis is second line
Documentation
Full config reference (variables, groups, transformers, templates, extending, tooltip styles) is on the wiki.
For developers
Other plugins can apply templates and read item data through the developer API. Setup and dependency instructions are on the wiki.
评论 0
登录后参与评分
还没有评论,来抢沙发吧