# GunPlugin - 枪械插件
[](https://minecraft.net)
[](https://spigotmc.org)
[](https://openjdk.java.net)
一个功能丰富的 Minecraft 枪械插件，支持多种枪械类型、配置、真实弹道系统和完整的射击体验。
一款功能丰富的 Minecraft 枪械插件，具有多种武器类型、自定义配置、逼真的弹道系统和完整的射击体验。
---
## 目录/目录
- [功能特性/Features](#功能特性--features)
- [安装指南/安装](#安装指南--安装)
- [配置说明/配置](#配置说明--configuration)
- [命令列表 / Commands](#命令列表--commands)
- [权限系统 / Permissions](#权限系统--permissions)
- [枪械目录 / 武器目录](#枪械目录--weapon-catalog)
- [自定义枪械 / Custom Weapons](#自定义枪械--custom-weapons)
- [更新日志 / 变更日志](#更新日志--变更日志)
- [常见问题 / FAQ](#常见问题--faq)
- [技术支持/支持](#技术支持--support)
---
## 功能特性/特点
### 核心功能/核心特性
- **多种枪械类型** / **多种武器类型**：手枪、高精度弹枪、狙击枪
- **真实弹道系统** / **Realistic Ballistics**: 子弹速度、重力下坠、近似效果
- **弹药管理系统** / **弹药系统**：弹匣容量、换弹机制、弹药显示机制
- **射击模式** / **射击模式**：单发、连发、霰弹枪多发
- **后坐力系统** / **反冲系统**：视觉反馈和粒子效果
- **爆头检测** / **爆头检测**：30% 额外伤害
- **血雾效果** / **血液效果**：击中实体的粒子效果
### 高级功能/高级功能
- **自定义枪械** / **自定义武器**: 通过配置文件创建自定义枪械
- **子弹散布** / **子弹散布**：移动时增加散布，鼓励平静射击
- **音效系统** / **声音系统**：多层次延迟音效，增强沉浸感
- **交互禁止** / **交互禁用**：持枪时取消左键攻击和右侧交互
- **自动射击** / **自动射击**：按住右键连续射击，开始停止
- **手动换弹** / **手动装弹**：F键手动换弹功能
---
## 安装指南/安装
### 系统要求/要求
- **我的世界版本** / **我的世界版本**：1.21.4
- ** 服务器类型** / **服务器类型**： Spigot/Paper
- **Java版本** / **Java版本**：8或更高版本/8或更高
- **内存要求** / **内存**：建议2GB以上 / 推荐2GB+
### 安装步骤/安装步骤
1. **下载插件** / **下载插件**
```bash
# 将GunPlugin.jar放入服务器的plugins文件夹
将 GunPlugin.jar 文件放入服务器的插件文件夹中
```
2. **启动服务器** / **启动服务器**
```bash
# 重启服务器以加载插件
# 重启服务器以加载插件
```
3. **配置插件** / **配置插件**
```bash
# 编辑plugins/GunPlugin/config.yml文件
# 编辑 plugins/GunPlugin/config.yml 文件
```
4. **设置权限** / **设置权限**
```bash
# 给玩家gunplugin.use权限
# 授予玩家 gunplugin.use 权限
```
---
## ⚙️ 配置说明/配置
###配置文件分工/配置文件角色
| 文件/文件| 路径 / 路径 | 作用/目的|
|---|---|---|
| **枪.yml** | `插件/GunPlugin/guns.yml` | **枪械目录**：每把枪的完整定义（伤害、`速率`、弹匣、换弹、`声音`、`后坐力`、`类别`/`行为`等）。根键名即枪械ID。
| **配置.yml** | `插件/GunPlugin/config.yml` | **插件与商店**：`settings`、购买与经济`buy_system`、`default_guns`单枪覆盖、配件价格等。
修改 **`guns.yml`** 或 **`config.yml`** 后请执行 **`/gun reload`**（需权限）或重启服务端。
### 基础配置示例 / 基本 `config.yml` 摘录
```yaml
设置：
禁用左键：true
禁用右键交互：true
debug_mode: false
# 可选：按枪械ID覆盖部分属性（材质、名称、射速等），参见配置内注释
# 默认枪支：
# 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`、`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
/gun reload
```
4. **发放**
```bash
/gun give <枪械ID>
```
### 注意事项 / 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 <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`**。详见上文 [自定义枪械](#自定义枪械--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!**