吐息武器

吐息武器

这是一个用于将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",
  ...
}

故障排除

粒子不显示

问题: 我生成了粒子,但游戏中没有出现。

解决方案:

  1. 检查粒子定义是否在正确的文件夹中:data/yourmodid/particles/name.json
  2. 验证粒子 ID 是否与 JSON 文件名匹配
  3. 使用 /reload 重新加载数据
  4. 检查纹理路径是否存在:assets/yourmodid/textures/particle/name.png
  5. 验证你在正确的层级(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);
}

纹理未加载

问题: 粒子出现但纹理错误。

解决方案:

  1. 验证纹理路径使用正斜杠:"mymod:particle/name"
  2. 检查纹理文件是否为 PNG 格式
  3. 纹理路径不应包含 .png 扩展名
  4. 纹理应位于 assets/yourmodid/textures/

光束位置错误

问题: 光束起点/终点位置错误。

解决方案:

  1. 使用世界空间坐标(而非相对坐标)
  2. 对于实体:使用 entity.getEyePosition() 获取眼睛高度
  3. 对于方块:使用 new Vec3(x + 0.5, y + 0.5, z + 0.5) 获取中心
  4. 验证 from 和 to 不是相同位置

粒子过慢/过快

问题: 粒子运动与预期速度不符。

解决方案:

  1. 增加 burst() 或 stream() 中的 speed 参数
  2. 调整 drag - 较低的值 = 速度保持更久
  3. 检查粒子生成速度是否正确
  4. 使用 gravity 随时间增加动量

GeckoLib 模型未加载

问题: 类型为 "geo" 但模型不渲染。

解决方案:

  1. 验证模型文件路径是否正确
  2. 检查 .geo.json 文件是否存在
  3. JSON 中的模型路径不应包含 .geo.json(仅使用不含扩展名的 path)
  4. 纹理路径必须与模型的纹理引用匹配
  5. 动画名称必须完全匹配(区分大小写)

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 服务器:

祝你创建出精彩的粒子效果!