特效系统

Behemiron 提供Snowstorm（Bedrock 粒子），通过 EffectManager 统一管理。

架构总览

模块导航

模块	说明	格式	适用场景
Snowstorm 粒子系统	Bedrock Edition 兼容粒子，MoLang 脚本驱动	JSON	简单粒子、Bedrock 兼容效果

Quick Start

使用统一的 EffectManager 播放任意特效：

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

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

// 根据文件扩展名自动识别系统（.json -> Snowstorm）
val runtime = EffectManager.playAuto("explosion.fx", level, pos)

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

// 统一操作
EffectManager.preloadAll()   // 预加载所有
EffectManager.reloadAll()    // 重新加载
EffectManager.stopAll()      // 停止所有

也可以直接使用各子系统的管理器：

// Snowstorm 直接播放
val runtime = SnowstormManager.play("snow.json", level, position)

统一接口

EffectEngine

所有特效系统实现 EffectEngine<T, R> 接口：

方法	返回值	说明
play(path, level, position)	R?	在指定位置播放特效
play(path, entity)	R?	播放并绑定到实体
stop(runtime)	Unit	停止指定运行时
stopAll()	Unit	停止所有运行时
preload(path, onComplete?)	Unit	预加载指定资源
preloadAll(onComplete?)	Unit	预加载所有资源
reload(path)	Unit	重载指定资源
reloadAll()	Unit	重载所有资源
getDefinition(path)	T?	获取定义（懒加载）
getActiveCount()	Int	获取活跃运行时数量

EffectRuntime

所有运行时实例实现 EffectRuntime 接口：

interface EffectRuntime {
    val path: String           // 特效路径
    var position: Vec3         // 当前位置

    fun isFinished(): Boolean  // 是否已完成
    fun stop()                 // 停止特效
    fun bindToEntity(entity: Entity)   // 绑定到实体
    fun unbindEntity()                 // 解绑实体
    fun getBoundEntity(): Entity?      // 获取绑定的实体
    fun tick()                         // Tick 更新
    fun getParticleCount(): Int        // 粒子数量
    fun getEmitterCount(): Int         // 发射器数量
}

系统别名

EffectManager 预注册了以下别名，可在 play() 中使用：

别名	目标系统
particle	snowstorm
bedrock	snowstorm

资源目录

Behemiron/
├── particles/           # Snowstorm 粒子（JSON）
│   ├── snow.json
└── └── fire.json

Ponder 集成

在 Ponder 场景中可以使用 EffectInstructions 播放特效：

// Ponder 场景中播放 Snowstorm 粒子
scene.effects.playSnowstormFx("snow.json", Vec3(2.0, 3.0, 2.0))