粒子程序 ​

粒子程序把一组简短脚本发送给客户端，由客户端在 TTL 内自行计算和生成原版粒子。它适合持续光环、环形提示、螺旋轨迹和周期爆发，避免服务端每 tick 重复执行粒子操作。

四种作用范围 ​

实体暂时不在客户端视野或尚未加载时，该组不生成粒子，但 TTL 仍继续计时。维度不一致和距离过远时同样暂停生成。

生命周期 ​

每个效果组都有 groupId：

1. 启动：创建组；相同 groupId 已存在时直接覆盖。
2. 更新：用新的范围、TTL 和脚本整体替换同名组；不是增量追加。
3. 停止：按 groupId 删除单个组。
4. 停止范围内全部：按全局、某维度、某实体或某方块清理其所有组。
5. 到期：TTL 归零后客户端自动删除。

groupId 在单个客户端中跨范围共用命名空间。同名的方块组和实体组会互相覆盖，因此建议使用 插件名_用途_目标 形式生成唯一 ID。

玩家断开服务器或客户端世界关闭时，全部粒子程序都会清理。

完整 DSL ​

一条脚本的基本格式：

<形状> <原版粒子ID> [字段 值...]

只接受无需额外粒子参数的简单原版粒子类型。粒子 ID 不存在或需要额外选项时，该行跳过。

形状 ​

字段 ​

数值无效时解析器使用该字段的默认值。为了让错误可见，建议在发布前逐条测试，不依赖容错结果。

四个可复制效果 ​

固定火焰：

spawn minecraft:flame at ~0 ~1 ~0 vel 0 0.02 0 count 3 every 2

治疗环：

ring minecraft:happy_villager at ~0 ~0.1 ~0 radius 1.5 points 24 spin 8 count 8 every 1

能量螺旋：

helix minecraft:end_rod radius 0.8 height 1.8 spin 14 rise 0.06 count 10 every 1

烟雾爆发：

burst minecraft:cloud radius 0.5 randvel 0.12 count 20 every 10

Java API 生命周期 ​

入口类是 ChaEngineParticleAPI。全局、维度、实体、方块四组方法都提供 start、update、stop、stopAll 语义。例如方块范围：

import com.github.ginirohikocha.engine.api.particle.ChaEngineParticleAPI;
import org.bukkit.Location;
import org.bukkit.entity.Player;

import java.util.Collection;
import java.util.List;

public boolean showAltar(
        Collection<Player> viewers,
        Location altar) {
    return ChaEngineParticleAPI.startBlock(
            viewers,
            altar,
            "myplugin_altar_aura",
            20 * 30,
            List.of(
                    "ring minecraft:happy_villager radius 1.2 points 18 spin 10 count 6 every 1",
                    "spawn minecraft:flame at ~0 ~1 ~0 vel 0 0.01 0 count 2 every 2"));
}

方法返回 true 表示操作已交给至少一个合格的在线接收者，不保证对方一定处于渲染距离，也不保证某个粒子 ID 能在客户端解析。空接收者、无合格客户端或发送失败时返回 false。

性能与限制 ​

• 每个客户端最多保留 128 个组；新增第 129 个不同 ID 时淘汰最早的组。
• 每组最多 64 条脚本，每条最多 1024 个字符。
• 每 tick 所有组合计最多生成 400 个粒子；先处理的组会先消耗预算。
• 最大渲染距离为 96 方块。
• TTL 最大 36,000 tick，即 30 分钟；小于等于零会改为 20 tick，不表示永久。
• count、every、points 会被限制到表中范围。

长时间效果应在到期前更新同一组，不要试图设置永久 TTL。先降低 count、提高 every，再增加脚本数量。

常见问题 ​

整组完全不显示：确认接收玩家安装 ChaEngineMod、范围与维度正确、距离不超过 96 方块，并检查组是否已到期。

只有某一行无效：检查形状和粒子 ID。需要颜色、方块状态等额外参数的复杂原版粒子不属于简单粒子类型。

新效果替换了另一处效果：两个调用使用了相同 groupId；范围不同也不能复用同名 ID。

停止全部误删范围外效果：核对调用的是全局、维度、实体还是方块版本。单组停止只按唯一 groupId 删除，范围批量停止才匹配锚点。

客户端掉帧：查看所有活动组的合计生成量，不要只看单条脚本；减少高频 count 并缩短看不见时仍存活的 TTL。

相关文档 ​

• 基岩版粒子
• Java API
• 故障排查