猹件开发组基岩版粒子
基岩版粒子从客户端 JSON 和 PNG 资源创建独立粒子实例。它与粒子程序是两套并列能力：前者读取受支持的基岩定义，后者用文本 DSL 组合简单原版粒子，二者不会互相回退。
当前六个客户端模块均支持该能力：Forge 1.16.5、Forge 1.20.1，以及 NeoForge 1.21.1、1.21.4、1.21.8、1.21.11。
资源索引
固定入口：
resourcepacks/ChaEngine/
├─ particles/
│ ├─ chaengine.index.json
│ └─ effects/
│ └─ spark.json
└─ textures/
└─ particle/
└─ spark.png完整 particles/chaengine.index.json：
{
"format_version": 1,
"effects": {
"chaengine:spark": "particles/effects/spark.json"
}
}索引 ID 必须是命名空间 ID，路径必须从 particles/ 开始并以 .json 结束。同一 ID 或同一规范化路径不能重复；路径不允许绝对位置、反斜杠、.、..、空段或平台保留名称。
最小完整定义
下面的 particles/effects/spark.json 是当前解析器可接受的最小完整示例：
{
"format_version": "1.10.0",
"particle_effect": {
"description": {
"identifier": "chaengine:spark",
"basic_render_parameters": {
"material": "particles_alpha",
"texture": "textures/particle/spark"
}
},
"components": {
"minecraft:emitter_rate_instant": {
"num_particles": 1
},
"minecraft:emitter_lifetime_once": {
"active_time": 1
},
"minecraft:emitter_shape_point": {},
"minecraft:particle_lifetime_expression": {
"max_lifetime": 1,
"expiration_expression": 0
},
"minecraft:particle_appearance_billboard": {
"size": [1, 1],
"facing_camera_mode": "lookat_xyz",
"uv": {
"texture_width": 16,
"texture_height": 16,
"uv": [0, 0],
"uv_size": [16, 16]
}
}
}
}
}定义的 description.identifier 必须与索引中的 chaengine:spark 完全一致。纹理省略扩展名时自动补为 .png。
支持范围
材质
particles_alphaparticles_addparticles_opaqueparticles_blend
必需组件类别
每个定义都必须恰好包含一项发射率、一项发射器寿命、一项发射形状、一项粒子寿命和公告板外观：
- 发射率：
minecraft:emitter_rate_instant或minecraft:emitter_rate_steady。 - 发射器寿命：
minecraft:emitter_lifetime_once或minecraft:emitter_lifetime_looping。 - 发射形状：point、sphere、box 或 disc 对应组件。
- 粒子寿命：
minecraft:particle_lifetime_expression。 - 外观：
minecraft:particle_appearance_billboard。
重复同一类别同样会拒绝定义。
可选组件与字段
- 发射形状支持
offset、radius、half_dimensions、disc 的plane_normal、surface_only，以及outwards、inwards或表达式向量方向。 - 初始状态支持
minecraft:particle_initial_speed、minecraft:particle_initial_spin。 - 动态运动支持线性加速度、线性阻力、旋转加速度和旋转阻力。
- 公告板朝向支持
lookat_xyz、lookat_y、rotate_xyz、rotate_y。 - UV 支持直接
uv/uv_size，或 flipbook 的base_UV、size_UV、step_UV、frames_per_second、max_frame、stretch_to_lifetime。 - 着色支持固定 RGBA，或按 interpolant 插值的 gradient。
- 光照支持
minecraft:particle_appearance_lighting。
明确不支持
当前会拒绝 collision、events、curves、parametric motion、emitter/particle initialization、manual rate、entityAABB shape、local space、自定义运动组件及其他未知组件。
已支持对象中出现未知的重要字段、缺少必需组件、重复组件类别或表达式无效，也会使整个定义加载失败。解析器不会静默猜测其他基岩实现的行为。
Molang 子集
支持数值、括号和以下运算：
- 一元：
+、-、! - 算术：
+、-、*、/、% - 比较：
<、<=、>、>=、==、!= - 逻辑：
&&、|| - 条件：
条件 ? 真值 : 假值
支持函数：
- 一个参数：
math.abs、math.ceil、math.cos、math.floor、math.round、math.sin、math.sqrt - 两个参数：
math.max、math.min、math.mod、math.pow、math.random - 三个参数：
math.clamp、math.lerp
q. 与 query. 等价，v. 与 variable. 等价。内置变量包括发射器/粒子的 age、lifetime，以及各自序号 1 到 4 的 random 变量。服务端自定义参数只能通过 v.<name> 或 variable.<name> 读取。
未知变量或函数、错误参数个数、赋值、语句、字符串和未知记号会在加载时失败。运行中出现除零、模零、无效平方根或非有限结果时，该次求值为 0。
实例生命周期与 API
入口类为 BedrockParticleAPI 和 BedrockParticleOptions：
playOnce：自动创建一次性实例 ID。start：以调用方给定的实例 ID 启动，可设置旋转、随机种子和 Molang 参数。stop：停止指定实例；目标不存在时仍是安全的幂等操作。stopAll：清理接收客户端的全部基岩粒子实例。
同一实例 ID 再次 start 会建立新代次并替换旧实例。旧的异步加载即使稍后完成，也不能覆盖新代次。
这些 API 必须在 Bukkit 主线程调用，位置必须有有效世界，接收者应处于对应维度。返回 true 仅表示至少一个合格客户端接收了操作，不表示它一定拥有或成功解析该资源。
ChaAssets 与失败关闭
安装 ChaAssetsMod 后，客户端先从虚拟根 ChaEngine 查询索引、定义和纹理：
- 找到加密资源时使用它，加密路径优先于同路径直接文件。
- 包未声明该路径或资源底座不可用时，允许回退
resourcepacks/ChaEngine/。 - 路径已声明但未授权，或加密包损坏时，立即失败，不读取同路径明文文件。
资源更新、授权撤销或资源代次变化会停止关联实例，并清理定义、运行状态和纹理缓存。解密内容不会写回明文文件。
限制
- 每客户端最多 128 个实例。
- 每实例最多 2,048 个存活粒子；全局最多 8,192 个。
- 每 tick 最多生成 400 个粒子，渲染距离 96 方块。
- TTL 最大 36,000 tick；小于等于零同样使用该上限，不表示永久。
- 每个实例最多 32 个参数；参数名使用小写字母、数字、下划线和点，最大 UTF-8 长度为 64。
- 索引最多 1,024 个效果，单条路径最大 UTF-8 长度为 512。
- 每个 JSON 最大 1 MiB；每张 PNG 最大 16 MiB，宽高不超过 4,096。
- 单条表达式最大 UTF-8 长度为 4,096，单个记号最长 256 个字符，语法树深度最多 64、节点最多 512。
需要运行超过 30 分钟时，应在到期前用相同实例 ID 刷新，并留出加载余量。
常见问题
索引能读但效果失败：核对定义内 identifier 是否和索引 ID 一致，再查看错误路径指向哪个组件或字段。
其他基岩工具能显示，ChaEngine 不能：定义可能使用了当前明确不支持的组件；按本页支持子集裁剪，不要依赖未知字段被忽略。
纹理找不到：从 resourcepacks/ChaEngine/ 计算完整路径，确认只使用安全相对路径和 PNG。
更新后仍看到旧效果：停止或用同实例 ID 重新启动，并确认客户端已经切换到新资源代次。