Event override - Revision history

Sunjammer at 18:59, 8 May 2014

2014-05-08T18:59:14Z

Sunjammer: Outlining risks of using engineevents

2014-05-08T18:52:54Z

Outlining risks of using engineevents

Sunjammer at 15:22, 8 May 2014

2014-05-08T15:22:48Z

Sunjammer at 15:20, 8 May 2014

2014-05-08T15:20:38Z

Sunjammer at 15:19, 8 May 2014

2014-05-08T15:19:12Z

Sunjammer: Fixing typo

2014-05-08T15:18:42Z

Fixing typo

Sunjammer: Reformatting

2014-05-08T15:18:03Z

Reformatting

Proleric1 at 10:19, 15 February 2011

2011-02-15T10:19:10Z

Kelamor: Add languages template

2010-10-28T01:27:18Z

Add languages template

BryanDerksen: {{Infobox script}}

2010-02-03T18:56:47Z

@@ Line 98: / Line 98: @@
+}
 </dascript>
 {{Languages}}
 [[Category:Events]]

@@ Line 5: / Line 5: @@
 == 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.
+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 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:
+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 <code>death_tyrant</code> with the following code:
 <dascript>
@@ Line 48: / Line 48: @@
 </dascript>
-And set this script as the event-handling script for Death Tyrants. When the game sends the Death Tyrant any event other than <code>EVENT_TYPE_DEATH</code>, it will get sent to the core <code>creature_core</code> event-handling script by the function call <code>HandleEvent(ev, RESOURCE_SCRIPT_CREATURE_CORE)</code>. However <code>EVENT_TYPE_DEATH</code> will be intercepted and handled by your own code.
+This script is then assigned to the Script property on the Death Tyrant resource.
-== Via the events 2DA ==
+When the game engine sends a Death Tyrant creature an event other than <code>EVENT_TYPE_DEATH</code> it will get sent to the core <code>creature_core</code> script by the<code>HandleEvent(evCurrent, RESOURCE_SCRIPT_CREATURE_CORE)</code>  function call. However <code>EVENT_TYPE_DEATH</code> will be intercepted and handled by your custom code.
-This is how you can do the same thing on a global scale, catching and overriding an event for all resources in the game.
+== Via the engineevents 2DA ==
-Create a [[Events.xls|engineevents]] [[2DA|m2da]] fragment (see [[2DA#Extending_the_game_via_M2DAs|extending the game via m2da files]] for details).
+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.
 [[File:Events.png]]
-In this case the <code>EVENT_TYPE_INVENTORY_ADDED</code> event will be overridden and handled in a custom script: <code>my_event_override</code>
+'''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.
-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).
+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:
 <dascript>
@@ Line 97: / Line 99: @@
 </dascript>
 {{Languages}}
 [[Category:Events]]

@@ Line 1: / Line 1: @@
 {{Infobox script}}
-The broadest definition of [[Event override|overriding an event]] means redirecting it from the default handler (or script) to some form of a custom handler.
+The broadest definition of [[Event override|overriding an event]] means redirecting an event from the default handler (or script) to some form of a custom handler.
 == Via a wrapper script ==

@@ Line 42: / Line 42: @@
      if(!nEventHandled)
+     {
-         HandleEvent(ev, RESOURCE_SCRIPT_CREATURE_CORE);
+         HandleEvent(evCurrent, RESOURCE_SCRIPT_CREATURE_CORE);
+     }
@@ Line 78: / Line 78: @@
          case EVENT_TYPE_INVENTORY_ADDED:
+         {
-             object oItem = GetEventObject(ev, 0);
+             // only show if the item went into the player's inventory
-−
-             // only show if the item went into the player's inventory
              if(IsPartyMember(oOwner))
+             {
                  DisplayFloatyMessage(oOwner, GetName(oItem) + " added", FLOATY_MESSAGE, 14654488, 10.0);
+             }

@@ Line 95: / Line 95: @@
+}
 </dascript>
 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, <code>HandleEvent(evCurrent)</code> ensures that any custom script on an object template is still executed.

@@ Line 1: / Line 1: @@
 {{Infobox script}}
-== How to override an event? ==
+The broadest definition of [[Event override|overriding an event]] means redirecting it from the default handler (or script) to some form of a custom handler.
-=== Via a wrapper script ===
+== 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.
@@ Line 16: / Line 16: @@
 void main()
+{
-     event ev = GetCurrentEvent();
+    int nEventHandled;
-     int nEventType = GetEventType(ev);
-     string sDebug;
+    // decompose the event
-     object oPC = GetHero();
+     event evCurrent = GetCurrentEvent();
-     object oParty = GetParty(oPC);
+     int nEventType = GetEventType(evCurrent);
-    int nEventHandled = FALSE;
      switch(nEventType)
@@ Line 27: / Line 30: @@
           case EVENT_TYPE_DEATH:
+          {
-              ...
+              // your custom code goes here
-              nEventHandled = TRUE; //set this if no further action is required for this event
               break;
+          }
+     }
-     if (!nEventHandled) //If this event wasn't handled by this script, let the core script try
+     {
          HandleEvent(ev, RESOURCE_SCRIPT_CREATURE_CORE);
+     }
+}
 </dascript>
-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'll get sent to the core creature_core event-handling script by the function call HandleEvent(ev, RESOURCE_SCRIPT_CREATURE_CORE). EVENT_TYPE_DEATH, on the other hand, will get intercepted and handled by your own code.
+And set this script as the event-handling script for Death Tyrants. When the game sends the Death Tyrant any event other than <code>EVENT_TYPE_DEATH</code>, it will get sent to the core <code>creature_core</code> event-handling script by the function call <code>HandleEvent(ev, RESOURCE_SCRIPT_CREATURE_CORE)</code>. However <code>EVENT_TYPE_DEATH</code> will be intercepted and handled by your own code.
-=== Via the Events 2DA ===
+== 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 [[Events.xls|Events]] M2DA File - for instructions look [[2DA#Extending_the_game_via_M2DAs|here]]:
+Create a [[Events.xls|engineevents]] [[2DA|m2da]] fragment (see [[2DA#Extending_the_game_via_M2DAs|extending the game via m2da files]] for details).
 [[File:Events.png]]
-In this case i used the "EVENT_TYPE_INVENTORY_ADDED" Event and Handle it in my custom Event-Handler-Script: my_event_override
+In this case the <code>EVENT_TYPE_INVENTORY_ADDED</code> event will be overridden and handled in a custom script: <code<my_event_override</code>
-Now just handle the event in your script as you like.
+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).
-−
-For example i want to have a screen-message every time i pick up an item (or steal one):
 <dascript>
 #include "utility_h"
 #include "wrappers_h"
 #include "events_h"
 void main()
+{
-     event ev   = GetCurrentEvent();
+     // decompose the event
-     int nEvent = GetEventType(ev);
+    event evCurrent = GetCurrentEvent();
-     object oOwner = GetEventCreator(ev);
+     int nEventType = GetEventType(evCurrent);
-     switch (nEvent)
+     switch(nEventType)
+     {
          case EVENT_TYPE_INVENTORY_ADDED:
+         {
              object oItem = GetEventObject(ev, 0);
-            if (IsPartyMember(oOwner)) // only show if the item went into the player's inventory
+             {
                  DisplayFloatyMessage(oOwner, GetName(oItem) + " added", FLOATY_MESSAGE, 14654488, 10.0);
+             }
-             //Now we didn't handle the event itself but just displayed a floaty --> let the original event handler take over.
-             HandleEvent(ev); // this passes the event to the default handler of the event's target object
+             // Since this script doesn't handle the event itself, but merely adds functionality (displaying the message),
              break;
+         }
+     }
+}
 // --- script end ---
 </dascript>
-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(ev) ensures that any custom script on an object template is still executed.
+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, <code>HandleEvent(evCurrent)</code> 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.
 {{Languages}}
 [[Category:Events]]

← Older revision		Revision as of 01:27, 28 October 2010
Line 89:		Line 89:
	</dascript>		</dascript>

		+	{{Languages}}
	[[Category:Events]]		[[Category:Events]]

← Older revision		Revision as of 18:56, 3 February 2010
Line 1:		Line 1:
		+	{{Infobox script}}
		+
	== How to override an event? ==		== How to override an event? ==