GunPlugin - 枪械插件

   一个功能丰富的 Minecraft 枪械插件，支持多种枪械类型、配置、真实弹道系统和完整的射击体验。 一款功能丰富的 Minecraft 枪械插件，具有多种武器类型、自定义配置、逼真的弹道系统和完整的射击体验。 --- ## 目录/目录 - 功能特性/Features - 安装指南/安装 - 配置说明/配置 - 命令列表 / Commands - 权限系统 / Permissions - 枪械目录 / 武器目录 - 自定义枪械 / Custom Weapons - 更新日志 / 变更日志 - 常见问题 / FAQ - 技术支持/支持 --- ## 功能特性/特点 ### 核心功能/核心特性 - 多种枪械类型 / 多种武器类型：手枪、高精度弹枪、狙击枪 - 真实弹道系统 / Realistic Ballistics: 子弹速度、重力下坠、近似效果 - 弹药管理系统 / 弹药系统：弹匣容量、换弹机制、弹药显示机制 - 射击模式 / 射击模式：单发、连发、霰弹枪多发 - 后坐力系统 / 反冲系统：视觉反馈和粒子效果 - 爆头检测 / 爆头检测：30% 额外伤害 - 血雾效果 / 血液效果：击中实体的粒子效果 ### 高级功能/高级功能 - 自定义枪械 / 自定义武器: 通过配置文件创建自定义枪械 - 子弹散布 / 子弹散布：移动时增加散布，鼓励平静射击 - 音效系统 / 声音系统：多层次延迟音效，增强沉浸感 - 交互禁止 / 交互禁用：持枪时取消左键攻击和右侧交互 - 自动射击 / 自动射击：按住右键连续射击，开始停止 - 手动换弹 / 手动装弹：F键手动换弹功能 --- ## 安装指南/安装 ### 系统要求/要求 - 我的世界版本 / 我的世界版本：1.21.4 - ** 服务器类型** / 服务器类型： Spigot/Paper - Java版本 / Java版本：8或更高版本/8或更高 - 内存要求 / 内存：建议2GB以上 / 推荐2GB+ ### 安装步骤/安装步骤 1. 下载插件 / 下载插件 bash <br> # 将GunPlugin.jar放入服务器的plugins文件夹 <br> 将 GunPlugin.jar 文件放入服务器的插件文件夹中 <br> 2. 启动服务器 / 启动服务器 bash <br> # 重启服务器以加载插件 <br> # 重启服务器以加载插件 <br> 3. 配置插件 / 配置插件 bash <br> # 编辑plugins/GunPlugin/config.yml文件 <br> # 编辑 plugins/GunPlugin/config.yml 文件 <br> 4. 设置权限 / 设置权限 bash <br> # 给玩家gunplugin.use权限 <br> # 授予玩家 gunplugin.use 权限 <br> --- ## ⚙️ 配置说明/配置 ###配置文件分工/配置文件角色 | 文件/文件| 路径 / 路径 | 作用/目的| |---|---|---| | 枪.yml | 插件/GunPlugin/guns.yml | 枪械目录：每把枪的完整定义（伤害、速率、弹匣、换弹、声音、后坐力、类别/行为等）。根键名即枪械ID。 | 配置.yml | 插件/GunPlugin/config.yml | 插件与商店：settings、购买与经济buy_system、default_guns单枪覆盖、配件价格等。 修改 guns.yml 或 config.yml 后请执行 /gun reload（需权限）或重启服务端。 ### 基础配置示例 / 基本 config.yml 摘录 yaml <br> 设置： <br> 禁用左键：true <br> 禁用右键交互：true <br> debug_mode: false <br> # 可选：按枪械ID覆盖部分属性（材质、名称、射速等），参见配置内注释 <br> # 默认枪支： <br> # ak74： <br> # fire_rate: 580 # RPM；≤4 的小数可按「秒/发」解析（见配置注释） <br> 枪械本体 不在 config.yml 的 guns: 下列出（旧版示例已废弃）；请使用 guns.yml。 --- ## 命令列表 / Commands 以下为 GunCommand 实际注册的子命令（见源码）；整条 /gun … 在执行器中统一校验 gunplugin.admin，控制台给予弹药需使用该权限。 ### 基础命令 / Basic Commands | 命令 / Command | 描述 / Description | |---|---| | /gun give <目标> <guns.yml 枪械 ID \| 弹药 \| 投掷物> [数量] | 给予枪械 / 弹药 / 投掷物（枪械 ID 与 guns.yml 根键一致；别名如 pistol→p250 见帮助） | | /gun ammo | 主手持枪：查看当前弹药 | | /gun ammo reload | 主手持枪：执行换弹 | | /gun reload | 重载插件配置与 guns.yml（不是游戏内换弹） | | /gun help | 显示帮助 | | /gun lang | /gun lang <代码> | 查看或切换语言（可用代码见语言管理器） | | /gun modify | /gun mod | 主手持枪：打开 配件改装 GUI | | /gun buy | 打开购买 GUI（需在 config 中启用购买系统） | ### 命令示例 / Command Examples bash <br> /gun give @p ak74 <br> /gun give @p 9mm 64 <br> /gun give PlayerName grenade 5 <br> /gun ammo <br> /gun ammo reload <br> /gun reload <br> /gun modify <br> /gun buy <br> --- ## 权限系统 / Permissions plugin.yml 中仅声明： | 权限 / Permission | 描述 / Description | 默认 / Default | |---|---|---| | gunplugin.use | 在游戏内使用枪械（射击、开镜、交互等） | true | | gunplugin.admin | 使用 /gun 全部子命令（默认 OP） | op | ### 权限配置示例 / Permission Configuration Example yaml <br> groups: <br> default: <br> permissions: <br> - gunplugin.use <br> admin: <br> permissions: <br> - gunplugin.admin <br> - gunplugin.use <br> --- ## 枪械目录 / Weapon catalog 默认及自定义枪械均由 plugins/GunPlugin/guns.yml 定义（根键即枪械 ID）。数值、别名与列表说明见该文件及仓库 CHANGELOG_5.0.0.md，此处不再维护易过期的静态枪械表。 --- ## ️ 自定义枪械 / Custom Weapons 当前版本枪械 完全由 guns.yml 数据驱动：复制任意现有枪械条目，修改 根键名（=枪械 ID，建议小写）并按需改字段即可新增一枪。 ### 步骤 / Steps 1. 编辑 plugins/GunPlugin/guns.yml - 根键：枪械 ID，用于 /gun give <id>、商店、物品 PDC gun_catalog_id。 - 必填字段（缺一不可）：material、display_name、damage、rate（RPM）、magazine、reload_duration（或 reload_speed）、fly_speed、bullet_drop、penetration、movement_spread、ammo、is_automatic、is_shotgun、is_sniper、category、reload_mode、bolt_after_shot、attachments、sounds（含 fire/reload/bolt，可为 []）、recoil。 - 可选：behavior（pistol/rifle/…）；不写则按 category 推断。 - rate：每分钟发数 RPM；射击间隔(秒) ≈ 60 / rate。 - recoil：style: normal（参数式）或 style: pattern + points 列表（每项 [水平, 垂直]）。 - 文件顶部有 中英文注释，逐项说明各键含义。 2. （可选）覆盖而不改 guns.yml 在 config.yml 的 default_guns.<枪械ID> 下可覆盖材质、显示名、弹匣、fire_rate、射击音效、弹药类型、is_automatic 等（详见该文件内注释）。 3. 重载 bash <br> /gun reload <br> 4. 发放 bash <br> /gun give <枪械ID> <br> ### 注意事项 / Notes - 同材质多枪：若多把枪共用同一 material，仅靠材质无法区分；请使用插件发放的枪（带 PDC 目录 ID），或为不同枪指定 不同材质。 - 购买价格：在 config.yml 的购买相关节配置，不在 guns.yml。 - 更细的字段表与音效格式说明见 guns.yml 文件头 与仓库内 CHANGELOG_5.0.0.md。 ### 极简骨架示例 / Minimal skeleton（省略音效与后坐力细节时请直接复制完整条目改 ID） yaml <br> # 建议复制 aa12 / ak74 等完整条目后改名修改，下列仅为结构提示 <br> my_custom_rifle: <br> material: IRON_HORSE_ARMOR <br> display_name: "自定义步枪" <br> magazine: 30 <br> damage: 5.0 <br> rate: 600 # RPM <br> fly_speed: 100 <br> bullet_drop: 0.05 <br> reload_duration: 2.5 <br> penetration: 1 <br> movement_spread: 0.5 <br> ammo: 762 <br> is_automatic: true <br> is_shotgun: false <br> is_sniper: false <br> category: rifle <br> reload_mode: magazine <br> bolt_after_shot: false <br> attachments: [] <br> sounds: { fire: [...], reload: [...], bolt: [] } <br> recoil: { style: normal, ... } <br> --- ## 更新日志 / Changelog 详见插件根目录 CHANGELOG.md（中文累计日志）、CHANGELOG_EN.md（英文）及 CHANGELOG_5.0.0.md（5.0.0 摘要）。 --- ## ❓ 常见问题 / FAQ ### Q: 如何获得枪械？ / How to get weapons? A: 使用命令 /gun give <枪械类型> 或通过配置文件自定义 / Use command /gun give <weapon_type> or customize via config file ### Q: 为什么子弹没有伤害？ / Why bullets don't deal damage? A: 检查玩家权限和插件配置，确保子弹更新任务正常运行 / Check player permissions and plugin configuration, ensure bullet update task is running ### Q: 如何自定义枪械？ / How to customize weapons? A: 在 plugins/GunPlugin/guns.yml 中新增或复制枪械条目（根键即枪械 ID），必要时用 config.yml 的 default_guns 做覆盖；执行 /gun reload。详见上文 自定义枪械。 / Edit plugins/GunPlugin/guns.yml (root key = gun id); optionally override via default_guns in config.yml; run /gun reload. See Custom Weapons. ### Q: 支持哪些Minecraft版本？ / Which Minecraft versions are supported? A: 目前支持Minecraft 1.21.x / Currently supports Minecraft 1.21.x ### Q: 如何调整子弹散步？ / How to adjust bullet spread? A: 在 guns.yml 中调整 movement_spread 及 recoil 相关参数 / Tune movement_spread and recoil in guns.yml --- ## 技术支持 / Support 欢迎通过 plugin.yml 中的 website（Modrinth 等发布页）反馈问题。 ### 许可证 / License 若仓库内附有许可证文件则以该文件为准；否则请以插件发布页的授权说明为准。 --- 享受射击的乐趣！ / Enjoy the shooting experience!