Описание
# GunPlugin - 枪械插件
[](https://minecraft.net)
[](https://spigotmc.org)
[](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](#功能特性--features)
- [安装指南 / Installation](#安装指南--installation)
- [配置说明 / Configuration](#配置说明--configuration)
- [命令列表 / Commands](#命令列表--commands)
- [权限系统 / Permissions](#权限系统--permissions)
- [枪械目录 / Weapon catalog](#枪械目录--weapon-catalog)
- [自定义枪械 / Custom Weapons](#自定义枪械--custom-weapons)
- [更新日志 / Changelog](#更新日志--changelog)
- [常见问题 / FAQ](#常见问题--faq)
- [技术支持 / Support](#技术支持--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 [数量]` | 给予枪械 / 弹药 / 投掷物（枪械 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 `、商店、物品 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.`** 下可覆盖材质、显示名、弹匣、`fire_rate`、射击音效、弹药类型、`is_automatic` 等（详见该文件内注释）。
3. **重载**
```bash
/gun reload
```
4. **发放**
```bash
/gun give
```
### 注意事项 / Notes
- **同材质多枪**：若多把枪共用同一 `material`，仅靠材质无法区分；请使用插件发放的枪（带 **PDC 目录 ID**），或为不同枪指定 **不同材质**。
- **购买价格**：在 `config.yml` 的购买相关节配置，不在 `guns.yml`。
- 更细的字段表与音效格式说明见 **`guns.yml` 文件头** 与仓库内 **`CHANGELOG_5.0.0.md`**。
### 极简骨架示例 / Minimal skeleton（省略音效与后坐力细节时请直接复制完整条目改 ID）
```yaml
# 建议复制 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.md)**（中文累计日志）、**[CHANGELOG_EN.md](CHANGELOG_EN.md)**（英文）及 **[CHANGELOG_5.0.0.md](CHANGELOG_5.0.0.md)**（5.0.0 摘要）。
---
## ❓ 常见问题 / FAQ
### Q: 如何获得枪械？ / How to get weapons?
**A**: 使用命令 `/gun give ` 或通过配置文件自定义 / Use command `/gun give ` 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`**。详见上文 [自定义枪械](#自定义枪械--custom-weapons)。 / Edit **`plugins/GunPlugin/guns.yml`** (root key = gun id); optionally override via **`default_guns`** in **`config.yml`**; run **`/gun reload`**. See [Custom Weapons](#自定义枪械--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!** 🎯