GunPlugin - 枪械插件

一个功能丰富的Minecraft枪械插件，支持多种枪械类型、自定义配置、真实弹道系统和完整的射击体验。

A feature-rich Minecraft gun plugin with multiple weapon types, custom configuration, realistic ballistics system, and complete shooting experience.

📋 目录 / Table of Contents

• 功能特性 / Features
• 安装指南 / Installation
• 配置说明 / Configuration
• 命令列表 / Commands
• 权限系统 / Permissions
• 枪械目录 / Weapon catalog
• 自定义枪械 / Custom Weapons
• 更新日志 / Changelog
• 常见问题 / FAQ
• 技术支持 / Support

🚀 功能特性 / Features

核心功能 / Core Features

• 多种枪械类型 / Multiple Weapon Types: 手枪、步枪、霰弹枪、狙击枪
• 真实弹道系统 / Realistic Ballistics: 子弹速度、重力下坠、穿透效果
• 弹药管理系统 / Ammunition System: 弹匣容量、换弹机制、弹药显示
• 射击模式 / Firing Modes: 单发、连发、霰弹枪多发
• 后坐力系统 / Recoil System: 视觉反馈和粒子效果
• 爆头检测 / Headshot Detection: 30%额外伤害
• 血雾效果 / Blood Effects: 击中实体的粒子效果

高级功能 / Advanced Features

• 自定义枪械 / Custom Weapons: 通过配置文件创建自定义枪械
• 子弹散步 / Bullet Spread: 移动时增加散步，鼓励静止射击
• 音效系统 / Sound System: 多层次延迟音效，增强沉浸感
• 交互禁用 / Interaction Disable: 持枪时禁用左键攻击和右键交互
• 自动射击 / Auto Fire: 按住右键连续射击，松开停止
• 手动换弹 / Manual Reload: F键手动换弹功能

📦 安装指南 / Installation

系统要求 / Requirements

• Minecraft版本 / Minecraft Version: 1.21.4
• 服务器类型 / Server Type: Spigot/Paper
• Java版本 / Java Version: 8 或更高版本 / 8 or higher
• 内存要求 / Memory: 建议2GB以上 / Recommended 2GB+

安装步骤 / Installation Steps

1. 下载插件 / Download Plugin

   # 将GunPlugin.jar放入服务器的plugins文件夹
   # Place GunPlugin.jar in your server's plugins folder

2. 启动服务器 / Start Server

   # 重启服务器以加载插件
   # Restart your server to load the plugin

3. 配置插件 / Configure Plugin

   # 编辑plugins/GunPlugin/config.yml文件
   # Edit plugins/GunPlugin/config.yml file

4. 设置权限 / Set Permissions

   # 给玩家gunplugin.use权限
   # Give players gunplugin.use permission

⚙️ 配置说明 / Configuration

配置文件分工 / Config File Roles

修改 guns.yml 或 config.yml 后请执行 /gun reload（需权限）或重启服务端。

基础配置示例 / Basic config.yml excerpt

settings:
  disable_left_click: true
  disable_right_click_interaction: true
  debug_mode: false

# 可选：按枪械 ID 覆盖部分属性（材质、名称、射速等），详见 config 内注释
# default_guns:
#   ak74:
#     fire_rate: 580   # RPM；≤4 的小数可按「秒/发」解析（见配置注释）

枪械本体 不在 config.yml 的 guns: 下列出（旧版示例已废弃）；请使用 guns.yml。

📝 命令列表 / Commands

以下为 GunCommand 实际注册的子命令（见源码）；整条 /gun … 在执行器中统一校验 gunplugin.admin，控制台给予弹药需使用该权限。

基础命令 / Basic Commands

命令示例 / Command Examples

/gun give @p ak74
/gun give @p 9mm 64
/gun give PlayerName grenade 5
/gun ammo
/gun ammo reload
/gun reload
/gun modify
/gun buy

🔐 权限系统 / Permissions

plugin.yml 中仅声明：

权限配置示例 / Permission Configuration Example

groups:
  default:
    permissions:
      - gunplugin.use
  admin:
    permissions:
      - gunplugin.admin
      - gunplugin.use

🔫 枪械目录 / 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. 重载

   /gun reload

4. 发放

   /gun give <枪械ID>

注意事项 / Notes

• 同材质多枪：若多把枪共用同一 material，仅靠材质无法区分；请使用插件发放的枪（带 PDC 目录 ID），或为不同枪指定 不同材质。
• 购买价格：在 config.yml 的购买相关节配置，不在 guns.yml。
• 更细的字段表与音效格式说明见 guns.yml 文件头 与仓库内 CHANGELOG_5.0.0.md。

极简骨架示例 / Minimal skeleton（省略音效与后坐力细节时请直接复制完整条目改 ID）

# 建议复制 aa12 / ak74 等完整条目后改名修改，下列仅为结构提示
my_custom_rifle:
  material: IRON_HORSE_ARMOR
  display_name: "自定义步枪"
  magazine: 30
  damage: 5.0
  rate: 600          # RPM
  fly_speed: 100
  bullet_drop: 0.05
  reload_duration: 2.5
  penetration: 1
  movement_spread: 0.5
  ammo: 762
  is_automatic: true
  is_shotgun: false
  is_sniper: false
  category: rifle
  reload_mode: magazine
  bolt_after_shot: false
  attachments: []
  sounds: { fire: [...], reload: [...], bolt: [] }
  recoil: { style: normal, ... }

📊 更新日志 / 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! 🎯