Custom Events

You can define any number of Custom Events in the LevelWaveSettings Game Object's last section. Core GameKit automatically notifies all receivers (or a subset if you configure it that way) when the event is fired so they can perform an action if they are configured to respond to that exact event. Custom Events can be used for the following things:

     
  1. Trigger a Wave in all Triggered Spawners in the Scene that "receive" that Custom Event. You make it a receiver by adding a Wave of event type "Custom Event" in the Triggered Spawner, then selecting the Custom Event name from a dropdown. Then fill out your Wave specifics as normal.

    Note: Triggered Spawners and the items they spawn can also be set to look at the Custom Event origin for very simplistic following AI.
    2.  
  2. Many utility functions can be triggered with the Universal Custom Event Receiver script.
    3.  
  3. Write your own subclass to do anything! All Custom Event receivers (including TriggeredSpawner) must implement the ICgkEventReceiver interface. That way Core GameKit will keep track of the receiver and be able to automatically notify it when events are fired. You can look at the bottom of the Triggered Spawner script in a region called ICgkEventReceiver events if you wish to write your own custom implementation and want to see an example.

 

Here's what the Inspector for Custom Events looks like at the bottom of LevelWaveSettings:

 

 

There are 2 sections on this page:

  1. Custom Event Controls: What each control does so you can set up your events the way you want.
  2. Typical Setup & Usage: Some common use cases and a little API.

 

Custom Event Settings

 

Category and Custom Event creation is explained here. Let's looks at the rest of the settings for Custom Events:

     
  1. Collapse All Button: Shrink all events down to one line each.
    2.  
  2. Category Settings: The blue title bars have the following controls:
       
    • Expand / Collapse Button: Expand or collapse the Custom Event settings.
      •  
    • Shift Up / Down Icon: Use these icons to re-order your Categories.
      •  
    • Gear Icon: Click this to edit the name of the category. When editing, change the text then click either the disk icon to save or the red X icon to cancel.
      •  
    • Delete Button: Deletes the Category. You can only delete Categories with no Custom Events in them. You can either delete the Events or move them to another Category first.
    3.  
  3. Per-Item Settings: Each Custom Event has the following settings:
       
    • Title Bar Controls: Buttons and Icons that do the following:
         
      • Category: Using the blue dropdown, you can move the Custom Event to a different Category.
        •  
      • Name: As with Categories, the Custom Event name can be edited by clicking the gear icon to enter edit mode. Then a yellow text box will appear for the name. After editing, click the red X icon to cancel or the disk icon to save changes.
        •  
      • Viz. Button: Shows visualization for all objects in the Scene that are listening for this Custom Event. Will update any "visualization prefabs" in the Scene that have been updated after they were last visualized.
        •  
      • Hide Button: Hides visualization for all objects in the Scene that are listening for this Custom Event.
        •  
      • Delete Button: Deletes the Custom Event.
      •  
    • Title Bar Runtime Controls: During runtime, the number of receivers for each event will be shown on the title bar. Buttons also appear then to select all receivers in the Hierarchy and to fire the Custom Event from the position of the LevelWaveSettings Game Object.
      •  
    • Send To Receivers Dropdown: This controls which receivers are going to be notified when the Custom Event is fired (although the next field comes into play before that happens). The options are:
         
      • Always: The default. Always send the event to all receivers.
        •  
      • Never: Never send the event to any receivers (this disables the event without deleting).
        •  
      • When Distance Less Than: Only send the event to all receivers that are closer than the Distance Threshold. Cool for smart enemies that attack when you get close.
           
        • Distance Threshold: The distance to use for When Distance Less Than.
        •  
      • When Distance More Than: Only send the event to all receivers that are further away than the Distance Threshold.
           
        • Distance Threshold: The distance to use for When Distance Less Than.
        •  
      • On Same Game object: Only send to receivers on the same Game Object.
        •  
      • On Child Game Object: Only send to receivers on a child Game Object, including 2nd generation children and so on.
        •  
      • On Parent Game Object: Only send to receivers on a parent Game Object, including 2nd generation parents and so on.
        •  
      • On Same Or Child Game Object: Combination of "On Child Game Object" and "On Same Game Object".
        •  
      • On Same Or Parent Game Object: Combination of "On Parent Game Object" and "On Same Game Object".

        Note: The 5 "On X Game Object" modes will only look at receivers in the same part of the Hierarchy, and the rest will look at all receivers. The ones that look at all receivers only allow the Custom Event to be fired once a frame. The others will allow you to fire the event as many times per frame as you like as long as the event origins are all different.
      •  
    • Valid Receivers: This lets you choose which receivers (after the list is filtered down by the Send To Receivers choice) to send the event to when it's fired. 3 choices:
         
      • All: The default. All receivers are valid.
        •  
      • Closest: The closest X will be notified. Specify X in the next field.
           
        • Valid Qty: This specifies how many of the closest receivers will be notified.
        •  
      • Random: Out of all the remaining receivers, choose X at random to be notified. Specify X in the next field.
           
        • Valid Qty: This specifies how many random receivers will be notified.
 

Typical Setup & Usage

 

Typical event setup is usually some of the following steps:

     
  1. Create the event as described above.
    2.  
  2. Set up the Custom Event receiver. Either use the Triggered Spawner script (enable Custom Event and select the Custom Event name) or create your own class implementing the ICgkEventReceiver interface.
    3.  
  3. Be able to fire the Custom Event.
       
    • There are several places built into Core GameKit that will do this:
         
      • Use Initialization Options: At top of LevelWaveSettings Inspector. Will fire as soon as LevelWaveSettings has been initialized and is ready to use.
        •  
      • Mechanim Core Custom Events: Add this behavior directly to a Mechanim state in the Animator window. It allows you to fire a Custom Event when a Mechanim state is entered, exited, or a certain percentage of the animation is completed.
        •  
      • Spawn Custom Events: This option shows up in Triggered Spawner's Wave Spawn Bonus & Events section, as well as other sections.
        •  
      • Wave Completion Custom Events: This option shows up in each Global Wave set up in LevelWaveSettings. They will fire at the end of a Global Wave.
        •  
      • Wave Repeat Custom Events: This option shows up in Syncro Spawner & Triggered Spawner Waves and will fire each time the Wave repeats.
        •  
      • Damage Custom Events: This option shows up in Killable's Damage Prefab Settings and will fire each time damage is taken.
        •  
      • Death Custom Events: This option shows up in Killable's Death Prefab Settings and will fire whenever the Killable is killed.
        •  
      • Respawn Custom Events: This option shows up in Killable's Respawn Settings & Events section and will fire each time the Killable respawns (per Respawn Settings on the Killable).
        •  
      • Custom Events: This option shows up in World Variables and will fire whenever the World Variable's value is changed.
      •  
    • Do it from code.
         
      • The following code will do it: LevelSettings.FireCustomEvent(string customEventName, Vector3 eventOrigin);

        Note: The event original is normally the position of the Transform of the object that is firing the event. It will be used for distance calculations and other useful things as well.
        •  
      • You can also fire a Custom Event with a parameter, and that uses this method: LevelSettings.FireCustomEventWithParam To retrieve the parameter, use this method during the same frame only (this means you must write your own class implementing the ICgkEventReceiver interface: LevelSettings.GetCustomEventParam
        •  
      • Decorator Attribute: You can decorate public string properties in your custom scripts with the CoreCustomEvent attribute so that you can select a Custom Event name from a dropdown. As below: [CoreCustomEvent] public string deathEvent;