ReferenceGuide - LuisAntonRebollo/Torque-3D-Wiki-Test GitHub Wiki

<SCRIPT SRC="../../../include/tutorial.js" LANGUAGE="JavaScript"></SCRIPT> <SCRIPT SRC="../../../include/prototype.js" LANGUAGE="JavaScript"></SCRIPT> <SCRIPT SRC="../../../include/scriptaculous.js" LANGUAGE="JavaScript"></SCRIPT> <SCRIPT SRC="../../../include/glossaryLookUp.js" LANGUAGE="JavaScript"></SCRIPT> <SCRIPT SRC="../../../include/referenceLookUp.js" LANGUAGE="JavaScript"></SCRIPT> <SCRIPT SRC="../../../include/component.js" LANGUAGE="JavaScript"></SCRIPT> <SCRIPT SRC="../../../include/componentContainer.js" LANGUAGE="JavaScript"></SCRIPT> <SCRIPT>DocImagePath = "../../../";</SCRIPT> <script> // this script chunk is to update the ToC to the current doc and expand it pageID = 64; parent.leftFrame.expandToItem('tree2', 'doc64'); var element = parent.leftFrame.document.getElementById('doc64'); if((element) && (element.className==parent.leftFrame.nodeClosedClass)) { element.className = parent.leftFrame.nodeOpenClass } ; </script> <title>Torque 3D - Torque Script Introduction</title> 
    <table border="0" cellpadding="0" cellspacing="0" width="700">
      <tbody>
        <tr>
          <td width="700"><table id="toc" summary="Contents">
              <tbody>
                <tr>
                  <td><div id="toctitle">
                      <h2>Contents</h2>
                    <ul>
                      <li class="toclevel-1"><a href="#Language_Features"><span class="tocnumber">1</span> <span class="toctext">Language Features</span></a></li>
                      <li class="toclevel-1"><a href="#Variable_Names"><span class="tocnumber">2</span> <span class="toctext">Variable Names</span></a></li>
                      <li class="toclevel-1"><a href="#Constants"><span class="tocnumber">3</span> <span class="toctext">Constants</span></a></li>
                      <li class="toclevel-1"><a href="#Operators"><span class="tocnumber">4</span> <span class="toctext">Operators</span></a></li>
                      <li class="toclevel-1"><a href="#Keywords"><span class="tocnumber">5</span> <span class="toctext">Keywords</span></a>
                        <ul>
                          <li class="toclevel-2"><a href="#break"><span class="tocnumber">5.1</span> <span class="toctext">break</span></a></li>
                          <li class="toclevel-2"><a href="#case"><span class="tocnumber">5.2</span> <span class="toctext">case</span></a></li>
                          <li class="toclevel-2"><a href="#continue"><span class="tocnumber">5.3</span> <span class="toctext">continue</span></a></li>
                          <li class="toclevel-2"><a href="#datablock"><span class="tocnumber">5.4</span> <span class="toctext">datablock</span></a></li>
                          <li class="toclevel-2"><a href="#default"><span class="tocnumber">5.5</span> <span class="toctext">default</span></a></li>
                          <li class="toclevel-2"><a href="#else"><span class="tocnumber">5.6</span> <span class="toctext">else</span></a></li>
                          <li class="toclevel-2"><a href="#FALSE"><span class="tocnumber">5.7</span> <span class="toctext">FALSE</span></a></li>
                          <li class="toclevel-2"><a href="#for"><span class="tocnumber">5.8</span> <span class="toctext">for</span></a></li>
                          <li class="toclevel-2"><a href="#function"><span class="tocnumber">5.9</span> <span class="toctext">function</span></a></li>
                          <li class="toclevel-2"><a href="#if"><span class="tocnumber">5.10</span> <span class="toctext">if</span></a></li>
                          <li class="toclevel-2"><a href="#new"><span class="tocnumber">5.11</span> <span class="toctext">new</span></a></li>
                          <li class="toclevel-2"><a href="#package"><span class="tocnumber">5.12</span> <span class="toctext">package</span></a></li>
                          <li class="toclevel-2"><a href="#parent"><span class="tocnumber">5.13</span> <span class="toctext">parent</span></a></li>
                          <li class="toclevel-2"><a href="#return"><span class="tocnumber">5.14</span> <span class="toctext">return</span></a></li>
                          <li class="toclevel-2"><a href="#switch"><span class="tocnumber">5.15</span> <span class="toctext">switch</span></a></li>
                          <li class="toclevel-2"><a href="#switch.24"><span class="tocnumber">5.16</span> <span class="toctext">switch$</span></a></li>
                          <li class="toclevel-2"><a href="#TRUE"><span class="tocnumber">5.17</span> <span class="toctext">TRUE</span></a></li>
                          <li class="toclevel-2"><a href="#while"><span class="tocnumber">5.18</span> <span class="toctext">while</span></a></li>
                        </ul>
                      </li>
                    </ul></td>
                </tr>
              </tbody>
            </table>
            <p>&nbsp;</p>
            <p><strong>IMPORTANT:</strong> You can download and view the Full TorqueScript Manual by clicking here: <a href="../Torque 3D - Script Manual.chm" class="downloads">TorqueScript Reference Manual</a></p><br />
            <p><strong>Note for Windows Users:</strong> Due to security measures, the OS may block the CHM after you download it. To unblock it, perform the following steps:<br /></p>
            <p>1. Locate CHM on your hard drive<br />
            2. Right click on the CHM, then click Properties<br />
            3. At the bottom, click the "Unblock" button<br />
            4. Apply and close the properties<br /><br /></p>
              <strong>Note for OSX Users:</strong> There is no default CHM viewer installed with Mac OSX. There are several free options available for download:<br />
                <ul><li><a href="http://chmox.sourceforge.net/" class="external">Chmox</a></li>
                <li><a href="http://www.robinlu.com/blog/ichm" class="external">iChm</a></li>
            </ul>
            <br />
            <p><a name="Language_Features" id="Language_Features"></a>
            </p>
            <h2> <span class="mw-headline">Language Features</span></h2>
            <p>TorqueScript is a typeless scripting language, with similarities in
              syntax to C/C++. In TorqueScript, you will find that most C/C++
              operators work in the familiar way (with important exceptions, as noted
              here). Besides a subset of C/C++, TorqueScript provides: </p>
            <ul>
              <li>Case-insensitive symbols; keywords <i>false</i> and <i>FALSE</i> are identical. </li>
              <li>Auto creation and destruction of local/global variables and their storage. </li>
              <li>String concatenation, comparison, and auto-string-constant creation. </li>
              <li>Function packaging. </li>
            </ul><br />
            <a name="Variable_Names" id="Variable_Names"></a>
            <h2> <span class="mw-headline">Variable Names</span></h2></td>
        </tr>
      </tbody>
    </table>
    <table bgcolor="#eeeeee" border="1" cellpadding="4" cellspacing="0" width="700">
      <tbody>
        <tr>
          <th bgcolor="#6699ff" width="10%"><b>Type</b></th>
          <th width="10%"><b>Syntax</b></th>
          <th><b>Example</b></th>
          <th><b>Explanation</b></th>
        </tr>
        <tr>
          <td bgcolor="#6699ff"><b>
            
              Global
            
            </b></td>
          <td>
              prefix $
            </td>
          <td>
              $a
            </td>
          <td>
              $a is a global variable
            </td>
        </tr>
        <tr>
          <td bgcolor="#6699ff"><b>
            
              Local
            
            </b></td>
          <td>
              prefix %
            </td>
          <td>
              %b
            </td>
          <td>
              %b is a local variable
            </td>
        </tr>
        <tr>
          <td rowspan="3" bgcolor="#6699ff" valign="top"><b>Array</b><br />
              (Global<br />
              or Local)
            </td>
          <td rowspan="2" bgcolor="#eeeeee" valign="top">
              postfix []
            </td>
          <td>
              $MyArray[n]
            </td>
          <td>
              Array
            </td>
        </tr>
        <tr>
          <td align="left" bgcolor="#eeeeee" valign="top">
              $MyMultiArray[n,m]
            
            
              $MyMultiArrayn_m
            </td>
          <td align="left" bgcolor="#eeeeee" valign="top">
              Multi-dimensional array
            </td>
        </tr>
        <tr>
          <td colspan="3" bgcolor="#eeeeee"><p><b>Note:</b> TorqueScript does not have support for arrays as such.
              Instead, the bracket notation is a shorthand for creating a variable
              name. $a[0] is synonymous with $a0, and $M[1,4] with $M1_4. You must
              not think of $a as the name of the array containing $a[5]. TorqueScript
              arrays provide the means for creating variable names dynamically: if $i
              is 5, then $a[$i] is synonymous with $a5. </p></td>
        </tr>
      </tbody>
    </table><br />
    <table border="0" cellpadding="0" cellspacing="0" width="700">
      <tbody>
        <tr>
          <td width="700"><a name="Constants" id="Constants"></a>
            <h2> <span class="mw-headline">Constants</span></h2></td>
        </tr>
      </tbody>
    </table>
    <table bgcolor="#eeeeee" border="1" cellpadding="4" cellspacing="0" width="700">
      <tbody>
        <tr>
          <th bgcolor="#6699ff" width="10%"><b>Type</b></th>
          <th bgcolor="#eeeeee" width="20%"><b>Example</b></th>
          <th bgcolor="#eeeeee"><b>Explanation</b></th>
        </tr>
        <tr>
          <td rowspan="2" bgcolor="#6699ff" valign="top"><b>
            
              Boolean
            
            </b></td>
          <td>
              TRUE
            </td>
          <td>
              1
            </td>
        </tr>
        <tr>
          <td align="left" bgcolor="#eeeeee" valign="top">
              FALSE
            </td>
          <td align="left" bgcolor="#eeeeee" valign="top">
              0
            </td>
        </tr>
        <tr>
          <td rowspan="2" bgcolor="#6699ff" valign="top"><b>
            
              Integer
            
            </b></td>
          <td>
              123
            </td>
          <td>
              decimal
            </td>
        </tr>
        <tr>
          <td align="left" bgcolor="#eeeeee" valign="top">
              0xabc
            </td>
          <td align="left" bgcolor="#eeeeee" valign="top">
              hexadecimal
            </td>
        </tr>
        <tr>
          <td rowspan="3" bgcolor="#6699ff" valign="top"><b>
            
              Float
            
            </b></td>
          <td align="left" bgcolor="#eeeeee" valign="top">
              1.23
            </td>
          <td align="left" bgcolor="#eeeeee" valign="top">
              floating-point
            </td>
        </tr>
        <tr>
          <td align="left" bgcolor="#eeeeee" valign="top">
              1.00E-003
            </td>
          <td align="left" bgcolor="#eeeeee" valign="top">
              scientific notation
            </td>
        </tr>
        <tr>
          <td colspan="2" bgcolor="#eeeeee"><b>Note</b>: If the float is less
            than 1, explicitly include the leading "0" before the ".", e.g., "0.2".
            Entering ".2" will not work in every circumstance.</td>
        </tr>
        <tr>
          <td rowspan="10" bgcolor="#6699ff" valign="top"><b>
            
              Character
            
            </b></td>
          <td>
              \n
            </td>
          <td>
              newline
            </td>
        </tr>
        <tr>
          <td align="left" bgcolor="#eeeeee" valign="top">
              \r
            </td>
          <td align="left" bgcolor="#eeeeee" valign="top">
              carriage return
            </td>
        </tr>
        <tr>
          <td align="left" bgcolor="#eeeeee" valign="top">
              \t
            </td>
          <td align="left" bgcolor="#eeeeee" valign="top">
              tab
            </td>
        </tr>
        <tr>
          <td align="left" bgcolor="#eeeeee" valign="top">
              \c0 .. \c9
            </td>
          <td align="left" bgcolor="#eeeeee" valign="top">
              colorize subsequent console output
            </td>
        </tr>
        <tr>
          <td align="left" bgcolor="#eeeeee" valign="top">
              \cr
            </td>
          <td align="left" bgcolor="#eeeeee" valign="top">
              reset to default color
            </td>
        </tr>
        <tr>
          <td align="left" bgcolor="#eeeeee" valign="top">
              \cp
            </td>
          <td align="left" bgcolor="#eeeeee" valign="top">
              push color from color stack
            </td>
        </tr>
        <tr>
          <td align="left" bgcolor="#eeeeee" valign="top">
              \co
            </td>
          <td align="left" bgcolor="#eeeeee" valign="top">
              pop color from color stack
            </td>
        </tr>
        <tr>
          <td align="left" bgcolor="#eeeeee" valign="top">
              \xhh
            </td>
          <td align="left" bgcolor="#eeeeee" valign="top">
              two-digit hex value ASCII code
            </td>
        </tr>
        <tr>
          <td align="left" bgcolor="#eeeeee" valign="top">
              \\
            </td>
          <td align="left" bgcolor="#eeeeee" valign="top">
              backslash
            </td>
        </tr>
        <tr>
          <td align="left" bgcolor="#eeeeee" valign="top">
              \"
            </td>
          <td align="left" bgcolor="#eeeeee" valign="top">
              double-quotes
            </td>
        </tr>
        <tr>
          <td rowspan="2" bgcolor="#6699ff" valign="top"><b>
            
              String
            
            </b></td>
          <td>
              "Hello world"
            </td>
          <td>
              Normal string
            </td>
        </tr>
        <tr>
          <td align="left" bgcolor="#eeeeee" valign="top">
              'Torque Rocks'
            </td>
          <td align="left" bgcolor="#eeeeee" valign="top">
              A tagged
              string, as used in communication between client and server. The value
              of a tagged string is sent only once; subsequently, only the tag is
              sent. Clients will store the string at an index identified by the tag
              and can look up the value, avoiding the need for it to be sent
              repeatedly.
            </td>
        </tr>
        <tr>
          <td rowspan="2" bgcolor="#6699ff" valign="top"><b>
            
              Vector
            
            </b></td>
          <td>
              "1.0 2.0 1.0 2.0"
            </td>
          <td>
              4-element vector
            </td>
        </tr>
        <tr>
          <td colspan="2" bgcolor="#eeeeee"><p><b>Note:</b> TorqueScript does not have support for vectors as such.
              The vector exemplified here is simply a space-separated string. Space-,
              tab-, and newline-separated strings crop up in the calling sequence of
              certain functions, notably in the return value, which technically is a
              scalar, but may be a string that can be interpreted as a vector. </p></td>
        </tr>
      </tbody>
    </table><br />
    <table border="0" cellpadding="0" cellspacing="0" width="700">
      <tbody>
        <tr>
          <td width="700"><a name="Operators" id="Operators"></a>
            <h2> <span class="mw-headline">Operators</span></h2></td>
        </tr>
      </tbody>
    </table>
    <table bgcolor="#eeeeee" border="1" cellpadding="4" cellspacing="0" width="700">
      <tbody>
        <tr>
          <th bgcolor="#eeeeee" width="15%"><b>
            
              Operator
            
            </b></th>
          <th bgcolor="#eeeeee" width="20%"><b>
            
              Name
            
            </b></th>
          <th bgcolor="#eeeeee" width="20%"><b>
            
              Example
            
            </b></th>
          <th bgcolor="#eeeeee" width="45%"><b>
            
              Explanation
            
            </b></th>
        </tr>
        <tr>
          <td colspan="4" bgcolor="#6699ff"><b>Arithmetic Operators</b>
            </td>
        </tr>
        <tr>
          <td>
              *
            </td>
          <td>
              multiplication
            </td>
          <td>
              $a * $b
            </td>
          <td>
              Multiply $a and $b.
            </td>
        </tr>
        <tr>
          <td>
              /
            </td>
          <td>
              division
            </td>
          <td>
              $a / $b
            </td>
          <td>
              Divide $a by $b.
            </td>
        </tr>
        <tr>
          <td>
              %
            </td>
          <td>
              modulo
            </td>
          <td>
              $a % $b
            </td>
          <td>
              Remainder of $a divided by $b.
            </td>
        </tr>
        <tr>
          <td>
              +
            </td>
          <td>
              addition
            </td>
          <td>
              $a + $b
            </td>
          <td>
              Add $a and $b.
            </td>
        </tr>
        <tr>
          <td>
              -
            </td>
          <td>
              subtraction
            </td>
          <td>
              $a - $b
            </td>
          <td>
              Subtract $b from $a.
            </td>
        </tr>
        <tr>
          <td>
              ++
            </td>
          <td>
              auto-increment<br />
              (post-fix only)
            </td>
          <td>
              $a++
            </td>
          <td>
              Increment $a. Note: ++$a is illegal.
            
            <b>Note:</b> the value of $a++ is that of the incremented variable: auto-increment
              is post-fix in syntax, but pre-increment in semantics (the variable is
              incremented, <i>before</i> the return value is calculated). This behavior is unlike that of C and C++.
            </td>
        </tr>
        <tr>
          <td>
              - -
            </td>
          <td>
              auto-decrement<br />
              (post-fix only)
            </td>
          <td>
              $b--
            </td>
          <td>
              Decrement $b. Note: --$b is illegal.
            
            <b>Note:</b> the value of $a-- is that of the decremented variable: auto-decrement
              is post-fix in syntax, but pre-decrement in semantics (the variable is
              decremented, <i>before</i> the return value is calculated). This behavior is unlike that of C and C++.
            </td>
        </tr>
        <tr>
          <td colspan="4" bgcolor="#6699ff"><b>Relations (Arithmetic, Logical, and String)</b>
            </td>
        </tr>
        <tr>
          <td>
              &lt;
            </td>
          <td>
              Less than
            </td>
          <td>
              $a &lt; $b
            </td>
          <td>
              1 if $a is less than % b (0 otherwise.)
            </td>
        </tr>
        <tr>
          <td>
              &gt;
            </td>
          <td>
              More than
            </td>
          <td>
              $a &gt; $b
            </td>
          <td>
              1 if $a is greater than % b (0 otherwise.)
            </td>
        </tr>
        <tr>
          <td>
              &lt;=
            </td>
          <td>
              Less than or Equal to
            </td>
          <td>
              $a &lt;= $b
            </td>
          <td>
              1 if $a is less than or equal to % b (0 otherwise.)
            </td>
        </tr>
        <tr>
          <td>
              &gt;=
            </td>
          <td>
              More than or Equal to
            </td>
          <td>
              $a &gt;= $b
            </td>
          <td>
              1 if $a is greater than or equal to % b (0 otherwise.)
            </td>
        </tr>
        <tr>
          <td>
              ==
            </td>
          <td>
              Equal to
            </td>
          <td>
              $a == $b
            </td>
          <td>
              1 if $a is equal to % b (0 otherwise.)
            </td>
        </tr>
        <tr>
          <td>
              !=
            </td>
          <td>
              Not equal to
            </td>
          <td>
              $a != $b
            </td>
          <td>
              1 if $a is not equal to % b (0 otherwise.)
            </td>
        </tr>
        <tr>
          <td>
              !
            </td>
          <td>
              Logical NOT
            </td>
          <td>
              !$a
            </td>
          <td>
              1 if $a is 0 (0 otherwise.)
            </td>
        </tr>
        <tr>
          <td>
              &amp;&amp;
            </td>
          <td>
              Logical AND
            </td>
          <td>
              $a &amp;&amp; $b
            </td>
          <td>
              1 if $a and $b are both non-zero (0 otherwise.)
            </td>
        </tr>
        <tr>
          <td>
              ||
            </td>
          <td>
              Logical OR
            </td>
          <td>
              $a || $b
            </td>
          <td>
              1 if either $a or $b is non-zero (0 otherwise.)
            </td>
        </tr>
        <tr>
          <td>
              $=
            </td>
          <td>
              String equal to
            </td>
          <td>
              $c $= $d
            </td>
          <td>
              1 if $c equal to $d .
            </td>
        </tr>
        <tr>
          <td>
              !$=
            </td>
          <td>
              String not equal to
            </td>
          <td>
              $c !$= $d
            </td>
          <td>
              1 if $c not equal to $d.
            </td>
        </tr>
        <tr>
          <td colspan="4" bgcolor="#6699ff"><b>Bitwise Operators</b>
            </td>
        </tr>
        <tr>
          <td>
              ~
            </td>
          <td>
              Bitwise complement
            </td>
          <td>
              ~$a
            </td>
          <td>
              flip bits 1 to 0 and 0 to 1. (i.e. ~10b  == 01b)
            </td>
        </tr>
        <tr>
          <td>
              &amp;
            </td>
          <td>
              Bitwise AND
            </td>
          <td>
              $a &amp; $b
            </td>
          <td>
              composite of elements where bits in same position are 1. (i.e. 1b &amp; 1b == 1b)
            </td>
        </tr>
        <tr>
          <td>
              |
            </td>
          <td>
              Bitwise OR
            </td>
          <td>
              $a | $b
            </td>
          <td>
              composite of elements where bits 1 in either of the two elements. (i.e. 100b &amp; 001b == 101b)
            </td>
        </tr>
        <tr>
          <td>
              ^
            </td>
          <td>
              Bitwise XOR
            </td>
          <td>
              $a ^ $b
            </td>
          <td>
              composite of elements where bits in same position are opposite.  (i.e. 100b &amp; 101b == 001b)
            </td>
        </tr>
        <tr>
          <td>
              &lt;&lt;
            </td>
          <td>
              Left Shift
            </td>
          <td>
              $a &lt;&lt; 3
            </td>
          <td>
              element shifted left by 3 and padded with zeros. (i.e. 11b &lt;&lt; 3d == 11000b)
            </td>
        </tr>
        <tr>
          <td>
              &gt;&gt;
            </td>
          <td>
              Right Shift
            </td>
          <td>
              $a &gt;&gt; 3
            </td>
          <td>
              element shifted right by 3 and padded with zeros. (i.e. 11010b &gt;&gt; 3d == 00011b)
            </td>
        </tr>
        <tr>
          <td colspan="4" bgcolor="#6699ff"><b>Assignment and  Assignment Operators</b>
            </td>
        </tr>
        <tr>
          <td>
              =
            </td>
          <td>
              Assignment
            </td>
          <td>
              $a = $b;
            </td>
          <td>
              Assign value of $b to $a.
            
            <b>Note</b>:  the value of an assignment is the value being assigned, so $a = $b = $c is legal.
            </td>
        </tr>
        <tr>
          <td>
              op=
            </td>
          <td>
              Assignment Operators
            </td>
          <td>
              $a <i>op</i>= $b;
            </td>
          <td>
              Equivalent to $a = $a <i>op</i> $b, where <i>op</i> can be any of:<br />
              *  /  %  +  -  &amp;  |  ^  &lt;&lt;  &gt;&gt;
            </td>
        </tr>
        <tr>
          <td colspan="4" bgcolor="#6699ff"><b>String Operators</b>
            </td>
        </tr>
        <tr>
          <td>
              @
            </td>
          <td>
              String concatenation
            </td>
          <td>
              $c @ $d
            </td>
          <td>
              Concatenates strings $c and $d into a single string. Numeric literals/variables convert to strings.
            </td>
        </tr>
        <tr>
          <td>
              NL
            </td>
          <td>
              New Line
            </td>
          <td>
              $c NL $d
            </td>
          <td>
              Concatenates strings $c and $d into a single string separated by new-line.
            
            <b>Note</b>: such a string can be decomposed with getRecord()
            </td>
        </tr>
        <tr>
          <td>
              TAB
            </td>
          <td>
              Tab
            </td>
          <td>
              $c TAB $d
            </td>
          <td>
              Concatenates strings $c and $d into a single string separated by tab.
            
            <b>Note</b>: such a string can be decomposed with getField()
            </td>
        </tr>
        <tr>
          <td>
              SPC
            </td>
          <td>
              Space
            </td>
          <td>
              $c SPC $d
            </td>
          <td>
              Concatenates strings $c and $d into a single string separated by space.
            
            <b>Note</b>: such a string can be decomposed with getWord()
            </td>
        </tr>
        <tr>
          <td colspan="4" bgcolor="#6699ff"><b>Miscellaneous</b>
            </td>
        </tr>
        <tr>
          <td>
              ? :
            </td>
          <td>
              Conditional
            </td>
          <td>
              x ? y : z
            </td>
          <td>
              Evaluates to y if x equal to 1, else evaluates to z.
            </td>
        </tr>
        <tr>
          <td>
              []
            </td>
          <td>
              Array element
            </td>
          <td>
              $a[5]
            </td>
          <td>
              Synonymous with $a5.
            </td>
        </tr>
        <tr>
          <td>
              ( )
            </td>
          <td>
              Delimiting,<br />
              <br />
              Grouping
            </td>
          <td>
              t2dGetMin(%a, %b)<br />
              if ( $a == $b )<br />
              ($a+$b)*($c-$d)
            </td>
          <td>
              Argument list for function call
            
            
              Used with <i>if</i>, <i>for</i>, <i>while</i>, <i>switch</i> keywords.
            
            
              Control associatively in expressions
            </td>
        </tr>
        <tr>
          <td>
              {}
            </td>
          <td>
              Compound statement<br />
              (Block)
            </td>
          <td>
              if (1) {$a = 1; $b = 2;}
            
            
              function foo() {$a = 1;}
            </td>
          <td>
              Delimit multiple statements
            
            
              optional for <i>if</i>, <i>else</i>, <i>for</i>, <i>while</i>
            
            
              Required for <i>switch</i>, <i>datablock</i>, <i>new</i>, <i>function</i>
            </td>
        </tr>
        <tr>
          <td>
              ,
            </td>
          <td>
              Listing
            </td>
          <td>
              t2dGetMin(%a, %b)<br />
              %M[1,2]
            </td>
          <td>
              Delimiter for arguments
            
            <b>Note</b>: there is no "comma operator", as defined in C/C++; $a = 1, $b = 2; is a parse error
            </td>
        </tr>
        <tr>
          <td>
              ::
            </td>
          <td>
              Namespace
            </td>
          <td>
              Item::onCollision()
            </td>
          <td>
              This definition of the onCollision() function is in the Item namespace.
            </td>
        </tr>
        <tr>
          <td>
              .
            </td>
          <td>
              Field/Method selection
            </td>
          <td>
              %obj.field <br />
               %obj.method()
            </td>
          <td>
              Select a console method or field
            </td>
        </tr>
        <tr>
          <td>
              //
            </td>
          <td>
              Single-line comment
            </td>
          <td>
              // This is a  comment
            </td>
          <td>
              Used to comment out a single line of code.
            </td>
        </tr>
        <tr>
          <td>
              /* */
            </td>
          <td>
              Multi-line comment
            </td>
          <td>
              /*This is a a<br />
              multi-line<br />
              comment*/<br />
            </td>
          <td>
              Used to comment out multiple consecutive lines.<br />
              /* opens the comment, and */ closes it.
            </td>
        </tr>
      </tbody>
    </table><br /><br />
    <table border="0" cellpadding="0" cellspacing="0" width="700">
      <tbody>
        <tr>
          <td width="700"><a name="Keywords" id="Keywords"></a>
            <h2> <span class="mw-headline">Keywords</span></h2>
            <p><b>Note:</b> Although keywords are not reserved, it is considered bad practice to use variables that have the same spelling as a keyword. </p><br /></td>
        </tr>
      </tbody>
    </table>
    <table border="1" cellpadding="0" cellspacing="0" width="700">
      <tbody>
        <tr>
          <td bgcolor="#6699ff" width="700"><b> <a name="break" id="break"></a>
            <h3> <span class="mw-headline">break</span></h3>
            </b></td>
        </tr>
        <tr>
          <td align="left" bgcolor="#eeeeee" valign="top" width="700"><p><b>Purpose</b> Use <i>break</i> to exit the innermost while loop.  
              Unlike C and C++, <i>break</i> has no effect in a switch or switch$ statement.<br />
            </p>
            <pre>%count = 0;

while( 1 ) {
echo(%count++); if (%count > 2) break; }

See Also
for and while


case

Purpose Used to label cases in a switch or switch$ statement.
Syntax
case expression :(colon character)
The argument of the enclosing switch or switch$ statement is evaluated and compared to the value of expression using operator == or $=, respectively.
If true, execute the statements up to the next case statement and exit the switch.
If false, skip to the next case statement.
See Also
switch and switch$


continue

Purpose Causes the script to skip to the next iteration of the for or while loop in which it appears; 

%count = 0;
while(%count++ < 8)
{
if ( %count > 2 )
continue; // echo will not be executed
echo(%count);
}

See Also
for and while


datablock

Purpose The datablock keyword is used to declare a new datablock. A datablock object is used in the declaration and initialization of a special set of classes that take a datablock(s). Datablocks are created on the server and ghosted to clients.

Syntax

datablock DatablockClass ( NewDatablockName : InheritDatablock )
{
className = "SomeName";

DataBlockBody
};
  • DatablockClass - A predefined engine class which inherits from SimDataBlock or one of it's children.
  • NewDatablockName - The name for this datablock. Must be unique.
  • InheritDatablock - Previously defined datablock to inherit (copy) DataBlockBody values from. Optional.
  • className - This is a special field which can be initialized with the name of a previously defined [in Torque Script] datablock. In effect, this inserts the "SomeName" name into the namespace calling sequence between NewDatablockName and DatablockClass. For some datablock classes, className can be a non-datablock name, but it isn't guaranteed to work for all calling sequences or classes.
  • DataBlockBody - Fields and the values that will be assigned for this datablock.
datablock SimDataBlock( myDataBlock )
{
newField = "Hello";
newField2 = 10;
};

Here we have declared a new SimDataBlock datablock named myDataBlock. Additionally, we have given it a new field named newField, initialized to "Hello" and a new field named newField2 initialized to 10. The namespace calling sequence for this datablock is: myDataBlock -> SimDataBlock

datablock SimDataBlock( mySecondDataBlock : myDataBlock)
{
className = "myDataBlock";
newField2 = 15;
};

Here we have declared a new SimDataBlock datablock named mySecondDataBlock that derives from myDataBlock. Because it is deriving from a prior datablock, it will copy any fields that were declared and/or initialized in the parent datablock. However, because we are re-declaring the field newField2. The new initialization value is taken in preference to the copied value, meaning that newField has the value "Hello" and newField2 has the value 15. Finally, we have defined className as myDataBlock, making the namespace calling sequence for mySecondDataBlock:

mySecondDataBlock -> myDataBlock -> SimDataBlock

See Also
new and parent


default

Purpose The default case in a switch or switch$ statement, i.e., the case that is executed if no other cases are chosen.
Syntax
default :(colon character)
Note: The default keyword must be listed after all case keywords. It is a syntax error to place it before subsequent case keywords.

See Also
switch and switch$


else

Purpose The else keyword is used with the if keyword to control the flow of a script. The general form of the well known if-then-else construct is as follows:

if (expression)
{
statement(s);
}
else
{
alternate statement(s);
}

Where the alternate statement(s) are executed if the expression evaluates to 0.

See (link to if) example.

See Also
if reference


FALSE

Purpose The false keyword is used for boolean comparison and evaluates to 0.

if( false == 0 )
{
echo( "false evaluates to" SPC 0 );
}

See Also
if and true


for

Purpose A looping construct, whose general form is:
for ( statement0 ; expression1 ; statement2 )
{
statements(s)
}
where,

  • statement0 - Usually an assignment.
  • expression1 - An expression, usually of the form: variable compare op value
  • statement2 - Usually an assignment.

Execution

  1. To begin, statement0 is executed.
  2. Then, expression1 is tested. If false, end the for loop.
  3. Execute statement(s), then execute statement2.
  4. Continue with Step 2 and 3.

Notes

  • All three of statement0, expression1, and statement2 are required. If you need statement0 or statement2 to be empty, just insert a 0.
  • Composite expressions of the form ( sub_expression0 , sub_expression1 , sub_expressionN ) are illegal.

Example 1 

for( %val = 0 ; %val <  3 ; %val++ )
{
echo( %val );
}

Example 2 Empty statement0 and statement2

%value = 0;
for( 0 ; %val < 3 ; 0 )
{
echo( %val );
 %val ++;
}

Example 3 Illegal sub-expressions (would produce an error while compiling): 

%val = 0;
for( %val0 = 0 , %val1 = 3 ; %val0 <  3 ; %val0++, %val1-- )

{
echo( %val0 );
echo( %val1 );
}

See Also
break, continue, and while


function

Purpose The function keyword is used to define a new console function or method. Unlike a language like C or C++, functions are not declared in one place and defined in another, but defined only. Redeclaring a named function later in script over-rides the previous definition. The format of a function takes one of two forms:

Function definition 

function func_name( [arg0] , ... , [argn] )
{
statements;
[return val;]
}
  • func_name - Name by which this function will be subsequently called.
  • [arg0] , ... , [argn] - Optional arguments.
  • statements - Any number of statements may be contained within the body of the function.
  • val - Functions may optionally return a value;


Console method definition 

function namespace::func_name( %this, [arg0] , ... , [argn] )
{
statements;
[return val;]
}
  • namespace - The name of a datablock or object classname.
  • :: - Namespace resolution operator.
  • %this - The first argument of a console method is always the handle to the object which is calling the method.


Defining a function 

function test( %val )
{
echo( "test(" SPC %val SPC ")" );

if( 10 == %val ) return true;


return false;
}

Defining a console method 

function Item::test( %this , %val )
{
echo( "Item::test(" SPC %this SPC "," SPC %val SPC ")" );

if( 10 = %val ) return true;


return false;
}

Instantiating a console object 

%obj = new Item(MyItem)
{
// ..
};

Invoking a console method 

Item::test( %obj, 10 ) ;
%obj.test( 10 ) ;
MyItem.test( 10 ) ;
%obj.getName().test( 10 ) ;
  • In the first example of invoking, it should be clear that we have simply defined a function in the Item, namespace and are now invoking it in the normal way.
  • In the second example, which is equivalent to the first, the syntax used automatically passes the object's handle as the first argument to the function.
  • In the third example, we take advantage of the ability of the .(dot) operator to use the name of an object in lieu of its handle.
  • The fourth example illustrates a different way of doing the same thing, this time using the SimObject::getName() function, defined for every console class.


if

PurposeThe if keyword is used with or without the else keyword to control the flow of a script. The general form of the well known if-then-else construct is as follows,

if (expression)
{
statement(s);
}
else
{
alternate statement(s);
}

Where the statement(s) are executed if the expression evaluates to a non-zero value.

if(0)
{
echo( "hello" );
}
else
{
echo( "goodbye" );
}

if(5)
{
echo( "hello" );
}
else
{
echo( "goodbye" );
}

See Also
else


new

Purpose The new keyword is used to instantiate (create) a new copy of a conobject. A conobject is:

  • an engine class available in the console (Item(), Player(), etc.), or
  • a datablock (derived or otherwise).
// New non-datablock (using) object
%obj = new ScriptObject();

//New datablock (using) object
datablock ItemData( GoldCoin )
{
...
};


%coin = new Item( myGoldCoin )
{
// ...
datablock = GoldCoin;
};

See Also
datablock


package

Purpose The package keyword tells the console that the subsequent block of code is to be declared but not loaded. Packages provide dynamic function-polymorphism in TorqueScript. In short, a function defined in a package will over-ride the prior definition of a same named function when the is activated. When the package is subsequently de-activated, the previous definition of any overridden functions will be re-asserted.

A package will have the following syntax: 

package package_name
{
function function_definition0()
{
[statements;]
}
...
function function_definitionN()
{
[statements;]
}
};

Things to know:

  • The same function can be defined in multiple packages.
  • Only functions can be packaged.
  • Datablocks cannot be packaged.
  • Packages 'stack' meaning that deactivating packages activated prior to the currently active (s) will deactivate all packages activated prior to the being deactivated (see example below).
  • Functions activate and deactivate packages.

Activating
In order to use the functions in a package, the package must be activated:

ActivatePackage(_name);

Deactivating
Subsequently a package can be deactivated:

DeactivatePackage(_name);

Usage
First, define a function and then two packages, each of which provides an alternative definition by the same name. 

function testFunction()
{
echo( "testFunction() - unpackaged." );
}

package MyPackage0
{
function testFunction()
{
echo( "testFunction() - MyPackage0." );
}
};


MyPackage1
{
function testFunction()
{
echo( "testFunction() - MyPackage1." );
}
};

Next, invoke that function under three different conditions. The following is as if run in the console, with our input set off by '==>' 

==> testFunction();
testFunction() - unpackaged.

==> ActivatePackage( MyPackage0 );


==> testFunction();
testFunction() - MyPackage0.


==> ActivatePackage( MyPackage1 );


==> testFunction();
testFunction() - MyPackage1.


==> DeactivatePackage( MyPackage0 );  // MyPackage1 is automatically deactivated.


==> testFunction();
testFunction() - unpackaged.

See Also
function and Parent


parent

Purpose The Parent keyword is used with the namespace operator (::) to reference the previous definition of a function that has been over-ridden either through inheritance or packaging. The Parent keyword can only be used within specific contexts:

  • From within a consoleMethod, or
  • from within a packaged function.
// Calling an inherited parent
datablock ItemData( GoldCoin )
{
...
};

function ItemData::onAdd( %db, %obj )
{
echo( "ItemData::onAdd()" );
}


function GoldCoin::onAdd( %db, %obj )
{
Parent::onAdd( %db, %obj );


echo( "GoldCoin::onAdd()" );
}


// Calling a  parent
function testFunction()
{
echo( "testFunction() - unpackaged." );
}


MyPackage0
{
function testFunction()
{
Parent::testFunction();
echo( "testFunction() - MyPackage0." );
}
};


...


testFunction();
// prints => testFunction() - unpackaged.


ActivatePackage( MyPackage0 );


testFunction();
// prints => testFunction() - unpackaged.
// prints => testFunction() - MyPackage0.

See Also
datablock and function


return

Purpose The return keyword is used to return a value from a function

function equal_to( %arg0 , %arg1 )
{
return ( %arg0 == %arg1 );
}

echo( equal_to(10,11) ); // prints 0


echo( equal_to(11,11) ); // prints 1

See Also
function


switch

Purpose The switch keyword is used to control the flow of a script.
It is like the switch$ statement, but intended for numeric comparisons instead of string comparisons.

The general form of a switch statement is as follows:

switch ( numeric expression )
{
case value0:
statement(s);
break;
case value1:
statement(s);
break;
. . .
case valueN:
statement(s);
break;
default:
statement(s);
}

Execution

  1. First, numeric expression is evaluated and compared with value0.
  2. If the result is true, the statement(s) associated with that case are executed, and the switch statement is exited.
  3. If not, control passes to the next case statement, where numeric expression is again evaluated, this time being compared to value1.
  4. If control falls through to the default case, its statements will be executed.

switch is intended for use ONLY with numerical comparisons (==). If string comparisons are desired, use switch$.
Note: Unlike C/C++, the break statement is not for use in switch. TorqueScript will only execute matching cases and will NOT automatically execute all subsequent cases. This is proven in the example below.

%tmp = 1;

switch( %tmp  )
{
case 0:
echo( 0 );
case 1:
echo( 1 );
default:
echo( "proof" );
}

See Also
case, default, and switch


switch$

Purpose The switch$ keyword is used to control the flow of a script.
It is like the switch statement, but intended for string comparisons instead of numeric comparisons.

The general form of the switch$ statement is:

switch$ ( string expression )
{
case string_value0:
statement(s);

case string_value1:
statement(s);
. . .
case string_valueN:
statement(s);


default:
statement(s);
}

Execution

  1. First, string expression is evaluated and compared with value0.
  2. If the result is true, the statement(s) associated with that case are executed, and the switch$ statement is exited.
  3. If not, control passes to the next case statement, where string expression is again evaluated, this time being compared to value1.
  4. If control falls through to the default case, its statements will be executed.

switch$ is intended for use ONLY with string comparisons ($=). If numeric comparisons are desired, use switch.
Note: Unlike C/C++, the break statement has no role in switch$, see switch.
See Also
case, default, switch, and switch$


TRUE

Purpose The true keyword is used for boolean comparison and evaluates to 1.

if(true == 1)
{
echo( "true evaluates to" SPC 1 );
}

See Also
if and false


while

Purpose The while keyword is a looping construct whose general form is:

while (expression)
{
statements(s);
}

Where expression is usually of the form: variable compare op value, and the loop continues to execute statement(s) until expression evaluates to false (i.e. 0).

%val=5;

while( %val )
{
echo( %val-- );
}

See Also
break, continue, and for
 
Home Back to Top
⚠️ **GitHub.com Fallback** ⚠️