Difference between revisions of "Event override"

Revision as of 16:20, 8 May 2014

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

Via a wrapper script

The safest and most common 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 event you want to override while passing on all other events to the core script to handle.

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

#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);
    }
 
}

And set this script as the event-handling script for Death Tyrants. When the game sends the Death Tyrant any event other than EVENT_TYPE_DEATH, it will get sent to the core creature_core event-handling script by the function call HandleEvent(ev, RESOURCE_SCRIPT_CREATURE_CORE). However EVENT_TYPE_DEATH will be intercepted and handled by your own code.

Via the events 2DA

This is how you can do the same thing on a global scale, catching and overriding an event for all resources in the game.

Create a engineevents m2da fragment (see extending the game via m2da files for details).

In this case the EVENT_TYPE_INVENTORY_ADDED event will be overridden and handled in a custom script: my_event_override

This custom script can do whatever is required, for example, displaying a message on screen every time the Player picks up an item (or steal one).

#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 that the "default handler" is the script specified on the resource template. So, even if events.xls is used to make a global change, HandleEvent(evCurrent) ensures that any custom script on an object template is still executed.

This is especially useful for compatibility purposes. If mods that affect all campaigns use events.xls, while custom campaigns use custom scripts on resource templates, the two can coexist.