Differences

This shows you the differences between two versions of the page.

--- modding:xml:events [2012/05/24 07:57] – fixing broken formatting from doom star_weaver
+++ modding:xml:events [2014/12/27 04:40] (current) – external edit 127.0.0.1
@@ Line 1: / Line 1: @@
+=====Pages that List Events=====
+  * [[SpaceObject#Events|SpaceObject]]
+  * [[DesignType#Events|DesignType]]
+=====Unclassified=====
+====<GetCreatePos>====
+====<GetMaxHP>====
+====<OnAddedAsEnhancement>====
+====<OnGameEnd>====
+Found inside //<AdventureDesc>//
+====<OnGameStart>====
+Found inside //<AdventureDesc>//
+====<OnShow>====
+When a communication menu messages is shown.
+=====Item Events=====
+====<OnAIUpdate>====
+**Populated variables:**
+  * gSource: object that carries the item
+  * gItem: the item
+The OnAIUpdate event for an item is called once every 30 ticks on every non-player ship that carries the item. Use this event to implement special behaviors. For example, an //<OnAIUpdate>// event on an armor patch item allows a non-player ship to use the armor patch when it is damaged.
+Use this event sparingly because it will impact performance.
+====<OnUpdate>====
+**Populated variables:**
+  * gSource: object that carries the item
+  * gItem: the item
+The OnUpdate event for an item is called once every 30 ticks on every object that carries the item. Use this event sparingly because it will impact performance.
+====<OnUninstall>====
+====<CanBeInstalled>====
+**Populated variables:**
+  * gSource: object that we're installing on
+  * gItem: item being installed
+You can return ''True'' if the item can be installed.
+Or you can return a string, which is the message that will be shown to the user to tell them why the item cannot be installed.
+<CanBeInstalled> is called on an item from inside shpCanInstallArmor and shpCanInstallDevice.
+====<CanBeUninstalled>====
+**Populated variables:**
+  * gSource: object that we're uninstalling from
+  * gItem: item being uninstalled
+You can return ''True'' if the item can be uninstalled.
+Or you can return a string, which is the message that will be shown to the user to tell them why the item cannot be uninstalled.
+<CanBeUninstalled> is called on an item from inside shpCanRemoveDevice. [There is currently no way to prevent an armor segment from being uninstalled. (said about 1.06)]
+====<OnFireWeapon>====
+====<OnInvokedByPlayer>====
+====<OnInstall>====
+====<OnOrderChanged>====
+====<OnOrdersCompleted>====
+For ships, when all queued orders are completed
+====<OnPlayerEnteredSystem>====
+In 1.07: \\
+aGateObj: The gate that was entered \\
+aDestNodeID: The destination node \\
+aDestEntryPoint: The destination entry point label \\
+====<OnPlayerLeftSystem>====
+====<OnRefuel>====
+====<OnRemovedAsEnhancement>====
+====<OnShieldDown>====
+=====Events and script=====
+Some events are very particular about where they can be called from and what kind of functions can be run in them.
+The <OnCreate> function can be placed in ships or stations but dosn't like running some functions due to the fact that what it is looking for may not yet have been create.  This event is best used to set timers for other events or register with a controller so it can be given orders at a later time.
+There are a number of functions that are used in cunjuction with events such as:
+<code lisp>
+(sysAddObjRecurringTimerEvent)
+    ;; will fire a specific event every n ticks until (sysCancelTimerEvent) is called
+(sysAddObjTimerEvent)
+    ;; will fire a specific event after a delay only once
+(sysCancelTimerEvent)
+    ;; will cancel a timer event (obviously!)
+(objFireEvent)
+    ;; will fire a specific event immediately
+(objFireItemEvent)
+    ;; will fire a specific event that is contained in an item immediately
+(objRegisterForEvents)
+    ;; creates a relationship between two objects so they can use eachother in events
+    ;; Some events can only be called once they have been registered such as <onObjDocked>
+(objUnregisterForEvents)
+    ;; cancels the relationship between objects
+</code>
+You are not limited to these events, you can create any event you wish but it must be called from a function that you define.
+<code lisp>
+	<Events>
+		<OnCreate>
+			(block Nil
+		  	 (itmEnumTypes "*" itemType
+				(block  Nil
+					(itmSetKnown itemType)
+					(itmSetReference itemType)
+					)
+				)
+			)
+	        </OnCreate>
+	</Events>
+</code>
+This little fella here is a great event to add to a ship that you use for debugging your mods.  It will fire the even <OnCreate> when the game loads.  <OnCreate> is a built in Event.  If you put it on another ship or a station it will still run but it's effects will not be noticed by you unless it is on your player ship.
+<code lisp>
+<Events>
+    <OnDestroy>
+        (block Nil
+            (plyMessage gPlayer "You haven't seen the last of me!!!! BOOM!")
+            (sysAddObjTimerEvent 100 gSource "Kaboom")
+            )
+    </OnDestroy>
+    <Kaboom>
+         (sysCreateWeaponFire &vtPlasmaExplosion2; gSource (objGetPos gSource) 0 0 gSource)
+    </Kaboom>
+</Events>
+</code>
+The <OnDestroy> event is called when ship or station that is holding this event is destroyed.  When it is run, it sends a message to the player and sets a timer to run the event called "Kaboom" after 100 ticks have passed.  The event <Kaboom> creates a little farewell fireworks display.  The <OnDestroy> event is built-in so it is called when it's condition is met.  In this case, when the object that has the event is destroyed.  The event <Kaboom> is not built-in, so we must call it when we want it to run, in this case 100 ticks after it is destroyed.
+====Old Lede=====
+Events are a powerful way to create behaviour in ships and stations.
+===Events===
+The following info is taken from the OTF, here -> http://neurohack.com/transcendence/forums/viewtopic.php?t=1997&highlight=events
+Check also what George wrote on events on the Tags section of the wiki: http://wiki.neurohack.com/transcendence/wiki/modding/xml/itemtype#events
+===== Notes =====
+<OnSystemExplosion> \\
+Found in BattleArena.xml, no idea what it does.