# CustomTextures 插件使用说明（Minecraft 1.12.2）
自写插件，用来给服务器加"原版物品换皮"：同样是钻石剑，名字叫红宝石剑的那把显示红宝石贴图，
普通钻石剑还是原版贴图。支持同一种材质做多套皮肤，互不串图。
---
## 一、装了什么
| 位置 | 说明 |
| --- | --- |
| `plugins\CustomTextures.jar` | 插件本体 |
| `plugins\CustomTextures\config.yml` | 配置（全中文注释） |
| `plugins\CustomTextures\textures\` | 你放贴图 png 的地方 |
| `plugins\CustomTextures\pack\CustomTextures.zip` | **封包产物**，给客户端用的资源包 |
---
## 二、第一次使用（4 步）
1. **启动服务器**（或 `/reload confirm`）。
控制台会出现：
```
[CustomTextures] 已生成资源包 ...\plugins\CustomTextures\pack\CustomTextures.zip（条目 7，物品模型 2，大小 2338 字节）
[CustomTextures] 资源包 SHA-1：639d56c183f09a33fa0571f5778ee99a59b2143d
[CustomTextures] 已加载 2 个自定义物品（/ct list 查看）
```
2. **资源包怎么到玩家手里**：
插件自带 HTTP 服务 + 进服自动下发，玩家进服会弹"是否下载资源包"，点"是"就自动装好。
3. **可选·手动启用**：进游戏 → `选项` → `资源包` → 找到 `CustomTextures` →
点箭头把它移到右侧（已选） → `完成`。想立即看到效果按 `F3 + T` 重载资源包。
4. **发物品试试**：
```
/ct give 你的名字 ruby_sword
/ct give 你的名字 sapphire_pickaxe
```
> 拿走物品后如果还是原版外观，99% 是第 2、3 步没生效：包里没这个 zip，或包没在右侧列表里。
---
## 三、常用命令
| 命令 | 作用 |
| --- | --- |
| `/ct list` | 列出已加载的自定义物品（带 Damage 值） |
| `/ct info <id>` | 看某个物品的详细配置 |
| `/ct give <玩家\|@a> <id> [数量]` | 发物品，数量 1~64 |
| `/ct build` | 重新封包（改了贴图/配置后用） |
| `/ct reload` | 重读 config.yml 并重新封包 |
| `/ct pack info` | 看下发状态：下载地址、SHA-1、已下发次数、HTTP 请求次数 |
| `/ct pack url` | 只打印资源包下载地址 |
| `/ct pack send <玩家\|@a>` | 立刻给玩家重发一次资源包 |
| `/ct pack restart` | 重启内置 HTTP 服务（改了端口/路径后） |
权限：`customtextures.use`（默认 OP）。
控制台执行命令不用加 `/`。
---
## 四、再加一个自定义物品（4 步）
以"翡翠弓"为例：
1. **放贴图**：把 16×16 或 32×32 的 png 放进 `plugins\CustomTextures\textures\`，比如 `emerald_bow.png`。
- 透明背景、画满整张画布；
- 尺寸大于 16×16 也行，客户端会自动缩放，但 16 的整数倍最稳。
2. **写配置**：在 `config.yml` 的 `items:` 下面加一段：
```yaml
emerald_bow:
material: BOW
offset: 1
texture: emerald_bow.png
display-name: "&a翡翠弓"
lore:
- "&7射出的箭会带绿色拖尾"
glow: true
unbreakable: true
enchantments: []
model-parent: ""
vanilla-texture: ""
```
3. **重载**：`/ct reload`（会顺带重新封包）。
4. **可选·手动更新客户端**：把新的 `pack\CustomTextures.zip` 重新复制进客户端 `resourcepacks`（覆盖旧的），
游戏里 `F3 + T`。**包内容变了，客户端就必须换包，否则看不到新贴图。**
### 关键规则：offset
1.12.2 没有"自定义物品贴图"接口，只能靠 **Damage 值**区分皮肤。插件给每个自定义物品分配一个
`offset`，物品实际 Damage = `该材质最大耐久 - offset`。
- 同一个 `material` 下，`offset` **不能重复**；重复时以 config.yml 里**先写**的那个为准，
后写的会被跳过并在控制台提示（不会崩服）。
- 钻石剑最大耐久 1561 → offset 只能 1~1560。
- 剑、镐、斧、锹、锄、弓、盾、钓鱼竿、剪刀、打火石、胡萝卜钓竿都可以用；
`STONE`、`APPLE` 这类没有耐久的物品不行（插件会提示并跳过）。
- 从 CustomItems 迁移过来的老物品，Damage 和新插件对不上，会显示成原版——**重新用 `/ct give` 发**即可。
---
## 五、为什么"不影响原版材质"
插件给原版模型（比如 `diamond_sword.json`）加了一条判定：
"当 Damage/最大耐久 ≥ (Damage-0.5)/最大耐久 时，用 `item/ct/<id>` 这个模型"。
- 判定值是 `(Damage - 0.5) / 最大耐久`，只有 Damage 恰好落在本物品那一格才会命中；
- **条目顺序**：1.12.2 客户端读取模型时会把 `overrides` 列表整个倒过来存，匹配取"第一个命中"，
等于 **JSON 里越靠后的条目优先级越高**。插件按 Damage **升序**写入，客户端里就变成
"Damage 大的先匹配"，同一材质的多个物品因此互不抢皮（这一点已用客户端字节码核实）；
- 原版模型的 `layer0`、`display`、以及弓/钓鱼竿自带的 `pulling`/`cast` 覆盖都原样保留，
所以普通钻石剑、普通的弓完全不受影响。
已实测：同一材质放两把剑（offset 1 和 2），两把剑的 Damage 分别是 1560/1559，贴图互不串；
弓的自定义皮肤不影响原版拉弓动画。
---
## 六、和其他资源包冲突
资源包改的是同一批原版模型文件（`assets/minecraft/models/item/diamond_sword.json`）：
**后加载的包会覆盖先加载的包**。所以：
- 客户端 `resourcepacks` 里如果还有旧的 `CustomItems RP.zip`，请删掉或移走（否则它可能盖住新贴图）；
- 在 `资源包` 界面里，把 `CustomTextures` 拖到列表最上面（最高优先级）。
---
## 七、常见问题
| 现象 | 原因 / 处理 |
| --- | --- |
| **同材质两个物品显示同一张贴图** | v1.0.0 的 bug（把优先级顺序理解反了），v1.0.1 已修：插件按 Damage 升序写 overrides。升级 jar → `/ct build` → 把新 zip 覆盖进客户端 → `F3+T` |
| 发出来的物品是原版外观 | 客户端没启用包 / 包是旧版本 / 没有 `F3+T`。先 `/ct build`，再重新复制 zip |
| 控制台提示"贴图不存在" | png 文件名和 `texture:` 不一致，或没放进 `textures\` 目录 |
| 提示"占用了同一个槽位" | 同 material 下 offset 重复，改成 2、3…… |
| 提示"不是有效的原版物品" | `material` 拼错，或该物品没有耐久值 |
| 客户端提示"资源包不兼容" | `pack-format` 被改过，1.12.2 必须保持 `3` |
| 改了贴图但游戏里没变 | 客户端用的是旧 zip。重跑 `/ct build`，把新 zip 覆盖进客户端，`F3+T` |
| 服务器重启后物品变回原版 | 物品是在别的插件/命令里发的（没有插件写入的 Damage/NBT）。统一用 `/ct give` 发 |
| 玩家进服没弹资源包窗口 | `/ct pack info` 看地址；浏览器能否打开；防火墙/安全组是否放行 8123；公网服要填 `public-host` |
| 玩家点"是"后下载失败 | 同上；内网 IP 外网访问不到是最常见原因，改用公网地址或 `mode: external` |
---
## 八、服务器自动发资源包（v1.0.2 起）
插件自己就是一个小型 HTTP 文件服务器：启动后在 8123 端口把 `pack\CustomTextures.zip`
发出去，玩家进服时自动下发。**你不需要在本地电脑上开任何网页服务或工具**，
把 jar 丢进服务器的 `plugins` 目录、重启服务器就行。
### 8.1 默认行为
- 服务器启动 → 自动封包 → 监听 `0.0.0.0:8123`，路径 `/customtextures.zip`；
- 玩家进服 1 秒后收到资源包，客户端弹"是否下载资源包"，点"是"即自动下载并启用；
- 改完贴图 `/ct build`，在线玩家会自动收到新包（`resend-on-build: true`）。
### 8.2 配置（`config.yml` 的 `delivery:` 段，注释已写在文件里）
| 键 | 默认 | 说明 |
| --- | --- | --- |
| `enabled` | true | 总开关 |
| `mode` | embedded | `embedded` 插件自己发；`external` 只下发 `public-url` |
| `public-url` | 空 | external 模式必填，例如 `https://你的网站/CustomTextures.zip` |
| `public-host` | 空 | 玩家访问用的主机名/IP；留空=自动探测（内网 IP） |
| `bind-host` | 0.0.0.0 | 监听地址，一般不用改 |
| `port` | 8123 | 监听端口，被占用就换一个 |
| `path` | /customtextures.zip | 下载路径 |
| `send-on-join` | true | 进服自动下发 |
| `send-delay-ticks` | 20 | 进服后延迟多少 tick 再发（1 秒） |
| `resend-on-build` | true | 重新封包后给在线玩家发新包 |
| `force` | false | 拒绝/下载失败就踢人 |
| `kick-message` | 见文件 | 踢出提示，支持 `&` 颜色代码 |
### 8.3 公网 / 云服务器要点
1. **放行 TCP 8123**：Windows 防火墙（入站规则）和云厂商安全组都要放行。
2. 服务器在 NAT 后面时，插件自动探测到的是内网 IP（如 `192.168.x.x`），玩家连不上：
- 在 `public-host` 填公网 IP 或域名（推荐）；或
- `mode: external` + `public-url` 指向你已有的网站 / 对象存储。
3. 自测：`/ct pack url` 拿到地址，用浏览器打开，能下载到 zip 就说明通了。
### 8.4 强制模式
`force: true` 后，玩家点"否"或下载失败会被踢出（`kick-message` 可改文案）。
管理员要进服调试：给权限 `customtextures.bypasspack`（默认 false）。
### 8.5 注意
- **不要**在 `server.properties` 里填 `resource-pack=`，否则服务器会再发一份，两个包互相覆盖；
- 包由插件下发后，就不要再手动往客户端 `resourcepacks` 里塞同名 zip，免得版本对不上；
- `embedded` 和 `external` 二选一，一个玩家只能收到一个下载地址。
---
## 九、卸载
删掉 `plugins\CustomTextures.jar`、`plugins\CustomTextures\` 目录，
再把客户端 `resourcepacks` 里的 `CustomTextures.zip` 删掉即可。
已经发出去的物品会变回原版外观（Damage 还在，但不影响使用）。
自写插件，用来给服务器加"原版物品换皮"：同样是钻石剑，名字叫红宝石剑的那把显示红宝石贴图，
普通钻石剑还是原版贴图。支持同一种材质做多套皮肤，互不串图。
---
## 一、装了什么
| 位置 | 说明 |
| --- | --- |
| `plugins\CustomTextures.jar` | 插件本体 |
| `plugins\CustomTextures\config.yml` | 配置（全中文注释） |
| `plugins\CustomTextures\textures\` | 你放贴图 png 的地方 |
| `plugins\CustomTextures\pack\CustomTextures.zip` | **封包产物**，给客户端用的资源包 |
---
## 二、第一次使用（4 步）
1. **启动服务器**（或 `/reload confirm`）。
控制台会出现：
```
[CustomTextures] 已生成资源包 ...\plugins\CustomTextures\pack\CustomTextures.zip（条目 7，物品模型 2，大小 2338 字节）
[CustomTextures] 资源包 SHA-1：639d56c183f09a33fa0571f5778ee99a59b2143d
[CustomTextures] 已加载 2 个自定义物品（/ct list 查看）
```
2. **资源包怎么到玩家手里**：
插件自带 HTTP 服务 + 进服自动下发，玩家进服会弹"是否下载资源包"，点"是"就自动装好。
3. **可选·手动启用**：进游戏 → `选项` → `资源包` → 找到 `CustomTextures` →
点箭头把它移到右侧（已选） → `完成`。想立即看到效果按 `F3 + T` 重载资源包。
4. **发物品试试**：
```
/ct give 你的名字 ruby_sword
/ct give 你的名字 sapphire_pickaxe
```
> 拿走物品后如果还是原版外观，99% 是第 2、3 步没生效：包里没这个 zip，或包没在右侧列表里。
---
## 三、常用命令
| 命令 | 作用 |
| --- | --- |
| `/ct list` | 列出已加载的自定义物品（带 Damage 值） |
| `/ct info <id>` | 看某个物品的详细配置 |
| `/ct give <玩家\|@a> <id> [数量]` | 发物品，数量 1~64 |
| `/ct build` | 重新封包（改了贴图/配置后用） |
| `/ct reload` | 重读 config.yml 并重新封包 |
| `/ct pack info` | 看下发状态：下载地址、SHA-1、已下发次数、HTTP 请求次数 |
| `/ct pack url` | 只打印资源包下载地址 |
| `/ct pack send <玩家\|@a>` | 立刻给玩家重发一次资源包 |
| `/ct pack restart` | 重启内置 HTTP 服务（改了端口/路径后） |
权限：`customtextures.use`（默认 OP）。
控制台执行命令不用加 `/`。
---
## 四、再加一个自定义物品（4 步）
以"翡翠弓"为例：
1. **放贴图**：把 16×16 或 32×32 的 png 放进 `plugins\CustomTextures\textures\`，比如 `emerald_bow.png`。
- 透明背景、画满整张画布；
- 尺寸大于 16×16 也行，客户端会自动缩放，但 16 的整数倍最稳。
2. **写配置**：在 `config.yml` 的 `items:` 下面加一段：
```yaml
emerald_bow:
material: BOW
offset: 1
texture: emerald_bow.png
display-name: "&a翡翠弓"
lore:
- "&7射出的箭会带绿色拖尾"
glow: true
unbreakable: true
enchantments: []
model-parent: ""
vanilla-texture: ""
```
3. **重载**：`/ct reload`（会顺带重新封包）。
4. **可选·手动更新客户端**：把新的 `pack\CustomTextures.zip` 重新复制进客户端 `resourcepacks`（覆盖旧的），
游戏里 `F3 + T`。**包内容变了，客户端就必须换包，否则看不到新贴图。**
### 关键规则：offset
1.12.2 没有"自定义物品贴图"接口，只能靠 **Damage 值**区分皮肤。插件给每个自定义物品分配一个
`offset`，物品实际 Damage = `该材质最大耐久 - offset`。
- 同一个 `material` 下，`offset` **不能重复**；重复时以 config.yml 里**先写**的那个为准，
后写的会被跳过并在控制台提示（不会崩服）。
- 钻石剑最大耐久 1561 → offset 只能 1~1560。
- 剑、镐、斧、锹、锄、弓、盾、钓鱼竿、剪刀、打火石、胡萝卜钓竿都可以用；
`STONE`、`APPLE` 这类没有耐久的物品不行（插件会提示并跳过）。
- 从 CustomItems 迁移过来的老物品，Damage 和新插件对不上，会显示成原版——**重新用 `/ct give` 发**即可。
---
## 五、为什么"不影响原版材质"
插件给原版模型（比如 `diamond_sword.json`）加了一条判定：
"当 Damage/最大耐久 ≥ (Damage-0.5)/最大耐久 时，用 `item/ct/<id>` 这个模型"。
- 判定值是 `(Damage - 0.5) / 最大耐久`，只有 Damage 恰好落在本物品那一格才会命中；
- **条目顺序**：1.12.2 客户端读取模型时会把 `overrides` 列表整个倒过来存，匹配取"第一个命中"，
等于 **JSON 里越靠后的条目优先级越高**。插件按 Damage **升序**写入，客户端里就变成
"Damage 大的先匹配"，同一材质的多个物品因此互不抢皮（这一点已用客户端字节码核实）；
- 原版模型的 `layer0`、`display`、以及弓/钓鱼竿自带的 `pulling`/`cast` 覆盖都原样保留，
所以普通钻石剑、普通的弓完全不受影响。
已实测：同一材质放两把剑（offset 1 和 2），两把剑的 Damage 分别是 1560/1559，贴图互不串；
弓的自定义皮肤不影响原版拉弓动画。
---
## 六、和其他资源包冲突
资源包改的是同一批原版模型文件（`assets/minecraft/models/item/diamond_sword.json`）：
**后加载的包会覆盖先加载的包**。所以：
- 客户端 `resourcepacks` 里如果还有旧的 `CustomItems RP.zip`，请删掉或移走（否则它可能盖住新贴图）；
- 在 `资源包` 界面里，把 `CustomTextures` 拖到列表最上面（最高优先级）。
---
## 七、常见问题
| 现象 | 原因 / 处理 |
| --- | --- |
| **同材质两个物品显示同一张贴图** | v1.0.0 的 bug（把优先级顺序理解反了），v1.0.1 已修：插件按 Damage 升序写 overrides。升级 jar → `/ct build` → 把新 zip 覆盖进客户端 → `F3+T` |
| 发出来的物品是原版外观 | 客户端没启用包 / 包是旧版本 / 没有 `F3+T`。先 `/ct build`，再重新复制 zip |
| 控制台提示"贴图不存在" | png 文件名和 `texture:` 不一致，或没放进 `textures\` 目录 |
| 提示"占用了同一个槽位" | 同 material 下 offset 重复，改成 2、3…… |
| 提示"不是有效的原版物品" | `material` 拼错，或该物品没有耐久值 |
| 客户端提示"资源包不兼容" | `pack-format` 被改过，1.12.2 必须保持 `3` |
| 改了贴图但游戏里没变 | 客户端用的是旧 zip。重跑 `/ct build`，把新 zip 覆盖进客户端，`F3+T` |
| 服务器重启后物品变回原版 | 物品是在别的插件/命令里发的（没有插件写入的 Damage/NBT）。统一用 `/ct give` 发 |
| 玩家进服没弹资源包窗口 | `/ct pack info` 看地址；浏览器能否打开；防火墙/安全组是否放行 8123；公网服要填 `public-host` |
| 玩家点"是"后下载失败 | 同上；内网 IP 外网访问不到是最常见原因，改用公网地址或 `mode: external` |
---
## 八、服务器自动发资源包（v1.0.2 起）
插件自己就是一个小型 HTTP 文件服务器：启动后在 8123 端口把 `pack\CustomTextures.zip`
发出去，玩家进服时自动下发。**你不需要在本地电脑上开任何网页服务或工具**，
把 jar 丢进服务器的 `plugins` 目录、重启服务器就行。
### 8.1 默认行为
- 服务器启动 → 自动封包 → 监听 `0.0.0.0:8123`，路径 `/customtextures.zip`；
- 玩家进服 1 秒后收到资源包，客户端弹"是否下载资源包"，点"是"即自动下载并启用；
- 改完贴图 `/ct build`，在线玩家会自动收到新包（`resend-on-build: true`）。
### 8.2 配置（`config.yml` 的 `delivery:` 段，注释已写在文件里）
| 键 | 默认 | 说明 |
| --- | --- | --- |
| `enabled` | true | 总开关 |
| `mode` | embedded | `embedded` 插件自己发；`external` 只下发 `public-url` |
| `public-url` | 空 | external 模式必填，例如 `https://你的网站/CustomTextures.zip` |
| `public-host` | 空 | 玩家访问用的主机名/IP；留空=自动探测（内网 IP） |
| `bind-host` | 0.0.0.0 | 监听地址，一般不用改 |
| `port` | 8123 | 监听端口，被占用就换一个 |
| `path` | /customtextures.zip | 下载路径 |
| `send-on-join` | true | 进服自动下发 |
| `send-delay-ticks` | 20 | 进服后延迟多少 tick 再发（1 秒） |
| `resend-on-build` | true | 重新封包后给在线玩家发新包 |
| `force` | false | 拒绝/下载失败就踢人 |
| `kick-message` | 见文件 | 踢出提示，支持 `&` 颜色代码 |
### 8.3 公网 / 云服务器要点
1. **放行 TCP 8123**：Windows 防火墙（入站规则）和云厂商安全组都要放行。
2. 服务器在 NAT 后面时，插件自动探测到的是内网 IP（如 `192.168.x.x`），玩家连不上：
- 在 `public-host` 填公网 IP 或域名（推荐）；或
- `mode: external` + `public-url` 指向你已有的网站 / 对象存储。
3. 自测：`/ct pack url` 拿到地址，用浏览器打开，能下载到 zip 就说明通了。
### 8.4 强制模式
`force: true` 后，玩家点"否"或下载失败会被踢出（`kick-message` 可改文案）。
管理员要进服调试：给权限 `customtextures.bypasspack`（默认 false）。
### 8.5 注意
- **不要**在 `server.properties` 里填 `resource-pack=`，否则服务器会再发一份，两个包互相覆盖；
- 包由插件下发后，就不要再手动往客户端 `resourcepacks` 里塞同名 zip，免得版本对不上；
- `embedded` 和 `external` 二选一，一个玩家只能收到一个下载地址。
---
## 九、卸载
删掉 `plugins\CustomTextures.jar`、`plugins\CustomTextures\` 目录，
再把客户端 `resourcepacks` 里的 `CustomTextures.zip` 删掉即可。
已经发出去的物品会变回原版外观（Damage 还在，但不影响使用）。
