Custom Scripted Material Reactions need much more info

[maxmitti]

The following is a painfully constructed fully working custom conversion script for material rain:

[Reaction]
Type=Script
TargetSpec=Solid
ScriptFunc=FlySnowConversion
CheckSlide=true
ExecMask=2

global func FlySnowConversion(int& x, int& y, int lsX, int lsY, int& xDir, int& yDir, int& mat, int lsMat, int event)
{
	var snow = Material("Snow");
	if (lsMat == snow || GetMaterial(lsX, lsY + 1) == snow || GetMaterial(lsX + 1, lsY + 1) == snow || GetMaterial(lsX - 1, lsY + 1) == snow)
	{
		mat = snow;
	}
	// InsertMaterial is the default behavior when a PXS lands on material with higher density
	InsertMaterial(mat, x, y);
	return true;
}

Notes:
The default behavior of converting the PXS into solid material when landing on material with higher density is disabled when the custom reaction is triggered.
Thus InsertMaterial + returning true (i.e. removing the PXS) is necessary. Otherwise the PXS would keep existing and possibly falling through solid material.

Without specifying ExecMask=2 (which targets only meePXSMove events) InsertMaterial causes infinite recursion, because InsertMaterial triggers meePXSPos. Also, the default behavior only reacts to this event.
CheckSlide is part of the default behavior when a PXS lands on material with higher density.

While there are constants for ExecMask / the event argument mentioned in the documentation, they are not defined (yet) in the engine.
Neither for script, nor for the c4m-definition.
It is also confusing, that the ExecMask needs to be constructed by setting the bits corresponding to the event types, while the event passed into the script function are the unshifted values. E.g. the ExecMask for only PXSMove is 2, while the event passed to the function for PXSMove is 1. Special attention has to be paid to this when constants are actually being defined in the engine.