openclonk/docs/sdk/script/Typechecks.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>Data Types</title>
  <h>Data Types</h>
  <part>
    <text>C4Script supports the following data types for variables, parameters, and return values:</text>
    <text>
      <table>
        <rowh>
          <col>Type Name</col>
          <col>Full Name</col>
          <col>Contents of Variable</col>
          <col>Example</col>
        </rowh>
        <row>
          <col><code>int</code></col>
          <col>Integer</col>
          <col>A whole number from -2.147.483.648 to +2.147.483.647.</col>
          <col><code>42</code></col>
        </row>
        <row>
          <col><code>bool</code></col>
          <col>Boolean</col>
          <col>"true" (value <code>true</code>) or "false" (value <code>false</code>). Expected as parameter by many structures such as <funclink>if</funclink> and <funclink>while</funclink>.</col>
          <col><code>true</code></col>
        </row>
        <row>
          <col><code>string</code></col>
          <col>String</col>
          <col>Any text.</col>
          <col><code>&quot;This is a text!&quot;</code></col>
        </row>
        <row>
          <col><code>array</code></col>
          <col>Array</col>
          <col>A type containing multiple variables, whose number can be enquired with <funclink>GetLength</funclink>, and which can be recalled with <code><em>array</em>[<em>index</em>]</code>.</col>
          <col><code>[0,23,Clonk]</code></col>
        </row>
        <row>
          <col><code>proplist</code></col>
          <col>Object</col>
          <col>A general purpose object type. <funclink>GetProperty</funclink> and <funclink>SetProperty</funclink> can get respectively set properties. If the property <code>"Prototype"</code> is set, and a property that is not set is gotten, the prototype is asked.</col>
          <col><code>{ foo = 0, &quot;bar baz&quot; = 13, Prototype = Clonk }</code></col>
        </row>
        <row>
          <col><code>func</code></col>
          <col>Function</col>
          <col>A function. At the moment, this is only used to store them in proplists.</col>
          <col><code>Flint.Hit</code></col>
        </row>
        <row>
          <col><code>nil</code></col>
          <col></col>
          <col>The type of <code>nil</code>.</col>
          <col><code>nil</code></col>
        </row>
        <row>
          <col><code>any</code></col>
          <col></col>
          <col>When used as a function parameter type, the type check is skipped.</col>
          <col></col>
        </row>
        <row>
          <col><code>def</code></col>
          <col><emlink href="definition/index.html">Object Definition</emlink></col>
          <col>Represents a DefCore.txt and the associated Script.c. A special kind of proplist.</col>
          <col><code>Clonk</code></col>
        </row>
        <row>
          <col><code>object</code></col>
          <col>Ingame Object</col>
          <col>An instance of an Object Definition. A special kind of proplist.</col>
          <col><code><funclink>CreateObject</funclink>(Clonk)</code></col>
        </row>
        <row>
          <col><code>effect</code></col>
          <col><emlink href="script/Effects.html">Effect</emlink></col>
          <col>A special kind of proplist with associated timers and stacking callbacks.</col>
          <col><code><funclink>AddEffect</funclink>("Shiny", nil, 1)</code></col>
        </row>
      </table>
    </text>
    <h>Arrays</h>
    <part>
		<text>Arrays can be created directly with <code>[<em>expression 1</em>, <em>expression 2</em>, ...]</code> or indirectly with <funclink>CreateArray</funclink>(). They are automatically enlarged if necessary on element access, but it's faster to create them with the needed length from the start. Arrays behave like objects, you can only store references of them. Example: <code>var a = CreateArray(), b = a; b[0] = 42; // a is now [42]</code> A copy of <code>a</code> can be obtained with <code>a[:]</code>, as explained below.</text>
      <text>Access to element <code>i</code> of array <code>a</code> is achieved through <code>a[i]</code>. <code>i=0</code> is the first element. Negative indices are counted from the end of the array, so that <code>a[-1]</code> refers to the last element of the array.</text>
      <text>A range within an array can be copied with <code>a[i:j]</code>. The resulting array contains all elements with indices in the half-open interval <code>[i,j)</code>. Negative indices are treated as when accessing single elements. Both indices are optional and assumed as <code>0</code> and <code><funclink>GetLength</funclink>(a)</code> respectively if not given.</text>
      <h>Example 1</h>
      <code>func ArraySum(array a)
{
  var l = <funclink>GetLength</funclink>(a);
  var result = 0;
  for (var i = 0; i &lt; l; ++i)
  {
    result += a[i];
  }
  return (result);
}</code>
      <text>This function adds up all elements of an array.</text>
      <h>Example 2</h>
      <code>func RandomID()
{
  var a = [Clonk, Wipf, Bird];
  return (a[<funclink>Random</funclink>(3)]);
}</code>
      <text>This function randomly chooses one out of four ids and returns it.</text>
      <h>Example 3</h>
      <code>func DetonateNearest()
{
  var a = <funclink>FindObjects</funclink>(<funclink>Find_ID</funclink>(Dynamite), <funclink>Sort_Distance</funclink>());
  for (var dyna in a[:6])
  {
    dyna-&gt;DoExplode();
  }
}</code>
	  <text>This function calls <code>DoExplode()</code> on the six nearest Dynamite objects.</text>
	  <text>An array may not exceed 1000000 elements. "ye shalt not create arrays larger than that!"</text>
    </part>
    <h>Proplists</h>
    <part>
      <text>Proplists are a datatype that maps values to strings and supports prototype inheritance.</text>
      <text>Proplists can be created with <code>{<i>key 1</i>=<i>expression 1</i>, <i>key 2</i>=<i>expression 2</i>, ...}</code> or with <funclink>CreateProplist</funclink>.</text>
    </part>
    <h>Conversion</h>
    <text>
      <ul>
        <li>All values except for <code>false</code>, <code>nil</code> and <code>0</code> are treated as <code>true</code> when a bool is required.</li>
        <li><code>nil</code> and <code>false</code> can be converted to <code>0</code>. <code>true</code> can be converted to <code>1</code>.</li>
        <li><code>nil</code> can always be used as a function parameter, if the function doesn't implement a separate check.</li>
        <li>Objects, Definitions and Effects can be converted to proplists, and then back. Normal proplists cannot be converted into them.</li>
      </ul>
    </text>
  </part>
  <author>Günther</author><date>2010-2011</date>
  <author>PeterW</author><date>2006-04</date>
</doc>