Z80Z Shoulder Cam & Aim

A client-side mod for Minecraft 1.20.1 (Forge 47.4.0, Java 17) that replaces vanilla third person with a swappable over-the-shoulder camera, with soft compatibility for TACZ gun aiming, zooming and scoping.

• F5 takeover: first person → over-shoulder → third person back → third person front, with smooth transitions and player-model fading (adjustable duration, 0 = instant)
• X to swap shoulders: 0.15s smooth slide with inertia; defaults away from R to avoid clashing with TACZ reloading
• Three follow modes: smoothed interpolation (SMOOTH), spring-damper (SPRING), fixed (FIXED, zero latency)
• Aim zoom + body push: holding a gun in aim narrows the FOV and pushes the camera toward the shoulder
• Forced first person for snipers: detected via TACZ gun-pack types; scoping switches to first person, releasing returns, with a lens-black transition
• Over-shoulder crosshair: TACZ only draws its crosshair in first person — this mod adds one while aiming from the shoulder, projected onto the real ballistic hit point
• Wall fade: when the camera is squeezed by walls, the body, armor and elytra fade to translucent instead of clipping
• Auto over-shoulder when mounting or gliding; reverts automatically
• Elytra roll: the screen rolls with your turn while gliding
• K settings screen: everything adjustable; three-column layout on widescreen, paged on narrow

Client config: config/z80z_shoulder_aim_sync-client.toml, or press K in game. Highlights: general.takeoverF5, general.autoShoulder (also for riding/elytra), camera.followMode (SMOOTH/SPRING/FIXED), camera.shoulderOffsetX/Y, camera.backDistance, camera.fadePlayerWhenClose, aim.zoomFactor, aim.aimPush, aim.deferToTaczScope, sniper.forceFirstPersonSniper, elytra.elytraRollScreen, compat.gunModIds (default ["tacz"]).

• TACZ: guns detected via IGun and the GunId NBT; ammo/attachments/workbenches are never misidentified; aim state reads TACZ's isAim() and scope progress; sniper detection prefers the gun pack's type field
• TACZ-addon: its enableBetterAimCamera auto-switches to first person on aim — disable it to use this mod's shoulder zoom
• ShoulderSurfing: both take over the camera; not recommended together

• The over-shoulder camera is offset while TACZ bullets originate at the eyes, so the crosshair sits at the projection of the ballistic hit point rather than screen center — geometrically correct by design
• Hip-fire inaccuracy spreads hits around the crosshair (a weapon property), and recoil briefly kicks the view

1. Install Minecraft Forge 1.20.1-47.4.0.
2. Download the latest z80z-shoulder-aim-sync-<version>.jar from Releases.
3. Drop it into the client's mods folder — servers don't need it. TACZ is optional; base over-shoulder works without it.

Wall fade and auto-third-person ideas reference Nimble by Snownee (MIT); the implementation here is independent, adding shoulder offsets, aim logic and ballistic crosshair projection.

MIT © 2026 Z80Z99

• 接管 F5：第一人称 → 越肩 → 第三人称后 → 第三人称前，切换带平滑过渡与模型淡入淡出（可调时长，0=瞬时）。
• X 键换肩：0.15 秒平滑横移，保留惯性；默认不用 R，避免与 TACZ 换弹冲突。
• 三种跟随模式：平滑插值（SMOOTH）、弹簧阻尼（SPRING）、固定跟随（FIXED，无延迟）。
• 瞄准变焦 + 机身前探：手持枪械瞄准时 FOV 渐进收窄、相机前移贴肩。
• 狙击强制第一人称：按 TACZ 枪包类型识别，开镜切第一人称，松手恢复，带镜片黑框过渡。
• 越肩准星：TACZ 只在第一人称绘制准星，本模组在越肩持枪时补一个，并按真实弹道命中点投影对齐。
• 贴墙虚化：镜头被墙挤近时，身体、盔甲、鞘翅一起变半透明，不再穿模。
• 自动越肩：上坐骑、鞘翅滑翔时自动切换，结束自动恢复。
• 鞘翅滚转：滑翔转弯时画面随倾斜滚转。
• K 键设置界面：参数全部可调，宽屏三栏、窄屏单栏分页。

1. 把 jar 放进客户端 mods 文件夹（不需要装服务端）。
2. 进世界后默认自动进入越肩视角；按 F5 在四种视角间循环。
3. 按 X 左右换肩；按 K 打开设置，可调肩部偏移、跟随模式、变焦强度等。
4. 手持枪械按住右键瞄准：越肩下会看到 FOV 收窄、机身前探。
5. 狙击枪开镜会自动切第一人称，松手立刻回到越肩。
6. 上坐骑或开始滑翔时自动切越肩，下来/落地自动恢复。

客户端配置：config/z80z_shoulder_aim_sync-client.toml，或游戏内按 K 修改。

• TACZ（永恒枪械工坊：零）：通过 IGun 接口和物品 NBT 的 GunId 识别枪械，弹药/配件/工作台不会被误判；瞄准状态读取 TACZ 的 isAim() 与开镜进度，改键或切换式瞄准也能同步；狙击识别优先用枪包自带的 type 字段，自定义枪包同样有效。
• TACZ-addon：其 enableBetterAimCamera 默认开启，会在瞄准时自动切第一人称，此时本模组的越肩变焦面板基本不生效；想用越肩变焦请关闭该项。
• ShoulderSurfing：两者都接管相机，不建议同时安装。

• 越肩相机横向偏移，而 TACZ 弹道从眼睛发出，因此准星画在弹道命中点的投影位置、不在屏幕中心——这是几何正确行为。
• 腰射散布（TACZ 的 inaccuracy）会让弹着点围绕准星随机分布，属枪械属性。
• 开火后坐力会短暂踢动视角，此时画面朝向与弹道方向不完全一致。

1. 安装 Minecraft Forge 1.20.1-47.4.0。
2. 从 Releases 下载最新的 z80z-shoulder-aim-sync-<版本>.jar。
3. 放入客户端 mods 文件夹，启动游戏。

模组是纯客户端实现，服务端不需要安装；TACZ 为可选依赖，不装也能用基础越肩功能。

需要 JDK 17，项目自带 Gradle Wrapper：

./gradlew build

产物位于 build/libs/z80z-shoulder-aim-sync-<版本>.jar。开发调试：./gradlew runClient。

• Minecraft 1.20.1
• Forge 47.4.0
• Java 17
• 仅客户端

贴墙虚化与自动第三人称的实现思路参考了 Nimble（作者 Snownee，MIT 许可）；本模组的实现独立编写，并额外提供肩部偏移、瞄准逻辑与弹道投影准星。

MIT © 2026 Z80Z99