doc/basic_tutorial.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
   2     "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
   6 <meta name="generator" content="AsciiDoc 8.2.1" />
   7 <style type="text/css">
   8 /* Debug borders */
   9 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
  10 /*
  11   border: 1px solid red;
  12 */
  13 }
  14
  15 body {
  16   margin: 1em 5% 1em 5%;
  17 }
  18
  19 a {
  20   color: blue;
  21   text-decoration: underline;
  22 }
  23 a:visited {
  24   color: fuchsia;
  25 }
  26
  27 em {
  28   font-style: italic;
  29 }
  30
  31 strong {
  32   font-weight: bold;
  33 }
  34
  35 tt {
  36   color: navy;
  37 }
  38
  39 h1, h2, h3, h4, h5, h6 {
  40   color: #527bbd;
  41   font-family: sans-serif;
  42   margin-top: 1.2em;
  43   margin-bottom: 0.5em;
  44   line-height: 1.3;
  45 }
  46
  47 h1 {
  48   border-bottom: 2px solid silver;
  49 }
  50 h2 {
  51   border-bottom: 2px solid silver;
  52   padding-top: 0.5em;
  53 }
  54
  55 div.sectionbody {
  56   font-family: serif;
  57   margin-left: 0;
  58 }
  59
  60 hr {
  61   border: 1px solid silver;
  62 }
  63
  64 p {
  65   margin-top: 0.5em;
  66   margin-bottom: 0.5em;
  67 }
  68
  69 pre {
  70   padding: 0;
  71   margin: 0;
  72 }
  73
  74 span#author {
  75   color: #527bbd;
  76   font-family: sans-serif;
  77   font-weight: bold;
  78   font-size: 1.1em;
  79 }
  80 span#email {
  81 }
  82 span#revision {
  83   font-family: sans-serif;
  84 }
  85
  86 div#footer {
  87   font-family: sans-serif;
  88   font-size: small;
  89   border-top: 2px solid silver;
  90   padding-top: 0.5em;
  91   margin-top: 4.0em;
  92 }
  93 div#footer-text {
  94   float: left;
  95   padding-bottom: 0.5em;
  96 }
  97 div#footer-badges {
  98   float: right;
  99   padding-bottom: 0.5em;
 100 }
 101
 102 div#preamble,
 103 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
 104 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
 105 div.admonitionblock {
 106   margin-right: 10%;
 107   margin-top: 1.5em;
 108   margin-bottom: 1.5em;
 109 }
 110 div.admonitionblock {
 111   margin-top: 2.5em;
 112   margin-bottom: 2.5em;
 113 }
 114
 115 div.content { /* Block element content. */
 116   padding: 0;
 117 }
 118
 119 /* Block element titles. */
 120 div.title, caption.title {
 121   font-family: sans-serif;
 122   font-weight: bold;
 123   text-align: left;
 124   margin-top: 1.0em;
 125   margin-bottom: 0.5em;
 126 }
 127 div.title + * {
 128   margin-top: 0;
 129 }
 130
 131 td div.title:first-child {
 132   margin-top: 0.0em;
 133 }
 134 div.content div.title:first-child {
 135   margin-top: 0.0em;
 136 }
 137 div.content + div.title {
 138   margin-top: 0.0em;
 139 }
 140
 141 div.sidebarblock > div.content {
 142   background: #ffffee;
 143   border: 1px solid silver;
 144   padding: 0.5em;
 145 }
 146
 147 div.listingblock {
 148   margin-right: 0%;
 149 }
 150 div.listingblock > div.content {
 151   border: 1px solid silver;
 152   background: #f4f4f4;
 153   padding: 0.5em;
 154 }
 155
 156 div.quoteblock > div.content {
 157   padding-left: 2.0em;
 158 }
 159
 160 div.attribution {
 161   text-align: right;
 162 }
 163 div.verseblock + div.attribution {
 164   text-align: left;
 165 }
 166
 167 div.admonitionblock .icon {
 168   vertical-align: top;
 169   font-size: 1.1em;
 170   font-weight: bold;
 171   text-decoration: underline;
 172   color: #527bbd;
 173   padding-right: 0.5em;
 174 }
 175 div.admonitionblock td.content {
 176   padding-left: 0.5em;
 177   border-left: 2px solid silver;
 178 }
 179
 180 div.exampleblock > div.content {
 181   border-left: 2px solid silver;
 182   padding: 0.5em;
 183 }
 184
 185 div.verseblock div.content {
 186   white-space: pre;
 187 }
 188
 189 div.imageblock div.content { padding-left: 0; }
 190 div.imageblock img { border: 1px solid silver; }
 191 span.image img { border-style: none; }
 192
 193 dl {
 194   margin-top: 0.8em;
 195   margin-bottom: 0.8em;
 196 }
 197 dt {
 198   margin-top: 0.5em;
 199   margin-bottom: 0;
 200   font-style: italic;
 201 }
 202 dd > *:first-child {
 203   margin-top: 0;
 204 }
 205
 206 ul, ol {
 207     list-style-position: outside;
 208 }
 209 ol.olist2 {
 210   list-style-type: lower-alpha;
 211 }
 212
 213 div.tableblock > table {
 214   border: 3px solid #527bbd;
 215 }
 216 thead {
 217   font-family: sans-serif;
 218   font-weight: bold;
 219 }
 220 tfoot {
 221   font-weight: bold;
 222 }
 223
 224 div.hlist {
 225   margin-top: 0.8em;
 226   margin-bottom: 0.8em;
 227 }
 228 div.hlist td {
 229   padding-bottom: 5px;
 230 }
 231 td.hlist1 {
 232   vertical-align: top;
 233   font-style: italic;
 234   padding-right: 0.8em;
 235 }
 236 td.hlist2 {
 237   vertical-align: top;
 238 }
 239
 240 @media print {
 241   div#footer-badges { display: none; }
 242 }
 243
 244 div#toctitle {
 245   color: #527bbd;
 246   font-family: sans-serif;
 247   font-size: 1.1em;
 248   font-weight: bold;
 249   margin-top: 1.0em;
 250   margin-bottom: 0.1em;
 251 }
 252
 253 div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
 254   margin-top: 0;
 255   margin-bottom: 0;
 256 }
 257 div.toclevel2 {
 258   margin-left: 2em;
 259   font-size: 0.9em;
 260 }
 261 div.toclevel3 {
 262   margin-left: 4em;
 263   font-size: 0.9em;
 264 }
 265 div.toclevel4 {
 266   margin-left: 6em;
 267   font-size: 0.9em;
 268 }
 269 /* Workarounds for IE6's broken and incomplete CSS2. */
 270
 271 div.sidebar-content {
 272   background: #ffffee;
 273   border: 1px solid silver;
 274   padding: 0.5em;
 275 }
 276 div.sidebar-title, div.image-title {
 277   font-family: sans-serif;
 278   font-weight: bold;
 279   margin-top: 0.0em;
 280   margin-bottom: 0.5em;
 281 }
 282
 283 div.listingblock div.content {
 284   border: 1px solid silver;
 285   background: #f4f4f4;
 286   padding: 0.5em;
 287 }
 288
 289 div.quoteblock-content {
 290   padding-left: 2.0em;
 291 }
 292
 293 div.exampleblock-content {
 294   border-left: 2px solid silver;
 295   padding-left: 0.5em;
 296 }
 297
 298 /* IE6 sets dynamically generated links as visited. */
 299 div#toc a:visited { color: blue; }
 300 </style>
 301 <script type="text/javascript">
 302 /*<![CDATA[*/
 303 window.onload = function(){generateToc(2)}
 304 /* Author: Mihai Bazon, September 2002
 305  * http://students.infoiasi.ro/~mishoo
 306  *
 307  * Table Of Content generator
 308  * Version: 0.4
 309  *
 310  * Feel free to use this script under the terms of the GNU General Public
 311  * License, as long as you do not remove or alter this notice.
 312  */
 313
 314  /* modified by Troy D. Hanson, September 2006. License: GPL */
 315  /* modified by Stuart Rackham, October 2006. License: GPL */
 316
 317 function getText(el) {
 318   var text = "";
 319   for (var i = el.firstChild; i != null; i = i.nextSibling) {
 320     if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
 321       text += i.data;
 322     else if (i.firstChild != null)
 323       text += getText(i);
 324   }
 325   return text;
 326 }
 327
 328 function TocEntry(el, text, toclevel) {
 329   this.element = el;
 330   this.text = text;
 331   this.toclevel = toclevel;
 332 }
 333
 334 function tocEntries(el, toclevels) {
 335   var result = new Array;
 336   var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
 337   // Function that scans the DOM tree for header elements (the DOM2
 338   // nodeIterator API would be a better technique but not supported by all
 339   // browsers).
 340   var iterate = function (el) {
 341     for (var i = el.firstChild; i != null; i = i.nextSibling) {
 342       if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
 343         var mo = re.exec(i.tagName)
 344         if (mo)
 345           result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
 346         iterate(i);
 347       }
 348     }
 349   }
 350   iterate(el);
 351   return result;
 352 }
 353
 354 // This function does the work. toclevels = 1..4.
 355 function generateToc(toclevels) {
 356   var toc = document.getElementById("toc");
 357   var entries = tocEntries(document.getElementsByTagName("body")[0], toclevels);
 358   for (var i = 0; i < entries.length; ++i) {
 359     var entry = entries[i];
 360     if (entry.element.id == "")
 361       entry.element.id = "toc" + i;
 362     var a = document.createElement("a");
 363     a.href = "#" + entry.element.id;
 364     a.appendChild(document.createTextNode(entry.text));
 365     var div = document.createElement("div");
 366     div.appendChild(a);
 367     div.className = "toclevel" + entry.toclevel;
 368     toc.appendChild(div);
 369   }
 370 }
 371 /*]]>*/
 372 </script>
 373 <title>Basic Tutorial</title>
 374 </head>
 375 <body>
 376 <div id="header">
 377 <h1>Basic Tutorial</h1>
 378 <div id="toc">
 379   <div id="toctitle">Table of Contents</div>
 380   <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
 381 </div>
 382 </div>
 383 <div id="preamble">
 384 <div class="sectionbody">
 385 <div class="admonitionblock">
 386 <table><tr>
 387 <td class="icon">
 388 <img src="./images/icons/note.png" alt="Note" />
 389 </td>
 390 <td class="content">The full source code of this tutorial is available in the <em>demos/tutorial</em> directory.</td>
 391 </tr></table>
 392 </div>
 393 </div>
 394 </div>
 395 <h2>1. How LuaGame Works (sorta)</h2>
 396 <div class="sectionbody">
 397 <p>LuaGame is an execution environment for games. It exposes a good amount of the
 398 functionality of SDL, and extends it with a standard library. LuaGame is <strong>not</strong>
 399 a game engine. It provides enough features to easily build one, but it is much
 400 more general. This tutorial should give one a good enough understanding of the
 401 basics of writing games in LuaGame. It's recommended that one learn the basics
 402 of Lua before reading the rest of this tutorial, although it's not required.</p>
 403 <p>Games in LuaGame must contain at least two files, <em>scripts/config.lua</em> and
 404 <em>base/init.lua</em>. Ideally, one will use the base library, in which case the file
 405 <em>scripts/main.lua</em> is also required.</p>
 406 <p>The basic directory structure of a game is as follows:</p>
 407 <div class="literalblock">
 408 <div class="content">
 409 <pre><tt> gamedir
 410  |-base
 411  |-scripts
 412  |-&lt;extra dir-1&gt;
 413     ...
 414  \-&lt;extra dir-n&gt;</tt></pre>
 415 </div></div>
 416 <div class="admonitionblock">
 417 <table><tr>
 418 <td class="icon">
 419 <img src="./images/icons/note.png" alt="Note" />
 420 </td>
 421 <td class="content">
 422 <div class="title">Paths</div>
 423 <p>The <em>gamedir</em> directory is the base path of the game. All resources (scripts,
 424 images, sounds, etc&#8230;) must be referenced relative to that.</p>
 425 <p>Ex: script <em>somescript.lua</em> is in <em>scripts/somescript.lua</em></p>
 426 </td>
 427 </tr></table>
 428 </div>
 429 <p>When LuaGame is executed in the <em>gamedir</em> directory or with the path to <em>gamedir</em>
 430 as an argument, it will do the following:</p>
 431 <ol>
 432 <li>
 433 <p>
 434 run the <em>config.lua</em> script
 435 </p>
 436 </li>
 437 <li>
 438 <p>
 439 initialize output surface
 440 </p>
 441 </li>
 442 <li>
 443 <p>
 444 run <em>base/init.lua</em>
 445 </p>
 446 </li>
 447 <li>
 448 <p>
 449 the init script will run <em>scripts/main.lua</em> (if one is using the base library)
 450 </p>
 451 </li>
 452 </ol>
 453 <div class="admonitionblock">
 454 <table><tr>
 455 <td class="icon">
 456 <img src="./images/icons/tip.png" alt="Tip" />
 457 </td>
 458 <td class="content">
 459 <div class="title">Why We Copy the <em>base</em> Directory</div>
 460 <p>We copy the <em>base</em> directory (instead of installing it globally in perhaps $PREFIX/share)
 461 because it allows one to change any part of it that they feel is necessary. For
 462 example, one can extend the library or change the API and by having it separate,
 463 it keeps it from breaking compatibility with any other LuaGame-based games. Also,
 464 it's pretty small, and won't add significant weight to distributables.</p>
 465 <p>Installing it globally also has the problem of making it more difficult to use
 466 LuaGame on Windows and Mac OSX (for both developer and end-user).</p>
 467 </td>
 468 </tr></table>
 469 </div>
 470 </div>
 471 <h2>2. Getting Started</h2>
 472 <div class="sectionbody">
 473 <h3>2.1. Initialize the Game Directory</h3>
 474 <p>Create a new directory and copy the <em>base</em> directory into it (if you want to use
 475 the base library, and you do).</p>
 476 <p>Now, create the <em>scripts</em> directory and create a file called <em>config.lua</em> in it.
 477 Into that file place the following lines:</p>
 478 <div class="listingblock">
 479 <div class="content"><!-- Generator: GNU source-highlight 2.4
 480 by Lorenzo Bettini
 481 http://www.lorenzobettini.it
 482 http://www.gnu.org/software/src-highlite -->
 483 <pre><tt><span style="font-style: italic"><span style="color: #9A1900">--variables that define the</span></span>
 484 <span style="font-style: italic"><span style="color: #9A1900">--screen properties</span></span>
 485 s_width <span style="color: #990000">=</span> <span style="color: #993399">640</span>
 486 s_height <span style="color: #990000">=</span> <span style="color: #993399">480</span>
 487 s_depth <span style="color: #990000">=</span> <span style="color: #993399">32</span>
 488 s_fullscreen <span style="color: #990000">=</span> <span style="color: #993399">0</span>
 489
 490 <span style="font-style: italic"><span style="color: #9A1900">--the name of the game. Appears in titlebar</span></span>
 491 s_gamename <span style="color: #990000">=</span> <span style="color: #FF0000">"my game"</span>
 492 </tt></pre></div></div>
 493 <p>The variable names should be self-explanatory. I'd recommend leaving s_depth at 32
 494 because it makes life a lot easier.</p>
 495 <p>Also, in <em>scripts</em>, create a blank file named <em>main.lua</em>. The directory is now
 496 set up and when run with LuaGame, it will produce a 640x480 window that will
 497 instantly disappear.</p>
 498 <h3>2.2. Keeping the Window Open</h3>
 499 <p>To keep the window open, one needs to add the main game loop to the <em>main.lua</em> file.</p>
 500 <p>So, just add this code to <em>main.lua</em>:</p>
 501 <div class="listingblock">
 502 <div class="content"><!-- Generator: GNU source-highlight 2.4
 503 by Lorenzo Bettini
 504 http://www.lorenzobettini.it
 505 http://www.gnu.org/software/src-highlite -->
 506 <pre><tt><span style="font-style: italic"><span style="color: #9A1900">--controls main game loop</span></span>
 507 done <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #0000FF">false</span></span>
 508
 509 <span style="font-style: italic"><span style="color: #9A1900">--main game loop</span></span>
 510 <span style="font-weight: bold"><span style="color: #0000FF">while</span></span> done <span style="color: #990000">~=</span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span> <span style="font-weight: bold"><span style="color: #0000FF">do</span></span>
 511
 512 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
 513 </tt></pre></div></div>
 514 <p>If one runs this right now, it will produce a window that can't be closed except
 515 by interrupting (Ctrl-C) LuaGame. We're going to fix that in the next section, but
 516 we're going to reduce the CPU usage of the game first using an FPSManager.</p>
 517 <p>The FPSManager is a class to handle proper delays and will attempt to run the main
 518 game loop at the chosen FPS. Add it to the code like so:</p>
 519 <div class="listingblock">
 520 <div class="content"><!-- Generator: GNU source-highlight 2.4
 521 by Lorenzo Bettini
 522 http://www.lorenzobettini.it
 523 http://www.gnu.org/software/src-highlite -->
 524 <pre><tt><span style="font-style: italic"><span style="color: #9A1900">--controls main game loop</span></span>
 525 done <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #0000FF">false</span></span>
 526
 527 fps <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">FPSManager:new</span></span><span style="color: #990000">()</span> <span style="font-style: italic"><span style="color: #9A1900">-- create the FPSManager object</span></span>
 528 <span style="font-weight: bold"><span style="color: #000000">fps:set_fps</span></span><span style="color: #990000">(</span><span style="color: #993399">30</span><span style="color: #990000">)</span> <span style="font-style: italic"><span style="color: #9A1900">-- set the FPS to 30</span></span>
 529
 530 <span style="font-style: italic"><span style="color: #9A1900">--main game loop</span></span>
 531 <span style="font-weight: bold"><span style="color: #0000FF">while</span></span> done <span style="color: #990000">~=</span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span> <span style="font-weight: bold"><span style="color: #0000FF">do</span></span>
 532   <span style="font-weight: bold"><span style="color: #000000">fps:update</span></span><span style="color: #990000">()</span> <span style="font-style: italic"><span style="color: #9A1900">-- delay to ensure proper FPS</span></span>
 533 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
 534 </tt></pre></div></div>
 535 <p>The <strong>fps:update()</strong> call should/must come at the end of the main game loop. This
 536 tutorial covers frame-based games. For smoother animation, one should use deltas.
 537 LuaGames supports this, but using it is beyond the scope of this tutorial.</p>
 538 <h3>2.3. Introduction to Events</h3>
 539 <p>It's now time to add an EventManager to deal with the mouse, keyboard, and joystick
 540 events that your game will encounter. The EventManager class is designed such
 541 that one can create an arbitrary number of them and then just use them at the
 542 appropriate time.</p>
 543 <div class="admonitionblock">
 544 <table><tr>
 545 <td class="icon">
 546 <img src="./images/icons/tip.png" alt="Tip" />
 547 </td>
 548 <td class="content">
 549 <p>For any real game, it's recommended that one put
 550 all declarations of EventManagers into a separate
 551 file for clarity (they can get pretty big).</p>
 552 </td>
 553 </tr></table>
 554 </div>
 555 <p>Adding an EventManager is easy. Just add the following code to your <em>main.lua</em>
 556 above the main game loop.</p>
 557 <div class="listingblock">
 558 <div class="content"><!-- Generator: GNU source-highlight 2.4
 559 by Lorenzo Bettini
 560 http://www.lorenzobettini.it
 561 http://www.gnu.org/software/src-highlite -->
 562 <pre><tt>evman <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">EventManager:new</span></span><span style="color: #990000">()</span>
 563 evman<span style="color: #990000">.</span>quit <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #0000FF">function</span></span> <span style="color: #990000">()</span> done <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
 564 evman<span style="color: #990000">.</span>keyboard<span style="color: #990000">.</span>pressed<span style="color: #990000">[</span>Keys<span style="color: #990000">.</span>ESCAPE<span style="color: #990000">]</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #0000FF">function</span></span><span style="color: #990000">()</span> done <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
 565 </tt></pre></div></div>
 566 <p>This creates an event manager and adds two events to it. The first event is the
 567 event fired when a user tries to close the window. The second is the event that
 568 occurs when one presses the escape key. When either event occurs, it causes the
 569 main game loop to exit. Notice, the events are assigned functions (in this case
 570 they're anonymous, but they just need to be functions). These functions are run
 571 when the events occur.</p>
 572 <div class="admonitionblock">
 573 <table><tr>
 574 <td class="icon">
 575 <img src="./images/icons/tip.png" alt="Tip" />
 576 </td>
 577 <td class="content">
 578 <p>Functions are first-class values in Lua, that is, they can be passed and
 579 assigned just like any other variable. In the above example, anonymous functions
 580 are used. However, it's just as easy to use previously declared functions. See
 581 the documentation for the <strong>EventManager</strong> class for an example of using events
 582 and object methods together (HINT: Write a wrapper function.)</p>
 583 </td>
 584 </tr></table>
 585 </div>
 586 <p>However, nothing's going to happen with just the declarations. We need to add a
 587 method call to the game loop to actually process any events.</p>
 588 <p>So, at the beginning of the main game loop, add this line:</p>
 589 <div class="listingblock">
 590 <div class="content"><!-- Generator: GNU source-highlight 2.4
 591 by Lorenzo Bettini
 592 http://www.lorenzobettini.it
 593 http://www.gnu.org/software/src-highlite -->
 594 <pre><tt><span style="font-weight: bold"><span style="color: #000000">evman:gather_events</span></span><span style="color: #990000">()</span>
 595 </tt></pre></div></div>
 596 <p>That's pretty much all there is to event managers. Mouse and especially joystick
 597 handling is a little harder, but that's for another tutorial.</p>
 598 <div class="admonitionblock">
 599 <table><tr>
 600 <td class="icon">
 601 <img src="./images/icons/tip.png" alt="Tip" />
 602 </td>
 603 <td class="content">
 604 <p>As is probably obvious now, making multiple event managers is an easy way to
 605 have multiple input contexts. By naming functions, common events don't need to
 606 have redundant code, and overall, it reduces the complexity of handling events.</p>
 607 </td>
 608 </tr></table>
 609 </div>
 610 </div>
 611 <h2>3. Objects</h2>
 612 <div class="sectionbody">
 613 <h3>3.1. Explanation of Objects</h3>
 614 <p>Objects in LuaGame are what one should be extending to create the actors in their
 615 games. The Object class is very much like a sprite class. It has a <strong>draw()</strong> method,
 616 an <strong>update()</strong> method, and an empty <strong>collide()</strong> method.</p>
 617 <p>It is expected that all Objects (pure and inherited) have the three methods
 618 mentioned above. This comes into effect later with the ObjectList's convenience
 619 methods.</p>
 620 <p>Besides those three methods, Objects have a position, heading, speed, rotation,
 621 and image.</p>
 622 <h3>3.2. Extending the Object</h3>
 623 <p>For the most part, one doesn't want to use the Object class directly. Thus, it is
 624 imperative to extend it to fit one's needs. Object Orientation in Lua is pretty
 625 simple. It's beyond the scope of this tutorial to cover the how or why it works.</p>
 626 <p>Inheritance starts by making the new class be an instance of the base class,
 627 in this case <strong>Object</strong>. The <strong>type</strong> property needs to be set to the name of the new
 628 class for the sake of collision detection and just to be able to identify them
 629 since classes are just tables.</p>
 630 <div class="listingblock">
 631 <div class="content"><!-- Generator: GNU source-highlight 2.4
 632 by Lorenzo Bettini
 633 http://www.lorenzobettini.it
 634 http://www.gnu.org/software/src-highlite -->
 635 <pre><tt>MyObj <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">Object:new</span></span><span style="color: #990000">()</span>
 636
 637 MyObj<span style="color: #990000">.</span>type <span style="color: #990000">=</span> <span style="color: #FF0000">"MyObj"</span>
 638 MyObj<span style="color: #990000">.</span>rects <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ObjectList:new</span></span><span style="color: #990000">()</span> <span style="font-style: italic"><span style="color: #9A1900">-- we'll come back to this</span></span>
 639 </tt></pre></div></div>
 640 <p>The <strong>Object:new()</strong> method is what makes the object orientation work. However, we
 641 need to create a <strong>new()</strong> method for the new class to make the inheritance work.</p>
 642 <div class="listingblock">
 643 <div class="content"><!-- Generator: GNU source-highlight 2.4
 644 by Lorenzo Bettini
 645 http://www.lorenzobettini.it
 646 http://www.gnu.org/software/src-highlite -->
 647 <pre><tt><span style="font-weight: bold"><span style="color: #0000FF">function</span></span> <span style="font-weight: bold"><span style="color: #000000">MyObj:new</span></span><span style="color: #990000">(</span>o<span style="color: #990000">)</span>
 648   o <span style="color: #990000">=</span> o <span style="font-weight: bold"><span style="color: #0000FF">or</span></span> <span style="color: #FF0000">{}</span>
 649   <span style="font-weight: bold"><span style="color: #000000">setmetatable</span></span><span style="color: #990000">(</span>o<span style="color: #990000">,</span> self<span style="color: #990000">)</span>
 650   self<span style="color: #990000">.</span>__index <span style="color: #990000">=</span> self
 651   <span style="font-weight: bold"><span style="color: #0000FF">return</span></span> o
 652 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
 653 </tt></pre></div></div>
 654 <p>Due to the fact that <strong>MyObj</strong> is also an <strong>Object</strong>, the methods of <strong>Object</strong> can be
 655 run on an instance of <strong>MyObj</strong>. But, for the sake of clarity (at least for now), we'll
 656 add a <strong>MyObj:update()</strong> method.</p>
 657 <div class="listingblock">
 658 <div class="content"><!-- Generator: GNU source-highlight 2.4
 659 by Lorenzo Bettini
 660 http://www.lorenzobettini.it
 661 http://www.gnu.org/software/src-highlite -->
 662 <pre><tt><span style="font-weight: bold"><span style="color: #0000FF">function</span></span> <span style="font-weight: bold"><span style="color: #000000">MyObj:update</span></span><span style="color: #990000">(</span>delta<span style="color: #990000">)</span>
 663   Object<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">update</span></span><span style="color: #990000">(</span>self<span style="color: #990000">,</span> delta<span style="color: #990000">)</span>
 664 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
 665 </tt></pre></div></div>
 666 <p>For the most part, this is entirely redundant code. But it showcases two things.
 667 Number one, the update method should accept a single variable that allows for
 668 the use of time deltas (required for time-based games). Number two, accessing
 669 a function in a table using the ":" operator instead of "." passes a hidden
 670 first argument <em>self</em> which is the table that the function is being called on.</p>
 671 <p>However, by defining the <strong>update()</strong> method we can extend it to do more than
 672 the base <strong>Object</strong> does, or we can exclude the call to <strong>Object.update(self,delta)</strong>
 673 entirely and write our own code.</p>
 674 <h3>3.3. Making MyObj Do More</h3>
 675 <p>At the moment, <strong>MyObj</strong> is basically just an <strong>Object</strong> with a different name. That's
 676 pretty boring, so we're going to make it do something a little different.</p>
 677 <p>Say we want to take this lovely image <span class="image">
 678 <img src="images/wikilogo.png" alt="images/wikilogo.png" />
 679 </span> and make it move
 680 around on the screen. We need to set the <strong>MyObj.image</strong> property to be that image. So,
 681 go ahead and download that image and place it in <em>gamedir</em>, perhaps in <em>data/images</em>.</p>
 682 <p>To actually load this image into <strong>MyObj</strong>, add the following code somewhere underneath
 683 the initial declaration.</p>
 684 <div class="listingblock">
 685 <div class="content"><!-- Generator: GNU source-highlight 2.4
 686 by Lorenzo Bettini
 687 http://www.lorenzobettini.it
 688 http://www.gnu.org/software/src-highlite -->
 689 <pre><tt>MyObj<span style="color: #990000">.</span>image<span style="color: #990000">,</span> MyObj<span style="color: #990000">.</span>w<span style="color: #990000">,</span> MyObj<span style="color: #990000">.</span>h <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">get_image</span></span><span style="color: #990000">(</span><span style="color: #FF0000">"data/images/wikilogo.png"</span><span style="color: #990000">)</span>
 690 </tt></pre></div></div>
 691 <div class="admonitionblock">
 692 <table><tr>
 693 <td class="icon">
 694 <img src="./images/icons/tip.png" alt="Tip" />
 695 </td>
 696 <td class="content">
 697 <p>The <strong>get_image()</strong> function loads up an image into the global image store. If the
 698 image has already been loaded, then it just returns it. To free an image from the
 699 global store, use <strong>release_image()</strong>. Note that the image is specified by its path
 700 relative to <em>gamedir</em>. To prevent a new copy from being loaded the exact same path
 701 must be used for all references to the image.</p>
 702 </td>
 703 </tr></table>
 704 </div>
 705 <p>Now that the image is loaded, all that's left to do is make it move around in an
 706 interesting way. The easiest interesting thing to do is make it bounce around, so
 707 we're going to do just that. It will bounce off the edges of the screen from the
 708 center. The <strong>MyObj:update()</strong> method is now going to look like this:</p>
 709 <div class="listingblock">
 710 <div class="content"><!-- Generator: GNU source-highlight 2.4
 711 by Lorenzo Bettini
 712 http://www.lorenzobettini.it
 713 http://www.gnu.org/software/src-highlite -->
 714 <pre><tt><span style="font-weight: bold"><span style="color: #0000FF">function</span></span> <span style="font-weight: bold"><span style="color: #000000">MyObj:reflect_x</span></span><span style="color: #990000">()</span>
 715   self<span style="color: #990000">.</span>heading <span style="color: #990000">=</span> <span style="color: #990000">(-</span><span style="color: #993399">1</span> <span style="color: #990000">*</span> self<span style="color: #990000">.</span>heading<span style="color: #990000">)</span> <span style="color: #990000">+</span> <span style="color: #993399">180</span>
 716   self<span style="color: #990000">.</span>heading <span style="color: #990000">=</span> self<span style="color: #990000">.</span>heading <span style="color: #990000">%</span> <span style="color: #993399">360</span>
 717 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
 718
 719 <span style="font-weight: bold"><span style="color: #0000FF">function</span></span> <span style="font-weight: bold"><span style="color: #000000">MyObj:reflect_y</span></span><span style="color: #990000">()</span>
 720   self<span style="color: #990000">.</span>heading <span style="color: #990000">=</span> <span style="color: #990000">-</span><span style="color: #993399">1</span> <span style="color: #990000">*</span> self<span style="color: #990000">.</span>heading
 721   self<span style="color: #990000">.</span>heading <span style="color: #990000">=</span> self<span style="color: #990000">.</span>heading <span style="color: #990000">%</span> <span style="color: #993399">360</span>
 722 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
 723
 724 <span style="font-weight: bold"><span style="color: #0000FF">function</span></span> <span style="font-weight: bold"><span style="color: #000000">MyObj:update</span></span><span style="color: #990000">(</span>delta<span style="color: #990000">)</span>
 725   Object<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">update</span></span><span style="color: #990000">(</span>self<span style="color: #990000">,</span> delta<span style="color: #990000">)</span>
 726
 727   <span style="font-style: italic"><span style="color: #9A1900">--this code is what makes it bounce</span></span>
 728   <span style="font-weight: bold"><span style="color: #0000FF">local</span></span> cx<span style="color: #990000">,</span> cy <span style="color: #990000">=</span> Object<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">get_center</span></span><span style="color: #990000">(</span>self<span style="color: #990000">)</span>
 729
 730   <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> cx <span style="color: #990000">&lt;=</span> <span style="color: #993399">0</span> <span style="font-weight: bold"><span style="color: #0000FF">then</span></span>
 731     self<span style="color: #990000">.</span>x <span style="color: #990000">=</span> <span style="color: #993399">0</span> <span style="color: #990000">-</span> math<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">floor</span></span><span style="color: #990000">(</span>self<span style="color: #990000">.</span>w<span style="color: #990000">/</span><span style="color: #993399">2</span><span style="color: #990000">)</span>
 732     <span style="font-weight: bold"><span style="color: #000000">self:reflect_x</span></span><span style="color: #990000">()</span>
 733   <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
 734
 735   <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> cx <span style="color: #990000">&gt;=</span> s_width <span style="font-weight: bold"><span style="color: #0000FF">then</span></span>
 736     self<span style="color: #990000">.</span>x <span style="color: #990000">=</span> s_width <span style="color: #990000">-</span> math<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">floor</span></span><span style="color: #990000">(</span>self<span style="color: #990000">.</span>w<span style="color: #990000">/</span><span style="color: #993399">2</span><span style="color: #990000">)</span>
 737     <span style="font-weight: bold"><span style="color: #000000">self:reflect_x</span></span><span style="color: #990000">()</span>
 738   <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
 739
 740   <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> cy <span style="color: #990000">&lt;=</span> <span style="color: #993399">0</span> <span style="font-weight: bold"><span style="color: #0000FF">then</span></span>
 741     self<span style="color: #990000">.</span>y <span style="color: #990000">=</span> <span style="color: #993399">0</span> <span style="color: #990000">-</span> math<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">floor</span></span><span style="color: #990000">(</span>self<span style="color: #990000">.</span>h<span style="color: #990000">/</span><span style="color: #993399">2</span><span style="color: #990000">)</span>
 742     <span style="font-weight: bold"><span style="color: #000000">self:reflect_y</span></span><span style="color: #990000">()</span>
 743   <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
 744
 745   <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> cy <span style="color: #990000">&gt;=</span> s_height <span style="font-weight: bold"><span style="color: #0000FF">then</span></span>
 746     self<span style="color: #990000">.</span>y <span style="color: #990000">=</span> s_height <span style="color: #990000">-</span> math<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">floor</span></span><span style="color: #990000">(</span>self<span style="color: #990000">.</span>h<span style="color: #990000">/</span><span style="color: #993399">2</span><span style="color: #990000">)</span>
 747     <span style="font-weight: bold"><span style="color: #000000">self:reflect_y</span></span><span style="color: #990000">()</span>
 748   <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
 749 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
 750 </tt></pre></div></div>
 751 <p>For the purpose of reducing clutter, we've also added two methods to handle
 752 angle of reflection.</p>
 753 <p>For now, we're done with <strong>MyObj</strong>. We'll be coming back to it shortly.</p>
 754 </div>
 755 <h2>4. Putting it Together</h2>
 756 <div class="sectionbody">
 757 <h3>4.1. Making a MyObj</h3>
 758 <p>Now that we've got a basic object, we're going to actually do something with it.
 759 So, we need to create one and add it to the main game loop. Place the following
 760 code somewhere above the loop.</p>
 761 <div class="listingblock">
 762 <div class="content"><!-- Generator: GNU source-highlight 2.4
 763 by Lorenzo Bettini
 764 http://www.lorenzobettini.it
 765 http://www.gnu.org/software/src-highlite -->
 766 <pre><tt><span style="font-style: italic"><span style="color: #9A1900">--create a MyObj</span></span>
 767 mo <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">MyObj:new</span></span><span style="color: #990000">()</span>
 768 math<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">randomseed</span></span><span style="color: #990000">(</span>os<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">time</span></span><span style="color: #990000">())</span>
 769 mo<span style="color: #990000">.</span>heading <span style="color: #990000">=</span> math<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">random</span></span><span style="color: #990000">(</span><span style="color: #993399">15</span><span style="color: #990000">,</span><span style="color: #993399">75</span><span style="color: #990000">)</span> <span style="font-style: italic"><span style="color: #9A1900">-- prevent shallow angles</span></span>
 770 mo<span style="color: #990000">.</span>speed <span style="color: #990000">=</span> <span style="color: #993399">3</span>
 771 mo<span style="color: #990000">.</span>angular_velocity <span style="color: #990000">=</span> <span style="color: #993399">8</span>
 772 </tt></pre></div></div>
 773 <p>What this does, is create a new object, assign a random heading to it, give it a
 774 speed of 3 pixels per frame, and an angular velocity of 8 degrees per frame.
 775 Angular velocity is how fast the image will rotate.</p>
 776 <div class="admonitionblock">
 777 <table><tr>
 778 <td class="icon">
 779 <img src="./images/icons/note.png" alt="Note" />
 780 </td>
 781 <td class="content">
 782 <div class="title">About Rotation</div>
 783 <p>When rotating an image, if it is a transparent PNG, it needs to be 32-bit, otherwise
 784 there will be an ugly background that rotates along with it.</p>
 785 </td>
 786 </tr></table>
 787 </div>
 788 <p>If you were to run the game now, nothing would happen. That's because the object
 789 isn't being drawn to the screen. By adding three lines in the main game loop, we
 790 can remedy this.</p>
 791 <div class="listingblock">
 792 <div class="content"><!-- Generator: GNU source-highlight 2.4
 793 by Lorenzo Bettini
 794 http://www.lorenzobettini.it
 795 http://www.gnu.org/software/src-highlite -->
 796 <pre><tt>  <span style="font-weight: bold"><span style="color: #000000">mo:update</span></span><span style="color: #990000">()</span>
 797   <span style="font-weight: bold"><span style="color: #000000">mo:draw</span></span><span style="color: #990000">()</span>
 798   <span style="font-weight: bold"><span style="color: #000000">update_screen</span></span><span style="color: #990000">()</span>
 799 </tt></pre></div></div>
 800 <p>The first line updates the object, the second draws it, and the third updates
 801 the screen so that everything that was drawn is visible. If we didn't update the
 802 screen then it would stay black and that's not very fun at all.</p>
 803 <p>Running the code now should produce something that vaguely resembles modern art.
 804 This isn't really what we wanted. We wanted just the object, not the trail it
 805 leaves (however pretty). So, we need to add a line to the game loop before we
 806 draw the object to clear the screen to black.</p>
 807 <div class="listingblock">
 808 <div class="content"><!-- Generator: GNU source-highlight 2.4
 809 by Lorenzo Bettini
 810 http://www.lorenzobettini.it
 811 http://www.gnu.org/software/src-highlite -->
 812 <pre><tt>  <span style="font-weight: bold"><span style="color: #000000">fill_screen</span></span><span style="color: #990000">(</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">)</span>
 813 </tt></pre></div></div>
 814 <h3>4.2. Making Many MyObj's</h3>
 815 <p>Now that we've made one, why not make a few more? The <em>main.lua</em> should now look
 816 like the code below.</p>
 817 <div class="listingblock">
 818 <div class="content"><!-- Generator: GNU source-highlight 2.4
 819 by Lorenzo Bettini
 820 http://www.lorenzobettini.it
 821 http://www.gnu.org/software/src-highlite -->
 822 <pre><tt>evman<span style="color: #990000">.</span>quit <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #0000FF">function</span></span> <span style="color: #990000">()</span> done <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
 823 evman<span style="color: #990000">.</span>keyboard<span style="color: #990000">.</span>pressed<span style="color: #990000">[</span>Keys<span style="color: #990000">.</span>ESCAPE<span style="color: #990000">]</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #0000FF">function</span></span><span style="color: #990000">()</span> done <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
 824
 825 <span style="font-style: italic"><span style="color: #9A1900">--controls main game loop</span></span>
 826 done <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #0000FF">false</span></span>
 827
 828 fps <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">FPSManager:new</span></span><span style="color: #990000">()</span> <span style="font-style: italic"><span style="color: #9A1900">-- create the FPSManager object</span></span>
 829 <span style="font-weight: bold"><span style="color: #000000">fps:set_fps</span></span><span style="color: #990000">(</span><span style="color: #993399">30</span><span style="color: #990000">)</span> <span style="font-style: italic"><span style="color: #9A1900">-- set the FPS to 30</span></span>
 830
 831 <span style="font-style: italic"><span style="color: #9A1900">--create a MyObj</span></span>
 832 mo <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">MyObj:new</span></span><span style="color: #990000">()</span>
 833 math<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">randomseed</span></span><span style="color: #990000">(</span>os<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">time</span></span><span style="color: #990000">())</span>
 834 mo<span style="color: #990000">.</span>heading <span style="color: #990000">=</span> math<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">random</span></span><span style="color: #990000">(</span><span style="color: #993399">15</span><span style="color: #990000">,</span><span style="color: #993399">80</span><span style="color: #990000">)</span> <span style="font-style: italic"><span style="color: #9A1900">-- prevent shallow angles</span></span>
 835 mo<span style="color: #990000">.</span>speed <span style="color: #990000">=</span> <span style="color: #993399">3</span>
 836 mo<span style="color: #990000">.</span>angular_velocity <span style="color: #990000">=</span> <span style="color: #993399">5</span>
 837
 838 <span style="font-style: italic"><span style="color: #9A1900">--create another MyObj</span></span>
 839 mo1 <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">MyObj:new</span></span><span style="color: #990000">()</span>
 840 mo1<span style="color: #990000">.</span>heading <span style="color: #990000">=</span> math<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">random</span></span><span style="color: #990000">(</span><span style="color: #993399">15</span><span style="color: #990000">,</span><span style="color: #993399">80</span><span style="color: #990000">)</span>
 841 mo1<span style="color: #990000">.</span>speed <span style="color: #990000">=</span> <span style="color: #993399">3</span>
 842 mo1<span style="color: #990000">.</span>angular_velocity <span style="color: #990000">=</span> <span style="color: #993399">5</span>
 843
 844 <span style="font-style: italic"><span style="color: #9A1900">--create yet another MyObj</span></span>
 845 mo2 <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">MyObj:new</span></span><span style="color: #990000">()</span>
 846 mo2<span style="color: #990000">.</span>heading <span style="color: #990000">=</span> math<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">random</span></span><span style="color: #990000">(</span><span style="color: #993399">15</span><span style="color: #990000">,</span><span style="color: #993399">80</span><span style="color: #990000">)</span>
 847 mo2<span style="color: #990000">.</span>speed <span style="color: #990000">=</span> <span style="color: #993399">3</span>
 848 mo2<span style="color: #990000">.</span>angular_velocity <span style="color: #990000">=</span> <span style="color: #993399">5</span>
 849
 850 <span style="font-style: italic"><span style="color: #9A1900">--main game loop</span></span>
 851 <span style="font-weight: bold"><span style="color: #0000FF">while</span></span> done <span style="color: #990000">~=</span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span> <span style="font-weight: bold"><span style="color: #0000FF">do</span></span>
 852   <span style="font-weight: bold"><span style="color: #000000">evman:gather_events</span></span><span style="color: #990000">()</span>
 853
 854   <span style="font-weight: bold"><span style="color: #000000">mo:update</span></span><span style="color: #990000">()</span>
 855   <span style="font-weight: bold"><span style="color: #000000">mo1:update</span></span><span style="color: #990000">()</span>
 856   <span style="font-weight: bold"><span style="color: #000000">mo2:update</span></span><span style="color: #990000">()</span>
 857
 858   <span style="font-weight: bold"><span style="color: #000000">fill_screen</span></span><span style="color: #990000">(</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">)</span>
 859
 860   <span style="font-weight: bold"><span style="color: #000000">mo:draw</span></span><span style="color: #990000">()</span>
 861   <span style="font-weight: bold"><span style="color: #000000">mo1:draw</span></span><span style="color: #990000">()</span>
 862   <span style="font-weight: bold"><span style="color: #000000">mo2:draw</span></span><span style="color: #990000">()</span>
 863
 864   <span style="font-weight: bold"><span style="color: #000000">update_screen</span></span><span style="color: #990000">()</span>
 865   <span style="font-weight: bold"><span style="color: #000000">fps:update</span></span><span style="color: #990000">()</span> <span style="font-style: italic"><span style="color: #9A1900">-- delay to ensure proper FPS</span></span>
 866 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
 867 </tt></pre></div></div>
 868 <p>When the game is run, three <strong>MyObj</strong>'s will be bouncing around the screen. This is
 869 certainly not a game (yet) and for the purposes of this tutorial, it won't be.
 870 Yeah, sorry about that. This tutorial's just to familiarize one with the basics
 871 of LuaGame.</p>
 872 <h3>4.3. Organization Through ObjectList</h3>
 873 <p>We have three <strong>MyObj</strong>'s now, and if we wanted to add more, the main loop would become
 874 cluttered pretty quickly. So, there's a very useful and flexible class called the
 875 <strong>ObjectList</strong>. It is basically a list that stores anything, but it has convenience
 876 methods for <strong>Object</strong>'s for updating and drawing. It also makes doing collision
 877 detection between a large number of objects much easier.</p>
 878 <p>So, we need to create an <strong>ObjectList</strong> and add the three objects to it. Add this
 879 code after the declaration of the three objects.</p>
 880 <div class="listingblock">
 881 <div class="content"><!-- Generator: GNU source-highlight 2.4
 882 by Lorenzo Bettini
 883 http://www.lorenzobettini.it
 884 http://www.gnu.org/software/src-highlite -->
 885 <pre><tt><span style="font-style: italic"><span style="color: #9A1900">--create an ObjectList</span></span>
 886 olist <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ObjectList:new</span></span><span style="color: #990000">()</span>
 887 <span style="font-weight: bold"><span style="color: #000000">olist:push_back</span></span><span style="color: #990000">(</span>mo<span style="color: #990000">)</span>
 888 <span style="font-weight: bold"><span style="color: #000000">olist:push_back</span></span><span style="color: #990000">(</span>mo1<span style="color: #990000">)</span>
 889 <span style="font-weight: bold"><span style="color: #000000">olist:push_back</span></span><span style="color: #990000">(</span>mo2<span style="color: #990000">)</span>
 890 </tt></pre></div></div>
 891 <p>Now, replace the three update calls with:</p>
 892 <div class="listingblock">
 893 <div class="content"><!-- Generator: GNU source-highlight 2.4
 894 by Lorenzo Bettini
 895 http://www.lorenzobettini.it
 896 http://www.gnu.org/software/src-highlite -->
 897 <pre><tt>  <span style="font-weight: bold"><span style="color: #000000">olist:update</span></span><span style="color: #990000">()</span>
 898 </tt></pre></div></div>
 899 <p>And replace the draw calls with:</p>
 900 <div class="listingblock">
 901 <div class="content"><!-- Generator: GNU source-highlight 2.4
 902 by Lorenzo Bettini
 903 http://www.lorenzobettini.it
 904 http://www.gnu.org/software/src-highlite -->
 905 <pre><tt>  <span style="font-weight: bold"><span style="color: #000000">olist:draw</span></span><span style="color: #990000">()</span>
 906 </tt></pre></div></div>
 907 <p>With that, one now knows the basics of the ObjectList. If one has ever used a C++
 908 STL list, the methods are basically the same.</p>
 909 <h3>4.4. Silly Collision Detection</h3>
 910 <p>This is the last part of the tutorial, and it deals lightly with collision detection
 911 in a very silly example. Since we actually want to have something happen when
 912 two <strong>MyObj</strong>'s collide, we need to add a method to the definition.</p>
 913 <div class="listingblock">
 914 <div class="content"><!-- Generator: GNU source-highlight 2.4
 915 by Lorenzo Bettini
 916 http://www.lorenzobettini.it
 917 http://www.gnu.org/software/src-highlite -->
 918 <pre><tt><span style="font-style: italic"><span style="color: #9A1900">--silly</span></span>
 919 <span style="font-weight: bold"><span style="color: #0000FF">function</span></span> <span style="font-weight: bold"><span style="color: #000000">MyObj:collide</span></span><span style="color: #990000">(</span>ids<span style="color: #990000">,</span> object<span style="color: #990000">)</span>
 920   <span style="font-weight: bold"><span style="color: #000000">print</span></span><span style="color: #990000">(</span><span style="color: #FF0000">"Ouch! You hit me, "</span><span style="color: #990000">..</span>object<span style="color: #990000">.</span>type<span style="color: #990000">..</span><span style="color: #FF0000">" at "</span><span style="color: #990000">..</span>os<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">time</span></span><span style="color: #990000">()..</span><span style="color: #FF0000">"!"</span><span style="color: #990000">)</span>
 921 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
 922 </tt></pre></div></div>
 923 <p>This will print out a silly message when two objects collide. However, nothing's
 924 going to happen yet, at least not until we add a collision check to the main loop.
 925 Add it right before the update call.</p>
 926 <div class="listingblock">
 927 <div class="content"><!-- Generator: GNU source-highlight 2.4
 928 by Lorenzo Bettini
 929 http://www.lorenzobettini.it
 930 http://www.gnu.org/software/src-highlite -->
 931 <pre><tt>  <span style="font-weight: bold"><span style="color: #000000">check_collisions_lists</span></span><span style="color: #990000">(</span>olist<span style="color: #990000">,</span> olist<span style="color: #990000">)</span>
 932 </tt></pre></div></div>
 933 <p>Remember way back when we defined the <strong>MyObj</strong> class? We defined the <em>rects</em> property
 934 to be an empty <strong>ObjectList</strong>. This is because we only want to deal with the overall
 935 bounding box, and <strong>MyObj</strong> doesn't have any bounding sub-rectangles.</p>
 936 <div class="admonitionblock">
 937 <table><tr>
 938 <td class="icon">
 939 <img src="./images/icons/tip.png" alt="Tip" />
 940 </td>
 941 <td class="content">
 942 <div class="title">Less Silly Collisions</div>
 943 <p>As an exercise to the reader, implement the objects bouncing off each other.
 944 This will require looking at more than the type of the object that has collided.
 945 Also, for the sake of having professional looking bounces, one can do a great
 946 deal of code to handle objects that are intersecting, or just move their starting
 947 positions so that they don't intersect.</p>
 948 </td>
 949 </tr></table>
 950 </div>
 951 <h3>4.5. The unload() Method</h3>
 952 <p>The Object class defines a method called unload(). This method has undefined
 953 behavior for the Object class itself. However, it's something that one should
 954 use if they plan on making a game with multiple objects/enemies/etc&#8230; that are
 955 not all needed at the same time. An example of this method for the object we
 956 created before is below.</p>
 957 <div class="listingblock">
 958 <div class="content"><!-- Generator: GNU source-highlight 2.4
 959 by Lorenzo Bettini
 960 http://www.lorenzobettini.it
 961 http://www.gnu.org/software/src-highlite -->
 962 <pre><tt><span style="font-weight: bold"><span style="color: #0000FF">function</span></span> <span style="font-weight: bold"><span style="color: #000000">MyObj:unload</span></span><span style="color: #990000">()</span>
 963         <span style="font-style: italic"><span style="color: #9A1900">--unload the image</span></span>
 964         <span style="font-weight: bold"><span style="color: #000000">release_image</span></span><span style="color: #990000">(</span><span style="color: #FF0000">"data/images/wikilogo.png"</span><span style="color: #990000">)</span>
 965         MyObj <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #0000FF">nil</span></span>
 966 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
 967 </tt></pre></div></div>
 968 <p>Basically, the image for the object is unloaded and then the class itself is set
 969 to nil and it will be garbage collected. One has to remember never to call this
 970 method unless all objects of the same type as the class have been destroyed and
 971 won't have methods or properties called on them. Otherwise, it will result in an
 972 error being thrown. Since this tutorial is small, this method is unneeded and
 973 isn't actually included.</p>
 974 </div>
 975 <h2>5. End</h2>
 976 <div class="sectionbody">
 977 <p>That's it. One should now have a good enough understanding to be able to make
 978 some small games, and with a little more exploration, it should be easy to make
 979 much larger things. Oh, and now that one knows how to do the basic setup of a
 980 game, the livecode template in the <em>demos</em> directory provides a nice template
 981 for a simple game.</p>
 982 </div>
 983 <div id="footer">
 984 <div id="footer-text">
 985 Last updated 09-Jan-2008 19:32:55 EDT
 986 </div>
 987 </div>
 988 </body>
 989 </html>