Creating custom parameters

Creating your own parameters involves the following steps:

1. Create a class MBParticle<YourParameterName> under Assets/Plugins/Magical Box/User Parameters and set class attributes
2. Override some methods
3. Create a GUI handler class MBEditorParticle<YourParameterName>Handler under Assets/Editor/Plugins/Magical Box/User Handlers
4. Enjoy!

Step 1: Creating the custom class and adding attributes

In this tutorial we want to create a parameter that scales the particle in relation to its velocity. First let's create our parameter class:

[MBParameterInfo(Menu = "User/Scale By Velocity",
                CanAnimateBirth = MBParameterAnimationMode.None,
                CanAnimateLife = MBParameterAnimationMode.Mandatory)]
public class MBParticleVelocityScale : MBParameter
{
        public float Multiplier; // Scale multiplier
        public float MaxSize; // maximum size
}

The MBParameterInfo attribute informs the editor about the parameter's menuname and the animation modes it supports. We want our parameter to be permanently called during a particle's lifetime, so we set CanAnimateLife to be mandatory and disable birth animation (we don't use it in this example).

Additionally we add Multiplier and MaxSize properties.

Step 2: Adding functionality

Because we only need lifetime animation, we just override MBParameter.OnLifeTime() :

public override bool OnLifetime(MBParticle PT)
{
        float f = Mathf.Min(MaxSize, 1 + PT.Velocity.magnitude * Multiplier);
        PT.Scale=new Vector3(f,f,0);
        return true;
}

After calculating the new size by scaling the velocity magnitude with our multiplier and limiting to MaxSize, we set the particle's scale and return true to let the particle alive. By returning false the particle would have died immediately without processing any further parameters.

Also, we add some code to reset this parameter:

public override void Reset()
{
        base.Reset();
        Order = 55;
        MaxSize = 10;
        Multiplier = 1;
}

Reset is called when adding the parameter and when the user resets the parameter from the editor. Note that we set the Parameters calling order to ensure our parameter is placed after Size/Size3 and Velocity. More details about parameter orders down this page, just read on...

There are more methods you can override in custom parameters. Here's a brief overview:

Method	Purpose
MBParameter.OnPlay()	Initialization, called when emitter starts playing
MBParameter.OnBirth()	Called on particle's birth
MBParameter.OnLifetime()	Called during particle's lifetime
MBParameter.Reset()	Reset parameter settings
MBParameter.Validate()	Validate properties set in the editor

Cheers, you've created your first parameter. Let's add a GUI for it...

Step 3: Create the GUI

First we need to create a handler class for our new parameter:

[MBParameterHandler(typeof(MBParticleVelocityScale))]
public class MBEditorParticleVelocityScaleHandler : MBEditorParameterHandler
{
}

The MBParameterHandler attribute informs the editor that this class contains GUI code for our parameter. Parameter handlers have two virtual GUI methods used for initial/birth-animated and lifetime animated GUI parts. As we have enforced this parameter to be lifetime animated only, we just need to override the specific method:

public override void OnLifetimeGUI()
{
        base.OnLifetimeGUI();
        MBParticleVelocityScale P = Target as MBParticleVelocityScale;
        EditorGUILayout.BeginHorizontal();
        P.Multiplier = MBGUI.DoFloatField("Multiplier", "Scale Multiplicator", P.Multiplier);
        P.MaxSize = MBGUI.DoFloatField("Max Size", "Maximum particle size", P.MaxSize);
        EditorGUILayout.EndHorizontal();
}

This is quite self-explanatory. We just show two float fields to alter our public properties. That's it. To make it perfect we disable the rendering of an empty initial/birth-animated box by creating a constructor and setting a hide flag:

public MBEditorParticleVelocityScaleHandler()
{
        HideBirthGUI = true;
}

Note:

When creating your own GUI you should use the methods provided in MBGUI for simplicity and a uniform look&feel.

Step 4: Enjoy!

Congratulation, you've finished your first custom parameter! As you see it's just a bit of copy&paste to integrate it into the framework, the rest is up to your creativity!

About parameter order

You should initialize MBParameter.Order in your overridden MBParameter.Reset(). To determine a good order for your custom parameter, consider the following:

• Does my parameter rely on values calculated by other parameters?
• Is it a calculation-heavy parameter? If so, give your parameter a high order to give other parameters the chance to kill the particle before calculating your parameter
• Do I decide whether a particle dies? If so, you want the parameter to execute as early as possible

See also:

Parameters calling order

About Particle User Data