界面自定义与资源包

资源包提供科技面板、分支线、物品节点和锁定 / 可研究 / 已完成三种外观，配合默认 12 章、97 节点路线。客户端无需功能模组，但必须加载资源包。目标为 Minecraft Java 26.2，资源格式为 88.0。

本次同时包含 compact 和 normal 两套字体与图片。默认紧凑面板为 234×198 GUI 像素、22×22 节点；标准面板为 288×252、28×28 节点。紧凑面板相对旧尺寸减少约 36% 面积。完整玩法与研究条件见 默认生存路线与自定义。

文件用途

安装包内路径	用途
resourcepack/LiTechTree-UI.zip	独立客户端资源包，可本地启用，或通过现有发包系统提供。
plugins/CraftEngine/resources/litechtree_dialog_ui/	已整理的 CE 独立内容包，包含 pack.yml、字体图片和原版素材来源记录。
plugins/LiTechTree/ui-layout.yml	与本次资源配套的服务端字体、坐标与样式签名。
plugins/LiTechTree/ui.yml	管理员配置：预设、按钮、显示选项和绘图参数。
resource-builder/	资源构建脚本、默认树/UI 配置与图标缓存，用于下文的深度自定义。

生成器另会输出 pack/tree-ui-manifest.json 构建记录和 previews/ 合成预览；后者不属于实机截图。原版素材版权属于 Mojang Studios / Microsoft。

资源不会修改 minecraft:default、原版按钮贴图或其他插件字体。平面物品图标取自原版贴图，支持的方块图标由原版模型和贴图进行固定视角投影。

合入现有 CraftEngine

首次安装可将安装包内 plugins/CraftEngine/resources/litechtree_dialog_ui/ 复制到服务器的同名目录。更新时先备份该独立目录，再替换本插件自己的素材。若使用生成器自定义，则将本次生成的 pack/assets/ 复制到该目录的 resourcepack/assets/：

服务器目录\plugins\CraftEngine\resources\litechtree_dialog_ui\
├─ pack.yml
└─ resourcepack\
   └─ assets\
      └─ litechtree\
         ├─ font\
         │  ├─ space.json
         │  └─ tree\
         │     ├─ compact\
         │     └─ normal\
         └─ textures\
            └─ tree\
               ├─ compact\
               └─ normal\

pack.yml 示例：

# 内容包作者；原版图标来源另见 asset-sources.json。
author: LaoLi
# 内容包版本，升级时随 LiTechTree 发布版本更新。
version: 1.3.1
# 展示说明，可按服务器需要修改。
description: LiTechTree 可定制图形 Dialog 科技树
# 命名空间，必须与插件引用的字体一致。
namespace: litechtree

将同次生成的 ui-layout.yml 复制到 服务器目录\plugins\LiTechTree\ui-layout.yml。先备份旧清单与旧 litechtree_dialog_ui 文件夹，再更新该独立目录。不要覆盖其他 CE 内容包、托管设置或管理员的自定义树。

从旧默认配置升级时，插件会识别未修改的 1.2.3 默认树和布局，先备份再更新；自定义树只导出新版示例，不自动合并。若服务器用的是自定义树，交付包内默认清单不适用于它，应先按下文重建专用包。

资源包生成与发送分别执行：

1. 执行 /ce reload all，读取新增内容包并生成合并资源包，等待控制台报告成功。
2. 若 CE 配置启用 resource-pack.delivery.auto-upload: true 和 resend-on-upload: true，生成成功后按现有托管方式上传并重发；不要在过程中手动发送旧包。
3. 需要单独重发时执行 /ce feature send-pack 玩家名，向全部在线玩家重发可用 /ce feature send-pack @a。这个命令只发送，不生成资源包。
4. 客户端下载并应用完成后，执行 /tech reload，再由玩家 /tech 查看。

若自动上传关闭，且实际托管方式需要上传，在生成成功后执行 /ce upload，完成后再发包。只更新已启用的资源素材时可用 /ce reload pack；首次加入独立内容包优先用 /ce reload all。控制台命令去掉开头的 /。

这些命令以服务器实际 CE 版本为准；管理员若改过命令别名或以后升级 CE，请按实际版本的生成、托管和发送流程执行。

先调小：无需重发资源包

在 plugins/LiTechTree/ui.yml 选择已打包的预设：

# 当前预设：compact 为紧凑，normal 为旧版标准尺寸。
# 两套素材已同时打包，修改此项后 /tech reload 即可。
preset: compact

预设	画布宽 × 高	节点大小	列间距 / 行间距
compact，默认	234×198	22×22	26 / 36
normal	288×252	28×28	32 / 45

这里的尺寸是 GUI 像素，实际屏幕占用还受客户端界面缩放影响。只有已经包含在当前客户端资源包和服务端清单中的预设，才能直接切换；旧 1.2.3 包没有紧凑预设，首次升级仍须发本次新包。

以下顶层选项同样只需 /tech reload，不重建图片：

选项	用途	合法值
navigation-button-width	上一章 / 目录 / 下一章按钮宽度	整数 40~200
action-button-width	详情研究 / 返回 / 关闭按钮宽度	整数 60~300
detail-width	详情正文宽度	整数 180~500
chapter-columns	章节目录每行按钮数	整数 1~3
chapter-button-width	章节目录按钮宽度	整数 60~300
hover-enabled	节点悬浮说明开关	true / false
show-balance	树页面研究点显示开关	true / false

改尺寸、配色或节点：成套重建

群内提供的安装包的 resource-builder/ 包含配套资源生成脚本、默认树和 UI 配置以及图标缓存。解压后在 resource-builder/ 目录执行下列命令；它仅生成资源图片与清单，不包含插件 Java 源码或测试工程。仅切换现有预设、按钮和文案无需运行生成工具。

presets 内的画布尺寸、节点大小、行列间距、边距、背景色、边框、连线和节点三种状态颜色都会生成到字体图片中。修改这些参数，或新增自己的预设，必须使用实际 ui.yml 的 --ui 参数重建。

tree.yml 的节点 ID、所属章节、位置 slot、图标 icon、前置 parents 或节点集合变化，也要重建。只改名称、说明、研究条件、费用、首次奖励与配方权限，不需要重绘，用 /tech reload 即可。

打开 PowerShell，先进入解压后的 resource-builder/，安装依赖并生成默认包：

cd resource-builder
python -m pip install Pillow PyYAML
python tools/build_tree_pack.py --ui 'src/main/resources/ui.yml'

为服务器实际配置生成独立输出，同时传入 --tree 和 --ui：

python tools/build_tree_pack.py --tree '服务器目录\plugins\LiTechTree\tree.yml' --ui '服务器目录\plugins\LiTechTree\ui.yml' --output '.\resourcepack\server\pack'

自定义构建输出：

resourcepack/server/pack/assets/litechtree/  最新字体与图片
resourcepack/server/ui-layout.yml          与本次包配套的清单
resourcepack/server/LiTechTree-UI.zip        独立资源包
resourcepack/server/previews/               各预设和章节的合成预览

将本次 assets/ 更新到 CE 独立内容目录，并将同一输出目录旁的 ui-layout.yml 更新到服务端。随后生成、托管、重发 CE 包，再 /tech reload。不要混用默认清单和自定义素材，也不要只改服务器清单中的尺寸。

新清单记录每个预设的尺寸、配色 SHA-256 签名，以及每章节点 ID、位置、图标和前置。插件发现当前绘图配置或节点布局不匹配时，会提示重建并拒绝打开该章，避免图形与点击区域错位。该检查不能读取客户端本地缓存，客户端仍需接收同次新包。

预设参数范围

参数	合法值或约束
预设 ID	1~32 位小写字母、数字、下划线或连字符
width	整数 180~360，必须覆盖全部节点
height	整数 153~360，必须为 9 的倍数
node-size	整数 16~40，不能大于行距或列距
column-spacing	整数 18~40
row-spacing	整数 27~63，必须为 9 的倍数
left-padding	整数 0~40
top-padding	整数 0~54，必须为 9 的倍数
background、连线颜色、各状态颜色	带引号的 '#RRGGBB'
border、lines.enabled	true / false

画布必须满足 left-padding + 8 × column-spacing + node-size ≤ width 与 top-padding + 4 × row-spacing + node-size ≤ height，否则会拒绝加载。复制完整 normal 或 compact 段创建自定义预设，可以保留所有必需字段后再逐项修改。

slot 范围仍为 0~44，表示 9 列 × 5 行。同章不能重复；实际坐标由当前预设计算：x = left-padding + (slot % 9) × column-spacing，y = top-padding + floor(slot / 9) × row-spacing。建议前置在上、后继在下。跨章前置不绘制本章连线，但仍会检查，并在说明和详情中列出。

可研究状态需要前置、材料、等级等条件与研究点同时满足；未就绪显示暗色，已研究显示完成状态。最终确认时会重新检查条件，避免玩家在打开页面后移动物品造成绕过。

图标与构建检查

构建器优先读取 src/main/resources/tree-ui/icons/ 的图标缓存。新增材质缺少缓存时，可加 --client '原版26.2客户端Jar路径'；省略时尝试 %APPDATA%\.minecraft\versions\26.2\26.2.jar。方块自动投影支持轴对齐模型，不支持的材质会明确报错，可在缓存目录提供对应小写材质名 RGBA PNG，例如 diamond_sword.png；配置中的材质仍必须是有效 Bukkit 物品材质。

只有 --tree 与 --ui 都使用项目默认源文件时，构建器才同步 Jar 源资源中的默认清单。管理员自定义构建不覆盖默认清单。构建会核对字形实际宽度和 advance，并把预览图排除在资源 ZIP 外。

常见问题

现象	检查方法
树还是太大	确认新包已加载，ui.yml 中使用 preset: compact 后重载；同时检查客户端界面缩放。
切换 compact 后提示不匹配	旧包或旧清单尚未升级，成套更新本次双预设资源。
改了颜色没有变化	presets 内的颜色需要 --ui 重建，更新清单并重新发包。
图标方框、面板空白	确认客户端应用新包，CE 合并包中存在 assets/litechtree/font/tree/compact/ 与对应纹理。
提示布局已变更	按实际 tree.yml 和 ui.yml 重建，同次更新素材与清单，再重载。
图形与点击位置不同	客户端缓存可能仍是旧包，完成生成、托管和重发后再打开。不要手改码位或清单坐标。
节点暗色、无法研究	查看详情中的前置、原版 / CE 材料、等级、权限、进度和研究点，缺项会显示。
明明有同材质物品仍不足	CE 自定义物品与原版材料分开统计；把 CE 物品写入 ce-items。库存包含主背包、装备、副手，不检查箱子或末影箱。
撤销后研究没有再发奖励	首次奖励历史保留，这是防重复领奖的设计。
点击无反应	页面可能超过 3 分钟或被重载失效，重新 /tech。
CE 合成仍未开放	核对节点权限与目标配方 permission 一致，检查 CE 版本支持条件且研究成功。

图片生成、服务端加载、实机显示、鼠标点击与真实 CE 合成都应分别验收。previews/ 仅是合成预览，实际客户端步骤与证据入口见 更新日志与验证。