03. 从零做一把枪（10 步照抄）¶
这一节是一整条主线：从空文件夹到游戏里能拿着开火。全程只需要文本编辑器，不需要写 Java。
📦 建议先做的事：把游戏目录下
tacz/tacz_default_gun/整体复制一份到你自己的工作目录，当作"格式说明书"。每一步都可以对照默认枪的文件来写。
Step 0 · 前置检查¶
| 检查项 | 怎么查 |
|---|---|
| TaCZ 装了没（客户端 + 服务端） | 启动游戏后看模组列表 / .minecraft/mods/ 里有 tacz 的 jar |
| 枪包目录在哪 | 单人：.minecraft/tacz/；服务器：<服务器根>/tacz/ |
| 版本对不对 | 枪包格式跟 TaCZ 版本走，别拿 1.21 的包塞进 1.20.1 |
| 有没有备份 | 改之前把要动的枪包复制一份，出了事能回滚 |
| 编辑器 | VS Code 之类带 JSON 校验的最省心（JSON 不允许注释和尾逗号） |
Step 1 · 建目录 + 写 gunpack.meta.json¶
mypack/
├─ gunpack.meta.json
├─ data/mypack/
└─ assets/mypack/
// mypack/gunpack.meta.json
{
"namespace": "mypack"
}
namespace全小写。它就是后面所有引用里的前缀mypack:xxx。
Step 2 · 写包信息 assets/mypack/gunpack_info.json¶
{
"version": "1.0.0",
"name": "我的第一个枪包",
"desc": "练习用，从 M4A1 开始",
"license": "GPL-3.0",
"authors": ["你的名字"],
"date": "2026-09-26"
}
Step 3 · 写枪的登记 data/mypack/index/guns/m4a1.json¶
{
"name": "mypack.gun.m4a1.name",
"tooltip": "mypack.gun.m4a1.desc",
"display": "mypack:m4a1_display",
"data": "mypack:m4a1_data",
"type": "rifle",
"item_type": "modern_kinetic",
"sort": 100
}
Step 4 · 写弹药登记 data/mypack/index/ammo/556x45.json¶
{
"name": "mypack.ammo.556x45.name",
"display": "mypack:556x45_display",
"stack_size": 60,
"sort": 100
}
Step 5 · 写枪的数值 data/mypack/data/guns/m4a1_data.json¶
{
"ammo": "mypack:556x45",
"ammo_amount": 30,
"bolt": "closed_bolt",
"rpm": 600,
"fire_mode": ["auto", "semi"],
"bullet": {
"life": 0.8,
"bullet_amount": 1,
"damage": 9,
"speed": 250,
"gravity": 0.15,
"pierce": 1,
"extra_damage": {
"armor_ignore": 0.25,
"head_shot_multiplier": 2.0,
"damage_adjust": [
{ "distance": 30, "damage": 9 },
{ "distance": "infinite", "damage": 6 }
]
}
},
"reload": {
"type": "magazine",
"feed": { "empty": 2.25, "tactical": 1.55 },
"cooldown": { "empty": 2.6, "tactical": 2.0 }
},
"draw_time": 0.35,
"put_away_time": 0.57,
"aim_time": 0.2,
"weight": 3.5,
"movement_speed": { "base": 0, "aim": -0.2, "reload": -0.15 }
}
Step 6 · 写表现 assets/mypack/display/guns/m4a1_display.json¶
{
"model": "mypack:gun/m4a1_geo",
"texture": "mypack:gun/uv/m4a1",
"slot": "mypack:gun/slot/m4a1",
"hud": "mypack:gun/hud/m4a1",
"animation": "mypack:m4a1",
"use_default_animation": "rifle",
"iron_zoom": 1.33,
"transform": {
"scale": {
"thirdperson": [0.6, 0.6, 0.6],
"ground": [0.6, 0.6, 0.6],
"fixed": [1.2, 1.2, 1.2]
}
},
"sounds": {
"shoot": "mypack:m4a1/shoot",
"reload": "mypack:m4a1/reload",
"draw": "mypack:m4a1/draw"
}
}
Step 7 · 弹药表现 assets/mypack/display/ammo/556x45_display.json¶
{
"slot": "mypack:ammo/slot/556x45"
}
Step 8 · 放素材（模型 / 动画 / 贴图 / 音效 / 语言）¶
| 文件 | 从哪来 |
|---|---|
assets/mypack/geo_models/gun/m4a1_geo.json |
Blockbench 导出（或先复制默认枪的 geo 改名） |
assets/mypack/animations/m4a1.animation.json |
Blockbench 导出（或复制默认枪动画改名） |
assets/mypack/textures/gun/uv/m4a1.png |
你的枪身贴图 |
assets/mypack/textures/gun/slot/m4a1.png |
背包图标（32×32 即可） |
assets/mypack/tacz_sounds/m4a1/shoot.ogg |
你的音效（Ogg Vorbis） |
assets/mypack/lang/zh_cn.json |
见下 |
// assets/mypack/lang/zh_cn.json
{
"pack.mypack.name": "我的第一个枪包",
"pack.mypack.desc": "练习用，从 M4A1 开始",
"mypack.gun.m4a1.name": "M4A1 突击步枪",
"mypack.gun.m4a1.desc": "自制枪包里的第一把枪",
"mypack.ammo.556x45.name": "5.56×45mm 弹药"
}
Step 9 · 装进游戏并验证¶
- 把
mypack/整个文件夹（或打成 zip）放进.minecraft/tacz/；多人服再复制一份到服务器tacz/； - 重进游戏（客户端）/ 重启服务端；
- 按顺序确认：
- 创造模式物品栏搜 "M4A1" → 能搜到（= index 与 lang 生效）
- 拿在手里 → 有模型有贴图（= display + geo + texture 生效）
- 右键 / 左键 → 能开枪、有音效（= data + tacz_sounds 生效）
- 按 R → 能换弹（= ammo 索引 + reload 字段生效）
Step 10 · 常见失败点速查¶
| 现象 | 先去查 |
|---|---|
| 物品栏搜不到 | gunpack.meta.json 有没有；index 层级对不对（data/<ns>/index/guns/） |
| 搜到但拿不到/是空气 | display 里的引用路径错 |
| 白模 | texture 路径错（对照 textures/gun/uv/<id>.png） |
| 没有动画 | animations 名字/骨骼名不对，或 use_default_animation 没写 |
| 能开枪但没声音 | sounds 路径错，或少了 .ogg 文件 |
| 名字是键名 | lang/zh_cn.json 没写或键不一致 |
| 单人正常多人不行 | 服务端 tacz/ 没放枪包 |
做出来之后：三步进阶¶
① 能开火（本章） → 只关心"目录对不对、引用通不通"
② 手感像样 → 调 data（射速/后坐/装填/伤害）+ display（缩放/开镜/HUD）
③ 长得像自己的枪 → Blockbench 做模型动画 + 画 UV 贴图 + 录/找音效
💡 进阶阶段最省事的做法：每次只改一个变量（比如只改
rpm），进游戏验证一次；一次改十个字段，出问题根本不知道是哪个。