高级插件 - GunPlugin | 我的世界Tinksp资源论坛

支持版本

1.21.X

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

下载插件 / Download Plugin

代码：

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

启动服务器 / Start Server

代码：

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

配置插件 / Configure Plugin

代码：

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

设置权限 / Set Permissions

代码：

# 给玩家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

代码：

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

代码：

/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

代码：

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

编辑 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 列表（每项 [水平, 垂直]）。
- 文件顶部有 中英文注释，逐项说明各键含义。
（可选）覆盖而不改 guns.yml
在 config.yml 的 default_guns.<枪械ID> 下可覆盖材质、显示名、弹匣、fire_rate、射击音效、弹药类型、is_automatic 等（详见该文件内注释）。
重载
代码：
```
/gun reload
```
发放
代码：
```
/gun give <枪械ID>
```

注意事项 / Notes

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

极简骨架示例 / Minimal skeleton

代码：

# 建议复制 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。

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!

反馈： xiaoqiannb

高级插件 GunPlugin 2026-05-11