DS TACZ Compat

A compatibility mod that makes dragon players hold guns naturally in DragonSurvival with Timeless & Classics Zero (Unofficial NeoForge Port).

In vanilla DragonSurvival, a dragon holding a TACZ gun renders the weapon against the dragon's side with a drooping muzzle, wrong aim direction, and broken animations — and first person still shows the human arm model. This mod repositions the gun to float above the dragon's head, tracks the muzzle toward the camera in real time, and faithfully preserves muzzle flash, shell ejection, and tracer effects. It also bundles a suite of TACZ quality-of-life features and fixes made for dragon players.

Installation — this mod must be installed on both the client and the server, and both sides must run the exact same version. A client-only install cannot join a server that does not have this mod, and a version mismatch is rejected on connection.

---

Features

Gun Rendering

• Third-person floating gun — the gun hovers above the dragon with fully configurable XYZ offsets.
• Camera-follow aiming — the muzzle smoothly follows your view direction.
• Muzzle flash, shell ejection & tracers — TACZ effects render correctly at the gun's new position, including for remote dragon players (client configurable).
• Back gun — the first gun in your hotbar (skipping the held slot) is displayed on the dragon's back, with per-model position / rotation / scale.
• Ammo box — the first ammo box in your inventory is displayed on the dragon's body, with per-model position / rotation / scale.
• Dragon-size scaling — gun size and offsets scale with the dragon's body size.

Aiming & Crosshair

• Third-person crosshair — the TACZ crosshair stays visible in third person.
• ADS crosshair & dragon fade — while aiming in third person, the crosshair stays and the dragon model fades so its head doesn't block your sight.

Gameplay

• First-person arm hiding — hides the redundant human arm model while holding a gun as a dragon.
• Gliding shooting — dragons can fire while gliding without being kicked out of flight (server).
• Recoil cancel — suppress dragon camera recoil, scoped to gliding / flying / always (client).
• Speed influence control — servers can tune how much TACZ slows dragons down (server).

Fixes & Improvements

• Max-level dragon flight muzzle offset fix — fixes the bullet spawn point drifting up/down when a max-level dragon switches between walking and flying.
• Remote player sync — remote dragon players show their back gun, muzzle flash, and shell ejection.

Other

• Per-dragon-model configuration — each dragon model (including addon dragons) gets independent floating-gun, back-gun and ammo-box settings, auto-generated on first launch with tuned defaults. Anchors can bind them to a specific bone in the model, so even a new addon dragon with no preset can be configured quickly.
• In-game config screen — a full Cloth Config screen, organized by feature, with live sliders.

---

Dependencies

Mod	Version
DragonSurvival	1.21.1 NeoForge
TACZ (Unofficial NeoForge Port)	1.21.1
GeckoLib	4.8+
Cloth Config API	15.0+ (optional, client)

---

Configuration

All options are editable in-game from the mod config screen (client options) or the server config file.

Client Options

Option	Default	Description
hideThirdPersonGuns	false	Third-person feature master switch
hideFirstPersonArms	true	Hide first-person arms
gunHeightOffset	1.0	Floating gun height offset (blocks)
gunFloatSpeed	0.5	Vertical bobbing speed (0 = off)
gunBaseScale	0.8	Base scale of the floating gun
gunScaleWithDragon	true	Scale gun size with dragon size
gunOffsetScaleWithDragon	true	Scale offsets with dragon size
gunOffsetX	0.0	Left/right offset (positive = left)
gunOffsetZ	0.0	Forward/back offset (positive = front)
aimSmoothing	0.15	Aim-follow smoothing time (seconds)
gunPitchClamp	60.0	Maximum downward pitch (degrees)
tracerVisible	true	Show local dragon tracers
hideRemoteTracer	true	Hide remote dragon tracers
forceShowCrosshair	true	Force crosshair in third person
adsFeatureEnabled	true	ADS crosshair + dragon fade
adsFadeAmount	0.8	Dragon fade while aiming (0 = opaque, 1 = invisible)
recoilCancelEnabled	true	No-recoil master switch
recoilCancelScope	gliding	No-recoil scope: gliding / flying / always
backGunEnabled	true	Back gun master switch
backGunScale	0.5	Back gun scale
syncRemoteGunEffects	true	Show muzzle flash / shell ejection for remote dragons
ammoBoxEnabled	true	Ammo box decoration master switch
ammoBoxScale	0.5	Ammo box decoration scale

Server Options

Option	Default	Description
glidingShooting	true	Allow shooting while gliding
speedInfluenceMultiplier	1.0	TACZ speed influence (0 disables the penalty)
syncBackGunToClients	true	Sync dragon back guns to nearby clients
syncAmmoBoxToClients	true	Sync dragon ammo box decorations to nearby clients

Per-Dragon-Model Options

A config/ds_tacz_compat/dragon_models.json file is generated on first launch, holding tuned defaults for the vanilla dragon and many popular dragon addons. Each model can independently configure its floating gun, back gun and ammo box (enabled, XYZ position/offset, rotation, scale); models without an entry fall back to the global defaults.

Floating Gun (floatingGun)

Option	Description
Enable Floating Gun	Toggle
X / Y / Z Offset	Displacement in the dragon body frame. Positive X = left, positive Z = forward, Y = height
Scale	Floating gun size
Anchor Bone	Bone name, case-sensitive. Blank = no binding; the position is computed entirely from the dragon body frame
Anchor Axes	Any combination of x / y / z (e.g. xy). Selects which position axes are borrowed from the anchor bone; unlisted axes keep the default position. Blank is equivalent to xyz
Anchor Cube Index	Counts from 0; -1 means the anchor bone's own pivot. Default 0
Offset Follow Axes	Same value format. Selects which offset axes follow the anchor cube's orientation; unlisted axes keep the body orientation. Blank means the offset does not follow the bone

Back Gun (backGun)

Option	Description
Enable Back Gun	Toggle
X / Y / Z Position	Displacement relative to the anchor bone
X / Y / Z Rotation	Orientation correction angles
Scale	Back gun size
Anchor Bone	Bone name, case-sensitive. Blank resolves to Torso
Anchor Cube Index	Counts from 0; -1 is the bone pivot. Default -1

Ammo Box (ammoBox)

The field layout is identical to the back gun (enable / position / rotation / scale / anchor bone / cube index). A blank anchor bone resolves to Pelvis.

The back gun and ammo box are rigidly attached to their anchor bone and provide no axis-selection options.

Obtaining Bone Names and Cube Indices

These cannot be queried in-game; the model file must be read:

1. Unzip the target dragon addon's jar and extract its .geo.json model file;
2. Open it in Blockbench — each group name in the model tree is a bone name, and the order of cubes within a group is the cube index (starting at 0).

The mod uses a cube's render centre as its reference point, so pivot offsets and the cube's own rotation need not be considered — supplying the correct cube index is sufficient.

If the anchor bone itself contains no cubes, the anchor falls back to that bone's pivot. In that case, supply a bone that does contain cubes (usually a descendant). The vanilla model's Head / Neck are such cases — the visible head geometry lives on a child bone.

Troubleshooting Order

When a position is wrong, check the anchor parameters first: bone-name spelling and case, and whether the cube index points to a cube that has geometry. The remaining frame parameters (offset, rotation) should not be the first suspects.

---

Compatibility

• Compatible with most TACZ gun packs and minigun-type weapons.
• Dragon body size changes are handled automatically.
• Built-in tuned presets for a wide range of DragonSurvival dragon addons.

---

License

Open source under the MIT License.

Declaration

Developed with the assistance of Deepseek AI.

---

龙之生存：永恒枪械工坊兼容

一个用于兼容龙之生存与永恒枪械工坊：零（非官方 NeoForge 移植）的模组，让龙玩家持枪更自然。

在原版龙之生存中，龙玩家手持 TACZ 枪械时枪械渲染存在许多问题，比如枪会贴在龙身体两侧、枪口下垂、瞄准方向错误、动画异常。龙玩家在第一人称视角下还会渲染不必要的人类手臂。本模组将枪械移至龙头上方，使其悬浮，枪口实时跟随视角，并完整保留枪口焰、抛壳与曳光弹特效；同时为龙玩家提供一系列 TACZ 相关特性与问题的兼容修复与改进。

安装说明 —— 本模组客户端与服务端都必须安装，且两端版本必须完全一致。仅客户端安装将无法进入未安装本模组的服务器，版本不一致会在连接时被拒绝。

---

特性

枪械渲染

• 第三人称悬浮枪械 —— 枪械悬浮于龙头上方，XYZ 偏移均可配置。
• 摄像机同步瞄准 —— 枪口朝向平滑跟随视角。
• 枪口焰、抛壳与曳光弹 —— 使悬浮枪正确显示 TACZ 特效，并支持远程龙玩家。
• 背枪 —— 快捷栏中第一把枪械将会显示在龙背上，位置/旋转/缩放均可按模型配置。
• 弹药箱装饰 —— 背包中的第一个弹药盒将会显示在龙身上，位置/旋转/缩放均可按模型配置。
• 枪械随龙大小缩放 —— 枪械大小与偏移随龙体型缩放。

瞄准与准星

• 第三人称准星 —— 使 TACZ 准星在第三人称下显示。
• 开镜准星与龙模型虚化 —— 使第三人称开镜时准星保持显示，同时虚化龙模型，防止视线被龙头遮挡。

玩法兼容

• 第一人称隐藏人类手臂 —— 龙玩家持枪时隐藏多余的人类手臂模型。
• 滑翔开枪 —— 龙可以在滑翔时开枪，瞄准或换弹不再退出滑翔（服务端功能）。
• 滑翔时无后坐 —— 使龙玩家滑翔时无后座力，方便空战。
• 移速影响控制 —— 可调节 TACZ枪械 对龙玩家的移速影响惩罚程度（服务端功能）。

修复与改进

• 满级龙飞行时枪口偏移修复 —— 修复满级龙切换飞行与行走时子弹出发点上/下偏移的问题。
• 远程玩家同步 —— 远程龙玩家的背枪、枪口焰与抛壳均可显示。

其他

• 龙模型独立配置 —— 每种龙模型（含扩展龙）拥有独立的悬浮枪，背枪与弹药箱装饰配置。首次启动自动生成调优默认值。配置锚点时可以使其锚定模型内指定骨骼，即使没有预设配置的新扩展龙模型也能快速配置。
• 游戏内配置界面 —— 完整详细的 Cloth Config 配置界面。

---

依赖

模组	版本
龙之生存	1.21.1 NeoForge
永恒枪械工坊：零（非官方移植）	1.21.1
GeckoLib	4.8+
Cloth Config API	15.0+（可选，客户端）

---

配置

所有选项均可通过游戏内配置界面（客户端选项）或服务端配置文件调整。

客户端选项

选项	默认值	说明
hideThirdPersonGuns	false	第三人称功能总开关
hideFirstPersonArms	true	第一人称隐藏手臂
gunHeightOffset	1.0	悬浮枪高度偏移（块）
gunFloatSpeed	0.5	上下浮动速度（0 = 停止）
gunBaseScale	0.8	悬浮枪基础大小
gunScaleWithDragon	true	枪械大小随龙体型缩放
gunOffsetScaleWithDragon	true	偏移随龙体型缩放
gunOffsetX	0.0	左右偏移（正值左移）
gunOffsetZ	0.0	前后偏移（正值前移）
aimSmoothing	0.15	瞄准平滑时间（秒）
gunPitchClamp	60.0	最大下俯角度（度）
tracerVisible	true	显示本地龙曳光弹
hideRemoteTracer	true	隐藏远程龙曳光弹
forceShowCrosshair	true	第三人称强制显示准星
adsFeatureEnabled	true	开镜显示准星 + 虚化龙身防挡
adsFadeAmount	0.8	开镜时龙虚化程度（0为不透明，设为1以完全隐藏模型）
recoilCancelEnabled	true	无后坐力总开关
recoilCancelScope	gliding	无后坐力作用范围：滑翔时生效 / 飞行时生效 / 总是生效
backGunEnabled	true	背枪渲染总开关
backGunScale	0.5	背枪缩放
syncRemoteGunEffects	true	显示远程龙玩家的枪口焰 / 抛壳
ammoBoxEnabled	true	弹药箱装饰渲染总开关
ammoBoxScale	0.5	弹药箱装饰缩放

服务端选项

选项	默认值	说明
glidingShooting	true	滑翔开枪开关
speedInfluenceMultiplier	1.0	TACZ 移速影响倍数（设为 0 禁用减速惩罚）
syncBackGunToClients	true	向附近客户端同步龙玩家背枪
syncAmmoBoxToClients	true	向附近客户端同步龙玩家弹药箱装饰

龙模型独立配置项

首次启动会生成 config/ds_tacz_compat/dragon_models.json，内置原版龙与众多主流龙扩展的调优默认值。每种模型可独立配置悬浮枪（启用、XYZ 偏移、缩放）与背枪（启用、XYZ 位置、XYZ 旋转、缩放）；新模型未配置时自动使用全局默认值。

悬浮枪（floatingGun）

配置项	说明
启用悬浮枪	开关
X / Y / Z 偏移	龙身坐标系下的位移量。X 正值为左，Z 正值为前，Y 为高度
缩放	悬浮枪大小
绑定基础锚点骨骼	骨骼名称，区分大小写。留空表示不绑定，位置完全按龙身坐标系计算
绑骨轴选择	取值为 x / y / z 的任意组合（如 xy）。指定从锚点骨骼借用的位置轴，未列出的轴维持默认位置。留空等价于 xyz
绑骨块索引	从 0 起计数，-1 表示锚点骨骼自身 pivot。默认 0
一级坐标系同步骨骼的轴向选择	取值格式同上。指定跟随锚点方块朝向的偏移轴，未列出的轴保持龙身朝向。留空表示偏移不跟随骨骼

背枪（backGun）

配置项	说明
启用背枪	开关
X / Y / Z 位置	相对锚点骨骼的位移
X / Y / Z 旋转	朝向校正角度
缩放	背枪大小
绑定基础锚点骨骼	骨骼名称，区分大小写。留空解析为 Torso
绑骨块索引	从 0 起计数，-1 为骨骼 pivot。默认 -1

弹药箱（ammoBox）

字段构成与背枪一致（启用 / 位置 / 旋转 / 缩放 / 锚点骨骼 / 块索引），锚点骨骼留空解析为 Pelvis。

背枪与弹药箱为刚性附着于锚点骨骼，不提供轴选择项。

骨骼名与块索引的获取

在游戏内无法查询，需读取模型文件：

1. 解压目标龙扩展的 jar，取出其中的 .geo.json 模型文件；
2. 以 Blockbench 打开，模型树中组（Group）名称即骨骼名，组内方块的排列顺序即块索引（自 0 起）。

模组取方块的计算基准为渲染中心，故无需考虑 pivot 偏移与方块自身旋转，填对块序号即可。

若锚点骨骼自身不含方块，锚点将回退至该骨骼 pivot。此时应改填具备方块的骨骼（通常为其后代骨骼）。原版模型的 Head / Neck 即属此类——可见头部几何位于下级骨骼。

排查顺序

位置异常时，应优先核查锚点参数：骨骼名拼写与大小写、块索引是否指向具备几何体的方块。其余坐标系参数（偏移、旋转）不应作为首要怀疑对象。

---

兼容性

• 兼容大部分 TACZ 枪包与加特林类机枪。
• 龙体型变化自动适配。
• 内置一些龙之生存扩展龙模组的调优预设配置。

---

开源协议

以 MIT 协议 开源。

声明

本模组借助 Deepseek AI 辅助完成。