特效系统

Behemiron 提供两套特效系统：Snowstorm（原生 Bedrock 粒子）和 Photon（类 Unity 特效）运行时。

概念导图

Snowstorm

Bedrock 粒子系统，使用 JSON 格式定义，支持 MoLang 脚本。

播放 API

kotlin

import com.behemiron.engine.forge.module.effect.snowstorm.SnowstormManager

// 在指定位置播放
val runtime = SnowstormManager.play("snow.json", level, position)

// 绑定到实体
val runtime = SnowstormManager.play("aura.json", entity)

// 停止
SnowstormManager.stop(runtime)
SnowstormManager.stopAll()

// 预加载
SnowstormManager.preload("snow.json") { fx ->
    println("Loaded: ${fx?.description?.identifier}")
}

// 统计
val count = SnowstormManager.getActiveCount()

运行时控制

kotlin

val runtime = SnowstormManager.play("effect.json", level, pos)

// 位置
runtime.position = Vec3(x, y, z)

// 状态
runtime.active = false  // 暂停发射
runtime.age             // 当前年龄（秒）
runtime.lifetime        // 总生命周期

// 绑定
runtime.bindToEntity(entity)

// 移除
runtime.remove()

JSON 格式

Snowstorm 使用 Bedrock 粒子格式（版本 1.10.0）：

json

{
  "format_version": "1.10.0",
  "particle_effect": {
    "description": {
      "identifier": "snowstorm:snow",
      "basic_render_parameters": {
        "material": "particles_alpha",
        "texture": "snow.png"
      }
    },
    "components": {
      "minecraft:emitter_rate_steady": {
        "spawn_rate": 80,
        "max_particles": 4000
      },
      "minecraft:emitter_lifetime_looping": {
        "active_time": 1
      },
      "minecraft:emitter_shape_box": {
        "offset": [0, 20, 0],
        "half_dimensions": [36, 0, 36],
        "direction": ["Math.random(-1, 1)", "-1.2", "Math.random(-1, 1)"]
      },
      "minecraft:particle_initial_speed": 1,
      "minecraft:particle_motion_dynamic": {
        "linear_acceleration": [0, -0.2, 0]
      },
      "minecraft:particle_appearance_billboard": {
        "size": [0.1, 0.1],
        "facing_camera_mode": "rotate_xyz",
        "uv": {
          "texture_width": 64,
          "texture_height": 64,
          "uv": [0, 0],
          "uv_size": [64, 64]
        }
      },
      "minecraft:particle_lifetime_expression": {
        "max_lifetime": 25
      }
    }
  }
}

组件列表

发射器生命周期：

minecraft:emitter_lifetime_looping - 循环
minecraft:emitter_lifetime_once - 单次
minecraft:emitter_lifetime_expression - 表达式控制

发射速率：

minecraft:emitter_rate_steady - 稳定速率
minecraft:emitter_rate_instant - 瞬间发射

发射形状：

minecraft:emitter_shape_point - 点
minecraft:emitter_shape_box - 立方体
minecraft:emitter_shape_sphere - 球体
minecraft:emitter_shape_disc - 圆盘
minecraft:emitter_shape_entity_aabb - 实体包围盒

粒子初始状态：

minecraft:particle_initial_speed - 初始速度
minecraft:particle_initial_spin - 初始旋转

粒子运动：

minecraft:particle_motion_dynamic - 动态运动（加速度）
minecraft:particle_motion_parametric - 参数化运动
minecraft:particle_motion_collision - 碰撞检测

粒子生命周期：

minecraft:particle_lifetime_expression - 表达式控制
minecraft:particle_expire_if_in_blocks - 进入方块时消亡
minecraft:particle_kill_plane - 平面边界

粒子外观：

minecraft:particle_appearance_billboard - 公告板渲染
minecraft:particle_appearance_tinting - 颜色着色
minecraft:particle_appearance_lighting - 光照

MoLang 变量

发射器变量：

molang

variable.emitter_lifetime    // 发射器生命周期
variable.emitter_age         // 发射器年龄
variable.emitter_random_1    // 随机数 1-4
variable.emitter_random_2
variable.emitter_random_3
variable.emitter_random_4

粒子变量：

molang

variable.particle_lifetime   // 粒子生命周期
variable.particle_age        // 粒子年龄
variable.particle_random_1   // 随机数 1-4
variable.particle_random_2
variable.particle_random_3
variable.particle_random_4

混合模式

材质名	混合模式
`particles_alpha`	Alpha 混合
`particles_add`	加法混合（发光）
`particles_blend`	乘法混合
`particles_opaque`	不透明

Photon

高级特效系统，支持粒子、光束、轨迹和 Bloom 效果。

播放 API

kotlin

import com.behemiron.engine.forge.module.effect.photon.PhotonManager

// 在指定位置播放
val runtime = PhotonManager.play("explosion.fx", level, position)

// 绑定到实体
val runtime = PhotonManager.play("aura.fx", entity)

// 停止
PhotonManager.stop(runtime)
PhotonManager.stopAll()

// 预加载
PhotonManager.preload("explosion.fx") { fx ->
    println("Loaded FX with ${fx?.mainFX?.fxObjects?.size} emitters")
}

// 统计
val count = PhotonManager.getActiveCount()

运行时控制

kotlin

val runtime = PhotonManager.play("effect.fx", level, pos)

// 变换
runtime.position = Vec3(x, y, z)
runtime.scale = Vector3f(2f, 2f, 2f)
runtime.forward = Vector3f(0f, 0f, 1f)  // 方向

// 颜色调制
runtime.colorR = 1f
runtime.colorG = 0.5f
runtime.colorB = 0.5f
runtime.colorA = 1f

// 绑定
runtime.bindToEntity(entity)
runtime.unbindEntity()

// 停止
runtime.stop()

发射器类型

类型	说明
`ParticleEmitter`	粒子发射器
`BeamEmitter`	光束发射器
`TrailEmitter`	轨迹发射器
`AraTrailEmitter`	弧形轨迹发射器

发射器配置

Photon 使用 NBT 二进制格式（.fx 文件），主要配置项：

生命周期：

duration - 持续时间（tick）
looping - 是否循环
startDelay - 开始延迟

粒子属性：

startLifetime - 初始生命周期
startSpeed - 初始速度
startSize - 初始大小
startRotation - 初始旋转
startColor - 初始颜色

模拟设置：

simulationSpace - 模拟空间（LOCAL/WORLD）
maxParticles - 最大粒子数
parallelUpdate - 并行更新
parallelRendering - 并行渲染

子系统：

emission - 发射设置
shape - 形状设置
material - 材质设置
renderer - 渲染器设置
physics - 物理设置
colorOverLifetime - 颜色随时间变化
sizeOverLifetime - 大小随时间变化
velocityOverLifetime - 速度随时间变化

形状类型

Dot - 点
Box - 立方体
Sphere - 球体
Circle - 圆形
Cone - 圆锥
Mesh - 网格

Bloom 配置

Photon 内置 Bloom 后处理：

kotlin

val bloom = PhotonBloomRenderer

// 配置
bloom.bloomIntensity = 0.3f    // Bloom 强度 (0-2)
bloom.bloomThreshold = 1.2f    // 亮度阈值
bloom.bloomKnee = 0.2f         // Soft-knee
bloom.bloomMipLevel = 5        // Mip 级数
bloom.filterRadius = 0.005f    // 滤波半径

统一管理

EffectManager

统一的特效管理器：

kotlin

import com.behemiron.engine.forge.module.effect.EffectManager

// 按系统名播放
val runtime = EffectManager.play("snowstorm", "snow.json", level, pos)
val runtime = EffectManager.play("photon", "explosion.fx", level, pos)

// 绑定到实体
val runtime = EffectManager.play("snowstorm", "aura.json", entity)

// 预加载所有
EffectManager.preloadAll()

// 重新加载
EffectManager.reloadAll()

// 停止所有
EffectManager.stopAll()

EffectRuntime

统一的运行时接口：

kotlin

interface EffectRuntime {
    val path: String
    var position: Vec3

    fun isFinished(): Boolean
    fun stop()
    fun bindToEntity(entity: Entity)
    fun unbindEntity()
    fun tick()
    fun getParticleCount(): Int
    fun getEmitterCount(): Int
}

资源目录

Behemiron/
├── particles/           # Snowstorm 粒子（JSON）
│   ├── snow.json
│   └── fire.json
└── photon/
    ├── fx/              # Photon 特效（NBT）
    │   ├── explosion.fx
    │   └── aura.fx
    ├── texture/         # Photon 纹理
    └── shader/          # Photon 着色器

对比

特性	Snowstorm	Photon
格式	JSON（可读）	NBT（二进制）
脚本	MoLang	NumberFunction
发射器	单一粒子	粒子/光束/轨迹
特效	基础粒子	Bloom/HDR
编辑	文本编辑器	专用工具
兼容	Bedrock 粒子	自定义格式
适用	简单粒子效果	复杂视觉特效

特效系统 ​

概念导图 ​

Snowstorm ​

播放 API ​

运行时控制 ​

JSON 格式 ​

组件列表 ​

MoLang 变量 ​

混合模式 ​

Photon ​

播放 API ​

运行时控制 ​

发射器类型 ​

发射器配置 ​

形状类型 ​

Bloom 配置 ​

统一管理 ​

EffectManager ​

EffectRuntime ​

资源目录 ​

对比 ​

特效系统

概念导图

Snowstorm

播放 API

运行时控制

JSON 格式

组件列表

MoLang 变量

混合模式

Photon

播放 API

运行时控制

发射器类型

发射器配置

形状类型

Bloom 配置

统一管理

EffectManager

EffectRuntime

资源目录

对比