GunPlugin

GunPlugin - 枪械插件

Minecraft Version

Spigot API

Java Version

一个功能丰富的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

- Blood Effects / Blood Effects: 手枪、步枪、霰弹枪、狙击枪 - Blood Effects / Blood Effects: 子弹速度、重力下坠、穿透效果 - Blood Effects / Blood Effects: 弹匣容量、换弹机制、弹药显示 - Blood Effects / Blood Effects: 单发、连发、霰弹枪多发 - Blood Effects / Blood Effects: 视觉反馈和粒子效果 - Blood Effects / Blood Effects: 30%额外伤害 - Blood Effects / Blood Effects: 击中实体的粒子效果

高级功能 / Advanced Features

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

---

📦 安装指南 / Installation

系统要求 / Requirements

- Memory / Memory: 1.21.4 - Memory / Memory: Spigot/Paper - Memory / Memory: 8 或更高版本 / 8 or higher - Memory / Memory: 建议2GB以上 / Recommended 2GB+

安装步骤 / Installation Steps

1. Download Plugin / Download Plugin ```bash

将GunPlugin.jar放入服务器的plugins文件夹

Place GunPlugin.jar in your server's plugins folder

```

2. Start Server / Start Server ```bash

重启服务器以加载插件

Restart your server to load the plugin

```

3. Configure Plugin / Configure Plugin ```bash

编辑plugins/GunPlugin/config.yml文件

Edit plugins/GunPlugin/config.yml file

```

4. Set Permissions / Set Permissions ```bash

给玩家gunplugin.use权限

Give players gunplugin.use permission

```

---

⚙️ 配置说明 / Configuration

配置文件分工 / Config File Roles

| 文件 / File | 路径 / Path | 作用 / Purpose | |---|---|---| | 插件与商店 | `plugins/GunPlugin/guns.yml` | 插件与商店：每把枪的完整定义（伤害、`rate`、弹匣、换弹、`sounds`、`recoil`、`category`/`behavior` 等）。根键名即枪械 ID。 | | 插件与商店 | `plugins/GunPlugin/config.yml` | 插件与商店：`settings`、购买与经济 `buy_system`、`default_guns` 单枪覆盖、配件价格等。 |

修改 `/gun reload` 或 `/gun reload` 后请执行 `/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 的小数可按「秒/发」解析（见配置注释）

```

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

---

📝 命令列表 / Commands

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

基础命令 / Basic Commands

| 命令 / Command | 描述 / Description | |---|---| | `/gun give <目标> <guns.yml 枪械 ID | 弹药 | 投掷物> [数量]` | 给予枪械 / 弹药 / 投掷物（枪械 ID 与 配件改装一致；别名如 `pistol`→`p250` 见帮助） | | `/gun ammo` | 主手持枪：查看当前弹药 | | `/gun ammo reload` | 主手持枪：执行换弹 | | `/gun reload` | 配件改装（不是游戏内换弹） | | `/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` | 在游戏内`/gun`（射击、开镜、交互等） | `true` | | `gunplugin.admin` | 使用 `/gun` 全部子命令（默认 OP） | `op` |

权限配置示例 / Permission Configuration Example

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

---

🔫 枪械目录 / Weapon catalog

默认及自定义枪械均由 `CHANGELOG_5.0.0.md` 定义（根键即枪械 ID）。数值、别名与列表说明见该文件及仓库 `CHANGELOG_5.0.0.md`，此处不再维护易过期的静态枪械表。

---

🛠️ 自定义枪械 / Custom Weapons

当前版本枪械 根键名：复制任意现有枪械条目，修改 根键名（=`枪械 ID`，建议小写）并按需改字段即可新增一枪。

步骤 / Steps

1. 中英文注释 `plugins/GunPlugin/guns.yml` - 根键：枪械 ID，用于 `/gun give <id>`、商店、物品 PDC `gun_catalog_id`。 - 中英文注释（缺一不可）：`material`、`display_name`、`damage`、`rate`（中英文注释）、`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` 推断。 - 中英文注释：每分钟发数 RPM；射击间隔(秒) ≈ `60 / rate`。 - 中英文注释：`style: normal`（参数式）或 `style: pattern` + `points` 列表（每项 `[水平, 垂直]`）。 - 文件顶部有 中英文注释，逐项说明各键含义。

2. `default_guns.<枪械ID>` 在 `config.yml` 的 `default_guns.<枪械ID>` 下可覆盖材质、显示名、弹匣、`fire_rate`、射击音效、弹药类型、`is_automatic` 等（详见该文件内注释）。

3. 重载 ```bash /gun reload ```

4. 发放 ```bash /gun give <枪械ID> ```

注意事项 / Notes

- `CHANGELOG_5.0.0.md`：若多把枪共用同一 `material`，仅靠材质无法区分；请使用插件发放的枪（带 `CHANGELOG_5.0.0.md`），或为不同枪指定 `CHANGELOG_5.0.0.md`。 - `CHANGELOG_5.0.0.md`：在 `config.yml` 的购买相关节配置，不在 `guns.yml`。 - 更细的字段表与音效格式说明见 `CHANGELOG_5.0.0.md` 与仓库内 `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_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?

`/gun reload`: 在 `/gun reload` 中新增或复制枪械条目（根键即枪械 ID），必要时用 `/gun reload` 的 `/gun reload` 做覆盖；执行 `/gun reload`。详见上文 `/gun reload`。 / Edit `/gun reload` (root key = gun id); optionally override via `/gun reload` in `/gun reload`; run `/gun reload`. See %%MD1%%.

Q: 支持哪些Minecraft版本？ / Which Minecraft versions are supported?

A: 目前支持Minecraft 1.21.x / Currently supports Minecraft 1.21.x

Q: 如何调整子弹散步？ / How to adjust bullet spread?

`guns.yml`: 在 `guns.yml` 中调整 `guns.yml` 及 `guns.yml` 相关参数 / Tune `guns.yml` and `guns.yml` in `guns.yml`

---

🆘 技术支持 / Support

欢迎通过 website 中的 website（Modrinth 等发布页）反馈问题。

许可证 / License

若仓库内附有许可证文件则以该文件为准；否则请以插件发布页的授权说明为准。

---

Enjoy the shooting experience! / Enjoy the shooting experience! 🎯