forked from Mirrors/openclonk
335 lines
18 KiB
XML
335 lines
18 KiB
XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
|
|
<!DOCTYPE doc
|
|
SYSTEM '../../clonk.dtd'>
|
|
<?xml-stylesheet type="text/xsl" href="../../clonk.xsl"?>
|
|
<doc>
|
|
<title>Object Scripts</title>
|
|
<h>Object Scripts</h>
|
|
<part>
|
|
<text>Object scripts control the complex behaviour of an object. For details on scripting see the <emlink href="script/index.html">C4Script</emlink> documentation.</text>
|
|
<h>Creation</h>
|
|
<text>For every object, the engine calls the function <a href="#Initialize">Initialize</a> in the object script when it is created and completed.</text>
|
|
<code>func Initialize()
|
|
{
|
|
<emlink href="script/fn/CreateContents.html">CreateContents</emlink>(Rock);
|
|
}
|
|
</code>
|
|
<text>An object with this script will be given a rock right after it has been created. The Initialize function is called only when the object has reached full size (a building only when its construction has been completed and a living being only when it is fully grown).</text>
|
|
<h>ActMap</h>
|
|
<text>An active object can also define activity script calls in its <emlink href="definition/actmap.html">ActMap</emlink>. The defined StartCall is made whenever an action begins (or repeats), an EndCall is made at the end of each activity. PhaseCall is called at each animation phase step and should only be used for very short animations. The call frequency of PhaseCalls is determined by the speed of the animation.</text>
|
|
<h>#include</h>
|
|
<text>An object script can also include the functionality of another script.</text>
|
|
<code>#include Clonk</code>
|
|
<text>At this position the complete script of the specified object definition (that of the clonk, in this case) is inserted, including all scripts that that script includes or got via <emlink href="script/AppendTo.html">#appendto</emlink>. The only exception is that every script is included only once, so including both the Clonk script and a script that is included by the Clonk script doesn't include that script twice. Other Obviously, the included definition must be valid and loaded. Declared functions can be overloaded by functions of the same name that occur later in the script. Also see <funclink>inherited</funclink>().</text>
|
|
<h>Interaction from other scripts</h>
|
|
<text>Other scripts can call functions of an object <code>obj</code> with the <code>-></code> and <code>->~</code> operators.</text>
|
|
<code>var obj = CreateObject(Flint); obj->Hit();</code>
|
|
<h id="ObjektCallsderEngine">Object calls made by the engine</h>
|
|
<text>
|
|
The engine calls the following functions is objects at the given time.
|
|
<table>
|
|
<rowh>
|
|
<col>Function</col>
|
|
<col>Parameter</col>
|
|
<col>Description</col>
|
|
</rowh>
|
|
<row id="Initialize">
|
|
<literal_col>Initialize</literal_col>
|
|
<col></col>
|
|
<col>When the object is completed (<emlink href="script/fn/GetCon.html">Con</emlink> >= 100).</col>
|
|
</row>
|
|
<row id="Construction">
|
|
<literal_col>Construction</literal_col>
|
|
<col>object by_object</col>
|
|
<col>When the object is created. The parameter is a pointer to the object the script of which has created this object. Also see <emlink href="script/fn/Construction.html">Construction</emlink></col>
|
|
</row>
|
|
<row id="Destruction">
|
|
<literal_col>Destruction</literal_col>
|
|
<col></col>
|
|
<col>When the object is removed.</col>
|
|
</row>
|
|
<row id="Hit">
|
|
<literal_col>Hit</literal_col>
|
|
<col></col>
|
|
<col>When the object collides with the landscape or is collected at high velocity (>=15).</col>
|
|
</row>
|
|
<row id="Hit2">
|
|
<literal_col>Hit2</literal_col>
|
|
<col></col>
|
|
<col>Like Hit, with speeds >= 20 (see <emlink href="script/fn/OCF_HitSpeed2.html">OCF_HitSpeed2</emlink>).</col>
|
|
</row>
|
|
<row id="Hit3">
|
|
<literal_col>Hit3</literal_col>
|
|
<col></col>
|
|
<col>Like Hit, with speeds >= 60 (see <emlink href="script/fn/OCF_HitSpeed3.html">OCF_HitSpeed3</emlink>).</col>
|
|
</row>
|
|
<row id="Grab">
|
|
<literal_col>Grab</literal_col>
|
|
<col>object target, bool grab</col>
|
|
<col>When the object grabs or lets go of another object.</col>
|
|
</row>
|
|
<row id="Grabbed">
|
|
<literal_col>Grabbed</literal_col>
|
|
<col>object by_object, bool grab</col>
|
|
<col>When the object is grabbed or let go by another object.</col>
|
|
</row>
|
|
<row id="Get">
|
|
<literal_col>Get</literal_col>
|
|
<col>object target</col>
|
|
<col>When the object takes another object from a container.</col>
|
|
</row>
|
|
<row id="Put">
|
|
<literal_col>Put</literal_col>
|
|
<col></col>
|
|
<col>When the object puts another object into a container.</col>
|
|
</row>
|
|
<row id="Damage">
|
|
<literal_col>Damage</literal_col>
|
|
<col>int change, int cause, int by_player</col>
|
|
<col>When the object is damaged. See <emlink href="script/Effects.html#damagecause">Fx*Damage</emlink>for <code>cause</code> values.</col>
|
|
</row>
|
|
<row id="DeepBreath">
|
|
<literal_col>DeepBreath</literal_col>
|
|
<col></col>
|
|
<col>When a living being surfaces after having used up more than half of its breath.</col>
|
|
</row>
|
|
<row id="Incineration">
|
|
<literal_col>Incineration</literal_col>
|
|
<col>int by_player</col>
|
|
<col>When the object is incinerated. Notice: with objects changing their definition via BurnTo, this call is made to the burned version!</col>
|
|
</row>
|
|
<row id="IncinerationEx">
|
|
<literal_col>IncinerationEx</literal_col>
|
|
<col>int by_player</col>
|
|
<col>When the object is incinerated in and immediately extinguished by a surrounding liquid. Otherwise as Incineration.</col>
|
|
</row>
|
|
<row id="Death">
|
|
<literal_col>Death</literal_col>
|
|
<col></col>
|
|
<col>When a living being dies.</col>
|
|
</row>
|
|
<row id="Activate">
|
|
<literal_col>Activate</literal_col>
|
|
<col>object by_object</col>
|
|
<col>Activation by double dig. Only applies to collected items or directly controlled crew objects. Called after internal handling of the double dig command has been completed (e.g. chopping of trees etc.)</col>
|
|
</row>
|
|
<row id="Contact_">
|
|
<literal_col>Contact_</literal_col>
|
|
<col></col>
|
|
<col>When the object collides with the landscape. See <emlink href="definition/cnat.html">CNAT - Contact Attachment</emlink>.</col>
|
|
</row>
|
|
<row id="Control_">
|
|
<literal_col>Control_</literal_col>
|
|
<col>object by_object</col>
|
|
<col>When the object is controlled from the outside. See <a href="#Control-Funktionen">Control Functions</a>.</col>
|
|
</row>
|
|
<row id="Contained_">
|
|
<literal_col>Contained_</literal_col>
|
|
<col>object by_object</col>
|
|
<col>When the object is controlled from the inside. See <a href="#Control-Funktionen">Control Functions</a>.</col>
|
|
</row>
|
|
<row id="ControlCommand">
|
|
<literal_col>ControlCommand</literal_col>
|
|
<col>string command, object target, int x, int y, object target2, int data, object command_object</col>
|
|
<col>When the object has received a command to be independently executed. See <a href="#Control-Funktionen">Control functions</a>.</col>
|
|
</row>
|
|
<row id="ControlCommandFinished">
|
|
<literal_col>ControlCommandFinished</literal_col>
|
|
<col>string command, object target, int x, int y, object target2, any Data</col>
|
|
<col>When the object has completed a command or execution of a command has failed.</col>
|
|
</row>
|
|
<row id="ControlTransfer">
|
|
<literal_col>ControlTransfer</literal_col>
|
|
<col>object obj, int x, int y</col>
|
|
<col>When an object (obj) using the internal pathfinding algorithm is trying to pass the transfer zone of this object on its way to point x/y. The transfer function can then help the object along by giving special script commands and returning <code>true</code>. Also see <emlink href="script/fn/SetTransferZone.html">SetTransferZone</emlink>().</col>
|
|
</row>
|
|
<row id="UpdateTransferZone">
|
|
<literal_col>UpdateTransferZone</literal_col>
|
|
<col></col>
|
|
<col>When an object is loaded from a savegame or network synchronization is performed. Objects with a transfer zone should reset the zone in this call. Also see <emlink href="script/fn/SetTransferZone.html">SetTransferZone</emlink>().</col>
|
|
</row>
|
|
<row id="MenuQueryCancel">
|
|
<literal_col>MenuQueryCancel</literal_col>
|
|
<col>int selection, object menu_object</col>
|
|
<col>When the player wants to close a user defined object menu. Return value <code>true</code> will keep the menu open.</col>
|
|
</row>
|
|
<row id="IsFulfilled">
|
|
<literal_col>IsFulfilled</literal_col>
|
|
<col></col>
|
|
<col>Only in game goal objects. A return value <code>true</code> indicates that this goal is fulfilled.</col>
|
|
</row>
|
|
<row id="ControlContents">
|
|
<literal_col>ControlContents</literal_col>
|
|
<col>id target</col>
|
|
<col>When a new inventory object is selected. See <a href="#Control-Funktionen">Control Functions</a>.</col>
|
|
</row>
|
|
<row id="Selection">
|
|
<literal_col>Selection</literal_col>
|
|
<col>object container</col>
|
|
<col>When the object is selected in an inventory change. If you are processing this event, the function should play its own selection sound.</col>
|
|
</row>
|
|
<row id="CatchBlow">
|
|
<literal_col>CatchBlow</literal_col>
|
|
<col>int level, object by</col>
|
|
<col>When the object is hit or punched by another object.</col>
|
|
</row>
|
|
<row id="QueryCatchBlow">
|
|
<literal_col>QueryCatchBlow</literal_col>
|
|
<col>object by</col>
|
|
<col>Called before the object is hit or punched by another object. By returning <code>true</code>, QueryCatchBlow can reject physical blows.</col>
|
|
</row>
|
|
<row id="LineBreak">
|
|
<literal_col>LineBreak</literal_col>
|
|
<col>int cause</col>
|
|
<col>When a line object is broken. cause: 0 by movement, 1 because of a missing or incomplete target object.</col>
|
|
</row>
|
|
<row id="BuildNeedsMaterial">
|
|
<literal_col>BuildNeedsMaterial</literal_col>
|
|
<col>id material_definition, int amount</col>
|
|
<col>When the object is building another object and building material is required. The parameters are the type and amount of the first needed material. If this function returns <code>true</code>, no material message is displayed above the object.</col>
|
|
</row>
|
|
<row id="AttachTargetLost">
|
|
<literal_col>AttachTargetLost</literal_col>
|
|
<col></col>
|
|
<col>When the object is in an ATTACH action and has lost its action target. At this time, the object's action has already been reset.</col>
|
|
</row>
|
|
<row id="CrewSelection">
|
|
<literal_col>CrewSelection</literal_col>
|
|
<col>bool deselect, bool cursor_only</col>
|
|
<col>When crew selection is changed. cursor_only specifies whether only that crew member has been selected which is also the cursor.</col>
|
|
</row>
|
|
<row id="GetObject2Drop">
|
|
<literal_col>GetObject2Drop</literal_col>
|
|
<col>object for_collection_of_object</col>
|
|
<col>Called to determine the least needed inventory object when a clonk tries to collect a new object and his inventory is full. The function should return the object to be dropped to gain space, or <code>nil</code> if none.</col>
|
|
</row>
|
|
<row id="OnMenuSelection">
|
|
<literal_col>OnMenuSelection</literal_col>
|
|
<col>int index, object menu_object</col>
|
|
<col>When an object menu entry is selected.</col>
|
|
</row>
|
|
<row id="CalcValue">
|
|
<literal_col>CalcValue</literal_col>
|
|
<col>object in_base, int for_player</col>
|
|
<col>Calculates the value of an object. Also see <emlink href="script/fn/GetValue.html">GetValue</emlink>().</col>
|
|
</row>
|
|
<row id="CalcDefValue">
|
|
<literal_col>CalcDefValue</literal_col>
|
|
<col>object in_base, int for_player</col>
|
|
<col>Calculates the value of an object type available to buy. Also see <emlink href="script/fn/GetValue.html">GetValue</emlink>().</col>
|
|
</row>
|
|
<row id="CalcBuyValue">
|
|
<literal_col>CalcBuyValue</literal_col>
|
|
<col>id item, int value</col>
|
|
<col>Returns the buying price of the object type.</col>
|
|
</row>
|
|
<row id="CalcSellValue">
|
|
<literal_col>CalcSellValue</literal_col>
|
|
<col>object obj, int object_value</col>
|
|
<col>Returns the selling price of the object type.</col>
|
|
</row>
|
|
<row id="LiftTop">
|
|
<literal_col>LiftTop</literal_col>
|
|
<col></col>
|
|
<col>When an object with LIFT action lifts its action target to the height specified in its DefCore or above.</col>
|
|
</row>
|
|
<row id="Stuck">
|
|
<literal_col>Stuck</literal_col>
|
|
<col></col>
|
|
<col>When the action target of the object's PUSH or LIFT action is stuck.</col>
|
|
</row>
|
|
<row id="GrabLost">
|
|
<literal_col>GrabLost</literal_col>
|
|
<col></col>
|
|
<col>When the action target of the object's PUSH or PULL action is lost.</col>
|
|
</row>
|
|
<row id="Collection">
|
|
<literal_col>Collection</literal_col>
|
|
<col>object obj, bool put</col>
|
|
<col>When the object has collected another object (obj) (by ingame collection or grabbing and getting).</col>
|
|
</row>
|
|
<row id="Collection2">
|
|
<literal_col>Collection2</literal_col>
|
|
<col>object obj</col>
|
|
<col>When the object has collected another object (obj) (in all cases, even in script controlled collection or entering).</col>
|
|
</row>
|
|
<row id="ContentsDestruction">
|
|
<literal_col>ContentsDestruction</literal_col>
|
|
<col>object destroyed</col>
|
|
<col>When an object contained in the object has been destroyed/removed. The object still exists when the callback is called, but will be destroyed afterwards.</col>
|
|
</row>
|
|
<row id="Departure">
|
|
<literal_col>Departure</literal_col>
|
|
<col>object container</col>
|
|
<col>When this object has left another object (container).</col>
|
|
</row>
|
|
<row id="Ejection">
|
|
<literal_col>Ejection</literal_col>
|
|
<col>object obj</col>
|
|
<col>When another object (obj) has left the contents of this object (also see script command Exit).</col>
|
|
</row>
|
|
<row id="Entrance">
|
|
<literal_col>Entrance</literal_col>
|
|
<col>object container</col>
|
|
<col>When the object has entered another object (container).</col>
|
|
</row>
|
|
<row id="ActivateEntrance">
|
|
<literal_col>ActivateEntrance</literal_col>
|
|
<col>object by_object</col>
|
|
<col>When another object is trying to enter this object through the entrance.</col>
|
|
</row>
|
|
<row id="RejectCollect">
|
|
<literal_col>RejectCollect</literal_col>
|
|
<col>id def, object obj</col>
|
|
<col>Called before Collection. If RejectCollect returns <code>true</code>, the collection of the other object is prevented.</col>
|
|
</row>
|
|
<row id="RejectEntrance">
|
|
<literal_col>RejectEntrance</literal_col>
|
|
<col>object into_object</col>
|
|
<col>Called before Entrance. If RejectEntrance returns <code>true</code>, then entrance of the other object is prevented.</col>
|
|
</row>
|
|
<row id="InitializePlayer">
|
|
<literal_col>InitializePlayer</literal_col>
|
|
<col>int player</col>
|
|
<col>Called in game goals, rules, or environment objects after the joining of a new player and before the corresponding call in the scenario script.</col>
|
|
</row>
|
|
<row id="SellTo">
|
|
<literal_col>SellTo</literal_col>
|
|
<col>int by_player</col>
|
|
<col>When the object is sold. Should return <code>nil</code> or the id of the object type which is actually added to the player's homebase material.</col>
|
|
</row>
|
|
<row id="Sale">
|
|
<literal_col>Sale</literal_col>
|
|
<col>int by_player</col>
|
|
<col>When the object is sold.</col>
|
|
</row>
|
|
<row id="Purchase">
|
|
<literal_col>Purchase</literal_col>
|
|
<col>int by_player, object buy_object</col>
|
|
<col>When the object is bought.</col>
|
|
</row>
|
|
<row id="Recruitment">
|
|
<literal_col>Recruitment</literal_col>
|
|
<col>int player</col>
|
|
<col>When the objet is added to the crew of a player.</col>
|
|
</row>
|
|
<row id="RejectTeamSwitch">
|
|
<literal_col>RejectTeamSwitch</literal_col>
|
|
<col>int player, int new_team</col>
|
|
<col>Callback in game goal, rule, and environment objects and in the scenario script. If RejectTeamSwitch returns <code>true</code>, the team switch of a player can be prevented (see <funclink>SetPlayerTeam</funclink>).</col>
|
|
</row>
|
|
<row id="OnTeamSwitch">
|
|
<literal_col>OnTeamSwitch</literal_col>
|
|
<col>int player, int new_team, int old_team</col>
|
|
<col>Callback in game goal, rule, and environment objects and in the scenario script. Called when a player has successfully switch from old_team to new_team (see <funclink>SetPlayerTeam</funclink>).</col>
|
|
</row>
|
|
</table>
|
|
|
|
</text>
|
|
</part>
|
|
<author>sulai</author><date>2003-11</date>
|
|
<author>Sven2</author><date>2004-02</date>
|
|
<author>matthes</author><date>2004-07</date>
|
|
<author>Clonkonaut</author><date>2008-04</date>
|
|
</doc>
|