CNPC-ImmersiveBoss

Adds animated multi-hitbox OBB collision to GeckoLib NPCs for CustomNPCs — 为 CustomNPCs 的 GeckoLib NPC 提供随骨骼动画变化的 OBB 多碰撞箱。

Attacks, interactions, projectiles, entity pushing and damage detection now follow the actual model shape, plus custom boss bars, per-part script events, animated damage windows and turn-speed APIs. 让大型或异形 NPC 的受击、交互、弹射物、实体推挤和攻击判定贴合实际模型，并提供自定义 Boss 血条、分部位脚本事件、碰撞伤害窗口和转向限速 API。

Current version 0.3.10 · Minecraft 1.20.1 · Forge 47.x · Java 17 ｜ 当前版本 0.3.10 · Minecraft 1.20.1 · Forge 47.x · Java 17

Features 特性

• Animated OBB hitboxes 动画 OBB 碰撞箱 — collision volumes follow GeckoLib bone translation, rotation and animation; multi-cube bones supported ／ 碰撞体积跟随 GeckoLib 骨骼平移、旋转和动画，支持多 cube 骨骼
• Per-part combat 分部位战斗 — crosshair, melee and vanilla projectiles (arrows, tridents) hit specific parts; read e.hitboxName in scripts ／ 准星、近战、箭/三叉戟等弹射物命中具体部位，脚本中读取 e.hitboxName
• Physical boxes & sensors 物理箱与传感器 — b boxes push entities apart, s sensors only detect overlap ／ b 箱参与实体互相推挤，s 传感器只检测重叠，互不干扰
• Large model support 大型模型支持 — OBBs outside the vanilla NPC AABB can still be attacked and interacted with ／ OBB 超出 NPC 原版 AABB 也能被攻击、交互和弹射物命中
• Animated damage windows 碰撞伤害窗口 — sword/tail bones deal damage on specific frames, with delay, repeat, target limits and callbacks ／ 让剑、尾巴等动画骨骼在指定帧造成伤害，可延迟、重复、限目标数、回调
• Custom boss bars 自定义 Boss 血条 — two-layer PNG texture, always-on or combat-only, configurable color/scale/offset ／ 上下分层 PNG 素材，常显或战斗时显示，可调颜色/缩放/偏移
• Debug rendering 调试渲染 — press F3+B to see OBB type, name, axes and overlap state ／ F3+B 直接查看 OBB 类型、名称、局部轴和重叠状态
• Optional TaCZ compatibility 可选 TaCZ 兼容 — gun raytraces include animated OBBs ／ 安装 TaCZ 后枪械射线包含动画 OBB 并传递部位名

Quick Start 快速开始

1. In Blockbench, add a bone named h[a][d][b|s]_name (e.g. hdb_body, hads_sword) ／ 在 Blockbench 的 GeckoLib 模型中新增骨骼，命名 h[a][d][b|s]_名称（如 hdb_body、hads_sword）
2. Put at least one cube inside, export .geo.json and assign to the NPC via CNPC Gecko Addon ／ 骨骼内放入至少一个 cube，导出 .geo.json 并通过 CNPC Gecko Addon 设置给 NPC
3. Enter the world and press F3+B to verify the OBB wireframes ／ 进入世界看到 NPC，按 F3+B 验证 OBB 线框
4. Add a damaged(e) script and read e.hitboxName for per-part logic ／ 在 NPC 脚本中添加 damaged(e) 读取 e.hitboxName 实现分部位逻辑

Installation 安装

1. Install Forge 1.20.1 with Java 17 ／ 安装 Forge 1.20.1，启动器使用 Java 17
2. Put the four required dependencies plus this mod's JAR into mods/ ／ 将四个必要依赖和本模组的 JAR 放入 mods/ 文件夹
3. Multiplayer: client and server MUST run identical versions ／ 多人游戏：客户端和服务端必须安装相同版本的模组及依赖
4. Put models/textures/boss bar assets in a resource pack enabled by every player ／ 将模型、贴图和血条素材放入资源包，确保所有玩家启用同一资源包

Dependencies 依赖

Required 必要

Optional 可选

This mod cannot be installed on only one side: hitbox definitions are parsed from the client resource manager, while animated OBBs and boss bar state are synced over the network. 本模组不能只安装在单侧：模型定义由客户端资源管理器读取，动画 OBB 和血条状态通过网络同步。

Compatibility 兼容性

• Minecraft 1.20.1, Forge 47.x (dev 47.4.20), Java 17
• GeckoLib 4.8.4, CustomNPCs Goodbird 1.20.1 port, CNPC Gecko Addon CE 1.2.2
• Full vanilla projectile support (arrows, tridents...) ／ 完整支持原版弹射物（箭、三叉戟等）；TaCZ 1.1.8-hotfix API 可选兼容

Documentation 文档

• 📖 Wiki: https://github.com/Sweda666/CNPC-ImmersiveBoss/wiki
• 📦 Source 源码: https://github.com/Sweda666/CNPC-ImmersiveBoss
• Installation & quick start, hitbox modeling, combat & interaction, boss bar setup, scripting API, troubleshooting, developer guide ／ 安装与快速开始、碰撞箱建模、战斗与交互、Boss 血条配置、脚本 API、常见问题、开发者指南