<text>Object scripts control the complex behaviour of an object. For details on scripting see the <emlinkhref="script/index.html">C4Script</emlink> documentation.</text>
<h>Creation</h>
<text>For every object, the engine calls the function <ahref="#Initialize">Initialize</a> in the object script when it is created and completed.</text>
<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>
<text>An active object can also define activity script calls in its <emlinkhref="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>
<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 <emlinkhref="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>
<hid="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>
<rowid="Initialize">
<literal_col>Initialize</literal_col>
<col></col>
<col>When the object is completed (<emlinkhref="script/fn/GetCon.html">Con</emlink> >= 100).</col>
</row>
<rowid="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 <emlinkhref="script/fn/Construction.html">Construction</emlink></col>
</row>
<rowid="Destruction">
<literal_col>Destruction</literal_col>
<col></col>
<col>When the object is removed.</col>
</row>
<rowid="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>
<rowid="Hit2">
<literal_col>Hit2</literal_col>
<col></col>
<col>Like Hit, with speeds >= 20 (see <emlinkhref="script/fn/OCF_HitSpeed2.html">OCF_HitSpeed2</emlink>).</col>
</row>
<rowid="Hit3">
<literal_col>Hit3</literal_col>
<col></col>
<col>Like Hit, with speeds >= 60 (see <emlinkhref="script/fn/OCF_HitSpeed3.html">OCF_HitSpeed3</emlink>).</col>
</row>
<rowid="Grab">
<literal_col>Grab</literal_col>
<col>object target, bool grab</col>
<col>When the object grabs or lets go of another 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>
<rowid="Contact_">
<literal_col>Contact_</literal_col>
<col></col>
<col>When the object collides with the landscape. See <emlinkhref="definition/cnat.html">CNAT - Contact Attachment</emlink>.</col>
</row>
<rowid="Control_">
<literal_col>Control_</literal_col>
<col>object by_object</col>
<col>When the object is controlled from the outside. See <ahref="#Control-Funktionen">Control Functions</a>.</col>
</row>
<rowid="Contained_">
<literal_col>Contained_</literal_col>
<col>object by_object</col>
<col>When the object is controlled from the inside. See <ahref="#Control-Funktionen">Control Functions</a>.</col>
</row>
<rowid="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 <ahref="#Control-Funktionen">Control functions</a>.</col>
</row>
<rowid="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>
<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 <emlinkhref="script/fn/SetTransferZone.html">SetTransferZone</emlink>().</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 <emlinkhref="script/fn/SetTransferZone.html">SetTransferZone</emlink>().</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>
<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>
<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>
<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>
<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>
<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>
<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>
<col>When object is deselected in editor. Use this callback to hide any information previously shown in EditCursorSelection. If deselection happens due to another object being selected, that object is passed in next_selection.</col>
<col>When object is moved in editor. Callback is also done when moved in non-network pause mode. old_x, old_y contains object position before movement.</col>
<col>Called when scenario is saved from the editor. Object should write creation of itself and properties to the buffer props. Return true if the object should be saved and false if saving of this object should be omitted. See <emlinkhref="definition/script.html#ScenSave">Scenario saving</emlink>.</col>
<text>When the user chooses the "Save Scenario" option from the editor menu, the engine calls a global function SaveScenarioObjects defined in System.ocg/SaveScenario.c. This function writes all objects to the Objects.c file in their current state. The function stores all objects except the crew of currently joined human players and objects of a type that starts with GUI_. By default, objects are recreated using a call to <funclink>CreateObject</funclink> followed by setting a number of default properties like position, rotation, speed, action, if they are not in their default state.</text>
<text>For most object, the default saving method should be fine. However, it is possible to override the SaveScenarioObject callback to control how objects are created and which properties are set.</text>
<text>For example if a switch wants to save its target which is stored in a local variable called "target", the switch definition can override the callback:</text>
if (target) props->AddCall("Target", this, "SetTarget", target);
return true;
}</code>
<text>As a result, the generated Objects.c file will include the call to SetTarget if the switch is saved. Dependent objects should always either be passed to the AddCall function or stored as a string from the <funclink>MakeScenarioSaveName</funclink> function. If this is done, that object is marked as a dependency. The saving mechanism will ensure that any object this object depends on will be created before. In case of circular dependencies, the object property setting script is detached from object creation script.</text>
<text>If an object should not be saved in scenarios - for example, because it is just the helper of another object - the SaveScenarioObject callback should be overloaded to return false.</text>
<text>The object creation procedure can also be adjusted. For example, the waterfall object (defined in Objects.ocd/Environment.ocd/Waterfall.ocd) is created using the global functions CreateWaterfall and CreateLiquidDrain, which create a Waterfall object and attach an effect to it. To generate the creation functions from the effects, the waterfall overrides SaveScenarioObject:</text>
<code>func SaveScenarioObject(props)
{
if (!inherited(props, ...)) return false;
var fx_waterfall = GetEffect("IntWaterfall", this);
<text>The call to RemoveCreation removes the existing object creation using <funclink>CreateObject</funclink>.</text>
<text>If you need access to one of the objects created in the editor, you can set its "StaticSaveVar" property to the name of a static variable. The InitializeObjects() function will then save the object in that variable.</text>
<text>The following table lists standard properties that are saved if their value is different from the default and if it is not removed using a props->Remove call.
<table>
<rowh>
<col>Property name</col>
<col>Default value</col>
<col>Description</col>
</rowh>
<rowid="defprops_Alive">
<literal_col>Alive</literal_col>
<col>true</col>
<col>Category C4D_Living only: If object is not alive, a call to SetKill is stored. See <funclink>GetAlive</funclink> and <funclink>Kill</funclink>.</col>
</row>
<rowid="defprops_Action">
<literal_col>Action</literal_col>
<col>this.DefaultAction</col>
<col>Action as retrieved using <funclink>GetAction</funclink> and set using <funclink>SetAction</funclink>. Includes ActionTargets. Not stored by default but only if <funclink>SaveScenarioObjectAction</funclink> is called.</col>
</row>
<rowid="defprops_Phase">
<literal_col>Phase</literal_col>
<col>0</col>
<col>Action phase (see <funclink>GetPhase</funclink> and <funclink>SetPhase</funclink>). Not stored by default but only if <funclink>SaveScenarioObjectAction</funclink> is called.</col>
</row>
<rowid="defprops_Dir">
<literal_col>Dir</literal_col>
<col>DIR_Left</col>
<col>Animation direction (see <funclink>GetDir</funclink> and <funclink>SetDir</funclink>)</col>
</row>
<rowid="defprops_ComDir">
<literal_col>ComDir</literal_col>
<col>COMD_Stop</col>
<col>Commanded movement direction (see <funclink>GetComDir</funclink> and <funclink>SetComDir</funclink>)</col>
</row>
<rowid="defprops_Con">
<literal_col>Con</literal_col>
<col>100</col>
<col>Construction percentage, i.e. object size (see <funclink>GetCon</funclink> and <funclink>SetCon</funclink>)</col>
</row>
<rowid="defprops_Category">
<literal_col>Category</literal_col>
<col>GetID()->GetCategory()</col>
<col>Object category (see <funclink>GetCategory</funclink> and <funclink>SetCategory</funclink>)</col>
</row>
<rowid="defprops_R">
<literal_col>R</literal_col>
<col>0</col>
<col>Rotation (see <funclink>GetR</funclink> and <funclink>SetR</funclink>)</col>
</row>
<rowid="defprops_XDir">
<literal_col>XDir</literal_col>
<col>0</col>
<col>Horizontal speed (see <funclink>GetXDir</funclink> and <funclink>SetXDir</funclink>)</col>
</row>
<rowid="defprops_YDir">
<literal_col>YDir</literal_col>
<col>0</col>
<col>Vertical speed (see <funclink>GetYDir</funclink> and <funclink>SetYDir</funclink>). Vertical speed is not saved it is very small and the object touches the ground to avoid saving of speed on idle objects.</col>
</row>
<rowid="defprops_RDir">
<literal_col>RDir</literal_col>
<col>0</col>
<col>Rotation speed (see <funclink>GetRDir</funclink> and <funclink>SetRDir</funclink>)</col>
</row>
<rowid="defprops_Color">
<literal_col>Color</literal_col>
<col>0, 0xffffffff</col>
<col>Object color of ColorByOwner-surfaces (see <funclink>GetColo</funclink> and <funclink>SetColor</funclink>)</col>
</row>
<rowid="defprops_ClrModulation">
<literal_col>ClrModulation</literal_col>
<col>0, 0xffffffff</col>
<col>Object color modulation of all surfaces (see <funclink>GetClrModulation</funclink> and <funclink>SetClrModulation</funclink>)</col>
</row>
<rowid="defprops_BlitMode">
<literal_col>BlitMode</literal_col>
<col>0</col>
<col>Object drawing mode (see <funclink>GetObjectBlitMode</funclink> and <funclink>SetObjectBlitMode</funclink>)</col>
<col>Object name (see <funclink>GetName</funclink> and <funclink>SetName</funclink>)</col>
</row>
<rowid="defprops_MaxEnergy">
<literal_col>MaxEnergy</literal_col>
<col>GetID().MaxEnergy</col>
<col>Maximum energy (see <emlinkhref="definition/properties.html">Properties</emlink>)</col>
</row>
<rowid="defprops_Energy">
<literal_col>Energy</literal_col>
<col>GetID().MaxEnergy/1000</col>
<col>Current energy level (see <funclink>GetEnergy</funclink> and <funclink>DoEnergy</funclink>)</col>
</row>
<rowid="defprops_Visibility">
<literal_col>Visibility</literal_col>
<col>VIS_All</col>
<col>Object visibility (see <emlinkhref="definition/properties.html">Properties</emlink>)</col>
</row>
<rowid="defprops_Plane">
<literal_col>Plane</literal_col>
<col>GetID().Plane</col>
<col>Object plane, i.e. z-order (see <emlinkhref="definition/properties.html">Properties</emlink>)</col>
</row>
<rowid="defprops_Position">
<literal_col>Position</literal_col>
<col></col>
<col>Object position. This is only set if the object has a rotation and could not be created directly at the correct offset (see <funclink>SetPosition</funclink>)</col>
</row>
<rowid="defprops_Commands">
<literal_col>Command</literal_col>
<col>None</col>
<col>Stores only the topmost command of the chain (see <funclink>GetCommand</funclink> and <funclink>SetCommand</funclink>)</col>
</row>
<rowid="defprops_Fire">
<literal_col>Fire</literal_col>
<col></col>
<col>Fire effect.</col>
</row>
</table>
</text>
<text>By default, effects are not saved in scenarios. To force saving of an effect, define the Fx*SaveScen callback. For example, the fire effect saves itself like this:</text>
<text>obj and fx refer to the object and effect proplist as for any effect call. save_name is the variable name of the effected object and is unset for global effects.</text>
<hid="ScenSave">Scenario saving reference</h>
<text>The following functions are available to call on the "props" parameter passed to SaveScenarioObject callbacks:</text>
<h>AddCall</h>
<text><code>bool AddCall(string id, object target, string function, any par1, any par2, ...);</code></text>
<text>Adds a new call of format target->Function(par1, par2, ...) to the stored object script. Object parameters may be passed as is; strings must be quoted explicitely.</text>
<text>The id parameter is an identifier which can be used by derived objects to remove the property again.</text>
<h>Add</h>
<text><code>bool AddCall(string id, string script, any par1, any par2, ...);</code></text>
<text>Adds a custom script snippet of any format. script may contain format characters and parameters are formatted into the string using <funclink>Format</funclink>().</text>
<h>Remove</h>
<text><code>int Remove(string id);</code></text>
<text>Remove all strings added previously using AddCall or Add with the given ID. Can also be used to remove default properties. Returns number of script lines removed.</text>
<h>RemoveCreation</h>
<text><code>bool RemoveCreation();</code></text>
<text>Remove all strings added previously using with IDs SAVEOBJ_Creation or SAVEOBJ_ContentsCreation.</text>
<h>Clear</h>
<text><code>bool Clear();</code></text>
<text>Remove all creation and property setting strings.</text>