Difference between revisions of "Event override"

Latest revision as of 19:59, 8 May 2014

The broadest definition of overriding an event means redirecting an event from the default handler (or script) to some form of a custom handler.

Via a wrapper script

The normal, and safest, way to override an event is to create an event script for the resource whose event-handling you want to override, and use that script to handle the specific events you want to override while passing on all other events to the core script to handle.

For example, if you have a creature called "Death Tyrant" that does something special when it receives the EVENT_TYPE_DEATH event, you could create a script named death_tyrant with the following code:

#include "utility_h"
#include "wrappers_h" 
#include "events_h"
 
void main()
{
    int nEventHandled;
 
    // decompose the event
    event evCurrent = GetCurrentEvent();
    int nEventType = GetEventType(evCurrent);
 
    // common variable
    object oHero = GetHero();
    object oParty = GetParty(oHero);   
 
    switch(nEventType)
    {
         case EVENT_TYPE_DEATH:
         {
             // your custom code goes here
 
             // set nEventHandled if no further action is required for this event
             nEventHandled = TRUE; 
 
             break;
         }
    }
 
    // if this event wasn't handled by this script, let the core script try
    if(!nEventHandled)
    {
        HandleEvent(evCurrent, RESOURCE_SCRIPT_CREATURE_CORE);
    }
 
}

This script is then assigned to the Script property on the Death Tyrant resource.

When the game engine sends a Death Tyrant creature an event other than EVENT_TYPE_DEATH it will get sent to the core creature_core script by theHandleEvent(evCurrent, RESOURCE_SCRIPT_CREATURE_CORE) function call. However EVENT_TYPE_DEATH will be intercepted and handled by your custom code.

Via the engineevents 2DA

An alternative, and more advanced, way to override an event is to use the engineevents 2da. Overriding an event in this way does it "global" scale, catching and redirecting an event for all resources in the game.

Create an engineevents 2da fragment (see extending the game via m2da files for further details) to override, for example, the EVENT_TYPE_INVENTORY_ADDED event so that it will be handled by the custom my_event_override script.

NOTE: this is a substitution fragment (i.e. one that replaces an original entry) rather than an extension fragment (i.e. one that adds a new entry) and will cause compatibility issues with any other mod that also attempts to override the same event using this technique.

The custom script can be constructed to do whatever is required, for example, displaying a message on screen every time the Player picks up (or steals) an item:

#include "utility_h"
#include "wrappers_h"
#include "events_h"
 
void main()
{
    // decompose the event
    event evCurrent = GetCurrentEvent();
    int nEventType = GetEventType(evCurrent);
    object oOwner = GetEventCreator(evCurrent);
 
    switch(nEventType)
    {
        case EVENT_TYPE_INVENTORY_ADDED:
        {
            // only show if the item went into the player's inventory
            if(IsPartyMember(oOwner))
            {
                object oItem = GetEventObject(evCurrent, 0);
 
                DisplayFloatyMessage(oOwner, GetName(oItem) + " added", FLOATY_MESSAGE, 14654488, 10.0);
            }
 
            // Since this script doesn't handle the event itself, but merely adds functionality (displaying the message),
            // the event is passed back to its default event handler for the event's target object
            HandleEvent(evCurrent); 
 
            break;
        }
    }
 
}

NOTE: the "default handler" is the script specified on the resource, therefore even if engineevents 2da is used to make a global change, calling HandleEvent(evCurrent) ensures that the script assigned to the resources Script property is still executed.