HG-Engine 背景切换与粒子系统指令教程

一、粒子系统指令

loadparticlefromspa – 加载粒子文件

loadparticlefromspa [粒子编号] [粒子文件编号]

功能说明：
将指定的粒子文件加载到内存中的指定编号位置。后续播放粒子效果时需要使用这个编号来引用。

参数说明：

参数	类型	说明
粒子编号	整数	内存槽位编号（0-15），用于后续引用
粒子文件编号	整数	SPA文件中的粒子资源ID

使用示例：

// 将371号粒子加载到0号内存槽
loadparticlefromspa 0, 371

// 将374号粒子加载到1号内存槽
loadparticlefromspa 1, 374

注意事项：

粒子编号通常从0开始顺序使用
同一编号重复加载会覆盖之前的粒子数据
建议在战斗开始前预先加载所需粒子

二、背景切换指令

changebg – 切换战斗背景

changebg [背景编号] [flag]

功能说明：
改变当前的战斗背景。需要配合 waitforchangebg 等待背景加载完成。

参数说明：

参数	类型	说明
背景编号	整数	目标背景的ID
flag	整数（位掩码）	切换效果标志，控制背景的显示方式和运动行为

flag 参数详解

flag 是一个32位整数值，由低16位的切换模式和高16位的子系统功能组合而成。

低16位：切换动作模式

// 低16位（0x0000FFFF）控制背景切换的过渡效果
#define WEDEF_HAIKEI_MODE_BLEND      (0)    // 混合模式：新背景从透明逐渐显现
#define WEDEF_HAIKEI_MODE_FADE       (1)    // 淡入淡出模式：先黑屏，再显示新背景
#define WEDEF_HAIKEI_MODE_NONE       (2)    // 无效果：直接切换
#define WEDEF_HAIKEI_MODE_END        (3)    // 结束标记（内部使用）

// 恢复时的模式（用于背景切换完成后恢复到正常状态）
#define WEDEF_HAIKEI_RC_MODE_BLEND   (0)    // 恢复时使用混合模式
#define WEDEF_HAIKEI_RC_MODE_FADE    (1)    // 恢复时使用淡入淡出
#define WEDEF_HAIKEI_RC_MODE_NONE    (2)    // 恢复时无效果

高16位：子系统功能标志

高16位控制背景的运动、光栅效果、调色板动画等附加功能。这些标志可以按位或（|）组合使用。

// 高16位（0xFFFF0000）控制背景的运动和其他特效
#define WEDEF_HAIKEI_SBIT_NONE           (0x0000 << 16) = 0x00000000 = 0          // 无任何功能
#define WEDEF_HAIKEI_SBIT_MOVE           (0x0002 << 16) = 0x00020000 = 131072      // 背景开始移动
#define WEDEF_HAIKEI_SBIT_STOP           (0x0004 << 16) = 0x00040000 = 262144      // 背景停止移动
#define WEDEF_HAIKEI_SBIT_EXIT           (0x0008 << 16) = 0x00080000 = 524288      // 子系统停止
#define WEDEF_HAIKEI_SBIT_NONE_DROP      (0x0010 << 16) = 0x00100000 = 1048576     // 无掉落效果
#define WEDEF_HAIKEI_SBIT_LASTER         (0x0020 << 16) = 0x00200000 = 2097152     // 启用光栅效果
#define WEDEF_HAIKEI_SBIT_LASTER_STOP    (0x0040 << 16) = 0x00400000 = 4194304     // 停止光栅效果
#define WEDEF_HAIKEI_SBIT_PLANM          (0x0080 << 16) = 0x00800000 = 8388608     // BG调色板动画开始
#define WEDEF_HAIKEI_SBIT_PLANM_STOP     (0x0100 << 16) = 0x01000000 = 16777216    // BG调色板动画停止
#define WEDEF_HAIKEI_SBIT_DEF_BG_MOVE    (0x0200 << 16) = 0x02000000 = 33554432    // 背景先行滚动

waitforchangebg – 等待背景切换完成

waitforchangebg

功能说明：
等待 changebg 指令的背景加载和切换效果完全完成。必须在 changebg 之后调用。

三、变量控制指令

cmd0C – 设置变量

cmd0C [var编号] [var值]

功能说明：
设置指定编号的变量值。这些变量会影响背景的运动行为、颜色属性等。

背景控制常用变量

var编号	功能说明	取值范围	备注
0	背景运动X轴速度	负值向左/正值向右	单位：像素/帧
1	背景运动Y轴速度	负值向上/正值向下	单位：像素/帧
2	背景X轴位置	任意整数	绝对位置
3	背景Y轴位置	任意整数	绝对位置
4	淡入淡出颜色	0=黑色 / 1=白色	仅对FADE模式有效
6	背景旋转速率	整数	可能控制背景旋转速度

四、完整使用示例

示例1：基本背景切换（无运动）

// 使用淡入淡出效果切换到52号背景
cmd0C 4, 0           // 设置淡出颜色为黑色
changebg 52, 1       // 1 = WEDEF_HAIKEI_MODE_FADE
waitforchangebg      // 等待切换完成

示例2：背景向上滚动

// 设置背景向上运动（Y轴负值表示向上）
cmd0C 4, 0                // 淡出颜色：黑色
cmd0C 0, 0                // X轴速度：0（不左右移动）
cmd0C 1, -2               // Y轴速度：-2（向上移动）
changebg 52, 0x20000 | 1   // 背景开始移动(0x20000) + 淡入淡出模式(1)
waitforchangebg

五、flag 值的快速参考表

效果组合	flag值（十进制）	flag值（十六进制）
仅淡入淡出	1	0x00000001
仅混合模式	0	0x00000000
仅无效果	2	0x00000002
背景开始移动	131072	0x00020000
背景停止移动	262144	0x00040000
光栅效果	2097152	0x00200000
BG调色板动画	8388608	0x00800000
移动 + 淡入淡出	131073	0x00020001
移动 + 光栅 + 淡入淡出	2228225	0x00220001
先行滚动 + 淡入淡出	33554433	0x02000001