docs/scripting/scripting.xml

   1 <?xml version='1.0' ?>
   2 <!--
   3 $Id$
   4
   5 SuperTux Documentation
   6 Copyright (C) 2005 Ondra Hosek <ondra.hosek@gmail.com>
   7
   8 This document is free; you can redistribute it and/or modify
   9 it under the terms of the GNU General Public License as
  10 published by the Free Software Foundation; either version 2
  11 of the License, or (at your option) any later version.
  12
  13 This document is distributed in the hope that it will be useful,
  14 but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 GNU General Public License for more details.
  17
  18 You should have received a copy of the GNU General Public License
  19 along with this program (see the file named 'COPYING'); if not,
  20 write to the Free Software Foundation, Inc., 59 Temple Place -
  21 Suite 330, Boston, MA 02111-1307, USA.
  22
  23 -->
  24 <!--<?xml-stylesheet type="text/xsl" href="/home/ondra/src/docbook-xsl-1.68.1/xhtml/docbook.xsl" ?>-->
  25 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.3//EN"
  26 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
  27
  28 <article xml:lang="en">
  29
  30 <articleinfo>
  31 <title>SuperTux Scripting Documentation</title>
  32 <author><firstname>Ondra</firstname><surname>Hosek</surname></author>
  33 </articleinfo>
  34 <para>Since May 2005, SuperTux sports a Squirrel scripting interface useful for level designers who want to add some interactive pep to their levels. This document poses as a reference article for those who want to explore the various objects of the SuperTux scripting model.</para>
  35 <sect1><title>What is Squirrel?</title>
  36 <para>One of your first questions might be, &quot;What does a rodent have to do
  37 with a penguin?&quot; <ulink url="http://squirrel.sourceforge.net/">Squirrel</ulink> is a language with a syntax not much unlike other C-like languages (C, C++, Java, ...). In the current implementation, it is integrated as elements in the SuperTux level files.</para>
  38 </sect1>
  39 <sect1><title>Squirrel, Scheme and SuperTux</title>
  40 <para>I have no clue if the developers simply chose Squirrel just because the name so nicely integrates into the series of words &quot;SuperTux&quot; and &quot;Scheme&quot;. Currently, the Squirrel code is integrated in string arguments of Scheme elements in SuperTux level files. (Whew.) This is an example code block inside a level:
  41 <programlisting>(supertux-level
  42   (version 2)
  43   (name _("Go Blind"))
  44   (author "Team")
  45   (sector
  46     (name "main")
  47     (music "Annoying_penguin_gawking_sounds.mod")
  48
  49     ;; (Tilemaps, objects, whatever.)
  50
  51     (init-script "
  52 DisplayEffect.fade_out(2.5);
  53 ")
  54   )
  55 )</programlisting>
  56 When this level loads, the screen fades out completely during two and a half seconds right after the level is loaded. (Mind you, this would be a frustrating experience for the player if you add a horde of badguys near the spawn point.)</para>
  57 </sect1>
  58
  59 <sect1><title>Object reference</title>
  60 <para>If you are interested in an object and what cans of worms you can open with it, this section is for you.</para>
  61 <para>&quot;(NYI)&quot; after the function name symbolises functions that haven't been implemented yet. Calling them will result in a line being printed to standard output informing anybody who reads it that the script is using a function that actually doesn't exist. (Win32 users will happily ignore this, because they simply start the application by opening it with Explorer. Unix users are going to be more interested in what SuperTux can actually tell them, so it's better if you don't use non-existent functions in your scripts.)</para>
  62
  63 <sect2><title>Global Functions</title>
  64 <para>These global functions access basic or generic methods of SuperTux. They are called without an object name.</para>
  65
  66 <sect3><title>display_text_file</title>
  67 <para>Usage: <code>display_text_file(string filename)</code></para>
  68 <para>Effect: Displays the SuperTux text file named <code>filename</code>. (The path is relative to the level file.)</para>
  69 <para>See also: SuperTux file format reference, SuperTux texts</para>
  70 </sect3>
  71
  72 <sect3><title>set_wakeup_time</title>
  73 <para>Usage: <code>set_wakeup_time(float waketime)</code></para>
  74 <para>Effect: When used before a call to <code>suspend()</code>, the script only stays suspended for <code>waketime</code> seconds.</para>
  75 </sect3>
  76
  77 <sect3><title>translate</title>
  78 <para>Usage: <code>translate(string text)</code></para>
  79 <para>Returns: Translated string</para>
  80 <para>Effect: Translates <code>text</code> into the user's locale.</para>
  81 <para>Note: This construct is not yet recognised by XGetText, and so is subject to change.</para>
  82 </sect3>
  83
  84 </sect2>
  85
  86 <sect2><title>DisplayEffect</title>
  87 <para><code>DisplayEffect</code> is an interface for toying with the display.</para>
  88
  89 <sect3><title>fade_out</title>
  90 <para>Usage: <code>DisplayEffect.fade_out(float fadetime)</code></para>
  91 <para>Effect: Gradually fades out the screen to black for the next <code>fadetime</code> seconds.</para>
  92 </sect3>
  93
  94 <sect3><title>fade_in</title>
  95 <para>Usage: <code>DisplayEffect.fade_in(float fadetime)</code></para>
  96 <para>Effect: Gradually fades in the screen from black for the next <code>fadetime</code> seconds.</para>
  97 </sect3>
  98
  99 <sect3><title>set_black</title>
 100 <para>Usage: <code>DisplayEffect.set_black(bool black)</code></para>
 101 <para>Effect: Blackens or un-blackens the screen (depending on the value of <code>black</code>).</para>
 102 </sect3>
 103
 104 <sect3><title>is_black</title>
 105 <para>Usage: <code>DisplayEffect.is_black()</code></para>
 106 <para>Returns: <code>bool</code></para>
 107 <para>Effect: Returns true if the screen has been blackened by <code>set_black</code>. Calling <code>fade_in</code> or <code>fade_out</code> resets the return value to <code>false</code>.</para>
 108 </sect3>
 109
 110 </sect2>
 111
 112 <sect2><title>Camera</title>
 113 <para><code>Camera</code> is an interface to manipulate the camera.</para>
 114
 115 <sect3><title>shake (NYI)</title>
 116 <para>Usage: <code>Camera.shake(float time, float x, float y)</code></para>
 117 <para>Warning: This function has not yet been implemented.</para>
 118 </sect3>
 119
 120 <sect3><title>set_pos (NYI)</title>
 121 <para>Usage: <code>Camera.set_pos(float x, float y)</code></para>
 122 <para>Warning: This function has not yet been implemented.</para>
 123 </sect3>
 124
 125 <sect3><title>set_mode (NYI)</title>
 126 <para>Usage: <code>Camera.set_mode(string modestring)</code></para>
 127 <para>Warning: This function has not yet been implemented.</para>
 128 </sect3>
 129
 130 </sect2>
 131
 132 <sect2><title>Level</title>
 133 <para>The <code>Level</code> class provides pretty basic controlling functions for the current level.</para>
 134
 135 <sect3><title>finish</title>
 136 <para>Usage: <code>Level.finish()</code></para>
 137 <para>Effect: Ends the current level and marks it as completed if launched from a worldmap.</para>
 138 <para>Tip: Very useful if you have created a frustrating level and want to, at some point, save the player from agony.</para>
 139 </sect3>
 140
 141 <sect3><title>spawn</title>
 142 <para>Usage: <code>Level.spawn(string sectorname, string spawnpointname)</code></para>
 143 <para>Effect: Respawns Tux in the sector <code>sectorname</code> at the <code>spawnpointname</code> spawnpoint.</para>
 144 <para>Exceptions: If <code>sectorname</code> or <code>spawnpointname</code> are empty or the specified sector does not exist, the function will bail out first chance it gets. If the specified spawnpoint doesn't exist, Tux will be spawned at the spawnpoint named <code>main</code>. If this spawnpoint doesn't exist either, Tux will simply end up at the origin (top-left 0, 0).</para>
 145 </sect3>
 146
 147 </sect2>
 148
 149 <sect2><title>ScriptedObject</title>
 150 <para>A <code>ScriptedObject</code> is basically a SuperTux object that can be scripted to move around and animate. This object will be used in the SuperTux cutscenes a whole lot.</para>
 151
 152 <sect3><title>Usage notes</title>
 153 <para>Since a <code>ScriptedObject</code> is a reference object and not an active object, you will have to build it into your level file, where a <code>scriptedobject</code> is a child of <code>sector</code>. This is an example definition:
 154 <programlisting>
 155 (scripted-object
 156   (name "WOOT")
 157   (x 420)
 158   (y 94)
 159   (sprite "snowball")
 160   (solid #t)
 161   (physic-enabled #f)
 162   (visible #t)
 163 )
 164 </programlisting>
 165 </para>
 166 <para>Now, the object can be accessed in code using the <code>WOOT</code> identifier like so:
 167 <programlisting>
 168 WOOT.set_animation("left");
 169 </programlisting>
 170 </para>
 171 </sect3>
 172
 173 <sect3><title>set_animation</title>
 174 <para>Usage: <code>&lt;scriptedobject&gt;.set_animation(string animation_name)</code></para>
 175 <para>Effect: Activates the sprite's animation specified in <code>animation_name</code>.</para>
 176 </sect3>
 177
 178 <sect3><title>get_animation</title>
 179 <para>Usage: <code>&lt;scriptedobject&gt;.get_animation()</code></para>
 180 <para>Returns: <code>string</code></para>
 181 <para>Effect: Returns the name of the sprite's current animation.</para>
 182 </sect3>
 183
 184 <sect3><title>move</title>
 185 <para>Usage: <code>&lt;scriptedobject&gt;.move(float x, float y)</code></para>
 186 <para>Effect: Moves the object by <code>x</code> units to the right and <code>y</code> down <emphasis>relative to its current position</emphasis>.</para>
 187 </sect3>
 188
 189 <sect3><title>set_pos</title>
 190 <para>Usage: <code>&lt;scriptedobject&gt;.set_pos(float x, float y)</code></para>
 191 <para>Effect: Basically identical to <code>move</code>, except its <emphasis>relativity to the sector origin</emphasis>.</para>
 192 </sect3>
 193
 194 <sect3><title>get_pos_x</title>
 195 <para>Usage: <code>&lt;scriptedobject&gt;.get_pos_x()</code></para>
 196 <para>Returns: <code>float</code></para>
 197 <para>Effect: Returns the X coordinate of the object's position.</para>
 198 </sect3>
 199
 200 <sect3><title>get_pos_y</title>
 201 <para>Usage: <code>&lt;scriptedobject&gt;.get_pos_y()</code></para>
 202 <para>Returns: <code>float</code></para>
 203 <para>Effect: Totally identical to <code>get_pos_x</code> except for its obvious choice of the other (Y) axis.</para>
 204 </sect3>
 205
 206 <sect3><title>set_velocity</title>
 207 <para>Usage: <code>&lt;scriptedobject&gt;.set_velocity(float x, float y)</code></para>
 208 <para>Effect: Makes the object move in a certain direction (with a certain speed) given by the <code>x</code> and <code>y</code> coordinates.</para>
 209 </sect3>
 210
 211 <sect3><title>get_velocity_x</title>
 212 <para>Usage: <code>&lt;scriptedobject&gt;.get_velocity_x()</code></para>
 213 <para>Returns: <code>float</code></para>
 214 <para>Effect: Returns the object's velocity in the direction of the X coordinate.</para>
 215 </sect3>
 216
 217 <sect3><title>get_velocity_y</title>
 218 <para>Usage: <code>&lt;scriptedobject&gt;.get_velocity_y()</code></para>
 219 <para>Returns: <code>float</code></para>
 220 <para>Effect: The difference between this function and <code>get_velocity_x</code> is just the same like between <code>get_pos_y</code> and <code>get_pos_x</code>: same thing, different coordinates.</para>
 221 </sect3>
 222
 223 <sect3><title>set_visible</title>
 224 <para>Usage: <code>&lt;scriptedobject&gt;.set_visible(bool visible)</code></para>
 225 <para>Effect: Shows or hides the object according to the value of <code>visible</code>.</para>
 226 </sect3>
 227
 228 <sect3><title>is_visible</title>
 229 <para>Usage: <code>&lt;scriptedobject&gt;.is_visible()</code></para>
 230 <para>Returns: <code>bool</code></para>
 231 <para>Effect: Returns <code>true</code> if the object is visible. (You've seen this coming, haven't you?)</para>
 232 </sect3>
 233
 234 <sect3><title>get_name</title>
 235 <para>Usage: <code>&lt;scriptedobject&gt;.get_name()</code></para>
 236 <para>Returns: <code>string</code></para>
 237 <para>Effect: Simply gives you the name of the scripted object (as if you didn't have it already...)</para>
 238 </sect3>
 239
 240 </sect2>
 241
 242 <sect2><title>Sound</title>
 243 <para>This class provides a very simple interface to the audio subsystem.</para>
 244
 245 <sect3><title>play_music (NYI)</title>
 246 <para>Usage: <code>Sound.play_music(string ???)</code></para>
 247 <para>Warning: This function has not yet been implemented.</para>
 248 </sect3>
 249
 250 <sect3><title>play_sound</title>
 251 <para>Usage: <code>Sound.play_sound(string sound_name)</code></para>
 252 <para>Effect: Plays the sound specified in <code>sound_name</code> (that is identical to the filename of the sound without the <code>.wav</code> extension).</para>
 253 </sect3>
 254
 255 </sect2>
 256
 257 <sect2><title>Text</title>
 258 <para>This module provides access to methods reponsible for displaying text on-screen.</para>
 259
 260 <sect3><title>set_text</title>
 261 <para>Usage: <code>Text.set_text(string text)</code></para>
 262 <para>Effect: Sets the text string to be displayed to <code>text</code>.</para>
 263 </sect3>
 264
 265 <sect3><title>set_font</title>
 266 <para>Usage: <code>Text.set_font(string font)</code></para>
 267 <para>Effect: Sets the font of the text to be displayed to <code>text</code>. Currently valid values are <code>gold</code>, <code>white</code>, <code>blue</code>, <code>gray</code>, <code>big</code> and <code>small</code>.</para>
 268 </sect3>
 269
 270 <sect3><title>fade_in</title>
 271 <para>Usage: <code>Text.fade_in(float time)</code></para>
 272 <para>Effect: Fades in the specified text for the next <code>time</code> seconds.</para>
 273 </sect3>
 274
 275 <sect3><title>fade_out</title>
 276 <para>Usage: <code>Text.fade_out(float time)</code></para>
 277 <para>Effect: Just the opposite of <code>fade_out</code>.</para>
 278 </sect3>
 279
 280 <sect3><title>set_visible</title>
 281 <para>Usage: <code>Text.set_visible(bool visible)</code></para>
 282 <para>Effect: Shows or hides the text abruptly (drastic counterpart to <code>fade_in</code> and <code>fade_out</code>).</para>
 283 </sect3>
 284
 285 </sect2>
 286
 287 </sect1>
 288
 289 </article>