-->
<!--<?xml-stylesheet type="text/xsl" href="/home/ondra/src/docbook-xsl-1.68.1/xhtml/docbook.xsl" ?>-->
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V5.0/EN" "http://www.oasis-open.org/docbook/xml/5.0/docbook.dtd">
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.3//EN"
+"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<article xml:lang="en">
-<artheader>
+<articleinfo>
<title>SuperTux Scripting Documentation</title>
<author><firstname>Ondra</firstname><surname>Hosek</surname></author>
-</artheader>
+</articleinfo>
<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>
<sect1><title>What is Squirrel?</title>
-<para>One of your first questions might be, "What does a rodent have to do with a penguin?" <link xlink:href="http://squirrel.sourceforge.net/">Squirrel</link> 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>
+<para>One of your first questions might be, "What does a rodent have to do
+with a penguin?" <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>
</sect1>
<sect1><title>Squirrel, Scheme and SuperTux</title>
<para>I have no clue if the developers simply chose Squirrel just because the name so nicely integrates into the series of words "SuperTux" and "Scheme". 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:
<sect1><title>Object reference</title>
<para>If you are interested in an object and what cans of worms you can open with it, this section is for you.</para>
-<para>"(NYI)" 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 of what SuperTux can actually tell them, so it's better if you don't use non-existent functions in your scripts.)</para>
+<para>"(NYI)" 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>
+
+<sect2><title>Global Functions</title>
+<para>These global functions access basic or generic methods of SuperTux. They are called without an object name.</para>
+
+<sect3><title>display_text_file</title>
+<para>Usage: <code>display_text_file(string filename)</code></para>
+<para>Effect: Displays the SuperTux text file named <code>filename</code>. (The path is relative to the level file.)</para>
+<para>See also: SuperTux file format reference, SuperTux texts</para>
+</sect3>
+
+<sect3><title>set_wakeup_time</title>
+<para>Usage: <code>set_wakeup_time(float waketime)</code></para>
+<para>Effect: When used before a call to <code>suspend()</code>, the script only stays suspended for <code>waketime</code> seconds.</para>
+</sect3>
+
+<sect3><title>translate</title>
+<para>Usage: <code>translate(string text)</code></para>
+<para>Returns: Translated string</para>
+<para>Effect: Translates <code>text</code> into the user's locale.</para>
+<para>Note: This construct is not yet recognised by XGetText, and so is subject to change.</para>
+</sect3>
+
+</sect2>
<sect2><title>DisplayEffect</title>
<para><code>DisplayEffect</code> is an interface for toying with the display.</para>
+
<sect3><title>fade_out</title>
<para>Usage: <code>DisplayEffect.fade_out(float fadetime)</code></para>
<para>Effect: Gradually fades out the screen to black for the next <code>fadetime</code> seconds.</para>
</para>
</sect3>
-<!-- TODO: documentation from this marker on -->
-
<sect3><title>set_animation</title>
-<para></para>
+<para>Usage: <code><scriptedobject>.set_animation(string animation_name)</code></para>
+<para>Effect: Activates the sprite's animation specified in <code>animation_name</code>.</para>
</sect3>
+
<sect3><title>get_animation</title>
-<para></para>
+<para>Usage: <code><scriptedobject>.get_animation()</code></para>
+<para>Returns: <code>string</code></para>
+<para>Effect: Returns the name of the sprite's current animation.</para>
</sect3>
+
<sect3><title>move</title>
-<para></para>
+<para>Usage: <code><scriptedobject>.move(float x, float y)</code></para>
+<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>
</sect3>
+
<sect3><title>set_pos</title>
-<para></para>
+<para>Usage: <code><scriptedobject>.set_pos(float x, float y)</code></para>
+<para>Effect: Basically identical to <code>move</code>, except its <emphasis>relativity to the sector origin</emphasis>.</para>
</sect3>
+
<sect3><title>get_pos_x</title>
-<para></para>
+<para>Usage: <code><scriptedobject>.get_pos_x()</code></para>
+<para>Returns: <code>float</code></para>
+<para>Effect: Returns the X coordinate of the object's position.</para>
</sect3>
+
<sect3><title>get_pos_y</title>
-<para></para>
+<para>Usage: <code><scriptedobject>.get_pos_y()</code></para>
+<para>Returns: <code>float</code></para>
+<para>Effect: Totally identical to <code>get_pos_x</code> except for its obvious choice of the other (Y) axis.</para>
</sect3>
+
<sect3><title>set_velocity</title>
-<para></para>
+<para>Usage: <code><scriptedobject>.set_velocity(float x, float y)</code></para>
+<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>
</sect3>
+
<sect3><title>get_velocity_x</title>
-<para></para>
+<para>Usage: <code><scriptedobject>.get_velocity_x()</code></para>
+<para>Returns: <code>float</code></para>
+<para>Effect: Returns the object's velocity in the direction of the X coordinate.</para>
</sect3>
+
<sect3><title>get_velocity_y</title>
-<para></para>
+<para>Usage: <code><scriptedobject>.get_velocity_y()</code></para>
+<para>Returns: <code>float</code></para>
+<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>
</sect3>
+
<sect3><title>set_visible</title>
-<para></para>
+<para>Usage: <code><scriptedobject>.set_visible(bool visible)</code></para>
+<para>Effect: Shows or hides the object according to the value of <code>visible</code>.</para>
</sect3>
+
<sect3><title>is_visible</title>
-<para></para>
+<para>Usage: <code><scriptedobject>.is_visible()</code></para>
+<para>Returns: <code>bool</code></para>
+<para>Effect: Returns <code>true</code> if the object is visible. (You've seen this coming, haven't you?)</para>
</sect3>
+
<sect3><title>get_name</title>
-<para></para>
+<para>Usage: <code><scriptedobject>.get_name()</code></para>
+<para>Returns: <code>string</code></para>
+<para>Effect: Simply gives you the name of the scripted object (as if you didn't have it already...)</para>
</sect3>
</sect2>
<sect2><title>Sound</title>
+<para>This class provides a very simple interface to the audio subsystem.</para>
+
+<sect3><title>play_music (NYI)</title>
+<para>Usage: <code>Sound.play_music(string ???)</code></para>
+<para>Warning: This function has not yet been implemented.</para>
+</sect3>
+
+<sect3><title>play_sound</title>
+<para>Usage: <code>Sound.play_sound(string sound_name)</code></para>
+<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>
+</sect3>
+
</sect2>
<sect2><title>Text</title>
+<para>This module provides access to methods reponsible for displaying text on-screen.</para>
+
+<sect3><title>set_text</title>
+<para>Usage: <code>Text.set_text(string text)</code></para>
+<para>Effect: Sets the text string to be displayed to <code>text</code>.</para>
+</sect3>
+
+<sect3><title>set_font</title>
+<para>Usage: <code>Text.set_font(string font)</code></para>
+<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>
+</sect3>
+
+<sect3><title>fade_in</title>
+<para>Usage: <code>Text.fade_in(float time)</code></para>
+<para>Effect: Fades in the specified text for the next <code>time</code> seconds.</para>
+</sect3>
+
+<sect3><title>fade_out</title>
+<para>Usage: <code>Text.fade_out(float time)</code></para>
+<para>Effect: Just the opposite of <code>fade_out</code>.</para>
+</sect3>
+
+<sect3><title>set_visible</title>
+<para>Usage: <code>Text.set_visible(bool visible)</code></para>
+<para>Effect: Shows or hides the text abruptly (drastic counterpart to <code>fade_in</code> and <code>fade_out</code>).</para>
+</sect3>
+
</sect2>
</sect1>
projects / supertux.git / blobdiff