02. 一个枪包的完整目录结构¶

全景图¶

mypack/                                  ← 枪包根目录（名字随意，就是"包名"）
├─ gunpack.meta.json                     ★ 必需：声明命名空间（全小写）
├─ data/
│   └─ mypack/                           ← 目录名 = 命名空间
│       ├─ index/                        ← "登记表"：有哪些东西
│       │   ├─ guns/<枪id>.json
│       │   ├─ ammo/<弹药id>.json
│       │   ├─ attachments/<配件id>.json
│       │   └─ blocks/<方块id>.json
│       ├─ data/                         ← "数值表"：东西长什么样
│       │   ├─ guns/<枪id>_data.json
│       │   ├─ ammo/<弹药id>_data.json
│       │   ├─ attachments/<配件id>_data.json
│       │   └─ blocks/<方块id>_data.json
│       ├─ recipes/                      ← 配方
│       │   ├─ gun/<枪id>.json           ← 枪械工作台配方
│       │   └─ …（普通合成配方）
│       └─ tacz_tags/                    ← 标签：约束"谁能装谁"
│           └─ attachments/
│               ├─ allow_attachments/<枪id>.json     ← 这把枪允许哪些配件
│               └─ <槽位类型>.json                    ← 这个槽位允许哪些配件
└─ assets/
    └─ mypack/
        ├─ gunpack_info.json             ★ 必需：包信息（版本/名字/作者/许可）
        ├─ icon.png                      ← 枪包列表里显示的图标（可选）
        ├─ lang/
        │   ├─ zh_cn.json
        │   └─ en_us.json
        ├─ display/                      ← "怎么显示、怎么发声"
        │   ├─ guns/<枪id>_display.json
        │   ├─ ammo/<弹药id>_display.json
        │   ├─ attachments/<配件id>_display.json
        │   └─ blocks/<方块id>_display.json
        ├─ geo_models/                   ← 基岩版几何模型
        │   ├─ gun/<枪id>_geo.json
        │   ├─ attachment/<配件id>_geo.json
        │   └─ block/<方块id>_geo.json
        ├─ animations/<枪id>.animation.json      ← 基岩版动画
        ├─ textures/
        │   ├─ gun/uv/<枪id>.png        ← 枪身 UV
        │   ├─ gun/slot/<枪id>.png      ← 背包图标
        │   ├─ gun/hud/<枪id>.png       ← HUD 图案
        │   ├─ attachment/uv/<配件id>.png
        │   ├─ attachment/slot/<配件id>.png
        │   ├─ ammo/slot/<弹药id>.png
        │   └─ block/uv/<方块id>.png
        ├─ tacz_sounds/                  ← 音效
        │   └─ <枪id>/shoot.ogg、reload.ogg …
        └─ scripts/                      ← 状态机脚本（进阶，可选）
            └─ <枪id>_state_machine.lua

每个位置干什么¶

位置	作用	少写会怎样
`gunpack.meta.json`	声明 `namespace`	整个包不加载
`assets/<ns>/gunpack_info.json`	包的名字/版本/作者	枪包列表里没有条目（部分版本容忍缺失，但强烈建议写）
`data/<ns>/index/**`	登记"有哪些枪/弹药/配件"	游戏里找不到这把枪
`data/<ns>/data/**`	枪的数值（伤害/射速/装填…）	枪出现但无数据（行为异常/无法开火）
`assets/<ns>/display/**`	模型/贴图/动画/音效的引用	枪是白模 / 无声 / 无动画
`data/<ns>/recipes/**`	合成配方	只能靠创造模式拿枪
`data/<ns>/tacz_tags/**`	配件与枪的匹配关系	配件装不上去（若不用配件可省）
`assets/<ns>/lang/**`	中英文本地化	显示成 `mypack.gun.xx.name` 键名

🧠 三件套：index / data / display¶

一把枪永远由这三个文件描述，三者的关系是"引用"：

index/guns/m4a1.json          ← 登记：名字 + 指向另外两个
   ├── "data":    "mypack:m4a1_data"      → data/guns/m4a1_data.json（数值）
   └── "display": "mypack:m4a1_display"   → assets/mypack/display/guns/m4a1_display.json（表现）
                                                    ├── model   → geo_models/gun/m4a1_geo.json
                                                    ├── texture → textures/gun/uv/m4a1.png
                                                    ├── slot    → textures/gun/slot/m4a1.png
                                                    ├── animation → animations/m4a1.animation.json
                                                    └── sounds  → tacz_sounds/m4a1/*.ogg

路径换算表（最容易错的地方）¶

JSON 里写的引用	实际文件位置
`mypack:m4a1_data`	`data/mypack/data/guns/m4a1_data.json`
`mypack:m4a1_display`	`assets/mypack/display/guns/m4a1_display.json`
`mypack:gun/m4a1_geo`	`assets/mypack/geo_models/gun/m4a1_geo.json`
`mypack:m4a1`（动画）	`assets/mypack/animations/m4a1.animation.json`
`mypack:gun/uv/m4a1`	`assets/mypack/textures/gun/uv/m4a1.png`
`mypack:gun/slot/m4a1`	`assets/mypack/textures/gun/slot/m4a1.png`
`mypack:m4a1/shoot`（音效）	`assets/mypack/tacz_sounds/m4a1/shoot.ogg`

规则： - 命名空间:路径 里的 命名空间 = gunpack.meta.json 的 namespace； - 引用里不写文件扩展名（不写 .json / .png / .ogg）； - data / display 的引用指向"逻辑名"（m4a1_data），不是文件路径（data/guns/m4a1_data.json）——由 TaCZ 按约定去对应目录找； - 目录层级多一层/少一层 = 找不到。

命名规则（踩坑重灾区）¶

东西	规则	例子
namespace	全小写，建议 `[a-z0-9_]`	`mypack`、`ffluryy`、`tacz`（本体）
枪/配件 id	小写 + 下划线，与文件名一致	`m4a1`、`scope_sar21_default`
文件名后缀	数值 `_data.json`、表现 `_display.json`、模型 `_geo.json`、动画 `.animation.json`	`m4a1_data.json`
语言键	`<ns>.gun.<id>.name` / `.desc`；配件 `<ns>.attachment.<id>.name`	`mypack.gun.m4a1.name`
包名/包描述键	`pack.<ns>.name` / `pack.<ns>.desc`	`pack.mypack.name`

⚠️ 大写字母、中文、空格、连字符都可能出问题；统一用蛇形命名（snake_case）最稳。

最小骨架（可直接复制的空包）¶

mypack/
├─ gunpack.meta.json                    {"namespace":"mypack"}
├─ data/mypack/
│   ├─ index/guns/.gitkeep
│   └─ data/guns/.gitkeep
└─ assets/mypack/
    ├─ gunpack_info.json
    ├─ lang/zh_cn.json
    ├─ display/guns/.gitkeep
    ├─ geo_models/gun/.gitkeep
    ├─ animations/.gitkeep
    └─ textures/gun/uv/.gitkeep

（.gitkeep 只是占位文件，用来让空目录能提交到 git；TaCZ 不会读它。）

结构类错误自查¶

namespace 有没有大写？——大写 = 全包不加载。
是不是写成了 data/mypack/guns/…？——少了一层 data，正确的是 data/mypack/data/guns/…。
是不是写成了 assets/mypack/guns/…？——正确的是 assets/mypack/display/guns/…。
zip 里是不是多套了一层文件夹？——zip 根目录下应该直接是 data/、assets/、gunpack.meta.json。
文件名与 JSON 里的引用（data/display/model/texture）是否逐字符一致？