<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!DOCTYPE funcs
  SYSTEM '../../../clonk.dtd'>
<?xml-stylesheet type="text/xsl" href="../../../clonk.xsl"?>
<funcs>
  <func>
    <title>SetCommand</title>
    <category>Objects</category>
    <subcat>Commands</subcat>
    <version>5.1 OC</version>
    <syntax>
      <rtype>bool</rtype>
      <params>
        <param>
          <type>string</type>
          <name>command</name>
          <desc>Command name (as string). See the table below.</desc>
        </param>
        <param>
          <type>object</type>
          <name>target</name>
          <optional />
          <desc>target object for the command</desc>
        </param>
        <param>
          <type>int</type>
          <name>x</name>
          <optional />
          <desc>X target coordinate</desc>
        </param>
        <param>
          <type>int</type>
          <name>y</name>
          <optional />
          <desc>Y target coordinate</desc>
        </param>
        <param>
          <type>object</type>
          <name>target2</name>
          <optional />
          <desc>secondary target object</desc>
        </param>
        <param>
          <type>any</type>
          <name>Data</name>
          <optional />
          <desc>additional data for the command</desc>
        </param>
        <param>
          <type>int</type>
          <name>retries</name>
          <optional />
          <desc>Number of retries if the command fails, until the command fails completely.</desc>
        </param>
      </params>
    </syntax>
    <desc>Gives a command to an object. The object will try to complete the command using the internal artificial intelligence (including pathfinding).</desc>
    <remark>
      The following commands are defined: 
      <table>
        <rowh>
          <col>command</col>
          <col>target</col>
          <col>x, y</col>
          <col>target2</col>
          <col>Data</col>
          <col>Description</col>
        </rowh>
        <row>
          <literal_col>Acquire</literal_col>
          <col>Null</col>
          <col>0,0</col>
          <col>Ignore container</col>
          <col>Object type (id)</col>
          <col>Type of object to be acquired. May be bought at the home base if necessary. Material contained in the specified container (Target2) is to be ignored in the search.</col>
        </row>
        <row>
          <literal_col>Activate</literal_col>
          <col>Target object</col>
          <col></col>
          <col></col>
          <col></col>
          <col>Activate the target object (exit from its container).</col>
        </row>
        <row>
          <literal_col>Activate</literal_col>
          <col>Null</col>
          <col>0,0</col>
          <col>Target object</col>
          <col></col>
          <col>Open the Get menu for the contents of the target object.</col>
        </row>
        <row>
          <literal_col>Activate</literal_col>
          <col>Null</col>
          <col>Number,0</col>
          <col>Target object</col>
          <col>Object type (id)</col>
          <col>Activate n objects of the specified type in the target object.</col>
        </row>
        <row>
          <literal_col>Attack</literal_col>
          <col>Target object</col>
          <col></col>
          <col></col>
          <col></col>
          <col>Attack the target object.</col>
        </row>
        <row>
          <literal_col>Buy</literal_col>
          <col>Null</col>
          <col>0,0</col>
          <col>Null</col>
          <col>Object type (id)</col>
          <col>Buy an object of the specified type at the closest friendly home base.</col>
        </row>
        <row>
          <literal_col>Buy</literal_col>
          <col>Basis</col>
          <col>Number,0</col>
          <col>Null</col>
          <col>Object type (id)</col>
          <col>Buy n objects of the specified type at the home base.</col>
        </row>
        <row>
          <literal_col>Buy</literal_col>
          <col>Basis</col>
          <col></col>
          <col></col>
          <col></col>
          <col>Open the Buy menu for the specified home base.</col>
        </row>
        <row>
          <literal_col>Call</literal_col>
          <col>Object</col>
          <col>Par(1),Par(2)</col>
          <col>Par(3)</col>
          <col><em>Function</em> (string)</col>
          <col>Call <em>Function</em> in the object script. Par(0) will be the calling object. If the command fails because underlaying commands have failed, the function <em>Function</em>Failed is called instead.</col>
        </row>
        <row>
          <literal_col>Chop</literal_col>
          <col>Target object</col>
          <col></col>
          <col></col>
          <col></col>
          <col>Fell the target object object (tree).</col>
        </row>
        <row>
          <literal_col>Dig</literal_col>
          <col>Null</col>
          <col>Target position</col>
          <col></col>
          <col></col>
          <col>Dig towards the target position.</col>
        </row>
        <row>
          <literal_col>Drop</literal_col>
          <col></col>
          <col></col>
          <col></col>
          <col></col>
          <col>Immediately drop the first object in the inventory.</col>
        </row>
        <row>
          <literal_col>Drop</literal_col>
          <col>Null</col>
          <col>Target position</col>
          <col></col>
          <col></col>
          <col>Drop the first object in the inventory at the target position.</col>
        </row>
        <row>
          <literal_col>Drop</literal_col>
          <col>Target object</col>
          <col>Target position</col>
          <col></col>
          <col></col>
          <col>Collect the target object and drop it at the target position.</col>
        </row>
        <row>
          <literal_col>Enter</literal_col>
          <col>Target object</col>
          <col></col>
          <col></col>
          <col></col>
          <col>Enter the target object.</col>
        </row>
        <row>
          <literal_col>Exit</literal_col>
          <col></col>
          <col></col>
          <col></col>
          <col></col>
          <col>Exit the current container.</col>
        </row>
        <row>
          <literal_col>Follow</literal_col>
          <col>Target object</col>
          <col></col>
          <col></col>
          <col></col>
          <col>Follow the target object (permanently).</col>
        </row>
        <row>
          <literal_col>Get</literal_col>
          <col>Target object</col>
          <col></col>
          <col></col>
          <col></col>
          <col>Collect the target object, dig it out if necessary.</col>
        </row>
        <row>
          <literal_col>Get</literal_col>
          <col>Null</col>
          <col>Number,0</col>
          <col>Target object</col>
          <col>Object type (id)</col>
          <col>Get the specified number of objects from the target object.</col>
        </row>
        <row>
          <literal_col>Grab</literal_col>
          <col>Target object</col>
          <col>Offset</col>
          <col></col>
          <col></col>
          <col>Grab the target object at the specified offset to the object center.</col>
        </row>
        <row>
          <literal_col>Home</literal_col>
          <col></col>
          <col></col>
          <col></col>
          <col></col>
          <col>Return to the closest friendly home base.</col>
        </row>
        <row>
          <literal_col>Jump</literal_col>
          <col></col>
          <col></col>
          <col></col>
          <col></col>
          <col>Jump into the current direction.</col>
        </row>
        <row>
          <literal_col>Jump</literal_col>
          <col>Null</col>
          <col>Target position</col>
          <col></col>
          <col></col>
          <col>Jump into the direction of the target position.</col>
        </row>
        <row>
          <literal_col>MoveTo</literal_col>
          <col>Target object</col>
          <col>0,0</col>
          <col>Null</col>
          <col>No automatic adjustment? (bool)</col>
          <col>Move to the position of the target object. Set iData to true to avoid automatic adjustment of the target coordinates to landscape surface.</col>
        </row>
        <row>
          <literal_col>MoveTo</literal_col>
          <col>Null</col>
          <col>Target position</col>
          <col>Null</col>
          <col>No automatic adjustment? (bool)</col>
          <col>Move to the target position. Set iData to true to avoid automatic adjustment of the target coordinates to landscape surface.</col>
        </row>
        <row>
          <literal_col>None</literal_col>
          <col></col>
          <col></col>
          <col></col>
          <col></col>
          <col>Clear all current commands.</col>
        </row>
        <row>
          <literal_col>PushTo</literal_col>
          <col>Target object</col>
          <col>Target position</col>
          <col></col>
          <col></col>
          <col>Push the target object to the target position.</col>
        </row>
        <row>
          <literal_col>PushTo</literal_col>
          <col>Object</col>
          <col>0,0</col>
          <col>Target object</col>
          <col></col>
          <col>Push the target object into the secondary target object.</col>
        </row>
        <row>
          <literal_col>Put</literal_col>
          <col>Target object</col>
          <col></col>
          <col></col>
          <col></col>
          <col>Put the first inventory object into the target object.</col>
        </row>
        <row>
          <literal_col>Put</literal_col>
          <col>Target object</col>
          <col>Number,0</col>
          <col></col>
          <col></col>
          <col>Put the specified number of inventory objects into the target object.</col>
        </row>
        <row>
          <literal_col>Put</literal_col>
          <col>Target object</col>
          <col>0,0</col>
          <col>Object</col>
          <col></col>
          <col>Collect the target object and put it into the secondary target object.</col>
        </row>
        <row>
          <literal_col>Put</literal_col>
          <col>Target object</col>
          <col>0,0</col>
          <col>Null</col>
          <col>Object type (id)</col>
          <col>Put the inventory object of the specified type into the target object.</col>
        </row>
        <row>
          <literal_col>Put</literal_col>
          <col>Target object</col>
          <col>Number,0</col>
          <col>Null</col>
          <col>Object type (id)</col>
          <col>Put the specified number of inventory objects of the specified type into the target object.</col>
        </row>
        <row>
          <literal_col>Sell</literal_col>
          <col>Null</col>
          <col>0,0</col>
          <col>Object2</col>
          <col>Object type (id)</col>
          <col>Sell an object of the specified type at the closest home base. If Object2 is specified, this one will be sold first.</col>
        </row>
        <row>
          <literal_col>Sell</literal_col>
          <col>Basis</col>
          <col>Number,0</col>
          <col>Object2</col>
          <col>Object type (id)</col>
          <col>Sell a number of objects of the specified type at the home base. If Object2 is specified, this one will be sold first.</col>
        </row>
        <row>
          <literal_col>Sell</literal_col>
          <col>Basis</col>
          <col></col>
          <col></col>
          <col></col>
          <col>Open Sell menu for the specified base object.</col>
        </row>
        <row>
          <literal_col>Throw</literal_col>
          <col></col>
          <col></col>
          <col></col>
          <col></col>
          <col>Throw the first inventory item immediately.</col>
        </row>
        <row>
          <literal_col>Throw</literal_col>
          <col>Null</col>
          <col>Target position</col>
          <col></col>
          <col></col>
          <col>Throw the first inventory item towards the target position.</col>
        </row>
        <row>
          <literal_col>Throw</literal_col>
          <col>Target object</col>
          <col>Target position</col>
          <col></col>
          <col></col>
          <col>Collect the target object and throw it towards the target position.</col>
        </row>
        <row>
          <literal_col>UnGrab</literal_col>
          <col></col>
          <col></col>
          <col></col>
          <col></col>
          <col>Let go of the object currently grabbed.</col>
        </row>
        <row>
          <literal_col>Wait</literal_col>
          <col>Null</col>
          <col>0,0</col>
          <col>Null</col>
          <col>Frames</col>
          <col>Wait specified number of frames/ticks.</col>
        </row>
      </table>

    </remark>
    <examples>
      <example>
        <code>SetCommand(&quot;Attack&quot;, <funclink>FindObject</funclink>(<funclink>Find_ID</funclink>(Clonk),<funclink>Sort_Distance</funclink>(0,0)), 0, 0, 0, 0, 10);</code>
        <text>This script gives the clonk the order to attack the closest clonk of player 1. If the command fails (e.g. due to unsuccessful pathfinding), retry 10 times.</text>
      </example>
    </examples>
    <related>
      <funclink>GetCommand</funclink>
      <funclink>AddCommand</funclink>
      <funclink>AppendCommand</funclink>
      <funclink>FinishCommand</funclink>
    </related>
  </func>
  <author>PeterW</author><date>2001-11</date>
</funcs>
