Events

Magical Box provides several useful events you can hook into for advanced control, e.g. you may want to play a fireworks emitter once a rocket particle dies.

The MBEvent class

On any event you receive a MBEvent parameter providing you detail information. MBEvent.Type provides information about the type of event (useful if you want to have a single event handler for multiple events), MBEvent.Source and MBEvent.Context provide information about the raising object and the details (usually a specific particle) and MBEvent.Data provides space for additional data, e.g. the DeathReason. For your convenience MBEvent.Particle returns the context as a MBParticle.

See the table below...

Event Overview

Class	Event	Description	Context	Data
MBEmitter	ParticleBirth	Raised after a particle is born	the particle	null
MBEmitter	ParticleDeath	Raised after a particle died	the particle	a MBDeathReason
MBEmitter	EmitterStopsPlaying	Raised when the emitter stops playing	the emitter	null
MBParticleCollider	ParticleCollides	Raised when a particle collides	the particle	the parameter
MBParticleZoneBase	ParticleInsideZone	Raised when a particle is inside a zone	the particle	the parameter

How to work with events

Magical Box provides two different ways you can use it's events:

• Callbacks: This is the most performant and preferred method. The only drawback is that you can't assign Callbacks in the editor, making them only work in play mode.
• Invoking Methods/"SendMessage": Basically this works like Unity's SendMessage, so you provide a GameObject and a method name to call. As this uses reflection this method is slower, but events can be assigned and run in the editor. Magical Box doesn't use the original SendMessage, so there are differences:
  • Reflection calls are cached, so it's faster like SendMessage
  • For the provided GameObject all script's methods that match the name will be called
  • You can also use static methods
  • Target script doesn't need to implement [ExecuteInEditMode]

Note:

If you assign both a Callback event and a SendMessage target only the callback event will be called in play mode. So a common practise is to code callbacks and also assign them in the editor to test them in edit mode.

Using events from code

Create a event handler method that takes a MBEvent as parameter:

void DoSomethingOnEvent(MBEvent e)
{
}

You need to register your event handler in order to catch the event, e.g. in OnEnable():

void OnEnable()
{
        MBEmitter em = GetComponent<MBEmitter>();
        em.ParticleDeath += new MBEventHandler(DoSomethingOnEvent);
}

You should unregister your event handler when you don't need events anymore, e.g. in OnDisable():

void OnDisable()
{
        MBEmitter em = GetComponent<MBEmitter>();
        em.ParticleDeath -= new MBEventHandler(DoSomethingOnEvent);
}

Using events in the designer

In a MonoBehaviour script that is attached to a GameObject, create a event handler method that takes a MBEvent as parameter:

void DoSomethingOnEvent(MBEvent e)
{
}

In the Magical Box editor assign the GameObject holding the above script to the appropriate event and set the name of the handler method and you're done.