04. 索引与数据字段详解

本章字段取自公开枪包的实际文件。TaCZ 版本之间字段可能微调——动手前请以你本机 tacz/tacz_default_gun 的对应文件为准，那里是最权威的"字段字典"。

4.1 index/guns/<id>.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
}

字段	必填	说明
name	✅	显示名的语言键（去 lang/zh_cn.json 找对应文字）
tooltip	⬜	物品描述的键
display	✅	指向 assets/<ns>/display/guns/<id>_display.json（写逻辑名 <id>_display，不带后缀）
data	✅	指向 data/<ns>/data/guns/<id>_data.json
type	✅	枪种：rifle / smg / pistol / sniper / shotgun / mg / rpg / melee 等（影响默认动画与部分行为）
item_type	✅	大类：modern_kinetic（现代动能）/ old_kinetic（老式）/ energy（能量）等
sort	⬜	创造物品栏排序，数字更小更靠前

4.2 index/ammo/<id>.json —— 弹药登记

{
  "name": "mypack.ammo.556x45.name",
  "display": "mypack:556x45_display",
  "stack_size": 60,
  "sort": 100
}

字段	说明
stack_size	一叠最多多少发（别超过原版堆叠上限太多）

4.3 index/attachments/<id>.json —— 配件登记

{
  "name": "mypack.attachment.scope_m4a1.name",
  "display": "mypack:scope_m4a1_display",
  "data": "mypack:scope_m4a1_data",
  "type": "scope"
}

字段	说明
type	槽位类型：scope（瞄具）/ muzzle（枪口）/ grip（握把）/ stock（枪托）/ extended_mag（扩容弹匣）/ laser（激光）等

4.4 data/guns/<id>_data.json —— 枪的数值

① 基础与弹药

字段	说明	例
ammo	用哪种弹药（完整 id）	"mypack:556x45"
ammo_amount	弹匣容量	30
extended_mag_ammo_amount	扩容弹匣各档容量数组	[30, 45, 60]
script / script_param	特殊装填逻辑（如扩容弹匣）	"tacz:xmag_reload_logic"

② 射击方式

字段	说明
bolt	closed_bolt / open_bolt（是否每发都需要上膛类行为）
rpm	每分钟射速（600 = 每秒 10 发）
fire_mode	可切换模式数组：["auto","semi","burst"]

③ 弹道（bullet）

字段	说明
damage	单发伤害（平衡最常改）
bullet_amount	一次射出几发弹丸（霰弹用；此时"总伤害 = damage × bullet_amount"）
speed	初速（越高弹道越平直）
gravity	重力下坠系数
life	弹丸存活时间（秒）
pierce	可穿透的实体数
knockback	击退
friction	空气阻力（越小越"飘"得远）
ignite_entity_time	命中点燃时长（燃烧弹）
tracer_count_interval	每隔几发显示曳光（0 = 不发）
extra_damage.armor_ignore	无视护甲比例（0~1）
extra_damage.head_shot_multiplier	爆头倍率（默认手感的核心参数之一）
extra_damage.damage_adjust	距离衰减表：[{ "distance": 30, "damage": 9 }, { "distance": "infinite", "damage": 6 }]

④ 装填（reload）

字段	说明
reload.type	magazine（换弹匣）等
reload.infinite	是否无限弹药（调试/特殊玩法用）
reload.feed.empty / .tactical	空仓换弹 / 战术换弹的"开始吃子弹"时间（秒）
reload.cooldown.empty / .tactical	两者的"结束冷却"时间（秒）

💡 两个时间的关系：feed 决定什么时候弹匣数量跳变，cooldown 决定什么时候能再次开火/开镜。空仓永远比战术换弹慢。

⑤ 手持手感

字段	说明
draw_time / put_away_time	切出 / 收起时间（秒）
aim_time	开镜时间
sprint_time	冲刺后收枪/开火准备时间
weight	重量（影响移速惩罚的手感）
movement_speed.base/aim/reload	基础 / 开镜 / 换弹时移速加成（负数=减速）
can_crawl / can_slide	是否允许趴下 / 滑铲（需配合玩法模组）

⑥ 音效与表现相关的数据

字段	说明
fire_sound.fire_multiplier	开火音量倍率
fire_sound.silence_multiplier	消音时的音量倍率

想调"音量/音色"本身要去 display.sounds 指向的 ogg 文件；这里只是倍率。

4.5 data/attachments/<id>_data.json —— 配件数值

{
  "weight": 0,
  "ads_addend": 0.1
}

字段	说明
weight	重量（叠加到枪上）
ads_addend	开镜速度修正（正数=更慢/更稳，按版本含义可能相反，改动后务必进游戏实测）

4.6 assets/<ns>/display/guns/<id>_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",
  "third_person_animation": "default",
  "iron_zoom": 1.33,
  "zoom_model_fov": 45,
  "ammo_count_style": "normal",
  "damage_style": "per_projectile",
  "show_crosshair": false,
  "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"
  }
}

字段	说明
model	geo_models/gun/<id>_geo.json（引用写 gun/m4a1_geo）
texture	textures/gun/uv/<id>.png
slot	背包图标 textures/gun/slot/<id>.png
hud	HUD 图案 textures/gun/hud/<id>.png（可选）
animation	animations/<id>.animation.json
use_default_animation	缺动画时复用的本体动画模板（rifle/pistol/…）——新枪强烈建议写上
third_person_animation	第三人称动画方案（default 等）
iron_zoom	机械瞄具的放大倍率
zoom_model_fov	开镜时的模型 FOV（越小越"推近"）
ammo_count_style	弹药数显示风格
damage_style	伤害显示口径（per_projectile = 按单颗弹丸）
show_crosshair	是否显示原版准星（枪械一般 false）
transform.scale.*	第三人称 / 掉落物 / 展示框的缩放
sounds	音效引用（不带 .ogg）

弹药 display 最小就一行：

{ "slot": "mypack:ammo/slot/556x45" }

配件 display 通常是 model / texture / slot 三件，套路与枪一致。

4.7 「我想改 XX，该动哪个字段」速查

想要的效果	改哪里
打得更疼	bullet.damage（霰弹注意 bullet_amount）
爆头更狠	bullet.extra_damage.head_shot_multiplier
射速更快	rpm（注意它和 fire_mode 的配合）
换弹更快	reload.feed.* / reload.cooldown.*
弹匣更大	ammo_amount（+ extended_mag_ammo_amount 若用扩容）
开镜更快	aim_time、display.iron_zoom
切枪更快	draw_time / put_away_time
远距离衰减更小	bullet.extra_damage.damage_adjust
模型太大/太小	display.transform.scale.*
枪名/描述	lang/*.json（不是 index！）
音量太大	fire_sound.fire_multiplier 或换 ogg