特效脚本的基础语法

脚本属性缩写重大变更：

r, g, b
r@13, g@14, b@15
X, Y, Z
为 arena 和 fb4, Beyond
C
color，彩色属性。意即：LED。
E
white。此为代用水泵属性，不用小写。如果是灯光，直接用 w@24
^
表示提前预置，相当于 MIB。Move in black. 已弃用。用 Fade in 解决 MIB。
G
groups。取代原来的 G。M 用于只关心成员数量的分组，与 MA2 一致。
U
wings，翼。避开 XYZ。
B
blocks，块。只关心块的数量，成员数量需计算。K，只关心成员数量，与 MA2 一致。
S
速度。取代原来的 M。
$
SingleShot。取代原来的 S。由于 SingleShot 使用率低，不必占用 S。
高低值颜色同时支持中文 {1, 2} 和英文单词 \d+。
:
冒号。分隔 group 名称与 Cues。
.
英文句号，表示与 Event end 一致。
~
波折号。表示一个 Cue 的开始符。一条 clip 中可以有多个 ~，表示 follow 关系的多个拼接 Cue。
( )
圆括号，包裹属性的 Effect 脚本
[ ]
方括号，包裹 tempG
{ }
花括号，包裹 concatG
?
问号。表示执行的周期次数。其直接影响 Speed
#
井号。表示 Effect Timer 的分隔符。tr1#1n1/4H20..100!
;
分号。当同一个 execAttrib 中有多个属性时，用分号隔开。例如：(r@13; g@14; b@15; rgb)，此例中最后的 rgb 属性可以省略，但仅限于 rgb，其他属性不能省略。
Q
表示参与的设备数量。
F
Fade in 淡入
Fo
Fade out 淡出
A
Delay 延迟
Ao
Delay out 延时输出
Sound Effect 语法。j：有间隔，k：无间隔。*：中心对称，&：连续，i: 幅度台阶。
r, g, b。分别代表 red， green，blue。
26 个英文字母都被用过至少一遍。有些是大小写。
如果使用灯具的属性，如：Gobo，Iris，Prism，可直接输入。

脚本 Effect Attribute 变更：

考虑到兼容灯光灯具的全部属性，参考 MA2 的 Effect attribute 名称。
在属性名称后加 @。原来：D24。现改为：D@24，或 Dim@24。
灯具属性可使用 MA2 的全称：StageX@24，ClipSelect@12。不限制大小写。
由于灯光灯具 DMX 通道都只有一个 Break。可将新增的属性放置在一个 Effect 中。
新增属性类别：Gobo, Beam, Focus, Control, Shapers。基本属性类别：Dimmer, Position, Color。后续考虑增加的属性类别：Video。
最好根据属性类别设置不同的 EffectExec。
对于操作包含多个属性的 Effect Exec，技术方面可能是个挑战。
不同属性与所在 Effect 中的行号必须建立对应关系，以便准确索引。
先从简单的开始。逐步完善多个属性类别。
好处：兼容更多的 MA2 灯具。

动态 Effect 的语法规则：

21.0 Attribute。D@12: D 为属性 Dim。12：为 Form 的索引。

21.1 Form。D@12：Dim，Form 12。T@12：Tilt，Form 12。N@12：Pan，Form12。C@12：RGB，Form 12。Red@13：Red，Form 13, Green@14, Blue@15。

21.2 Speed。S30

21.3 Dir。>, <, ><, <>;

21.4 Low value。L20。彩色低值支持中英文和缩写。C@24W50Lr, Lred, L红

21.5 High value。H100。彩色低值支持中英文和缩写。C@24W50Hc, Hcyan, H青

21.6 Width。W100。

21.7 Phase。P0..-360

21.8 Groups。G2，只关心组数，不关心每组内的设备数量，不完整的组仍被保留。G0, 为最多组数，即：两两一组。 M3，表示 Members Qty is 3，只关心每组内的设备数量，不关心总的组数，不完整的组被省略掉。Groups > 1 时，是否对 Speed 做补偿？需要验证效果。

21.9 Blocks。B4，K5

21.10 Wings。U2。

21.11 Interleave。Vo, Ve, V13, V23, V33, V14, V24, V34, V44。

21.12 SingleShot。$0, $1

新增 D3 摄像机机位切换的简化脚本：

原始脚本已经使用正常。
简化脚本可在已知机位数据的前提下，由 playServer 自动计算出全部的摄像机原始脚本，大幅简化人工操作，显著降低难度和提高效率。
语法 1。~F100(near1W80far2)。解释：near1 向 far2 机位切换。宽度：W80。
语法 2。31.4~(far2)。解释：far2 机位保持到 31.4 小节。
全部机位数据存于 JSON 文件中，或数据库中。
机位数据中必须包括以下属性：Sx, Sy, Sz, Rx, Ry, Rz, Fov.
机位根据远近分类：closest, near, middle, far。
机位根据观察角度分类：1，前视。2，右侧视。3，俯视。4，左侧视。5，仰视。

新增 MA2 Effect 定时器，可定时修改 Effect 某个属性：

1 先决条件
- MA2 新增 15 个 Plugin，对应 15 个 Timer Action。
- MA2 新增 15 个 Macro，Macro 中加载并执行对应的 Plugin。
- MA2 新增 15 个字符串变量，对应 Timer 的脚本。
- 脚本由外部主控时间线指令传入执行，或由 SequCue Cmd 调用执行。
- 变量为空串或 nil，则定时器停止执行。
2 play server 增加 15 个 Macro 的生成功能。

2.1 在 Stage 中与其他 Exec 一起生成。

2.2 15 个变量也一起生成。
3 脚本语法

3.1 Timer 脚本位置在 selfix 中。Timer 选择位置在属性 Effect 脚本中。

3.2 Timer 用法。tr1#30P0..359b1/4!m120，与动态 Effect 语法并不完全一致。位置放在属性 Effect ( ) 的前面，而且可由属性 Effect 选择。也就是说，一个 timer 可作用于多个属性。tr1 ~ tr15

3.3 Timer 语法： tr1#30n1/4P0..360!。
- tr1 表示 Timer 1，
- #30 表示：相位步长 Step，即：每次修改的相位数值，百分号表示修改目标最大值的百分比，分数表示与目标最大值的比例。
- P 表示相位的初始值，
- n 表示时间间隔，interval，百分号表示 BPM 的百分比。分数表示 BPM 与分数的乘积；纯数值表示：秒数。
- ！表示为结束符号。
- 程序会自动在！前面加上 BPM，例如：m120。
- 还会自动加上 e371，表示修改目标为 Effect 371。这些都不需在脚本编辑时添加。
- 还要自动加上 x26.1，表示修改目标关联的 Exec 为 Exec 26.1。interleave 修改后需要先 Off 再 On 才能生效。
3.4 完整语法举例。龙行天下: .~tr1#10n1/2P0..40!(C@24HredLblueW50P0S1/4)tr2#-20n1/2P0..359!(D@20W50S1/4)

3.5 Timer 可以定时修改 Effect 的多个属性，包括：Interleave, Form, Speed, Phase，Width，HighValue，LowValue，Groups, Blocks, Wings.

3.6 如果一个定时器同时修改多个属性，属性之间要加分隔符号 &，或其他：_ 。例如：高低值。语法如下：tr1#10n1/2H20..100&8n1/3L0..40!

3.7 若 step 为正值。则从范围的最低值向上加。

3.8 若 step 为负值。则从范围的最高值向下减。
4 注意事项
- 如何执行 Timer ？Timer 代码由 Lua 语言编写。由 MA2 Macro 加载 Timer Plugin，并执行，或直接 Go Plugin name。
- 调用 Macro 的指令保存在 SequCue Cmd 中。或由外部 Timeline 指令调用。
- Timer 脚本在调用 Macro 之前保存到 MA2 Timer 脚本变量中。
- 当多个属性 Effect 选用同一个 Timer 时，脚本要拼接到变量尾部。多个属性的起止时间点必须一致。否则，Timer 关闭就存在问题。
- 何时关闭 Timer ? 当 Event release 时发出关闭 Timer 的指令。
- 如何关闭 Timer ? 只要将 Timer 脚本置空即可。或者简单粗暴直接 RelaodPlugins /nc.
- 当多个 Timer 同时执行时，是否会出现并发问题？有待验证。
实现思路

1 编写一个 Timer Plugin 代码。

2 由 Macro 导入 Plugin，并执行。15 个 Timer 均导入相同的代码，只是 Plugin 索引不同。

3 15 个 Timer 脚本变量初始为空字串，或不存在。

4 tr 脚本在 selfix 中被识别。指令保存到 SequCue Cmd 中，或主控 Timeline 指令中。

5 指令中主要是对 MA2 Timer 脚本变量的赋值，以及调用 Macro 去加载和执行 Plugin。

6 Macro 在 Stage 中 createExecutors( ) 函数中生成。

7 当 Effect 解析到 Timer 时，则添加执行 Plugin 的指令。

新增 “幅度主控” 和 “速度主控”

Fader Master，Speed Master：

1 先决条件
- MA2 新增 15 个 Exec，对应绑定 15 个 Speed Master。
- MA2 新增 15 个 Fixtures，DMX 数据输入到 Art-Net Input。
- MA2 设置 Art-Net Input Active: On。如果仅内部数据输入，Off 也可。
- MA2 新增 15 个 DMX Remote，数据关联 15 个 Exec。
- 同样的，再添加 50 个 Fader Fixtures, 50 个 Exec，50 个 DMX Remote。
2 play server 增加 Fader EffectExec 生成功能。

2.1 在 Stage 中与其他 Exec 一起生成。
3 脚本语法

3.1 选设备：组名。concatG、tempG

3.2 Fader Effect 语法。Fader Master 语法： (fm1@10P0H100L20W10)，与动态 Effect 语法完全一致。不同点是：位置放在属性 Effect ( ) 的前后都可以，而且可由后面的属性选择 fm。也就是说，一个 Fader 可作用于多个属性。fa1 ~ fa50

3.3 Speed Master 语法： (sm1@12P0H100L20W10)。sm1 ~ sm15

3.4 完整语法举例。龙行天下: .~(C@24fm1HredLblueW50P0S1/4)(D@20W50S1/4)

幅度主控: .~(fm1@10P0H100L20W10)

龙舞九州: .~(D@20fm1W50S1/4)

幅度主控: .~(fm1@12P0H100L20W10)

龙舞九州: .~(r@20fm1sm1j718; b@20sm1j718)

幅度主控: .~(fm1@10P0H100L20W10)

速度主控: .~(sm1@12P0H100L20W10)

龙舞九州: .~(D@20fm1W50S1/4)(N@10fm2P0..356H25L-25)

幅度主控: .~(fm1@10P0H100L20W10)(fm2@10P0)
4 注意事项
- 幅度主控不能共享。只能是一对一的关系。而速度主控可以共享。
- 当 Fader 执行时，EffectExec 之前设置的 Fade in，Fade out 数据不起作用了。
- 当 Fader Exec 关闭时，对应控制的 EffectExec 的 Fader 或 Speed 为 0。这可能导致意料之外的效果。
- 如果 Cue 之后没有其他 Cue Follow 衔接，Fader 为 0 不是问题。
- 当两个 Cue 之间是 Follow 衔接时，不能让 Fader 为 0，或 Speed 为 0，即使是瞬间为 0 也不能接受。
- 要关注 Delay out 的时间，与 Fader 的关闭时间。
- 注意：如果对变频跑泉使用幅度主控，则应作用于 pump，而不是 dim （电磁阀）
实现思路

1 如果将 Remote 绑定 SequExec，则情况稍微麻烦一些。如果绑定 EffectExec 就简单多了。

2 如果将 Remote 绑定 SequExec，Cue 中必须用一个单独的 part cue 的 cmd 执行 Remote fader 设置指令。因为 fa 和 sm 都是公共资源，必须动态使用的，不能锁定给某一个 Exec。注意：必须用一个单独的 part cue，防止 cmd 被循环执行。

3 cmd 需在一个 Event 结束时解绑 Exec，也要指令设置。这个可能与新的绑定指令产生时间上的先后冲突，需考虑避免。方法：前后两个 Event 最好使用不同的 fa 和 sm。

4 sm 不需要设置 SequExec，不用修改其 Speed Master 选项。只需修改 Effect 即可。

5 fm 和 sm 都需要有各自的 SequExec，将 Effect 生成的数据以 Cue 的形式保存进去，被 Timecode 根据 Event 时间点调用。

6 对于 fm 和 sm 的 Effect，用指令修改其参数即可，无需用 Import 的方式，这样可省去生成 xml file 的步骤。

新增 MA2 脚本中多属性合并在一个 Effect 的多个 line 中：

1 先决条件
- 将在一个 Effect 中不同行的多属性归类为一个 exec 属性，在 MA2 中有一个单独的 EffectExec。
- 多属性在 Effect 中的行索引固定。
- 如果不是全部索引都被引用，其他的灯具选择为空值。确保不起任何作用。
- 属性之间时序一致，不能有不同的相应延时。那样的话，最好不放在一个 Effect 中。
2 通过 effectExecutors 自动生成 effect xml 文件。

2.1 。
3 脚本语法

3.1 选设备：组名。concatG、tempG

3.2 多行 Effect 属性语法。在一个圆括号内用分号 ; 间隔。龙舞九州: .~(r@13; g@14; b@15)，这是典型的彩虹色写法。

3.3 Red, Green, Blue 都属于 EffectExec 属性 Color，在 MA2 中有独立的 Color 执行器。

3.4 Red, Green, Blue 在 Effect 中有固定的行号索引，分别是：1，2，3。

3.5 如果只有部分属性有效，比如：只有 (r@13)，则 Green, Blue 为空选灯。Form 被自动填充为 Stomp, 即：g@2, b@2
4 优点
- 可兼容很多的多属性设备。特别是虚拟设备和灯光设备，如：Camera，Mover。
- 编程的灵活性更多。
- 声控特效可单独一个或多个颜色属性生效。

2024.07.07

新增 MA2 Sound Input 声控脚本：

1 先决条件
- 电脑声卡设置为混音。
- MA2 设置 Sound Input 模块中的 Sound Gain，Fade 参数。
2 play server 增加 Sound Effect Exec 生成功能。

2.1 无需增加空的 Effect Exec。在 EffectExec 中生成所需的 Effect Line。
3 脚本语法

3.1 选设备：组名。concatG、tempG

3.2 Sound Effect 语法。有间隔中心对称语法： j7*17，表示：频带为 7 段，每段最少设备数量为 17。间隔的设备数量为 1。一般用于线性非封闭中心对称布局，直线，或弧线。

3.3 无间隔连续：(k7&10)，表示：频带为 11 段，每段最少设备数量为 10。无间隔。一般用于圆形封闭非对称布局。

3.4 j：有间隔，k：无间隔。*：中心对称，&：连续。

3.5 有间隔连续：j11&7

3.6 无间隔中心对称：k11*10

3.7 后续再考虑加入方向。可用 f 表示反向。

3.8 完整语法举例。龙行天下: .~(C@24HredLblueW50P0S1/4)(D@20j7*17)

3.9 末尾添加 i 表示幅度台阶。j11&7i5。i5 表示段与段之间的幅度台阶为：5%

3.10 注意：如果对变频跑泉使用幅度台阶，则应作用于 pump，而不是 dim （电磁阀）

龙舞九州: .~(D@20j7*18)

龙舞九州: .~(C@20j718)(b@20j718)

龙舞九州: .~(r@20j7*16; b@20k7&16)
4 优点
- Dim 与 Color 属性等各个属性可单独编写。互不影响。
- 每个编组的分段可分别单独控制，增加灵活性和多样性。
- 可选择多个 MA2 编组参与声控特效。
- 可用一句脚本实现一个编组的多段 Sound 特效。相当于生成了多句脚本。
- 可精准控制时间线。
- 与其他脚本混编，可提高水秀质量，有鲜明的可辨识特点。
- 可将 Camera 引入，生成更好的视频。

动态 Effect 如何设定 Delay 和 out Delay：

Cue 中的 Delay 是 Fade in 之前的时长。相当于延时开始 Cue。
OutDelay 是 Fade in 之后，到 Fade out 开始之前的时长。相当于 Fade in 完成之后，多长时间之后再开始 Fade out. Fade out 默认与 Fade in 相同，除非单独设定。
Fade out 之后，此 Cue 动作即告完成。
从现实角度来看，outDelay 决定了 Cue 的实际特效的执行时长。
outDelay 有效的前提是：下一个相邻的 Cue 触发必须是 Follow。
Fade out 必须依赖 outDelay 才会生效。否则，系统是无法计算何时开始 Fade out 的。
如果用多 Effect 拼接来实现 Fade in 和 Fade out. 那 outDelay 可以省略。
如果对于较为简单的场景，例如：数控喷头的喷高，用一条样线就可完成 Fade in 和 Fade out，完全不必要额外设定。
Fade in 和 Fade out 参数只对动态 Effect 第三种实现方式生效。即：对静态数据的 Sequence Cue 生效。对于其他的动态 Effect 实现方式无法起到任何作用。
Fade in 在 MA2 中生效的前提是：Exec 状态必须由 Off 到 On，必须执行 On Exec，或 Fader Exec num At 100。
Fade out 在 MA2 中生效的前提是：Exec 状态必须由 On 到 Off，需执行 Off Exec。或者 outDelay 有效，而且后面的 Cue 触发为 Follow。
Delay 脚本语法。A20，表示延时 20% 的 duration。A1/8，表示延时 12.5% 的 duration。

动态 Effect 用拼接来做 Fade in 和 Fade out：

Cue 中 Fade in 和 Fade out 在很多场景下非常实用。特别是对于水和灯的控制。
如果设定了 Fade in，那么默认 Fade out 等于 Fade in。除非另外设定。
但 Fade out 必须依赖 outDelay 才会生效。否则，系统是无法计算何时开始 Fade out 的。在没有 outDelay 情况下，Fade out 也在 Off Exec 之后生效。
从现实角度来看，outDelay 决定了 Cue 的实际特效的执行时长。
Effect Exec 与 Sequ Exec 一样，也有 Fade in 和 Fade out 功能。但有一个重要的前提：Exec 的状态必须是由 On 向 Off 转换，或者相反。还有个限制：只针对 Dim 属性。
由于要 On 或 Off Exec。而对于动态 EffectExec 来说，大多数时候，是不会 Off Exec 的。Fade in，Fade out 显然对于动态 Effect 是无法适用的。但适用于静态 Sequ Exec 的场景。
可用多 Effect 拼接来实现 Fade in 和 Fade out。多 cue，follow 触发。
这样相比于 Cue 还是麻烦一些，但好在可以实现。有方案总比没有好。
也可以考虑根据 Fade in 和 Fade out 参数自动加入拼接脚本。但这显然会损失灵活性
好处是可以用于全部属性的特效。而 MA2 Cue 的 Fade 功能只限定于 dimmer 属性。
动态的 Fade in，Fade out 突破了 MA2 的 dimmer 属性限制。Fade in 还可以用作 MIB 功能。
注意：必须区别使用 Fade in，Fade out 与幅度主控。Fade in 在 Event 起点前执行，Fade out 在 Event 终点后执行，这与 MA2 的定义也是类似的。而幅度主控是在 Event 起点与终点之间执行，与其他属性的 Effect 无异。
注意：MA2 的 Fade in， Fade out 要谨慎使用。起止时间点尤为重要。Fade in，Fade out 的时长不是有效的 Event 时长的一部分。这个很容易被弄错。
动态 EffectExec 的 Fade in 脚本。~F5(C@10P0Hg)(D@10P0H80)，加在全部 Effect 脚本的最前面一个 follow。在 Event 起点之前执行。Sequ Exec 必须将 Interval 提前。Fade in 必须是 follow 0.
动态 EffectExec 的 Fade out 脚本。~Fo5(C@11P0Hg)(D@11P0H80)，加在全部 Effect 脚本的最后一个 follow。在 Event 终点之后执行。必须将 endInterval 延后。Fade out 必须是 follow 最后一个。
对于一个属性，不能同时使用 Fade in，Fade out 和幅度主控。这样会造成 Fade in 无效。