GunPlugin

# GunPlugin - 枪械插件 (https://img.shields.io/badge/Minecraft-1.21.4-green.svg)](https://minecraft.net) (https://img.shields.io/badge/Spigot-API-blue.svg)](https://spigotmc.org) (https://img.shields.io/badge/Java-8+-orange.svg)](https://openjdk.java.net) 一个功能丰富的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** ```bash # 将GunPlugin.jar放入服务器的plugins文件夹 # Place GunPlugin.jar in your server's plugins folder ``` 2. **启动服务器** / **Start Server** ```bash # 重启服务器以加载插件 # Restart your server to load the plugin ``` 3. **配置插件** / **Configure Plugin** ```bash # 编辑plugins/GunPlugin/config.yml文件 # Edit plugins/GunPlugin/config.yml file ``` 4. **设置权限** / **Set Permissions** ```bash # 给玩家gunplugin.use权限 # Give players gunplugin.use permission ``` --- ## ⚙️ 配置说明 / Configuration ### 配置文件分工 / Config File Roles | 文件 / File | 路径 / Path | 作用 / Purpose | |---|---|---| | **guns.yml** | `plugins/GunPlugin/guns.yml` | **枪械目录**：每把枪的完整定义（伤害、`rate`、弹匣、换弹、`sounds`、`recoil`、`category`/`behavior` 等）。根键名即枪械 ID。 | | **config.yml** | `plugins/GunPlugin/config.yml` | **插件与商店**：`settings`、购买与经济 `buy_system`、`default_guns` 单枪覆盖、配件价格等。 | 修改 **`guns.yml`** 或 **`config.yml`** 后请执行 **`/gun reload`**（需权限）或重启服务端。 ### 基础配置示例 / Basic `config.yml` excerpt ```yaml 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 | 描述 / 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 /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 | 描述 / Description | 默认 / Default | |---|---|---| | `gunplugin.use` | 在游戏内**使用枪械**（射击、开镜、交互等） | `true` | | `gunplugin.admin` | 使用 **`/gun`** 全部子命令（默认 OP） | `op` | ### 权限配置示例 / Permission Configuration Example ```yaml 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`、`