
吐息武器
这是一个用于将geckolib模型渲染为粒子的库/API模组
查看大图使用 BreathWeapon
本指南说明如何将 BreathWeapon 粒子系统集成到你的 Minecraft 模组中,无需编写复杂的渲染代码即可创建自定义粒子。
环境配置
1. 添加依赖
在你的 build.gradle 中,将 BreathWeapon 添加到依赖项:
mavenCentral()
exclusiveContent {
forRepository {
maven {
name = "Modrinth"
url = "https://api.modrinth.com/maven"
}
}
forRepositories(fg.repository)
filter {
includeGroup "maven.modrinth"
}
}
dependencies {
implementation fg.deobf("maven.modrinth:breath-weapon:0.0.1")
}
2. 导入 API
在你的代码中,导入生成工具类:
import com.dracolich777.breathweapon.util.ParticleSpawner;
import com.dracolich777.breathweapon.api.particle.ParticleRegistry;
import net.minecraft.resources.ResourceLocation;
快速开始
最小配置
1. 创建粒子定义 JSON:
src/main/resources/data/yourmodid/particles/my_effect.json
{
"type": "sprite",
"lifetime": 50
}
2. 在代码中生成粒子:
ParticleSpawner.spawn(level,
new ResourceLocation("yourmodid", "my_effect"),
x, y, z,
vx, vy, vz);
就这么简单!粒子将以默认纹理和物理效果渲染。
创建粒子定义
粒子定义是放置在你模组数据包中的 JSON 文件。创建位置:
src/main/resources/data/yourmodid/particles/particle_name.json
文件结构
src/main/resources/
├── assets/yourmodid/
│ └── textures/
│ └── particle/
│ ├── beam.png
│ ├── spark.png
│ └── smoke.png
└── data/yourmodid/
└── particles/
├── my_beam.json
├── my_spark.json
└── my_smoke.json
基础 JSON 结构
每个粒子定义都具有以下结构:
{
"type": "sprite | beam | geo",
"texture": "yourmodid:textures/particle/name",
"lifetime": 200,
"scale": 1.0,
"gravity": 0.0,
"drag": 1.0,
"light": { ... },
"animation": { ... }
}
通用属性
所有粒子类型都支持:
| 属性 | 类型 | 默认值 | 描述 |
|---|---|---|---|
type |
string | "sprite" | 粒子类型:sprite、beam 或 geo |
lifetime |
int | 200 | 持续时间(以刻为单位,1 刻 = 50ms) |
scale |
float | 1.0 | 尺寸倍数(0.1 - 10.0) |
gravity |
float | 0.0 | 向下加速度(负值 = 向上) |
drag |
float | 1.0 | 速度阻尼(0.9 = 每刻减速 10%) |
texture |
string | null | 纹理路径,格式为 modid:path |
光照配置
为粒子添加发光/动态光照:
{
"type": "sprite",
"light": {
"mode": "glow",
"color": [1.0, 0.5, 0.0],
"intensity": 1.0
}
}
光照模式:
"none"- 无特殊光照"glow"- 恒定发光效果"pulse"- 脉冲式亮度
用于 Glow/Pulse:
"light": {
"mode": "glow",
"color": [r, g, b],
"intensity": brightness_0_to_2
}
用于 Pulse:
"light": {
"mode": "pulse",
"color": [r, g, b],
"intensity": 1.0,
"pulse_min": 0.3,
"pulse_max": 1.0,
"pulse_speed": 0.1
}
生成粒子
基础生成
单个粒子:
ParticleSpawner.spawn(level,
new ResourceLocation("yourmodid", "my_particle"),
x, y, z,
velocityX, velocityY, velocityZ);
模式生成
爆发(随机方向):
ParticleSpawner.burst(level,
new ResourceLocation("yourmodid", "spark"),
center, // Vec3 位置
count, // 粒子数量(例如 10)
speed); // 速度,单位为方块/刻(例如 0.5)
流(定向):
ParticleSpawner.stream(level,
new ResourceLocation("yourmodid", "smoke"),
entity, // 生成粒子的实体
count, // 粒子数量
speed, // 粒子速度
spread); // 角度散布,单位为弧度
光束生成
均匀光束:
ParticleSpawner.spawnBeam(level,
new ResourceLocation("yourmodid", "laser"),
from, // Vec3 起始位置
to, // Vec3 结束位置
width); // 光束宽度(例如 0.3f)
锥形光束(宽度沿长度变化):
ParticleSpawner.spawnBeam(level,
new ResourceLocation("yourmodid", "laser"),
from, // Vec3 起点
to, // Vec3 终点
startWidth, // 起始宽度(例如 0.5f)
endWidth); // 结束宽度(例如 0.1f)
粒子类型
类型 1:Sprite(默认)
简单的 2D 粒子。快速且轻量。
定义:
{
"type": "sprite",
"texture": "yourmodid:particle/spark",
"lifetime": 30,
"scale": 0.5,
"gravity": 0.05,
"drag": 0.98,
"light": {
"mode": "glow",
"color": [1.0, 1.0, 0.0],
"intensity": 0.8
}
}
最适用于: 火花、闪光、尘土、简单效果
类型 2:Beam
两点之间的公告板。支持动态端点。
定义:
{
"type": "beam",
"texture": "yourmodid:particle/laser",
"lifetime": 100,
"scale": 1.0,
"light": {
"mode": "glow",
"color": [1.0, 0.0, 0.0],
"intensity": 1.5
}
}
最适用于: 激光、能量冲击、定向攻击、追踪弹
类型 3:Geo(GeckoLib 模型)
支持动画的完整 3D 模型。
定义:
{
"type": "geo",
"model": "yourmodid:geo/explosion.geo.json",
"texture": "yourmodid:textures/particle/explosion.png",
"animation": "yourmodid:animations/explosion.animation.json",
"anim_name": "animation.explosion.burst",
"lifetime": 50,
"scale": 0.8,
"gravity": -0.05,
"drag": 0.95,
"spin": {
"yaw": 5.0,
"pitch": 2.0,
"roll": 3.0
}
}
属性:
model- 你的 GeckoLib.geo.json文件路径texture- 模型的纹理animation- 动画文件路径(可选)anim_name- 要播放的动画名称(可选)spin- 旋转速度,单位为度/刻(可选)
最适用于: 复杂效果、爆炸、魔法效果、自定义模型
高级功能
动态光束端点
让光束追踪目标或随时间移动:
import com.dracolich777.breathweapon.client.particle.SimpleBeamParticle;
// 生成时,你需要直接访问粒子
// 这需要自定义生成方式或事件监听器
SimpleBeamParticle.EndpointProvider provider = (age, lifetime) -> {
// 根据存活时间计算新位置
float progress = age / (float) lifetime;
// 示例:螺旋端点
double angle = progress * Math.PI * 4; // 2 圈旋转
double newX = centerX + Math.cos(angle) * radius;
double newY = centerY + Math.sin(angle) * radius;
double newZ = centerZ + Math.sin(progress * Math.PI) * 5;
return new SimpleBeamParticle.BeamEndpoint(newX, newY, newZ);
};
// 设置到粒子上(需要通过事件或钩子直接访问粒子)
particle.setEndpointProvider(provider);
物理自定义
控制粒子的运动方式:
{
"gravity": 0.1, // 下落速度(正值 = 向下,负值 = 向上)
"drag": 0.95, // 每刻减速 5%
"scale": 1.5 // 使其变大 1.5 倍
}
示例:
- 漂浮效果:
"gravity": -0.01, "drag": 1.0 - 缓慢下落:
"gravity": 0.02, "drag": 0.99 - 淡出: 使用较短的 lifetime + 较高的 drag
- 快速缩放: 使用较高的初始速度 + 较低的 gravity
完整示例
示例 1:能量光束攻击
JSON 定义(data/mymod/particles/energy_blast.json):
{
"type": "beam",
"texture": "mymod:particle/energy_beam",
"lifetime": 80,
"scale": 0.9,
"light": {
"mode": "glow",
"color": [0.2, 0.7, 1.0],
"intensity": 1.3
}
}
生成代码(在技能处理器中):
@SubscribeEvent
public static void onPlayerAttack(LivingAttackEvent event) {
if (event.getEntity() instanceof Player player &&
player.level() instanceof ServerLevel level) {
Vec3 from = player.getEyePosition();
Vec3 to = from.add(player.getLookAngle().scale(50));
ParticleSpawner.spawnBeam(level,
new ResourceLocation("mymod", "energy_blast"),
from, to, 0.2f);
}
}
示例 2:爆炸效果
JSON 定义(data/mymod/particles/explosion_burst.json):
{
"type": "sprite",
"texture": "mymod:particle/explosion",
"lifetime": 40,
"scale": 1.2,
"gravity": -0.02,
"drag": 0.96,
"light": {
"mode": "pulse",
"color": [1.0, 0.6, 0.0],
"intensity": 1.5,
"pulse_min": 0.5,
"pulse_max": 1.5,
"pulse_speed": 0.15
}
}
生成代码:
public static void createExplosion(ServerLevel level, Vec3 center, int power) {
ParticleSpawner.burst(level,
new ResourceLocation("mymod", "explosion_burst"),
center,
power * 3, // 爆炸越大,粒子越多
power * 0.1); // 爆炸越大,散布越快
}
示例 3:魔法光环
JSON 定义(data/mymod/particles/mana_dust.json):
{
"type": "sprite",
"texture": "mymod:particle/mana",
"lifetime": 100,
"scale": 0.6,
"gravity": -0.005,
"drag": 0.98,
"light": {
"mode": "glow",
"color": [0.7, 0.3, 1.0],
"intensity": 0.9
}
}
生成代码(在实体 tick 中):
public void createManaAura(Entity entity, ServerLevel level) {
Vec3 pos = entity.position().add(0, entity.getBbHeight() / 2, 0);
// 在实体周围生成少量粒子爆发
ParticleSpawner.burst(level,
new ResourceLocation("mymod", "mana_dust"),
pos,
5, // 5 个粒子
0.3); // 缓慢散布
}
示例 4:状态效果指示器
JSON 定义(data/mymod/particles/poison_cloud.json):
{
"type": "sprite",
"texture": "mymod:particle/poison",
"lifetime": 60,
"scale": 0.8,
"gravity": 0.01,
"drag": 0.99,
"light": {
"mode": "glow",
"color": [0.3, 0.8, 0.2],
"intensity": 0.7
}
}
生成代码(效果激活期间):
@SubscribeEvent
public static void onLivingUpdate(LivingTickEvent event) {
LivingEntity entity = event.getEntity();
if (entity.hasEffect(MobEffects.POISON) &&
entity.level() instanceof ServerLevel level &&
entity.tickCount % 5 == 0) { // 每 5 刻
Vec3 pos = entity.position().add(
(Math.random() - 0.5) * 0.5,
Math.random() * entity.getBbHeight(),
(Math.random() - 0.5) * 0.5
);
ParticleSpawner.spawn(level,
new ResourceLocation("mymod", "poison_cloud"),
pos.x, pos.y, pos.z,
0, -0.05, 0); // 轻微向上飘移
}
}
检查粒子可用性
生成之前,验证粒子已注册:
import com.dracolich777.breathweapon.api.particle.ParticleRegistry;
ResourceLocation particleId = new ResourceLocation("yourmodid", "my_particle");
if (ParticleRegistry.has(particleId)) {
// 可以安全生成
ParticleSpawner.spawn(level, particleId, x, y, z, 0, 0, 0);
} else {
LOGGER.warn("Particle not found: {}", particleId);
}
获取粒子信息:
var definition = ParticleRegistry.get("yourmodid:my_particle");
if (definition != null) {
int lifetime = definition.getLifetime();
float scale = definition.getScale();
String type = definition.getType(); // "beam", "geo", "sprite"
}
最佳实践
1. 组织你的粒子
data/yourmodid/particles/
├── abilities/
│ ├── fireball.json
│ ├── lightning.json
│ └── healing_circle.json
├── effects/
│ ├── hit_effect.json
│ ├── death_burst.json
│ └── buff_indicator.json
└── ambient/
├── magical_dust.json
├── fire_embers.json
└── water_splash.json
2. 保持较短的持续时间
不要让粒子的持续时间超过所需:
- 火花:20-60 刻
- 光束:50-150 刻
- 爆炸:30-100 刻
- 环境粒子:60-200 刻
3. 测试物理效果
{
"gravity": 0.0, // 从无重力开始
"drag": 1.0 // 从无阻尼开始
}
然后根据视觉表现进行调整。
4. 使用合适的类型
- Sprite - 大多数效果(快速)
- Beam - 定向效果、攻击
- Geo - 特殊场合(较慢)
5. 复用定义
创建一个定义并多次生成:
for (int i = 0; i < 10; i++) {
ParticleSpawner.spawn(level,
new ResourceLocation("mymod", "explosion"),
x, y, z,
randomVelX, randomVelY, randomVelZ);
}
6. 为 JSON 添加描述
{
"_comment": "Blue energy beam - used for mage spell attacks",
"type": "beam",
...
}
故障排除
粒子不显示
问题: 我生成了粒子,但游戏中没有出现。
解决方案:
- 检查粒子定义是否在正确的文件夹中:
data/yourmodid/particles/name.json - 验证粒子 ID 是否与 JSON 文件名匹配
- 使用
/reload重新加载数据 - 检查纹理路径是否存在:
assets/yourmodid/textures/particle/name.png - 验证你在正确的层级(ServerLevel,而非 ClientLevel)
调试代码:
var def = ParticleRegistry.get("yourmodid:my_particle");
if (def == null) {
LOGGER.error("Particle not found in registry!");
} else {
LOGGER.info("Particle found: {}", def);
}
纹理未加载
问题: 粒子出现但纹理错误。
解决方案:
- 验证纹理路径使用正斜杠:
"mymod:particle/name" - 检查纹理文件是否为 PNG 格式
- 纹理路径不应包含
.png扩展名 - 纹理应位于
assets/yourmodid/textures/
光束位置错误
问题: 光束起点/终点位置错误。
解决方案:
- 使用世界空间坐标(而非相对坐标)
- 对于实体:使用
entity.getEyePosition()获取眼睛高度 - 对于方块:使用
new Vec3(x + 0.5, y + 0.5, z + 0.5)获取中心 - 验证
from和to不是相同位置
粒子过慢/过快
问题: 粒子运动与预期速度不符。
解决方案:
- 增加
burst()或stream()中的speed参数 - 调整
drag- 较低的值 = 速度保持更久 - 检查粒子生成速度是否正确
- 使用
gravity随时间增加动量
GeckoLib 模型未加载
问题: 类型为 "geo" 但模型不渲染。
解决方案:
- 验证模型文件路径是否正确
- 检查
.geo.json文件是否存在 - JSON 中的模型路径不应包含
.geo.json(仅使用不含扩展名的path) - 纹理路径必须与模型的纹理引用匹配
- 动画名称必须完全匹配(区分大小写)
API 参考
ParticleSpawner 方法
// 单个粒子
ParticleSpawner.spawn(level, id, x, y, z, vx, vy, vz);
ParticleSpawner.spawn(level, id, x, y, z, vx, vy, vz, extraData);
// 模式
ParticleSpawner.burst(level, id, center, count, speed);
ParticleSpawner.stream(level, id, entity, count, speed, spread);
// 光束
ParticleSpawner.spawnBeam(level, id, from, to, width);
ParticleSpawner.spawnBeam(level, id, from, to, startWidth, endWidth);
ParticleRegistry 方法
ParticleRegistry.register(id, definition);
ParticleRegistry.get(id);
ParticleRegistry.has(id);
ParticleRegistry.getAll();
ParticleRegistry.getAllFromMod(namespace);
需要帮助?
- 在 Discord 上私信我或加入我的 Discord 服务器:
- Discord 服务器
.themrsuit
祝你创建出精彩的粒子效果!
正在加载版本记录…

正在加载评论…
评论在新手盒子客户端中发表,这里同步展示。