# LLTerritory 图标资源包与发布说明
## 项目简介
这套交付为 `LLTerritory` 插件提供了一整套可直接使用的 Bedrock 菜单图标方案，目标是让 `SimpleForm` 菜单从纯文字入口升级为带图标的功能菜单。
当前仓库包含两部分内容：
- 插件侧图标映射配置：`plugins/LLTerritory/ui-icons.json`
- 客户端资源包：`LLTerritory_Icons_RP/`
图标接入逻辑已经在插件脚本中完成，资源包也已经实测通过。你后续要做的通常只有两件事：启用资源包，或替换同名 PNG。
## 当前交付
- `111` 个 `32x32 PNG` 按钮图标，位于 `LLTerritory_Icons_RP/textures/ui/llterritory/`
- `pack_icon.png` 资源包封面图
- `plugins/LLTerritory/ui-icons.json` 图标键名与材质路径映射
- 兼容现有脚本逻辑的回退机制：缺图时优先走默认图标，再退回纯文字按钮
## 目录结构
```text
codex/
├─ LLTerritory_v3.js
├─ README.md
├─ plan.md
├─ plugins/
│ └─ LLTerritory/
│ └─ ui-icons.json
└─ LLTerritory_Icons_RP/
├─ manifest.json
├─ pack_icon.png
├─ README.md
└─ textures/
└─ ui/
└─ llterritory/
└─ *.png
```
## 安装步骤
### 1. 放置插件侧映射文件
确保服务器上的 `plugins/LLTerritory/ui-icons.json` 与当前仓库版本一致，并和插件脚本一起部署。
### 2. 放置资源包
把 `LLTerritory_Icons_RP` 放到你的 Bedrock 资源包目录，或者放到服务器/世界会向玩家下发的资源包位置。
### 3. 启用资源包
让客户端加载这个资源包，或让服务器自动下发给玩家。只有客户端拿到这套贴图，`SimpleForm` 按钮上的材质路径才会显示成图标。
### 4. 进服抽测
建议至少抽测这些页面：
- 主菜单
- 领地管理
- 城镇主菜单
- 公共大厅
- 管理后台
- 模板中心
- 备份中心
## `ui-icons.json` 的作用
`ui-icons.json` 负责把插件里用到的 `iconKey` 映射到资源包贴图路径。
配置结构固定为：
```json
{
"enabled": true,
"fallback": "common.default",
"paths": {
"main.create": "textures/ui/llterritory/main_create",
"land.boundary": "textures/ui/llterritory/land_boundary"
}
}
```
说明：
- `enabled`：是否启用图标
- `fallback`：某个键找不到贴图时使用的默认图标键
- `paths`：`iconKey -> 材质路径` 映射表
注意：
- `paths` 里的路径不带 `.png` 后缀
- 不建议随意改现有键名
- 默认优先通过替换同名 PNG 来换图，不需要改脚本
## 如何替换图标
最稳的做法是直接替换同名文件。
例如你想重做“创建领地”按钮图标，只需要替换：
```text
LLTerritory_Icons_RP/textures/ui/llterritory/main_create.png
```
替换时建议遵守这些规则：
- 保持文件名不变
- 保持尺寸为 `32x32`
- 保持透明背景
- 保持像素风和对比度，避免在游戏里看不清
## 什么时候才需要改路径映射
只有在你真的要改文件名或目录层级时，才需要同步修改 `plugins/LLTerritory/ui-icons.json`。
例如把：
```json
"main.create": "textures/ui/llterritory/main_create"
```
改成别的路径后，你必须保证资源包里存在对应 PNG，否则客户端会显示不出图标。
## 回退规则
当前图标系统的回退顺序如下：
1. 先读取当前按钮自己的 `iconKey`
2. 如果贴图缺失，回退到 `fallback`
3. 如果 `fallback` 也不可用，则按钮仍以纯文字方式显示
这意味着：
- 资源包没加载时，菜单依然能开
- 个别图标缺失时，不会把整个页面弄坏
- 旧服升级时，不需要为图标额外改菜单逻辑
## 基础验收建议
完成部署后，建议按下面顺序检查：
1. 确认资源包加载成功，图标能正常显示
2. 确认按钮顺序、回调索引、权限判断没有偏移
3. 抽测主菜单和高频二级页，确认没有错图、空白图、路径写错
4. 临时禁用资源包或删掉一张图，确认回退逻辑仍然正常
## 维护建议
- 想换美术风格时，优先替换同名 PNG
- 想增加新图标键时，再同时修改脚本与 `ui-icons.json`
- 每次改完资源包后，最好进服抽测一次主菜单和领地管理菜单
这份 `README.md` 是当前仓库的主发布说明；资源包目录里的 `README.md` 只保留轻量说明与入口指引。
