Custom Events

This section appears in the Master Audio game object. In Master Audio, you can define Custom Events. These are useful to create complex reaction to a single game event. For instance, you could have different enemies make a different sound at their location whenever a player grabs a new weapon, and not need to write any code! This is also used for music "stingers", as explained here. You can fire Custom Events from the Event Sounds script with no coding!

You create a Custom Event by giving it a name and clicking "Create New Event". Each Custom Event can have any number of Custom Event receivers. Master Audio automatically notifies all receivers (or a subset, more options below) when the event is fired so they can perform an action if they are configured to respond to that Custom Event. You can use Event Sounds to fire a Custom Event (when another built-in event such as onInvisible happens), and EventSounds can also receive the event if you want to do a normal Master Audio function such as Play a Sound Group, change song in a Playlist, fade a Bus, etc. You can also create per-Scene Custom Events by using a Dynamic Sound Group Creator.

Creating Custom Events

To create a Custom Event, type the name of your new Event in the "New Event Name" textbox and click the Create New Event button under it. An event will be created and shown in a collapsible section underneath. For basic events, that's all you need to do. There are other options as well.

 
1. New Category Name: You can create any number of Categories for your own visual organization. Type the name here and click "Create New Category" to create more.
 
2. Default Event Category: Whatever you select here will be the category for any future Custom Events you create.
 
3. Expand / Collapse All: This button will expand or collapse all the Custom Events.
 
4. Category Controls: All the Custom Events in the category will be listed under it.
    
   • Rename: You can change the name by clicking the gear icon to edit. Then click the X to cancel or the disc to rename it after changing the name.
    
   • Other actions: Shift up / down / collapse / expand / delete.
 
5. Per-event Controls:
    
   • Category: The blue dropdown next to the Custom Event name lets you move the event to a different Category.
    
   • Custom Event name: You can change the name by clicking the gear icon to edit. Then click the X to cancel or the disc to rename it after changing the name.
    
   • Delete button: Deletes the Custom Event.
    
   • Send To Receivers: This controls what happens each time the Custom Event is fired. The options are:
      
     • Always: Always send the event to all receivers. This is the default.
      
     • Never: Never send the event to any receivers (this disables the event without deleting).
      
     • When Distance Less Than: Only send the event to receivers that are closer than the Distance Threshold. Cool for triggering sounds from enemies in range.
      
     • When Distance More Than: Only send the event to receivers that are further away than the Distance Threshold.
      
     • On Same Game Object: Only send the event to receivers that are on the same Game Object as the sender (not parents or children).
      
     • On Child Game Objects: Only send the event to receivers that are child Game Objects of the sender.
      
     • On Parent Game Objects: Only send the event to receivers that are parents of the sender.
      
     • On Same Or Child Game Object: Only send the event to receivers that are either on the same Game Object or a child Game Object or the sender.
      
     • On Same Or Parent Game Object: Only send the event to receivers that are either on the same Game Object or a parent Game Object of the sender.
    
   • Distance Threshold: The distance to use for When Distance Less / When Distance More Than is chosen for Send To Receivers. Only visible when those options are chosen.
    
   • Valid Receivers: 3 choices to optionally limit the number of receivers that will be notified.
      
     • All: The default.
      
     • Closest: Only the X closest receivers will be notified. Specify X on the "Valid Qty" field that appears underneath.
      
     • Random: Only a random number of X receivers will be notified. Specify X on the "Valid Qty" field that appears underneath.

Runtime

During runtime in this section in the Inspector, the number of receivers for each Custom Event will be shown on the Custom Event row. Buttons also appear then to select all receivers in the Hierarchy and to fire the Custom Event from the position of the Master Audio game object.

Interface & Coding

The interface: All Custom Event Receivers (including Event Sounds) must implement the ICustomEventReceiver interface (see API website). That way Master Audio will keep track of the receiver and be able to automatically notify it when events are fired. There is a sample class that implements the interface called "MA_SampleICustomEventReceiver" in the Example Scene. It's attached to the Main Camera game object. You can look at that if you wish to respond to multiple events in a single receiver or perform more customized behavior for Custom Events than EventSounds can do.

Typical Custom Event setup:

• Create the event in either Master Audio game object or Dynamic Sound Group Creator game object (the latter only if you want the event to be per-Scene instead of permanent).
• Set up the Custom Event Receiver. Either use Event Sounds script or create your own class implementing the ICustomEventReceiver class.
• Be able to fire the event. You can use Event Sounds (choose Custom Event Control for Action Type) for this or you can call the following code method: MasterAudio.FireCustomEvent(string customEventName, Vector3 eventOrigin);
   
  The eventOrigin parameter is normally the position of the Transform of the object that is firing the event. It will be used for distance calculations if you are using the distance-based modes. Otherwise, it's ignored.