홈 탐색 도움말
로그인
TorqueEngine
/
Torque2D
의 미러 https://github.com/TorqueGameEngines/Torque2D.git
2
0
포크 0
파일 이슈 0 위키
트리: 9aa0867d16
브랜치 태그
Torque2D
/
TorqueScriptDocs
/
html
/
md_syntax_ScriptPage.html

md_syntax_ScriptPage.html 64 KB
히스토리 Raw

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685 
  1. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
    2. 

  2. <html xmlns="http://www.w3.org/1999/xhtml">
    3. 

  3. <head>
    4. 

  4. <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
    5. 

  5. <meta http-equiv="X-UA-Compatible" content="IE=9"/>
    6. 

  6. <meta name="generator" content="Doxygen 1.8.3.1"/>
    7. 

  7. <title>TorqueScript Reference: TorqueScript Syntax</title>
    8. 

  8. <link href="tabs.css" rel="stylesheet" type="text/css"/>
    9. 

  9. <script type="text/javascript" src="jquery.js"></script>
    10. 

  10. <script type="text/javascript" src="dynsections.js"></script>
    11. 

  11. <link href="doxygen.css" rel="stylesheet" type="text/css" />
    12. 

  12. <link href="t2d-stylesheet-extra.css" rel="stylesheet" type="text/css"/>
    13. 

  13. </head>
    14. 

  14. <body>
    15. 

  15. <div id="top"><!-- do not remove this div, it is closed by doxygen! -->
    16. 

  16. <div id="titlearea">
    17. 

  17. <table cellspacing="0" cellpadding="0">
    18. 

  18.  <tbody>
    19. 

  19.  <tr style="height: 56px;">
    20. 

  20.   <td style="padding-left: 0.5em;">
    21. 

  21.    <div id="projectname">TorqueScript Reference
    22. 

  22.    </div>
    23. 

  23.   </td>
    24. 

  24.  </tr>
    25. 

  25.  </tbody>
    26. 

  26. </table>
    27. 

  27. </div>
    28. 

  28. <!-- end header part -->
    29. 

  29. <!-- Generated by Doxygen 1.8.3.1 -->
    30. 

  30.   <div id="navrow1" class="tabs">
    31. 

  31.     <ul class="tablist">
    32. 

  32.       <li><a href="index.html"><span>Main&#160;Page</span></a></li>
    33. 

  33.       <li class="current"><a href="pages.html"><span>Related&#160;Pages</span></a></li>
    34. 

  34.       <li><a href="modules.html"><span>Modules</span></a></li>
    35. 

  35.       <li><a href="annotated.html"><span>Classes</span></a></li>
    36. 

  36.     </ul>
    37. 

  37.   </div>
    38. 

  38. </div><!-- top -->
    39. 

  39. <div class="header">
    40. 

  40.   <div class="headertitle">
    41. 

  41. <div class="title">TorqueScript Syntax </div>  </div>
    42. 

  42. </div><!--header-->
    43. 

  43. <div class="contents">
    44. 

  44. <div class="textblock"><h2>Main Rules</h2>
    45. 

  45. <p>Like other languages, TorqueScript has certain syntactical rules you need to follow. The language is very forgiving, easy to debug, and is not as strict as a low level language like C++. Observe the following line in a script:</p>
    46. 

  46. <div class="fragment"><div class="line"><span class="comment">// Create test variable with a temporary variable</span></div>
    47. 

  47. <div class="line">%testVariable = 3;</div>
    48. 

  48. </div><!-- fragment --><p> The three most simple rules obeyed in the above code are:</p>
    49. 

  49. <ol type="1">
    50. 

  50. <li>Ending a line with a semi-colon (;)</li>
    51. 

  51. <li>Proper use of white space.</li>
    52. 

  52. <li>Commenting</li>
    53. 

  53. </ol>
    54. 

  54. <p>The engine will parse code line by line, stopping whenever it reaches a semi-colon. This is referred to as a statement termination, common to other programming languages such as C++, Javascript, etc. The following code will produce an error that may cause your entire script to fail:</p>
    55. 

  55. <div class="fragment"><div class="line">%testVariable = 3</div>
    56. 

  56. <div class="line">%anotherVariable = 4;</div>
    57. 

  57. </div><!-- fragment --><p>To the human eye, you are able to discern two separate lines of code with different actions. Here is how the script compiler will read it:</p>
    58. 

  58. <div class="fragment"><div class="line">%testVariable = 3%anotherVariable = 4;</div>
    59. 

  59. </div><!-- fragment --><p>This is obviously not what the original code was meant to do. There are exemptions to this rule, but they come into play when multiple lines of code are supposed to work together for a single action:</p>
    60. 

  60. <div class="fragment"><div class="line"><span class="keywordflow">if</span>(%testVariable == 4)</div>
    61. 

  61. <div class="line">  <a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>(<span class="stringliteral">&quot;Variable equals 4&quot;</span>);</div>
    62. 

  62. </div><!-- fragment --><p>We have not covered conditional operators or echo commands yet, but you should notice that the first line does not have a semi-colon. The easiest explanation is that the code is telling the compiler: "Read the first line, do the second line if we meet the requirements." In other words, perform operations between semi-colons. Complex operations require multiple lines of code working together.</p>
    63. 

  63. <p>The second rule, proper use of whitespace, is just as easy to remember. Whitespace refers to how your script code is separated between operations. Let's look at the first example again:</p>
    64. 

  64. <div class="fragment"><div class="line">%testVariable = 3;</div>
    65. 

  65. </div><!-- fragment --><p>The code is storing a value (3) in a local variable (<code>%testVariable</code>). It is doing so by using a common mathematical operator, the equal sign. TorqueScript recognizes the equal sign and performs the action just as expected. It does not care if there are spaces in the operation:</p>
    66. 

  66. <div class="fragment"><div class="line">%testVariable=3;</div>
    67. 

  67. </div><!-- fragment --><p>The above code works just as well, even without the spaces between the variable, the equal sign, and the 3. The whitespace rule makes a lot more sense when combined with the semi-colon rule and multiple lines of code working together. The following will compile and run without error:</p>
    68. 

  68. <div class="fragment"><div class="line"><span class="keywordflow">if</span>(%testVariable == 4) <a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>(<span class="stringliteral">&quot;Variable equals 4&quot;</span>);</div>
    69. 

  69. </div><!-- fragment --><h2>Comments</h2>
    70. 

  70. <p>The last rule is optional, but should be used as often as possible if you want to create clean code. Whenever you write code, you should try to use comments. Comments are a way for you to leave notes in code which are not compiled into the game. The compiler will essentially skip over these lines.</p>
    71. 

  71. <p>There are two different comment syntax styles. The first one uses the two slashes, <code>//</code>. This is used for single line comments:</p>
    72. 

  72. <p>Example: </p>
    73. 

  73. <div class="fragment"><div class="line"><span class="comment">// This comment line will be ignored</span></div>
    74. 

  74. <div class="line"><span class="comment">// This second line will also be ignored</span></div>
    75. 

  75. <div class="line">%testVariable = 3;</div>
    76. 

  76. <div class="line"><span class="comment">// This third line will also be ignored</span></div>
    77. 

  77. </div><!-- fragment --><p>In the last example, the only line of code that will be executed has to do with <code>%testVariable</code>. If you need to comment large chunks of code, or leave a very detailed message, you can use the <code>/*comment*/</code> syntax. The <code>/*</code> starts the commenting, the <code>*/</code> ends the commenting, and anything in between will be considered a comment.</p>
    78. 

  78. <p>Example:</p>
    79. 

  79. <div class="fragment"><div class="line"><span class="comment">/*</span></div>
    80. 

  80. <div class="line"><span class="comment">While attending school, an instructor taught a mantra I still use:</span></div>
    81. 

  81. <div class="line"><span class="comment"></span></div>
    82. 

  82. <div class="line"><span class="comment">&quot;Read. Read Code. Code.&quot;</span></div>
    83. 

  83. <div class="line"><span class="comment"></span></div>
    84. 

  84. <div class="line"><span class="comment">Applying this to Torque 2D development is easy: </span></div>
    85. 

  85. <div class="line"><span class="comment"></span></div>
    86. 

  86. <div class="line"><span class="comment">READ the documentation first. </span></div>
    87. 

  87. <div class="line"><span class="comment"></span></div>
    88. 

  88. <div class="line"><span class="comment">READ CODE written by other Torque developers.</span></div>
    89. 

  89. <div class="line"><span class="comment"></span></div>
    90. 

  90. <div class="line"><span class="comment">CODE your own prototypes based on what you have learned.</span></div>
    91. 

  91. <div class="line"><span class="comment">*/</span></div>
    92. 

  92. </div><!-- fragment --><p>As you can see, the comment makes full use of whitespace and multiple lines. While it is important to comment what the code does, you can also use this to temporarily remove unwanted code until a better solution is found:</p>
    93. 

  93. <p>Example:</p>
    94. 

  94. <div class="fragment"><div class="line"><span class="comment">// Why are you using multiple if statements. Why not use a switch$?</span></div>
    95. 

  95. <div class="line"><span class="comment">/*</span></div>
    96. 

  96. <div class="line"><span class="comment">if(%testVariable == &quot;Mich&quot;)</span></div>
    97. 

  97. <div class="line"><span class="comment">  echo(&quot;User name: &quot;, %testVariable);</span></div>
    98. 

  98. <div class="line"><span class="comment"></span></div>
    99. 

  99. <div class="line"><span class="comment">if(%testVariable == &quot;Heather&quot;)</span></div>
    100. 

  100. <div class="line"><span class="comment">  echo(&quot;User Name: &quot;, %testVariable);</span></div>
    101. 

  101. <div class="line"><span class="comment"></span></div>
    102. 

  102. <div class="line"><span class="comment">if(%testVariable == &quot;Nikki&quot;)</span></div>
    103. 

  103. <div class="line"><span class="comment">  echo(&quot;User Name: &quot;, %testVariable);</span></div>
    104. 

  104. <div class="line"><span class="comment">*/</span></div>
    105. 

  105. </div><!-- fragment --><h1>Variables</h1>
    106. 

  106. <h2>Usage</h2>
    107. 

  107. <p>Now that you know the two most basic rules of writing code in TorqueScript, this is the best time to learn about variables. A variable is a letter, word, or phrase linked to a value stored in your game's memory and used during operations. Creating a variable is a one line process. The following code creates a variable by naming it and assigning a value:</p>
    108. 

  108. <div class="fragment"><div class="line">%localVariable = 3;</div>
    109. 

  109. </div><!-- fragment --><p>You can assign any type value to the variable you want. This is referred to as a language being type-insensitive. TorqueScript does not care (insensitive) what you put in a variable, even after you have created it. The following code is completely valid:</p>
    110. 

  110. <div class="fragment"><div class="line">%localVariable = 27;</div>
    111. 

  111. <div class="line">%localVariable = <span class="stringliteral">&quot;Heather&quot;</span>;</div>
    112. 

  112. <div class="line">%localVariable = <span class="stringliteral">&quot;7 7 7&quot;</span>;</div>
    113. 

  113. </div><!-- fragment --><p>The main purpose of the code is to show that TorqueScript treats all data types the same way. It will interpret and convert the values internally, so you do not have to worry about typecasting. That may seem a little confusing. After all, when would you want a variable that can store a number, a string, or a vector?</p>
    114. 

  114. <p>You will rarely need to, which is why you want to start practicing good programming habits. An important practice is proper variable naming. The following code will make a lot more sense, considering how the variables are named:</p>
    115. 

  115. <div class="fragment"><div class="line">%userName = <span class="stringliteral">&quot;Heather&quot;</span>;</div>
    116. 

  116. <div class="line">%userAge = 27;</div>
    117. 

  117. <div class="line">%userScores = <span class="stringliteral">&quot;7 7 7&quot;</span>;</div>
    118. 

  118. </div><!-- fragment --><p>Earlier, I mentioned that TorqueScript is more forgiving than low level programming languages. While it expects you to obey the basic syntax rules, it will allow you to get away with small mistakes or inconsistency. The best example is variable case sensitivity. At some point in school you learned the difference between upper case and lower case letters.</p>
    119. 

  119. <p>With variables, TorqueScript is not case sensitive. You can create a variable and refer to it during operations without adhering to case rules:</p>
    120. 

  120. <div class="fragment"><div class="line">%userName = <span class="stringliteral">&quot;Heather&quot;</span>;</div>
    121. 

  121. <div class="line"><a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>(%Username);</div>
    122. 

  122. </div><!-- fragment --><p>In the above code, <code>%userName</code> and <code>%Username</code> are the same variable, even though they are using different capitalization. You should still try to remain consistent in your variable naming and usage, but you will not be punished if you slip up occasionally.</p>
    123. 

  123. <h2>Variable Types</h2>
    124. 

  124. <p>There are two types of variables you can declare and use in TorqueScript: local and global. Both are created and referenced similarly:</p>
    125. 

  125. <div class="fragment"><div class="line">%localVariable = 1;</div>
    126. 

  126. <div class="line">$globalVariable = 2;</div>
    127. 

  127. </div><!-- fragment --><p>As you can see, local variable names are preceded by the percent sign <code>(%%)</code>. Global variables are preceded by the dollar sign <code>($)</code>. Both types can be used in the same manner: operations, functions, equations, etc. The main difference has to do with how they are scoped.</p>
    128. 

  128. <p>In programming, scoping refers to where in memory a variable exists and its life. A local variable is meant to only exist in specific blocks of code, and its value is discarded when you leave that block. Global variables are meant to exist and hold their value during your entire programs execution. Look at the following code to see an example of a local variable:</p>
    129. 

  129. <div class="fragment"><div class="line"><span class="keyword">function</span> test()</div>
    130. 

  130. <div class="line">{</div>
    131. 

  131. <div class="line">   %userName = <span class="stringliteral">&quot;Heather&quot;</span>;</div>
    132. 

  132. <div class="line">   <a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>(%userName);</div>
    133. 

  133. <div class="line">}</div>
    134. 

  134. </div><!-- fragment --><p>We will cover functions a little later, but you should know that functions are blocks of code that only execute when you call them by name. This means the variable, <code>%userName</code>, does not exist until the test() function is called. When the function has finished all of its logic, the <code>%userName</code> variable will no longer exist. If you were to try to access the %userName variable outside of the function, you will get nothing.</p>
    135. 

  135. <p>Most variables you will work with are local, but you will eventually want a variables that last for your entire game. These are extremely important values used throughout the project. This is when global variables become useful. For the most part, you can declare global variables whenever you want:</p>
    136. 

  136. <div class="fragment"><div class="line">$PlayerName = <span class="stringliteral">&quot;Heather&quot;</span>;</div>
    137. 

  137. <div class="line"></div>
    138. 

  138. <div class="line"><span class="keyword">function</span> printPlayerName()</div>
    139. 

  139. <div class="line">{</div>
    140. 

  140. <div class="line">   <a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>($PlayerName);</div>
    141. 

  141. <div class="line">}</div>
    142. 

  142. <div class="line"></div>
    143. 

  143. <div class="line"><span class="keyword">function</span> setPlayerName()</div>
    144. 

  144. <div class="line">{</div>
    145. 

  145. <div class="line">   $PlayerName = <span class="stringliteral">&quot;Nikki&quot;</span>;</div>
    146. 

  146. <div class="line">}</div>
    147. 

  147. </div><!-- fragment --><p>The above code makes full use of a global variable that holds a player's name. The first declaration of the variable happens outside of the functions, written anywhere in your script. Because it is global, you can reference it in other locations, including separate script files. Once declared, your game will hold on to the variable until shutdown.</p>
    148. 

  148. <h2>Data Types</h2>
    149. 

  149. <p>TorqueScript implicitly supports several variable data-types: numbers, strings, booleans, and arrays and vectors. If you wish to test the various data types, you can use the echo(...) command. For example:</p>
    150. 

  150. <div class="fragment"><div class="line">%meaningOfLife = 42;</div>
    151. 

  151. <div class="line"><a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>(%meaningOfLife);</div>
    152. 

  152. <div class="line"></div>
    153. 

  153. <div class="line">$name = <span class="stringliteral">&quot;Heather&quot;</span>;</div>
    154. 

  154. <div class="line"><a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>($name);</div>
    155. 

  155. </div><!-- fragment --><p>The echo will post the results in the console, which can be accessed by pressing the ctrl+tilde key (<code>~</code>) while in game.</p>
    156. 

  156. <h2>Numbers</h2>
    157. 

  157. <p>TorqueScript handles standard numeric types</p>
    158. 

  158. <div class="fragment"><div class="line">123     (<a class="code" href="group__TorqueScriptTypes.html#ga85be84504cf913ad90b8ee4f264195d3">Integer</a>)</div>
    159. 

  159. <div class="line">1.234   (floating point)</div>
    160. 

  160. <div class="line">1234e-3 (scientific notation)</div>
    161. 

  161. <div class="line">0xc001  (hexadecimal)</div>
    162. 

  162. </div><!-- fragment --><h2>Strings</h2>
    163. 

  163. <p>Text, such as names or phrases, are supported as strings. Numbers can also be stored in string format. Standard strings are stored in double-quotes.</p>
    164. 

  164. <div class="fragment"><div class="line"><span class="stringliteral">&quot;abcd&quot;</span></div>
    165. 

  165. </div><!-- fragment --><p>Example:</p>
    166. 

  166. <div class="fragment"><div class="line">$UserName = <span class="stringliteral">&quot;Heather&quot;</span>;</div>
    167. 

  167. </div><!-- fragment --><p>Strings with single quotes are called "tagged strings."</p>
    168. 

  168. <div class="fragment"><div class="line"><span class="stringliteral">&#39;abcd&#39;</span>  (tagged string)</div>
    169. 

  169. </div><!-- fragment --><p>Tagged strings are special in that they contain string data, but also have a special numeric tag associated with them. Tagged strings are used for sending string data across a network. The value of a tagged string is only sent once, regardless of how many times you actually do the sending.</p>
    170. 

  170. <p>On subsequent sends, only the tag value is sent. Tagged values must be de-tagged when printing. You will not need to use a tagged string often unless you are in need of sending strings across a network often, like a chat system.</p>
    171. 

  171. <p>Example:</p>
    172. 

  172. <div class="fragment"><div class="line">$a = <span class="stringliteral">&#39;This is a tagged string&#39;</span>;</div>
    173. 

  173. <div class="line"><a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>(<span class="stringliteral">&quot;  Tagged string: &quot;</span>, $a);</div>
    174. 

  174. <div class="line"><a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>(<span class="stringliteral">&quot;Detagged string: &quot;</span>, detag(<span class="stringliteral">&#39;$a&#39;</span>));</div>
    175. 

  175. </div><!-- fragment --><p>The output will be similar to this:</p>
    176. 

  176. <div class="fragment"><div class="line">24</div>
    177. 

  177. <div class="line">___</div>
    178. 

  178. </div><!-- fragment --><p>The second echo will be blank unless the string has been passed to you over a network.</p>
    179. 

  179. <h2>String Operators</h2>
    180. 

  180. <p>There are special values you can use to concatenate strings and variables. Concatenation refers to the joining of multiple values into a single variable. The following is the basic syntax:</p>
    181. 

  181. <div class="fragment"><div class="line"><span class="stringliteral">&quot;string 1&quot;</span> operation <span class="stringliteral">&quot;string 2&quot;</span></div>
    182. 

  182. </div><!-- fragment --><p>You can use string operators similarly to how you use mathematical operators (=, +, -, *). You have four operators at your disposal:</p>
    183. 

  183. <p><b>String Operators</b></p>
    184. 

  184. <table class="doxtable">
    185. 

  185. <tr>
    186. 

  186. <th>Operator </th><th align="center">Name </th><th align="center">Example </th><th>Explanation </th></tr>
    187. 

  187. <tr>
    188. 

  188. <td>@ </td><td align="center">String concatenation </td><td align="center"><code>$c @ $d</code> </td><td>Concatenates strings $c and $d into a single string. Numeric literals/variables convert to strings. </td></tr>
    189. 

  189. <tr>
    190. 

  190. <td>NL </td><td align="center">New Line </td><td align="center"><code>$c NL $d</code> </td><td>Concatenates strings $c and $d into a single string separated by new-line. </td></tr>
    191. 

  191. <tr>
    192. 

  192. <td>TAB </td><td align="center">Tab </td><td align="center"><code>$c TAB $d</code> </td><td>Concatenates strings $c and $d into a single string separated by tab. </td></tr>
    193. 

  193. <tr>
    194. 

  194. <td>SPC </td><td align="center">Space </td><td align="center"><code>$c SPC $d</code> </td><td>Concatenates strings $c and $d into a single string separated by space. Note: such a string can be decomposed with <a class="el" href="group__FieldManipulatorFunctions.html#gab9848b8f9ac4309659e4412700fa969b">getWord()</a> </td></tr>
    195. 

  195. </table>
    196. 

  196. <p>The <code>@</code> symbol will concatenate two strings together exactly how you specify, without adding any additional whitespace:</p>
    197. 

  197. <p>Note: Do not type in OUTPUT: ___. This is placed in the sample code to show you what the console would display</p>
    198. 

  198. <p>Example: </p>
    199. 

  199. <div class="fragment"><div class="line">%newString = <span class="stringliteral">&quot;Hello&quot;</span> @ <span class="stringliteral">&quot;World&quot;</span>;</div>
    200. 

  200. <div class="line"><a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>(%newString);</div>
    201. 

  201. <div class="line"></div>
    202. 

  202. <div class="line">OUTPUT: HelloWorld</div>
    203. 

  203. </div><!-- fragment --><p>Notice how the two strings are joined without any spaces. If you include whitespace, it will be concatenated along with the values:</p>
    204. 

  204. <p>Example: </p>
    205. 

  205. <div class="fragment"><div class="line">%newString = <span class="stringliteral">&quot;Hello &quot;</span> @ <span class="stringliteral">&quot;World&quot;</span>;</div>
    206. 

  206. <div class="line"><a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>(%newString);</div>
    207. 

  207. <div class="line"></div>
    208. 

  208. <div class="line">OUTPUT: Hello World</div>
    209. 

  209. </div><!-- fragment --><p>String operators work with variables as well:</p>
    210. 

  210. <p>Example: </p>
    211. 

  211. <div class="fragment"><div class="line">%hello = <span class="stringliteral">&quot;Hello &quot;</span>;</div>
    212. 

  212. <div class="line">%world = <span class="stringliteral">&quot;World&quot;</span>;</div>
    213. 

  213. <div class="line"></div>
    214. 

  214. <div class="line"><a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>(%hello @ %world);</div>
    215. 

  215. <div class="line"></div>
    216. 

  216. <div class="line">OUTPUT: Hello World</div>
    217. 

  217. </div><!-- fragment --><p>The rest of the operators will apply whitespace for you, so you do not have to include it in your values:</p>
    218. 

  218. <p>Example: </p>
    219. 

  219. <div class="fragment"><div class="line"><a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>(<span class="stringliteral">&quot;Hello&quot;</span> @ <span class="stringliteral">&quot;World&quot;</span>);</div>
    220. 

  220. <div class="line"><a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>(<span class="stringliteral">&quot;Hello&quot;</span> <a class="code" href="group__StringOperators.html#gab83c1b39c9138720059c3f543a18cd55">TAB</a> <span class="stringliteral">&quot;World&quot;</span>);</div>
    221. 

  221. <div class="line"><a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>(<span class="stringliteral">&quot;Hello&quot;</span> <a class="code" href="group__StringOperators.html#gabf1384363ad54002ac32ee03855e9b39">SPC</a> <span class="stringliteral">&quot;World&quot;</span>);</div>
    222. 

  222. <div class="line"><a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>(<span class="stringliteral">&quot;Hello&quot;</span> <a class="code" href="group__StringOperators.html#ga84608e15108e0361ce63b906480a8181">NL</a> <span class="stringliteral">&quot;World&quot;</span>);</div>
    223. 

  223. <div class="line"></div>
    224. 

  224. <div class="line">OUTPUT:</div>
    225. 

  225. <div class="line">HelloWorld</div>
    226. 

  226. <div class="line">Hello   World</div>
    227. 

  227. <div class="line">Hello World</div>
    228. 

  228. <div class="line">Hello</div>
    229. 

  229. <div class="line">World</div>
    230. 

  230. </div><!-- fragment --><h2>Booleans</h2>
    231. 

  231. <p>Like most programming languages, TorqueScript also supports Booleans. Boolean numbers have only two values- true or false.</p>
    232. 

  232. <pre>
    233. 

  233. true    (1)
    234. 

  234. false   (0)
    235. 

  235. </pre><p>Again, as in many programming languages the constant "true" evaluates to the number 1 in TorqueScript, and the constant "false" evaluates to the number 0. However, non-zero values are also considered true. Think of booleans as "on/off" switches, often used in conditional statements.</p>
    236. 

  236. <p>Example: </p>
    237. 

  237. <div class="fragment"><div class="line">$lightsOn = <span class="keyword">true</span>;</div>
    238. 

  238. <div class="line"></div>
    239. 

  239. <div class="line"><span class="keywordflow">if</span>($lightsOn)</div>
    240. 

  240. <div class="line">  <a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>(<span class="stringliteral">&quot;Lights are turned on&quot;</span>);</div>
    241. 

  241. </div><!-- fragment --><h2>Arrays</h2>
    242. 

  242. <p>Arrays are data structures used to store consecutive values of the same data type.</p>
    243. 

  243. <div class="fragment"><div class="line">$TestArray[n]   (Single-dimension)</div>
    244. 

  244. <div class="line">$TestArray[m,n] (Multidimensional)</div>
    245. 

  245. <div class="line">$TestArray[m_n] (Multidimensional)</div>
    246. 

  246. </div><!-- fragment --><p>If you have a list of similar variables you wish to store together, try using an array to save time and create cleaner code. The syntax displayed above uses the letters 'n' and 'm' to represent where you will input the number of elements in an array. The following example shows code that could benefit from an array:</p>
    247. 

  247. <p>Example: </p>
    248. 

  248. <div class="fragment"><div class="line">$firstUser = <span class="stringliteral">&quot;Heather&quot;</span>;</div>
    249. 

  249. <div class="line">$secondUser = <span class="stringliteral">&quot;Nikki&quot;</span>;</div>
    250. 

  250. <div class="line">$thirdUser = <span class="stringliteral">&quot;Mich&quot;</span>;</div>
    251. 

  251. <div class="line"></div>
    252. 

  252. <div class="line"><a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>($firstUser);</div>
    253. 

  253. <div class="line"><a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>($secondUser);</div>
    254. 

  254. <div class="line"><a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>($thirdUser);</div>
    255. 

  255. </div><!-- fragment --><p>Instead of using a global variable for each user name, we can put those values into a single array:</p>
    256. 

  256. <p>Example: </p>
    257. 

  257. <div class="fragment"><div class="line">$userNames[0] = <span class="stringliteral">&quot;Heather&quot;</span>;</div>
    258. 

  258. <div class="line">$userNames[1] = <span class="stringliteral">&quot;Nikki&quot;</span>;</div>
    259. 

  259. <div class="line">$userNames[2] = <span class="stringliteral">&quot;Mich&quot;</span>;</div>
    260. 

  260. <div class="line"></div>
    261. 

  261. <div class="line"><a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>($userNames[0]);</div>
    262. 

  262. <div class="line"><a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>($userNames[1]);</div>
    263. 

  263. <div class="line"><a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>($userNames[2]);</div>
    264. 

  264. </div><!-- fragment --><p>Now, let's break the code down. Like any other variable declaration, you can create an array by giving it a name and value:</p>
    265. 

  265. <div class="fragment"><div class="line">$userNames[0] = <span class="stringliteral">&quot;Heather&quot;</span>;</div>
    266. 

  266. </div><!-- fragment --><p>What separates an array declaration from a standard variable is the use of brackets []. The number you put between the brackets is called the index. The index will access a specific element in an array, allowing you to view or manipulate the data. All the array values are stored in consecutive order.</p>
    267. 

  267. <p>If you were able to see an array on paper, it would look something like this:</p>
    268. 

  268. <div class="fragment"><div class="line">[0] [1] [2]</div>
    269. 

  269. </div><!-- fragment --><p>In our example, the data looks like this:</p>
    270. 

  270. <div class="fragment"><div class="line">[<span class="stringliteral">&quot;Heather&quot;</span>] [<span class="stringliteral">&quot;Nikki&quot;</span>] [<span class="stringliteral">&quot;Mich&quot;</span>]</div>
    271. 

  271. </div><!-- fragment --><p>Like other programming languages, the index is always a numerical value and the starting index is always 0. Just remember, index 0 is always the first element in an array. As you can see in the above example, we create the array by assigning the first index (0) a string value ("Heather").</p>
    272. 

  272. <p>The next two lines continue filling out the array, progressing through the index consecutively.</p>
    273. 

  273. <div class="fragment"><div class="line">$userNames[1] = <span class="stringliteral">&quot;Nikki&quot;</span>;</div>
    274. 

  274. <div class="line">$userNames[2] = <span class="stringliteral">&quot;Mich&quot;</span>;</div>
    275. 

  275. </div><!-- fragment --><p>The second array element (index 1) is assigned a different string value ("Nikki"), as is the third (index 2). At this point, we still have a single array structure, but it is holding three separate values we can access. Excellent for organization.</p>
    276. 

  276. <p>The last section of code shows how you can access the data that has been stored in the array. Again, you use a numerical index to point to an element in the array. If you want to access the first element, use 0:</p>
    277. 

  277. <div class="fragment"><div class="line"><a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>($userNames[0]);</div>
    278. 

  278. </div><!-- fragment --><p>In a later section, you will learn about looping structures that make using arrays a lot simpler. Before moving on, you should know that an array does not have to be a single, ordered list. TorqueScript also supports multidimensional arrays.</p>
    279. 

  279. <p>An single-dimensional array contains a single row of values. A multidimensional array is essentially an array of arrays, which introduces columns as well. The following is a visual of what a multidimensional looks like with three rows and three columns:</p>
    280. 

  280. <div class="fragment"><div class="line">[x] [x] [x]</div>
    281. 

  281. <div class="line">[x] [x] [x]</div>
    282. 

  282. <div class="line">[x] [x] [x]</div>
    283. 

  283. </div><!-- fragment --><p>Defining this kind of array in TorqueScript is simple. The following creates an array with 3 rows and 3 columns.</p>
    284. 

  284. <p>Example: </p>
    285. 

  285. <div class="fragment"><div class="line">$testArray[0,0] = <span class="stringliteral">&quot;a&quot;</span>;</div>
    286. 

  286. <div class="line">$testArray[0,1] = <span class="stringliteral">&quot;b&quot;</span>;</div>
    287. 

  287. <div class="line">$testArray[0,2] = <span class="stringliteral">&quot;c&quot;</span>;</div>
    288. 

  288. <div class="line"></div>
    289. 

  289. <div class="line">$testArray[1,0] = <span class="stringliteral">&quot;d&quot;</span>;</div>
    290. 

  290. <div class="line">$testArray[1,1] = <span class="stringliteral">&quot;e&quot;</span>;</div>
    291. 

  291. <div class="line">$testArray[1,2] = <span class="stringliteral">&quot;f&quot;</span>;</div>
    292. 

  292. <div class="line"></div>
    293. 

  293. <div class="line">$testArray[2,0] = <span class="stringliteral">&quot;g&quot;</span>;</div>
    294. 

  294. <div class="line">$testArray[2,1] = <span class="stringliteral">&quot;h&quot;</span>;</div>
    295. 

  295. <div class="line">$testArray[2,2] = <span class="stringliteral">&quot;i&quot;</span>;</div>
    296. 

  296. </div><!-- fragment --><p>Notice that we are are now using two indices, both starting at 0 and stopping at 2. We can use these as coordinates to determine which array element we are accessing:</p>
    297. 

  297. <div class="fragment"><div class="line">[0,0] [0,1] [0,2]</div>
    298. 

  298. <div class="line">[1,0] [1,1] [1,2]</div>
    299. 

  299. <div class="line">[2,0] [2,1] [2,2]</div>
    300. 

  300. </div><!-- fragment --><p>In our example, which progresses through the alphabet, you can visualize the data in the same way:</p>
    301. 

  301. <div class="fragment"><div class="line">[a] [b] [c]</div>
    302. 

  302. <div class="line">[d] [e] [f]</div>
    303. 

  303. <div class="line">[g] [h] [i]</div>
    304. 

  304. </div><!-- fragment --><p>The first element <code>[0,0]</code> points to the letter 'a'. The last element <code>[2,2]</code> points to the letter 'i'.</p>
    305. 

  305. <h2>Vectors</h2>
    306. 

  306. <p>"Vectors" are a helpful data-type which are used throughout Torque 2D. For example, many fields on SceneObjects take numeric values in sets of 2 or 3. These are stored as strings and interpreted as "vectors".</p>
    307. 

  307. <div class="fragment"><div class="line"><span class="stringliteral">&quot;1.0 1.0&quot;</span>  (2 element vector)</div>
    308. 

  308. </div><!-- fragment --><p>The most common example of a vector would be a world position. Like most 2D coordinate systems, an object's position is stored as <code>(X Y)</code>. You can use a two element vector to hold this data:</p>
    309. 

  309. <p>Example: </p>
    310. 

  310. <div class="fragment"><div class="line">%position = <span class="stringliteral">&quot;25 32&quot;</span>;</div>
    311. 

  311. </div><!-- fragment --><p>You can separate the values using spaces or tabs (both are acceptable whitespace). Another example is storing color data in a four element vector. The values that make up a color are "Red Blue Green Alpha," which are all numbers. You can create a vector for color using hard numbers, or variables:</p>
    312. 

  312. <p>Example: </p>
    313. 

  313. <div class="fragment"><div class="line">%firstColor = <span class="stringliteral">&quot;100 100 100 1.0&quot;</span>;</div>
    314. 

  314. <div class="line"><a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>(%firstColor);</div>
    315. 

  315. <div class="line"></div>
    316. 

  316. <div class="line">%red = 128;</div>
    317. 

  317. <div class="line">%blue = 255;</div>
    318. 

  318. <div class="line">%green = 64;</div>
    319. 

  319. <div class="line">%alpha = 1.0;</div>
    320. 

  320. <div class="line"></div>
    321. 

  321. <div class="line">%secondColor = %red <a class="code" href="group__StringOperators.html#gabf1384363ad54002ac32ee03855e9b39">SPC</a> %blue <a class="code" href="group__StringOperators.html#gabf1384363ad54002ac32ee03855e9b39">SPC</a> %green <a class="code" href="group__StringOperators.html#gabf1384363ad54002ac32ee03855e9b39">SPC</a> %alpha;</div>
    322. 

  322. <div class="line"><a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>(%secondColor);</div>
    323. 

  323. </div><!-- fragment --><h1>Operators</h1>
    324. 

  324. <p>Operators in TorqueScript behave very similarly to operators in real world math and other programming languages. You should recognize quite a few of these from math classes you took in school, but with small syntactical changes. The rest of this section will explain the syntax and show a brief example, but we will cover these in depth in later guides.</p>
    325. 

  325. <p><b>Arithmetic Operators</b></p>
    326. 

  326. <table class="doxtable">
    327. 

  327. <tr>
    328. 

  328. <th align="center">Operator </th><th align="center">Name </th><th align="center">Example </th><th>Explanation </th></tr>
    329. 

  329. <tr>
    330. 

  330. <td align="center">* </td><td align="center">multiplication </td><td align="center"><code>$a * $b</code> </td><td>Multiply $a and $b. </td></tr>
    331. 

  331. <tr>
    332. 

  332. <td align="center">/ </td><td align="center">division </td><td align="center"><code>$a / $b</code> </td><td>Divide $a by $b. </td></tr>
    333. 

  333. <tr>
    334. 

  334. <td align="center">% </td><td align="center">modulo </td><td align="center"><code>$a % $b</code> </td><td>Remainder of $a divided by $b. </td></tr>
    335. 

  335. <tr>
    336. 

  336. <td align="center">+ </td><td align="center">addition </td><td align="center"><code>$a + $b</code> </td><td>Add $a and $b. </td></tr>
    337. 

  337. <tr>
    338. 

  338. <td align="center">- </td><td align="center">subtraction </td><td align="center"><code>$a - $b</code> </td><td>Subtract $b from $a. </td></tr>
    339. 

  339. <tr>
    340. 

  340. <td align="center">++ </td><td align="center">auto-increment (post-fix only) </td><td align="center">$a++ </td><td>Increment $a. The value of $a++ is that of the incremented variable: auto-increment is post-fix in syntax, but pre-increment in sematics (the variable is incremented, before the return value is calculated). This behavior is unlike that of C and C++. </td></tr>
    341. 

  341. <tr>
    342. 

  342. <td align="center">-- </td><td align="center">auto-decrement (post-fix only) </td><td align="center">$b-- </td><td>Decrement $b. The value of $a-- is that of the decremented variable: auto-decrement is post-fix in syntax, but pre-decrement in sematics (the variable is decremented, before the return value is calculated). This behavior is unlike that of C and C++. </td></tr>
    343. 

  343. </table>
    344. 

  344. <p><b>Relational Operators</b></p>
    345. 

  345. <p>Used in comparing values and variables against each other. Relations can be arithmetic, logical, and string:</p>
    346. 

  346. <table class="doxtable">
    347. 

  347. <tr>
    348. 

  348. <th align="center">Operator </th><th align="center">Name </th><th align="center">Example </th><th>Explanation </th></tr>
    349. 

  349. <tr>
    350. 

  350. <td align="center"><code>&lt;</code> </td><td align="center">Less than </td><td align="center"><code>$a &lt; $b</code> </td><td>1 if $a is less than $b (0 otherwise.) </td></tr>
    351. 

  351. <tr>
    352. 

  352. <td align="center"><code>&gt;</code> </td><td align="center">More than </td><td align="center"><code>$a &gt; $b</code> </td><td>1 if $a is greater than $b (0 otherwise.) </td></tr>
    353. 

  353. <tr>
    354. 

  354. <td align="center"><code>&lt;=</code> </td><td align="center">Less than or Equal to </td><td align="center"><code>$a &lt;= $b</code> </td><td>1 if $a is less than or equal to $b (0 otherwise.) </td></tr>
    355. 

  355. <tr>
    356. 

  356. <td align="center"><code>&gt;=</code> </td><td align="center">More than or Equal to </td><td align="center"><code>$a &gt;= $b</code> </td><td>1 if $a is greater than or equal to $b (0 otherwise.) </td></tr>
    357. 

  357. <tr>
    358. 

  358. <td align="center"><code>==</code> </td><td align="center">Equal to </td><td align="center"><code>$a == $b</code> </td><td>1 if $a is equal to $b (0 otherwise.) </td></tr>
    359. 

  359. <tr>
    360. 

  360. <td align="center"><code>!=</code> </td><td align="center">Not equal to </td><td align="center"><code>$a != $b</code> </td><td>1 if $a is not equal to % b (0 otherwise.) </td></tr>
    361. 

  361. <tr>
    362. 

  362. <td align="center"><code>!</code> </td><td align="center">Logical NOT </td><td align="center"><code>!$a</code> </td><td>1 if $a is 0 (0 otherwise.) </td></tr>
    363. 

  363. <tr>
    364. 

  364. <td align="center"><code>&amp;&amp;</code> </td><td align="center">Logical AND </td><td align="center"><code>$a &amp;&amp; $b</code> </td><td>1 if $a and $b are both non-zero (0 otherwise.) </td></tr>
    365. 

  365. <tr>
    366. 

  366. <td align="center"><code>$=</code> </td><td align="center">String equal to </td><td align="center"><code>$c $= $d</code> </td><td>1 if $c equal to $d . </td></tr>
    367. 

  367. <tr>
    368. 

  368. <td align="center"><code>!$=</code> </td><td align="center">String not equal to </td><td align="center"><code>$c !$= $d</code> </td><td>1 if $c not equal to $d. </td></tr>
    369. 

  369. </table>
    370. 

  370. <p>One additional operator is the logical OR, represented by <code>||</code>. Example:</p>
    371. 

  371. <div class="fragment"><div class="line">$a || $b</div>
    372. 

  372. </div><!-- fragment --><p> OR will return 1 if either <code>$a</code> or <code>$b</code> is non-zero (0 otherwise.)</p>
    373. 

  373. <p><b>Bitwise Operators</b></p>
    374. 

  374. <p>Used for comparing and shifting bits</p>
    375. 

  375. <table class="doxtable">
    376. 

  376. <tr>
    377. 

  377. <th align="center">Operator </th><th align="center">Name </th><th align="center">Example </th><th>Explanation </th></tr>
    378. 

  378. <tr>
    379. 

  379. <td align="center">~ </td><td align="center">Bitwise complement </td><td align="center">~$a </td><td>flip bits 1 to 0 and 0 to 1. (i.e. ~10b == 01b) </td></tr>
    380. 

  380. <tr>
    381. 

  381. <td align="center">&amp; </td><td align="center">Bitwise AND </td><td align="center">$a &amp; $b </td><td>composite of elements where bits in same position are 1. (i.e. 1b &amp; 1b == 1b) </td></tr>
    382. 

  382. <tr>
    383. 

  383. <td align="center">^ </td><td align="center">Bitwise XOR </td><td align="center">$a ^ $b </td><td>composite of elements where bits in same position are opposite. (i.e. 100b &amp; 101b == 001b) </td></tr>
    384. 

  384. <tr>
    385. 

  385. <td align="center">&lt;&lt; </td><td align="center">Left Shift </td><td align="center">$a &lt;&lt; 3 </td><td>element shifted left by 3 and padded with zeros. (i.e. 11b &lt;&lt; 3d == 11000b) </td></tr>
    386. 

  386. <tr>
    387. 

  387. <td align="center">&gt;&gt; </td><td align="center">Right Shift </td><td align="center">$a &gt;&gt; 3 </td><td>element shifted right by 3 and padded with zeros. (i.e. 11010b &gt;&gt; 3d == 00011b) </td></tr>
    388. 

  388. </table>
    389. 

  389. <p>One additional operator is the bitwise OR, represented by <code>|</code>. Example:</p>
    390. 

  390. <div class="fragment"><div class="line">$a | $b</div>
    391. 

  391. </div><!-- fragment --><p> This will return composite of elements where bits 1 in either of the two elements. (i.e. <code>100b &amp; 001b == 101b</code>).</p>
    392. 

  392. <p><b>Assignment Operators</b></p>
    393. 

  393. <p>Used for setting the value of variables.</p>
    394. 

  394. <table class="doxtable">
    395. 

  395. <tr>
    396. 

  396. <th align="center">Operator </th><th align="center">Name </th><th align="center">Example </th><th>Explanation </th></tr>
    397. 

  397. <tr>
    398. 

  398. <td align="center">Assignment </td><td align="center">$a = $b; </td><td align="center">Assign value of $b to $a. </td><td>Note: the value of an assignment is the value being assigned, so $a = $b = $c is legal. </td></tr>
    399. 

  399. <tr>
    400. 

  400. <td align="center">op= </td><td align="center">Assignment Operators </td><td align="center">$a op= $b; </td><td>Equivalent to $a = $a op $b, where op can be any of: <code>*</code> <code>/</code> <code>%</code> <code>+</code> <code>-</code> <code>&amp;</code> <code>^</code> <code>&lt;&lt;</code> <code>&gt;&gt;</code> | </td></tr>
    401. 

  401. </table>
    402. 

  402. <h1>Control Statements</h1>
    403. 

  403. <p>TorqueScript provides basic branching structures that will be familiar to programmers that have used other languages. If you are completely new to programming, you use branching structures to control your game's flow and logic. This section builds on everything you have learned about TorqueScript so far.</p>
    404. 

  404. <h2>if, then, else</h2>
    405. 

  405. <p>This type of structure is used to test a condition, then perform certain actions if the condition passes or fails. You do not always have to use the full structure, but the following syntax shows the extent of the conditional:</p>
    406. 

  406. <div class="fragment"><div class="line"><span class="keywordflow">if</span>(&lt;<span class="keywordtype">boolean</span> expression&gt;) </div>
    407. 

  407. <div class="line">{</div>
    408. 

  408. <div class="line">   pass logic</div>
    409. 

  409. <div class="line">}</div>
    410. 

  410. <div class="line"><span class="keywordflow">else</span> </div>
    411. 

  411. <div class="line">{</div>
    412. 

  412. <div class="line">   alternative logic</div>
    413. 

  413. <div class="line">}</div>
    414. 

  414. </div><!-- fragment --><p>Remember how boolean values work? Essentially, a bool can either be true (1) or false (0). The condition (boolean) is always typed into the parenthesis after the "if" syntax. Your logic will be typed within the brackets {}. The following example uses specific variable names and conditions to show how this can be used:</p>
    415. 

  415. <p>Example: </p>
    416. 

  416. <div class="fragment"><div class="line"><span class="comment">// Global variable that controls lighting</span></div>
    417. 

  417. <div class="line">$lightsShouldBeOn = <span class="keyword">true</span>;</div>
    418. 

  418. <div class="line"></div>
    419. 

  419. <div class="line"><span class="comment">// Check to see if lights should be on or off</span></div>
    420. 

  420. <div class="line"><span class="keywordflow">if</span>($lightsShouldBeOn)</div>
    421. 

  421. <div class="line">{</div>
    422. 

  422. <div class="line">   <span class="comment">// True. Call turn on lights function</span></div>
    423. 

  423. <div class="line">   turnOnLights();</div>
    424. 

  424. <div class="line"></div>
    425. 

  425. <div class="line">   <a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>(<span class="stringliteral">&quot;Lights have been turned on&quot;</span>);</div>
    426. 

  426. <div class="line">}</div>
    427. 

  427. <div class="line"><span class="keywordflow">else</span></div>
    428. 

  428. <div class="line">{</div>
    429. 

  429. <div class="line">   <span class="comment">// False. Turn off the lights</span></div>
    430. 

  430. <div class="line">   turnOffLights();</div>
    431. 

  431. <div class="line"></div>
    432. 

  432. <div class="line">   <a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>(<span class="stringliteral">&quot;Lights have been turned off&quot;</span>);</div>
    433. 

  433. <div class="line">}</div>
    434. 

  434. </div><!-- fragment --><p>Brackets for single line statements are optional. If you are thinking about adding additional logic to the code, then you should use the brackets anyway. If you know you will only use one logic statement, you can use the following syntax:</p>
    435. 

  435. <p>Example: </p>
    436. 

  436. <div class="fragment"><div class="line"><span class="comment">// Global variable that controls lighting</span></div>
    437. 

  437. <div class="line">$lightsShouldBeOn = <span class="keyword">true</span>;</div>
    438. 

  438. <div class="line"></div>
    439. 

  439. <div class="line"><span class="comment">// Check to see if lights should be on or off</span></div>
    440. 

  440. <div class="line"><span class="keywordflow">if</span>($lightsShouldBeOn)</div>
    441. 

  441. <div class="line">  turnOnLights();   <span class="comment">// True. Call turn on lights function</span></div>
    442. 

  442. <div class="line"><span class="keywordflow">else</span></div>
    443. 

  443. <div class="line">  turnOffLights(); <span class="comment">// False. Turn off the lights</span></div>
    444. 

  444. </div><!-- fragment --><h2>switch and switch$</h2>
    445. 

  445. <p>If your code is using several cascading if-then-else statements based on a single value, you might want to use a switch statement instead. Switch statements are easier to manage and read. There are two types of switch statements, based on data type: numeric (<code>switch</code>) and string (<code>switch$</code>).</p>
    446. 

  446. <p>Switch Syntax: </p>
    447. 

  447. <div class="fragment"><div class="line"><span class="keywordflow">switch</span>(&lt;numeric expression&gt;) </div>
    448. 

  448. <div class="line">{</div>
    449. 

  449. <div class="line">   <span class="keywordflow">case</span> value0:</div>
    450. 

  450. <div class="line">       statements;</div>
    451. 

  451. <div class="line">   <span class="keywordflow">case</span> value1:</div>
    452. 

  452. <div class="line">       statements;</div>
    453. 

  453. <div class="line">   <span class="keywordflow">case</span> value3:</div>
    454. 

  454. <div class="line">       statements;</div>
    455. 

  455. <div class="line">   <span class="keywordflow">default</span>:</div>
    456. 

  456. <div class="line">       statements;</div>
    457. 

  457. <div class="line">}</div>
    458. 

  458. </div><!-- fragment --><p>As the above code demonstrates, start by declaring the switch statement by passing in a value to the <code>switch(...)</code> line. Inside of the brackets <code>{}</code>, you will list out all the possible cases that will execute based on what value being tested. It is wise to always use the default case, anticipating rogue values being passed in.</p>
    459. 

  459. <p>Example: </p>
    460. 

  460. <div class="fragment"><div class="line"><span class="keywordflow">switch</span>($ammoCount)</div>
    461. 

  461. <div class="line">{</div>
    462. 

  462. <div class="line">   <span class="keywordflow">case</span> 0:</div>
    463. 

  463. <div class="line">      <a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>(<span class="stringliteral">&quot;Out of ammo, time to reload&quot;</span>);</div>
    464. 

  464. <div class="line">      reloadWeapon();</div>
    465. 

  465. <div class="line">   <span class="keywordflow">case</span> 1:</div>
    466. 

  466. <div class="line">      <a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>(<span class="stringliteral">&quot;Almost out of ammo, warn user&quot;</span>);</div>
    467. 

  467. <div class="line">      lowAmmoWarning();</div>
    468. 

  468. <div class="line">   <span class="keywordflow">case</span> 100:</div>
    469. 

  469. <div class="line">      <a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>(<span class="stringliteral">&quot;Full ammo count&quot;</span>);</div>
    470. 

  470. <div class="line">      playFullAmmoSound();</div>
    471. 

  471. <div class="line">   <span class="keywordflow">default</span>:</div>
    472. 

  472. <div class="line">      doNothing();</div>
    473. 

  473. <div class="line">}</div>
    474. 

  474. </div><!-- fragment --><p><code>switch</code> only properly evaluates numerical values. If you need a switch statement to handle a string value, you will want to use <code>switch$</code>. The <code>switch$</code> syntax is similar to what you just learned:</p>
    475. 

  475. <p>Switch$ Syntax: </p>
    476. 

  476. <div class="fragment"><div class="line"><span class="keywordflow">switch</span>$ (&lt;<span class="keywordtype">string</span> expression&gt;) </div>
    477. 

  477. <div class="line">{</div>
    478. 

  478. <div class="line">   <span class="keywordflow">case</span> <span class="stringliteral">&quot;string value 0&quot;</span>:</div>
    479. 

  479. <div class="line">       statements;</div>
    480. 

  480. <div class="line"></div>
    481. 

  481. <div class="line">   <span class="keywordflow">case</span> <span class="stringliteral">&quot;string value 1&quot;</span>:</div>
    482. 

  482. <div class="line">       statements;</div>
    483. 

  483. <div class="line">...</div>
    484. 

  484. <div class="line">   <span class="keywordflow">case</span> <span class="stringliteral">&quot;string value N&quot;</span>:</div>
    485. 

  485. <div class="line">       statements;</div>
    486. 

  486. <div class="line"></div>
    487. 

  487. <div class="line">   <span class="keywordflow">default</span>:</div>
    488. 

  488. <div class="line">       statements;</div>
    489. 

  489. <div class="line">}</div>
    490. 

  490. </div><!-- fragment --><p>Appending the <code>$</code> sign to switch will immediately cause the parameter passed in to be parsed as a string. The following code applies this logic:</p>
    491. 

  491. <p>Example: </p>
    492. 

  492. <div class="fragment"><div class="line"><span class="comment">// Print out specialties</span></div>
    493. 

  493. <div class="line"><span class="keywordflow">switch</span>($userName)</div>
    494. 

  494. <div class="line">{</div>
    495. 

  495. <div class="line">   <span class="keywordflow">case</span> <span class="stringliteral">&quot;Heather&quot;</span>:</div>
    496. 

  496. <div class="line">      <a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>(<span class="stringliteral">&quot;Sniper&quot;</span>);</div>
    497. 

  497. <div class="line">   <span class="keywordflow">case</span> <span class="stringliteral">&quot;Nikki&quot;</span>:</div>
    498. 

  498. <div class="line">      <a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>(<span class="stringliteral">&quot;Demolition&quot;</span>);</div>
    499. 

  499. <div class="line">   <span class="keywordflow">case</span> <span class="stringliteral">&quot;Mich&quot;</span>:</div>
    500. 

  500. <div class="line">      <a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>(<span class="stringliteral">&quot;Meat shield&quot;</span>);</div>
    501. 

  501. <div class="line">   <span class="keywordflow">default</span>:</div>
    502. 

  502. <div class="line">      <a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>(<span class="stringliteral">&quot;Unknown user&quot;</span>);</div>
    503. 

  503. <div class="line">}</div>
    504. 

  504. </div><!-- fragment --><h1>Loops</h1>
    505. 

  505. <p>As the name implies, this structure type is used to repeat logic in a loop based on an expression. The expression is usually a set of variables that increase by count, or a constant variable changed once a loop has hit a specific point.</p>
    506. 

  506. <h2>For Loop</h2>
    507. 

  507. <div class="fragment"><div class="line"><span class="keywordflow">for</span>(expression0; expression1; expression2) </div>
    508. 

  508. <div class="line">{</div>
    509. 

  509. <div class="line">    statement(s);</div>
    510. 

  510. <div class="line">}</div>
    511. 

  511. </div><!-- fragment --><p>One way to label the expressions in this syntax are <code>(startExpression; testExpression; countExpression)</code>. Each expression is separated by a semi-colon.</p>
    512. 

  512. <p>Example: </p>
    513. 

  513. <div class="fragment"><div class="line"><span class="keywordflow">for</span>(%count = 0; %count &lt; 3; %count++) </div>
    514. 

  514. <div class="line">{</div>
    515. 

  515. <div class="line">    <a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>(%count);</div>
    516. 

  516. <div class="line">}</div>
    517. 

  517. <div class="line"></div>
    518. 

  518. <div class="line">OUTPUT:</div>
    519. 

  519. <div class="line">0</div>
    520. 

  520. <div class="line">1</div>
    521. 

  521. <div class="line">2</div>
    522. 

  522. </div><!-- fragment --><p>The first expression creates the local variable <code>count</code> and initializing it to 0. In the second expression determines when to stop looping, which is when the <code>count</code> is no longer less than 3. Finally, the third expression increases the count the loop relies on.</p>
    523. 

  523. <h2>While Loop</h2>
    524. 

  524. <p>A while loop is a much simpler looping structure compared to a for loop.</p>
    525. 

  525. <div class="fragment"><div class="line"><span class="keywordflow">while</span>(expression) </div>
    526. 

  526. <div class="line">{</div>
    527. 

  527. <div class="line">    statements;</div>
    528. 

  528. <div class="line">}</div>
    529. 

  529. </div><!-- fragment --><p>As soon as the expression is met, the while loop will terminate:</p>
    530. 

  530. <p>Example: </p>
    531. 

  531. <div class="fragment"><div class="line">%countLimit = 0;</div>
    532. 

  532. <div class="line"></div>
    533. 

  533. <div class="line"><span class="keywordflow">while</span>(%countLimit &lt;= 5)</div>
    534. 

  534. <div class="line">{</div>
    535. 

  535. <div class="line">   <a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>(<span class="stringliteral">&quot;Still in loop&quot;</span>);</div>
    536. 

  536. <div class="line">   %count++;</div>
    537. 

  537. <div class="line">}</div>
    538. 

  538. <div class="line"><a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>(<span class="stringliteral">&quot;Loop was terminated&quot;</span>);</div>
    539. 

  539. </div><!-- fragment --><h1>Functions</h1>
    540. 

  540. <p>Much of your TorqueScript experience will come down to calling existing functions and writing your own. Functions are a blocks of code that only execute when you call them by name. Basic functions in TorqueScript are defined as follows:</p>
    541. 

  541. <div class="fragment"><div class="line"><span class="comment">// function - Is a keyword telling TorqueScript we are defining a new function.</span></div>
    542. 

  542. <div class="line"><span class="comment">// function_name - Is the name of the function we are creating.</span></div>
    543. 

  543. <div class="line"><span class="comment">// ... - Is any number of additional arguments.</span></div>
    544. 

  544. <div class="line"><span class="comment">// statements - Your custom logic executed when function is called</span></div>
    545. 

  545. <div class="line"><span class="comment">// return val - The value the function will give back after it has completed. Optional.</span></div>
    546. 

  546. <div class="line"></div>
    547. 

  547. <div class="line"><span class="keyword">function</span> function_name([arg0],...,[argn]) </div>
    548. 

  548. <div class="line">{</div>
    549. 

  549. <div class="line">    statements;</div>
    550. 

  550. <div class="line">    [<span class="keywordflow">return</span> val;]</div>
    551. 

  551. <div class="line">}</div>
    552. 

  552. </div><!-- fragment --><p>The <code>function</code> keyword, like other TorqueScript keywords, is case sensitive. You must type it exactly as shown above. The following is an example of a custom function that takes in two parameters, then executes code based on those arguments.</p>
    553. 

  553. <p>TorqueScript can take any number of arguments, as long as they are comma separated. If you call a function and pass fewer parameters than the function's definition specifies, the un-passed parameters will be given an empty string as their default value.</p>
    554. 

  554. <p>Example: </p>
    555. 

  555. <div class="fragment"><div class="line"><span class="keyword">function</span> echoRepeat (%echoString, %repeatCount) </div>
    556. 

  556. <div class="line">{</div>
    557. 

  557. <div class="line">   <span class="keywordflow">for</span> (%count = 0; %count &lt; %repeatCount; %count++)</div>
    558. 

  558. <div class="line">   {</div>
    559. 

  559. <div class="line">      <a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>(%echoString);</div>
    560. 

  560. <div class="line">   }</div>
    561. 

  561. <div class="line">}</div>
    562. 

  562. </div><!-- fragment --><p> You can cause this function to execute by calling it in the console, or in another function:</p>
    563. 

  563. <div class="fragment"><div class="line">echoRepeat(<span class="stringliteral">&quot;hello!&quot;</span>, 5);</div>
    564. 

  564. <div class="line"></div>
    565. 

  565. <div class="line">OUTPUT:</div>
    566. 

  566. <div class="line"><span class="stringliteral">&quot;hello!&quot;</span></div>
    567. 

  567. <div class="line"><span class="stringliteral">&quot;hello!&quot;</span></div>
    568. 

  568. <div class="line"><span class="stringliteral">&quot;hello!&quot;</span></div>
    569. 

  569. <div class="line"><span class="stringliteral">&quot;hello!&quot;</span></div>
    570. 

  570. <div class="line"><span class="stringliteral">&quot;hello!&quot;</span></div>
    571. 

  571. </div><!-- fragment --><p>If you define a function and give it the same name as a previously defined function, TorqueScript will completely override the old function. This still applies even if you change the number of parameters used; the older function will still be overridden.</p>
    572. 

  572. <p><b>Console Methods</b> Console Methods are C++ functions that have been exposed to TorqueScript, which are attached to specific objects.</p>
    573. 

  573. <p><b>Console Functions</b> Console Functions are written in C++, then exposed to TorqueScript. These are global functions you can call at any time, and are usually very helpful or important. Throughout this document, I have been using a ConsoleFunction: <code>echo(...)</code>. The <code>echo</code> function definition exists in C++:</p>
    574. 

  574. <p>C++ echo:</p>
    575. 

  575. <div class="fragment"><div class="line">ConsoleFunction(<a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>, <span class="keywordtype">void</span>, 2, 0, <span class="stringliteral">&quot;echo(text [, ... ])&quot;</span>)</div>
    576. 

  576. <div class="line">{</div>
    577. 

  577. <div class="line">   U32 len = 0;</div>
    578. 

  578. <div class="line">   S32 i;</div>
    579. 

  579. <div class="line">   <span class="keywordflow">for</span>(i = 1; i &lt; argc; i++)</div>
    580. 

  580. <div class="line">      len += dStrlen(argv[i]);</div>
    581. 

  581. <div class="line"></div>
    582. 

  582. <div class="line">   <span class="keywordtype">char</span> *ret = Con::getReturnBuffer(len + 1);</div>
    583. 

  583. <div class="line">   ret[0] = 0;</div>
    584. 

  584. <div class="line">   <span class="keywordflow">for</span>(i = 1; i &lt; argc; i++)</div>
    585. 

  585. <div class="line">      dStrcat(ret, argv[i]);</div>
    586. 

  586. <div class="line"></div>
    587. 

  587. <div class="line">   Con::printf(<span class="stringliteral">&quot;%s&quot;</span>, ret);</div>
    588. 

  588. <div class="line">   ret[0] = 0;</div>
    589. 

  589. <div class="line">}</div>
    590. 

  590. </div><!-- fragment --><p>Instead of having to write that out every time, or create a TorqueScript equivalent, the ConsoleFunction macro in C++ exposes the command for you. This is much cleaner, and more convenient. We will cover all the ConsoleFunctions later.</p>
    591. 

  591. <p><b>Objects</b> The most complex aspect of TorqueScript involves dealing with game objects. One thing to remember is that everything in TorqueScript is a string. However, when accessing a sprite, sceneObject, or any other object, a string is converted to an object ID under the hood.</p>
    592. 

  592. <p><em>Syntax</em> Even though objects are originally created in C++, they are exposed to script in a way that allows them to be declared using the following syntax:</p>
    593. 

  593. <p>Object Definition: </p>
    594. 

  594. <div class="fragment"><div class="line"><span class="comment">// In TorqueScript</span></div>
    595. 

  595. <div class="line">%objectID = <span class="keyword">new</span> ObjectType(Name) </div>
    596. 

  596. <div class="line">{   </div>
    597. 

  597. <div class="line">   [existing_field0 = InitialValue0;]</div>
    598. 

  598. <div class="line">   ...</div>
    599. 

  599. <div class="line">   [existing_fieldN = InitialValueN;]</div>
    600. 

  600. <div class="line"></div>
    601. 

  601. <div class="line">   [dynamic_field0 = InitialValue0;]</div>
    602. 

  602. <div class="line">   ...</div>
    603. 

  603. <div class="line">   [dynamic_fieldN = InitialValueN;]</div>
    604. 

  604. <div class="line">};</div>
    605. 

  605. </div><!-- fragment --><p>Syntax Breakdown:</p>
    606. 

  606. <p>**objectID** - Is the variable where the object's handle will be stored. new - Is a key word telling the engine to create an instance of the following ObjectType.</p>
    607. 

  607. <p><b>ObjectType</b> - Is any class declared in the engine or in script that has been derived from <a class="el" href="classSimObject.html">SimObject</a> or a subclass of <a class="el" href="classSimObject.html">SimObject</a>. SimObject-derived objects are what we were calling "game world objects" above.</p>
    608. 

  608. <p><b>Name (optional)</b> - Is any expression evaluating to a string, which will be used as the object's name.</p>
    609. 

  609. <p><b>existing_fieldN</b> - You may initialize existing class members (fields) here. Note: In order to modify a member of a C++-defined class, the member must be exposed to the Console. This concept is discussed in detail later.</p>
    610. 

  610. <p><b>dynamic_fieldN</b> - Lastly, you may create new fields (which will exist only in Script) for your new object. These are unique to the instance of the object you are creating.</p>
    611. 

  611. <p><b>Handles vs Names</b> Every game object added to a level can be accessed by two parameters:</p>
    612. 

  612. <p><b>Handle</b> - A unique numeric ID generated when the object is created</p>
    613. 

  613. <p><b>Name</b> - This is an optional parameter given to an object when it is created.</p>
    614. 

  614. <p>Example:</p>
    615. 

  615. <div class="fragment"><div class="line"><span class="comment">// In this example, Truck is the name of the object</span></div>
    616. 

  616. <div class="line"><span class="keyword">new</span> <a class="code" href="classSceneObject.html">SceneObject</a>(Truck) </div>
    617. 

  617. <div class="line">{</div>
    618. 

  618. <div class="line">   position = <span class="stringliteral">&quot;0 0&quot;</span>;</div>
    619. 

  619. <div class="line">   size = <span class="stringliteral">&quot;5 5&quot;</span>;</div>
    620. 

  620. <div class="line">};</div>
    621. 

  621. </div><!-- fragment --><p><b>Object Fields</b> Objects instantiated via script may have data members (referred to as Fields)</p>
    622. 

  622. <p><b>Methods</b> In addition to the creation of stand-alone functions, TorqueScript allows you to create and call methods attached to objects. Some of the more important ConsoleMethods are already written in C++, then exposed to script. You can call these methods by using the dot (.) notation.</p>
    623. 

  623. <p>Syntax: </p>
    624. 

  624. <div class="fragment"><div class="line">objHandle.function_name();</div>
    625. 

  625. <div class="line"></div>
    626. 

  626. <div class="line">objName.function_name();</div>
    627. 

  627. </div><!-- fragment --><p>Example: </p>
    628. 

  628. <div class="fragment"><div class="line"><span class="keyword">new</span> <a class="code" href="classSceneObject.html">SceneObject</a>(Truck) </div>
    629. 

  629. <div class="line">{</div>
    630. 

  630. <div class="line">   position = <span class="stringliteral">&quot;0 0&quot;</span>;</div>
    631. 

  631. <div class="line">   size = <span class="stringliteral">&quot;5 5&quot;</span>;</div>
    632. 

  632. <div class="line">};</div>
    633. 

  633. <div class="line"></div>
    634. 

  634. <div class="line"><span class="comment">// Write all the objects methods to the console log</span></div>
    635. 

  635. <div class="line">Truck.<a class="code" href="classSimObject.html#accd2600060dbaee3a3b41aed4034c63c">dump</a>();</div>
    636. 

  636. <div class="line"></div>
    637. 

  637. <div class="line"><span class="comment">// Get the ID of an object, using the object&#39;s name</span></div>
    638. 

  638. <div class="line">$objID = Truck.getID();</div>
    639. 

  639. <div class="line"></div>
    640. 

  640. <div class="line"><span class="comment">// Print the ID to the console</span></div>
    641. 

  641. <div class="line"><a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>(<span class="stringliteral">&quot;Object ID: &quot;</span>, $objID);</div>
    642. 

  642. <div class="line"></div>
    643. 

  643. <div class="line"><span class="comment">// Get the object&#39;s position, using the object&#39;s handle</span></div>
    644. 

  644. <div class="line">%position = $objID.getPosition();</div>
    645. 

  645. <div class="line"></div>
    646. 

  646. <div class="line"><span class="comment">// Print the position to the console</span></div>
    647. 

  647. <div class="line"><a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>(<span class="stringliteral">&quot;Object Position: &quot;</span>, %position);</div>
    648. 

  648. </div><!-- fragment --><p>The above example shows how you can call an object's method by using its name or a variable containing its handle (unique ID number). Additionally, TorqueScript supports the creation of methods that have no associated C++ counterpart.</p>
    649. 

  649. <p>Syntax:</p>
    650. 

  650. <div class="fragment"><div class="line"><span class="comment">// function - Is a keyword telling TorqueScript we are defining a new function.</span></div>
    651. 

  651. <div class="line"><span class="comment">// ClassName::- Is the class type this function is supposed to work with.</span></div>
    652. 

  652. <div class="line"><span class="comment">// function_name - Is the name of the function we are creating.</span></div>
    653. 

  653. <div class="line"><span class="comment">// ... - Is any number of additional arguments.</span></div>
    654. 

  654. <div class="line"><span class="comment">// statements - Your custom logic executed when function is called</span></div>
    655. 

  655. <div class="line"><span class="comment">// %this- Is a variable that will contain the handle of the &#39;calling object&#39;.</span></div>
    656. 

  656. <div class="line"><span class="comment">// return val - The value the function will give back after it has completed. Optional.</span></div>
    657. 

  657. <div class="line"><span class="keyword">function</span> Classname::func_name(%<span class="keyword">this</span>, [arg0],...,[argn]) </div>
    658. 

  658. <div class="line">{</div>
    659. 

  659. <div class="line">   statements;</div>
    660. 

  660. <div class="line">   [<span class="keywordflow">return</span> val;]</div>
    661. 

  661. <div class="line">}</div>
    662. 

  662. </div><!-- fragment --><p>At a minimum, Console Methods require that you pass them an object handle. You will often see the first argument named this. People use this as a hint, but you can name it anything you want. As with Console functions any number of additional arguments can be specified separated by commas.</p>
    663. 

  663. <p>As a simple example, let's say there is an object called Samurai, derived from the Player class. It is likely that a specific appearance and play style will be given to the samurai, so custom ConsoleMethods can be written. Here is a sample:</p>
    664. 

  664. <p>Example: </p>
    665. 

  665. <div class="fragment"><div class="line"><span class="keyword">function</span> Samurai::sheatheSword(%<span class="keyword">this</span>)</div>
    666. 

  666. <div class="line">{</div>
    667. 

  667. <div class="line">    <a class="code" href="group__ConsoleOutputFunctions.html#ga530570e5951963de5e7ae349e996691c">echo</a>(<span class="stringliteral">&quot;Katana sheathed&quot;</span>);</div>
    668. 

  668. <div class="line">}</div>
    669. 

  669. </div><!-- fragment --><p>When you create a Samurai object, it will be given an ID. Let's pretend the handle (ID number) is <code>1042</code>. We can call its ConsoleMethod once it is defined, using the period syntax:</p>
    670. 

  670. <p>Example: </p>
    671. 

  671. <div class="fragment"><div class="line">1042.sheatheSword();</div>
    672. 

  672. <div class="line"></div>
    673. 

  673. <div class="line">OUTPUT: <span class="stringliteral">&quot;Katana sheathed&quot;</span></div>
    674. 

  674. </div><!-- fragment --><p>Notice that no parameters were passed into the function. The <code>this</code> parameter is inherent, and the original function did not require any other parameters.</p>
    675. 

  675. <h1>Conclusion</h1>
    676. 

  676. <p>This guide covered the basics of TorqueScript syntax. Compared to other languages, such as C++, it is easier to learn and work with. However, no one is expected to become a TorqueScript master over night, or even in a week. You will most likely need to refer back to this documentation several times for reminders. </p>
    677. 

  677. </div></div><!-- contents -->
    678. 

  678. <!-- start footer part -->
    679. 

  679. <hr class="footer"/><address class="footer"><small>
    680. 

  680. Generated by &#160;<a href="http://www.doxygen.org/index.html">
    681. 

  681. <img class="footer" src="doxygen.png" alt="doxygen"/>
    682. 

  682. </a> 1.8.3.1
    683. 

  683. </small></address>
    684. 

  684. </body>
    685. 

  685. </html>
    686.