跳到主要内容

元指令参数指南

meta参数是一个元指令区域,以CompoundTag的形式呈现,被设计用来保障未来更新时的兼容性和扩展性。

你可以根据下列标志的介绍、你的需求及当前版本,来选择性地填写内容。

信息

下列一些值给出了推荐范围。尽管你可能可以在游戏内填写超出推荐范围的值,但我们不推荐您如此做。填写超出推荐范围的值是未定义行为。


喷花筒标记

可用版本:0.3.+

形式:"tada":1

值类型:布尔值(填写01

表示这是一条喷花筒指令,客户端需计算玩家手部位置并在生成粒子时进行对应偏移。

脉冲

可用版本:0.4.19+

形式:"pulse":1

值类型:布尔值

将喷花筒的工作模式设定为脉冲式。发射一次粒子后,玩家需抬起右键才能再次发射粒子。


数学表达式:dx、dy、dz

可用版本:0.4.+

形式:"dx":"<数学表达式f(t)>"

示例:"dy":"0.2*sin(3t)+0.5*t"

值类型:字符串

你可以填写一个以t为自变量的函数表达式,来取得对每tick中粒子在X、Y、Z三轴上增量的高级控制。由于直接控制粒子的绝对坐标会极大地影响指令的复用性,所以假设你想要粒子在X轴上的的运动轨迹为F(t),你就需要填写其导数f(t),以此消除绝对坐标的影响。

同样地,为了消除不同粒子寿命对指令复用性的影响,t的值域为[0,1](对应粒子生成到消失),在实际应用时按照粒子寿命进行放缩。

警告

如果你在此处指定了dx、dy、dz:

  • 对应的gravityxDeflectionzDeflection将会失效,friction将会被覆盖;
  • interactWithEntity(与玩家互动)的效果会叠加;
信息

考虑到复杂的表达式可能会对性能造成影响,目前的计算方式为:

  1. 若存在指定的dx、dy、dz,则交由其他线程进行粒子对象初始化,每一条指令对应一个线程,初始化一批粒子;
    1. 初始化过程包含dx、dy、dz的预计算过程:将0.00~1.00之间共101(若粒子寿命小于100,则取粒子寿命+1)个t代入所给表达式,求出对应值以供查询;
  2. 一批粒子初始化完成后,在适当的时候加入世界;
  3. 粒子在运动时读取保存的dx、dy、dz数组,以类似alphaModeSIN模式,使用查表和线性插值得到对应的值。

如此做的好处在于尽量减少粒子对mspt的影响,但目前的弊端是会占用相对较多的内存资源。

支持的运算符

以下列出支持的所有运算符号:

  • +-*/:加、减(负)、乘、除;
  • ^:幂;
  • %:取模;

如示例所示,你可以在适当的时候省略乘号。

支持的常数

以下列出支持的所有常数:

  • piπ:圆周率,3.14159265358979323846
  • e:自然常数,2.7182818284590452354
  • φ:黄金比例,1.61803398874

支持的函数

以下列出支持的所有函数:

  • abs:绝对值;
  • sincostan:正弦,余弦,正切;单位为弧度;
  • asinacosatan:反正弦,反余弦,反正切;
  • sinhcoshtanh:双曲正弦,双曲余弦,双曲正切;
  • sqrtcbrt:平方根,立方根;
  • floorceil:不大于的最大整数,不小于的最小整数;
  • exp:以e为底的幂;
  • loglog10log2:自然对数(底数e),常用对数(底数10),对数(底数2);
  • signum:符号函数;

科学计数法

技术上讲确实支持,但是我实在想不到什么样的粒子需要科学计数法......


寿命误差

可用版本:0.4.+

形式:"life":"<误差百分数>"

示例:"life":"20"

值类型:整数(1~99

覆盖粒子生成时默认的10%寿命误差。示例中即为20%的寿命误差。


碰撞后消失

可用版本:0.4.3+

形式:"disappearOnCollision":"<触发时碰撞次数>"

示例:"disappearOnCollision":"2"

值类型:整数(大于0

是粒子在达到指定的碰撞次数时立即消失。示例中即为粒子在第二次碰撞时消失。

你可以利用此特性,结合expireThen,来使某个粒子在碰撞时变为其他的粒子。


倒放

信息

这是一条长期实验性的元指令标志,这意味着它可能会在未来被更改或取消。

可用版本:0.4.7+

形式:"tenet":1

值类型:布尔值

在生成粒子时进行一遍预计算,计算完成后加入世界并按预计算的轨迹倒放。

预计算(正向)

可用版本:0.4.21+

形式:"preCalculate":1

值类型:布尔值

在生成粒子时进行正向预计算,计算完成后再加入世界。有效减少碰撞计算对主线程的压力。

警告

如果你指定了倒放或预计算:

  • 倒放逻辑已包含预计算,因此若两标记同时出现则倒放优先。
  • interactWithEntity(与玩家互动)会失效;
  • 不能对粒子预计算完成后改变的地形做出反应。
危险

目前倒放和预计算对子粒子的兼容性可能不佳。

危险

预计算只适用于少量粒子的场景。在大量粒子的场景下,由于CPU被占满而无法起到优化效果。


亮度

信息

这是一条测试阶段的元指令标志,这意味着它没有经过完整的测试,在某些情况下(例如使用光影时)可能会产生异常。

可用版本:0.4.9+

形式:"light":"<数学表达式f(t)>"

示例:"light":"15t"

值类型:字符串

与dx、dy、dz相似,你可以填写一个以t为自变量的函数表达式,同样采用预计算-查表-插值的方式进行应用。计算时函数值将会被向下取整,并以截取的方式限定在0~15之内。

警告

倒放粒子(即"tenet")对指定的亮度变化无效。


压缩传输

可用版本:0.7.2+

形式:"halfPrecision":1

值类型:布尔值

使用半精度浮点数来传输部分参数。通常在视觉上无感而可以节省约28%服务器流量。


索引传输

可用版本:0.8.1+

形式:"indexed":1

值类型:布尔值

使用索引号来传输几乎全部指令。索引为随机生成的整数以代表一整条指令,可以极大地节省服务器流量消耗。

信息

客户端在第一次执行某条指令时会先向服务器查询指令对应的指令文本以作缓存。故第一次执行某指令可能会产生三倍的延迟。

警告

索引传输和压缩传输不兼容。同时存在时,索引传输会覆盖压缩传输。

提示

如果你对应该使用何种优化参数感到困惑,以下是一张帮你选择前缀和传输方式的简图:

image-20241008223015928