- 版权类型
- 原创
- 插件中文名称
- 射击
- 插件英文名称
- Shoot
- 支持的核心(服务端)
- Spigot
- Paper
- Purpur
- PufferFish
- 语言支持
- 中文(简体)
- 适配版本(Java)
- 最新版本
- 26.x
- 1.21
- 1.20
[MD]
# Shoot — 模块化枪械、制导弹道与粒子技能引擎
[](#)
[](https://papermc.io/)
[](#)
[](#)
**Shoot** 是一款面向现代 Paper 及其衍生服务端的高性能、零强依赖枪械与粒子技能插件。无需客户端 Mod 或强制材质包,即可在原版客户端中实现 **6 种射击模式、10 种可缩放 3D 实体/粒子投射物、7 种制导与几何曲线弹道、31 种复合粒子几何图层、100 种可组合枪械技能事件**,并提供**全中文可视化游戏内 GUI 造枪工作台**与完善的开发者 API。
---
## 核心特性
- **零前置开箱即用**:无任何硬性前置依赖,放入 `plugins/` 即可独立运行;同时原生支持 `Vault` 经济与 `DeathZombieV4` 小游戏软依赖桥接。
- **单包宽跨度跨版本兼容**:底层内置反射与命名空间键兼容层(`BukkitSounds` / `BukkitParticles` / `BukkitPotions` / `BukkitAttributes`),单个 JAR 无缝运行于 **Paper / Purpur `1.20.5 ~ 26.3+`**(Java 21 ~ 25)。
- **全可视化 GUI 造枪工作台**:无需手写复杂 YAML,在游戏内通过 `/shoot make` 即可点选材质(含模糊搜索)、试听并检索原版全量音效、调节 3D 弹丸尺寸、配置追踪弹道、组合多层粒子与百种技能参数。
- **开箱自带 28 把预设武器 + 5 把进阶自定义样板枪**:涵盖常规热武器(手枪、步枪、霰弹枪、冲锋枪、狙击步枪、机枪、火箭筒)与科幻奇幻神器(黑洞吞噬者、超级激光炮、星辉主宰者、虚空星尘使者、循声炮、闪电链枪等)。
- **纯净生存服安全加固**:
- **PDC 防伪签名**:强制校验 `shoot:gun_id` 持久化标签,彻底杜绝生存玩家通过铁砧改名伪造神器。
- **生存经验无损快照**:使用经验条展示备弹进度时,切枪自动备份玩家真实生存等级与经验,切回普通物品或退服时原样归还,并在持枪期间拦截附魔台/铁砧消耗虚拟等级。
- **防刷枪与防误消耗闭环**:防止高弹匣堆叠枪械被拆分、工作台合成、熔炉烧炼、砂轮祛魔、副手方块放置或作为食物吞食。
- **世界与领地友好**:严格遵守世界 PvP 开关、创造/旁观免疫、`NPC` 保护、`Unbreakable` 装备保护以及原版伤害事件链,绝不误删玩家放置的末影水晶、装饰盔甲架或第三方商店悬浮物。
- **高并发密集战斗优化**:内置全局与单玩家双层粒子限流器(`ParticleLimiter`)、距离桶采样及 `minimal_shoot_particles` 极简性能开关,百怪同屏依然稳定 20 TPS。
---
## 环境要求与安装
| 项目 | 要求 |
| :--- | :--- |
| **服务端核心** | Paper / Purpur / Pufferfish 等基于 Paper API 的核心(推荐 Paper) |
| **Minecraft 版本** | `1.20.5` ~ `1.21.x` ~ `26.3+` |
| **Java 版本** | Java `21` 及以上(兼容 Java 21 ~ 25) |
| **必装前置** | **无** |
| **可选联动(SoftDepend)** | `Vault`(消耗型特效扣费)、`DeathZombieV4`(僵尸小游戏深度桥接) |
### 快速安装
1. 将 `shoot-1.5.0.jar` 放入服务端 `plugins/` 目录(若存在旧版 `shoot-*.jar`,请先删除旧包)。
2. 启动服务器,插件将自动生成 `plugins/Shoot/config.yml`、`preset_guns.yml` 与 `custom_guns.yml`。
3. 管理员可在游戏内输入 `/shoot gui` 打开枪械库直接取枪试射,或输入 `/shoot make list` 打开自定义枪械工作台。
---
## 基础操作指南
| 动作 | 默认操作方式 | 说明 |
| :--- | :--- | :--- |
| **开火射击** | 手持枪械 **右键** | 弹匣耗尽时若仍有备弹将自动触发换弹 |
| **手动换弹** | 手持枪械 **快速双击左键**(300ms 内) | 显示物品动态耐久进度条与 ActionBar 换弹百分比读条 |
| **弹药显示** | 物品堆叠数 + 物品 Lore + 经验条 | 物品数量实时映射当前弹匣余量(上限夹紧至 `99`),经验条等级显示剩余总备弹 |
| **提示开关** | `/shoot display <start\|hit\|reload> <on\|off>` | 玩家可自由开关个人的射击/命中/换弹屏幕标题反馈 |
---
## 模块化武器引擎能力一览
### 1. 六大射击模式(`shoot_mode`)
- `SINGLE_BULLET` — **单发子弹**:标准单发弹道推进,支持穿透、重力与射程控制
- `BURST` — **连发模式**:单次扣动扳机连续点射多发弹丸
- `SHOTGUN` — **霰弹模式**:一次扇形迸射多颗弹丸(可调弹丸数 `pellets` 与散射角 `spread`)
- `BEAM` — **持续光束**:高密度贯穿能量束/喷火射线(可调宽度 `width` 与持续时长 `duration`)
- `MISSILE` — **导弹轨迹**:抛物线/重型制导飞弹,支持落点范围爆轰
- `RAYCAST` — **即时命中**:零飞行延迟激光/狙击射线判定
### 2. 十种弹道介质与 3D 缩放投射物(`projectile`)
除纯粒子射线外,子弹可直接化为可见实体,且支持 **`0.2x ~ 5.0x` 3D 模型与碰撞箱自由缩放**(基于 `BlockDisplay` / `ItemDisplay` 与物理载体同步驱动):
- `PARTICLE`(纯粒子无实体)、`FALLING_BLOCK`(任意方块投射)、`ITEM`(任意物品/刀剑投射)
- `FIREBALL`(火球爆轰,不破坏地形)、`SMALL_FIREBALL`(高速烈焰弹)、`ENDER_CRYSTAL`(末影水晶引爆)
- `POTION`(自定义 Buff/Debuff 喷溅药水弹)、`TRIDENT`(旋转三叉戟)、`WIND_CHARGE`(击退微风弹)、`ARROW`(原版飞箭)
### 3. 七种动态弹道轨迹(`trajectory`)
- `STRAIGHT` — **常规直射**:经典高速无偏转直线
- `HOMING` — **智能锁敌**:自动索敌前方敌对目标,平滑角速度追踪咬合
- `LASER_GUIDED` — **准星制导**:飞行途中实时跟随射手准星视线拐弯,指哪打哪
- `SNAKE_WAVE` — **灵蛇摆动**:沿前进方向叠加正弦波横向游走
- `HELIX` — **螺旋回旋**:围绕主轴螺旋公转推进
- `BOOMERANG` — **回旋折返**:飞至射程远端后沿大圆弧折返射手手中
- `RANDOM` — **完全随机**:混沌扰动轨迹
### 4. 百种枪械技能事件(`gun_events`)与五种触发器
支持在同一把枪上叠加任意数量的技能事件,并绑定至 5 个生命周期节点:
`ON_SHOOT`(开火时)、`ON_HIT`(命中时)、`ON_KILL`(击杀时)、`ON_RELOAD_START`(开始换弹)、`ON_RELOAD_COMPLETE`(换弹完成)。
涵盖 **100 种内置技能事件**,包括但不限于:
- **元素与控制**:`LIGHTNING_STRIKE`(雷击)、`CHAIN_LIGHTNING`(连锁闪电)、`FREEZE`(冰封)、`FROST_NOVA`(寒霜新星)、`WEB_TRAP` / `ICE_PRISON` / `RUNE_PRISON`(蛛网/冰牢/符文囚笼,到期或关服自动无损回滚方块)、`GRAVITY_WELL`(重力井)、`STASIS_FIELD`(停滞力场)
- **机动与战术**:`PHASE_SHIFT`(相位突袭绕后)、`TEMPEST_RUSH`(风暴冲锋)、`PHOENIX_ASCENT`(凤凰升腾)、`SNAPBACK`(回返印)、`SWAP`(换位)、`DISARM`(缴械)、`ARMOR_BREAK`(破甲)、`DISPEL` / `SPELLBREAKER`(驱散/破法)
- **终极神技**:`METEOR_STRIKE`(陨火坠击)、`STARFALL`(星落碎片)、`JUDGMENT`(灵魂锁链分摊撕裂)、`TRIDENT_VORTEX`(空中三叉戟旋涡引雷)、`CEASELESS_HUNT`(混沌轮盘随机触发池)、`BLOOD_PACT`(血棱卫阵)、`SCARLET_REAP`(绯红收割)等
### 5. 复合粒子图层(`particle_composite`)与战术特效(`special_effects`)
- **31 种 3D 几何粒子形状**:点、线、圆、球、锥、螺旋、双螺旋、波浪、星形、环、圆柱、立方体、多边形、心形、无限符号 `∞`、花瓣、穹顶、金字塔、龙卷风及自定义点阵,支持按 `LAUNCH` / `FLIGHT` / `IMPACT` 阶段独立编排。
- **14 种特殊领域与支援效果**:`BLACK_HOLE`、`FIRE_ZONE`、`FREEZE_ZONE`、`LIGHTNING_FIELD`、`VOID_ZONE`、`WITHER_FIELD`、`SONIC_BLAST`、`TRIDENT_STORM`、`SLIME_MORPH`、`WEAPON_ENHANCEMENT`、`MASS_REVIVE`、`ULTIMATE_DAMAGE`、`AMMO_SUPPLY` 等。
---
## 指令与权限
主指令:`/shoot`(短别名:`/sh`)
### 基础与管理指令
| 指令 | 执行端 | 权限节点 | 说明 |
| :--- | :--- | :--- | :--- |
| `/shoot help` | 玩家 / 控制台 | `shoot.use` | 查看当前权限可见的指令帮助 |
| `/shoot display <start\|hit\|reload> <on\|off>` | 玩家 | `shoot.use` | 开关个人射击、命中、换弹屏幕 Title 提示 |
| `/shoot get <枪械ID或名称>` | 玩家 | `shoot.admin` | 给自己发放指定预设枪或自定义枪(已持有则自动补满弹药) |
| `/shoot give <玩家> <枪械ID或名称>` | **玩家 / 控制台** | `shoot.admin` | 向指定在线玩家发枪或补弹(可直接对接菜单、抽奖箱、命令方块) |
| `/shoot up` | 玩家 | `shoot.admin` | 立即补满主手枪械的弹匣与备用弹药 |
| `/shoot gui` | 玩家 | `shoot.admin` | 打开分页枪械库 GUI 点击取枪 |
| `/shoot reload` | **玩家 / 控制台** | `shoot.admin` | 热重载 `config.yml`、`preset_guns.yml`、`custom_guns.yml` 并刷新在线玩家枪械显示 |
| `/shoot clean` | **玩家 / 控制台** | `shoot.admin` | 立即清扫所有世界中残留的插件临时投射物实体并回滚临时陷阱方块 |
| `/shoot debuggun` / `/shoot debugfire` | 玩家 | `shoot.admin` | 查看主手枪械解析状态 / 强制触发一次调试射击 |
### 自定义枪械工作台指令(`/shoot make`)
| 指令 | 执行端 | 权限节点 | 说明 |
| :--- | :--- | :--- | :--- |
| `/shoot make list` | 玩家 | `shoot.make` | 打开「自定义枪械库」总览面板(支持新建、左键编辑、右键直接取枪试射) |
| `/shoot make create <gunId>` | 玩家 | `shoot.make` | 打开可视化创建面板新建枪械(保存时自动规范化 `custom_` 前缀) |
| `/shoot make edit [gunId]` | 玩家 | `shoot.make` | 编辑指定枪械;省略参数时直接编辑当前主手所持自定义/导入枪械 |
| `/shoot make delete <gunId>` | 玩家 | `shoot.make` | 删除指定自定义枪械 |
| `/shoot make give <玩家> <gunId>` | **玩家 / 控制台** | `shoot.make` | 发放指定自定义或 API 导入枪械 |
| `/shoot make reload` | **玩家 / 控制台** | `shoot.make.reload` | 单独热重载 `custom_guns.yml` |
### 权限节点说明
- `shoot.use`(默认:`true`):允许使用 `/shoot help` 与 `/shoot display`
- `shoot.make`(默认:`op`):允许使用自定义枪械 GUI 工作台全部功能(包含 `shoot.make.reload`)
- `shoot.make.reload`(默认:`op`):允许重载自定义枪械配置
- `shoot.admin`(默认:`op`):管理员全量权限(自动继承 `shoot.use`、`shoot.make`、`shoot.make.reload`)
---
## 配置文件说明
### 1. `config.yml`
```yaml
# 调试日志开关(生产环境请保持 false)
debug: false
# 防移动/防副手/防丢弃拦截时是否发送聊天框提示(false = 静默拦截)
error_messages:
enabled: false
# 弹药显示与生存服经验保护
ammo_display:
use_xp_bar: true
# 开启后切枪自动快照玩家真实生存经验,切回普通物品或退服时原样归还,且持枪期间禁止附魔台消耗虚拟等级
snapshot_survival_xp: true
# 旧版无 PDC 物品名称匹配兼容(生存服请务必保持 false,防止铁砧改名伪造枪械)
legacy:
allow_display_name_matching: false
# 密集战斗粒子限流
particles:
global_max: 8000
per_player_max: 400
fallback: FLAME
# 极简射击粒子模式(开启后仅保留命中瞬间粒子,最大化帧率与网络吞吐)
performance:
minimal_shoot_particles: false
```
### 2. `custom_guns.yml` 进阶配置示例
除了在游戏内使用 `/shoot make` 可视化编辑外,也可直接编写 YAML:
```yaml
custom_guns:
star_seeker:
name: "&b&l星轨追猎者"
material: DIAMOND_HOE
lore:
- "&7发射自动索敌的末影水晶能量弹"
ammo: 180
clip_size: 18
reload_time: 2.2
cooldown: 0.35
damage: 120
special_damage: 80
range: 75
sounds:
shoot_start: "ENTITY_ILLUSIONER_CAST_SPELL"
shoot_hit: "ENTITY_GENERIC_EXPLODE"
volume: 1.0
pitch: 1.2
shoot_mode:
type: "SINGLE_BULLET"
speed: 2.2
range: 75
penetration: false
gravity: false
projectile:
type: "ENDER_CRYSTAL"
speed: 2.2
size: 0.6
lifetime: 5.0
trajectory:
enabled: true
pattern: "HOMING"
turn_rate: 0.18
lock_distance: 28.0
gun_events:
- type: "CHAIN_LIGHTNING"
trigger: "ON_HIT"
max_targets: 4
range: 8.0
damage_reduction: 0.6
- type: "SPEED_BOOST"
trigger: "ON_KILL"
duration: 3.0
level: 2
```
---
## 开发者 API 接入指南
`Shoot` 在启动时通过 Bukkit `ServicesManager` 注册了 `org.Ver_zhzh.shoot.api.ShootApi` 服务,第三方插件(如 RPG 怪物/Boss 插件、小游戏插件、商店插件)可零耦合接入:
### 1. `plugin.yml` 声明软依赖
```yaml
softdepend: [Shoot]
```
### 2. 获取 `ShootApi` 实例与常用调用
```java
import org.Ver_zhzh.shoot.api.ShootApi;
import org.bukkit.Bukkit;
import org.bukkit.entity.LivingEntity;
import org.bukkit.entity.Player;
import org.bukkit.inventory.ItemStack;
import org.bukkit.util.Vector;
ShootApi shootApi = Bukkit.getServicesManager().load(ShootApi.class);
if (shootApi != null) {
// 1. 生成带标准防伪 PDC 签名的枪械物品,或直接向玩家发枪/补弹
ItemStack gunItem = shootApi.createGunItem("毁灭者");
shootApi.giveGun(player, "custom_lightning_rifle");
// 2. 让任意实体(玩家、自定义怪物、Boss)朝指定方向向量直接发射任意枪械!
Vector aimDirection = bossEntity.getLocation().getDirection();
shootApi.shootGun(bossEntity, "步枪", aimDirection);
// 3. 给玩家当前主手枪械施加 30 秒临时超载(1.5 倍伤害 + 0.8 倍冷却 + 额外弹匣 + 命中附带雷击)
var currentGun = shootApi.resolveGunFromItem(player.getInventory().getItemInMainHand());
if (currentGun != null) {
shootApi.applyTemporaryWeaponUpgrade(player, currentGun, 30, 1.5, 0.8, 10, 60, "LIGHTNING_STRIKE");
}
// 4. 一键补满玩家背包内所有枪械弹药
int refilledCount = shootApi.replenishAllPlayerGuns(player);
}
```
此外,`ShootApi` 还提供:
- `registerGunEvent(...)` / `registerSpecialEffect(...)`:注册外部自定义的枪械事件与特殊效果,自动融入 Shoot 执行链;
- `registerImportedGun(Gun)`:动态注入外部插件定义的枪械,可在 `/shoot make list` 面板中查看与快照调参;
- `applyAllGunsDamageBoost(...)` / `activateNextHitHealthPercentBonus(...)` / `activateMoneyMultiplier(...)` / `scheduleTeamRally(...)`:团队增益状态与倒计时 BossBar 托管。
---
## 从源码构建
需要 JDK 21+ 与 Maven 3.9+:
```bash
# 标准构建并运行全部单元测试(生成 target/shoot-1.5.0.jar)
mvn clean package
```
---
## 作者与许可
- **作者**:`Ver_zhzh`
- **当前版本**:`1.5.0`
[/MD]
##运行截图(部分的)
##运行截图(部分的)