This wiki has been moved to https://github.com/SuperTux/wiki into the mediawiki branch.

Difference between revisions of "Scripting reference"

From SuperTux
Jump to: navigation, search
(Added descriptions, removed obsolete stuff)
(Undo revision 13252 by 50.80.139.102 (Talk))
 
(11 intermediate revisions by 3 users not shown)
Line 16: Line 16:
 
     (music "Annoying_penguin_gawking_sounds.ogg")
 
     (music "Annoying_penguin_gawking_sounds.ogg")
  
     ;; (Tilemaps, objects, whatever.)
+
     ;; tilemaps, objects, whatever. (optional)
 +
    ;...
  
 
     (init-script "
 
     (init-script "
DisplayEffect.fade_out(2.5);
+
Effect.fade_out(2.5);
 
")
 
")
 +
 +
    ;; more tilemaps, objects, and whatever. (optional)
 +
    ;...
 +
 
   )
 
   )
 
)</pre>
 
)</pre>
  
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.)
+
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...)
  
 
== Object reference ==
 
== Object reference ==
Line 50: Line 55:
 
! [[ScriptingLevel|Level]]
 
! [[ScriptingLevel|Level]]
 
| Control over the status the game keeps about the current level.
 
| Control over the status the game keeps about the current level.
 +
|-
 +
! [[ScriptingLevelTime|Level time]]
 +
| Scripting interface to level time object
 
|-
 
|-
 
! [[ScriptingScriptedObject|ScriptedObject]]
 
! [[ScriptingScriptedObject|ScriptedObject]]
Line 61: Line 69:
 
|-
 
|-
 
! [[ScriptingPlatform|Platform]]
 
! [[ScriptingPlatform|Platform]]
| Scripting interface to Platform object
+
| Scripting interface to [[Moving platform|Platform]] object
 +
|-
 +
! [[ScriptingTilemap|Tilemap]]
 +
| Scripting interface to [[Tilemap]] object
 
|-
 
|-
 
! [[ScriptingWind|Wind]]
 
! [[ScriptingWind|Wind]]
| Scripting interface to Wind object
+
| Scripting interface to [[Wind]] object
 
|-
 
|-
 
! [[ScriptingCandle|Candle]]
 
! [[ScriptingCandle|Candle]]
Line 70: Line 81:
 
|-
 
|-
 
! [[ScriptingThunderstorm|Thunderstorm]]
 
! [[ScriptingThunderstorm|Thunderstorm]]
| Scripting interface to Thunderstorm object
+
| Scripting interface to [[Thunderstorm]] object
 
|-
 
|-
 
! [[ScriptingAmbientSound|AmbientSound]]
 
! [[ScriptingAmbientSound|AmbientSound]]
 
| Scripting interface to AmbientSound object
 
| Scripting interface to AmbientSound object
 +
|-
 +
! [[ScriptingWill-o-wisp|Will-o-wisp]]
 +
| Scripting interface to [[Will-o-wisp]] object
 +
|-
 +
! [[ScriptingSector|Sector]]
 +
| Scripting interface to the [[Sector]] itself.
 
|-
 
|-
 
|}
 
|}
  
TODO: Convert the rest of the scripting docu to the new format (and improve format maybe?)
+
TODO: Improve format maybe?
 
+
 
+
 
+
=== Global Functions ===
+
These global functions access basic or generic methods of SuperTux. They are called without an object name. TODO: Move these into the globals section above.
+
 
+
==== display ====
+
Usage: <tt>display(*** object)</tt>
+
 
+
Displays the string value of <tt>object</tt> in the [[Console]]. Object can be of any data type.
+
 
+
==== print_stacktrace ====
+
Usage: <tt>print_stacktrace()</tt>
+
 
+
Displays contents of the current stack.
+
 
+
==== get_current_thread ====
+
Usage: <tt>get_current_thread()</tt>
+
 
+
Returns the currently running thread.
+
 
+
==== display_text_file ====
+
Usage: <tt>display_text_file(string filename)</tt>
+
 
+
Displays the SuperTux text file named <tt>filename</tt>. (The path is relative to the data root, e.g. "/home/joe/src/supertux-trunk/data")
+
 
+
See also: SuperTux file format reference, SuperTux texts
+
 
+
==== load_worldmap ====
+
Usage: <tt>load_worldmap(string filename)</tt>
+
 
+
Loads and runs the worldmap specified in <tt>filename</tt>. (The path is relative to the data root.)
+
 
+
==== load_level ====
+
Usage: <tt>load_level(string filename)</tt>
+
 
+
Loads and runs the level specified in <tt>filename</tt>. (The path is relative to the data root.)
+
 
+
==== wait ====
+
Usage: <tt>wait(float time)</tt>
+
 
+
Pauses execution of the Squirrel code for <tt>time</tt> seconds.
+
 
+
==== wait_for_screenswitch ====
+
Usage: <tt>wait_for_screenswitch()</tt>
+
 
+
Pauses execution of the Squirrel code until a new screen is displayed (e.g. menu &rarr; worldmap or worldmap &rarr; level).
+
 
+
==== exit_screen ====
+
Usage: <tt>exit_screen()</tt>
+
 
+
Exits the current screen, returning to the previous one or, if the active screen is the last one, exiting SuperTux.
+
 
+
==== fadeout_screen ====
+
Usage: <tt>fadeout_screen(float seconds)</tt>
+
 
+
Does a fadeout for the specified number of seconds before next screenchange.
+
 
+
==== shrink_screen ====
+
Usage: <tt>shrink_screen(float dest_x, float dest_y, float seconds)</tt>
+
 
+
Does a shrinking fade towards the destposition for the specified number of seconds before next screenchange
+
 
+
==== translate ====
+
Usage: <tt>translate(string text)</tt>
+
 
+
Returns: translated <tt>string</tt>
+
 
+
Translates <tt>text</tt> into the user's locale.
+
 
+
Note: This construct is unfortunately not yet recognised by XGetText, so translation files have to be written manually.
+
 
+
==== import ====
+
Usage: <tt>import(string filename)</tt>
+
 
+
Imports and runs the Squirrel script <tt>filename</tt>. (The path is relative to the data root.)
+
 
+
==== save_status ====
+
Usage: <tt>save_status()</tt>
+
 
+
Dumps the current state into the user's save game file.
+
 
+
==== play_music ====
+
Usage: <tt>play_music(string musicfile)</tt>
+
 
+
Changes music to musicfile
+
 
+
==== play_sound ====
+
Usage: <tt>play_sound(string soundfile)</tt>
+
 
+
Plays a soundfile
+
 
+
=== FloatingImage ===
+
The FloatingImage class contains methods for handling an image floating in mid-air, such as the SuperTux logo.
+
 
+
==== Constructor ====
+
Usage: <tt>&lt;floatimage&gt; &lt;- FloatingImage(string filename)</tt>
+
 
+
Creates a FloatingImage from <tt>filename</tt> (which is relative to the data root).
+
 
+
==== set_layer ====
+
Usage: <tt>&lt;floatimage&gt;.set_layer(int layer)</tt>
+
 
+
Puts the image on <tt>layer</tt>.
+
 
+
See also: src/video/drawing_context.hpp for the predefined layers and their values (note that you can't use these constants in your Squirrel code).
+
 
+
==== get_layer ====
+
Usage: <tt>&lt;floatimage&gt;.get_layer()</tt>
+
 
+
Returns: <tt>int</tt>; the layer the floating image is on.
+
 
+
==== set_pos ====
+
Usage: <tt>&lt;floatimage&gt;.set_pos(float x, float y)</tt>
+
 
+
Move the image in relation to the current anchor point.
+
 
+
==== get_pos_x ====
+
Usage: <tt>&lt;floatimage&gt;.get_pos_x()</tt>
+
 
+
Get the image's X coordinate relative to the current anchor point.
+
 
+
==== get_pos_y ====
+
Usage: <tt>&lt;floatimage&gt;.get_pos_y()</tt>
+
 
+
Get the image's Y coordinate relative to the current anchor point.
+
 
+
==== set_anchor_point ====
+
Usage: <tt>&lt;floatimage&gt;.set_anchor_point(int anchorpt)</tt>
+
 
+
Set the image's anchor point. Possible values are represented by the ANCHOR_* constants.
+
 
+
==== get_anchor_point ====
+
Usage: <tt>&lt;floatimage&gt;.get_anchor_point()</tt>
+
 
+
Returns: <tt>int</tt>; the current anchor point
+
 
+
==== set_visible ====
+
Usage: <tt>&lt;floatimage&gt;.set_visible(bool visible)</tt>
+
 
+
Set the image visibility according to <tt>visible</tt>.
+
 
+
==== get_visible ====
+
Usage: <tt>&lt;floatimage&gt;.get_visible()</tt>
+
 
+
Returns: <tt>bool</tt>; is the image visible?
+
 
+
==== set_action ====
+
Usage: <tt>&lt;floatimage&gt;.set_action(string action)</tt>
+
 
+
Set current action.
+
 
+
==== get_action ====
+
Usage: <tt>&lt;floatimage&gt;.get_action()</tt>
+
 
+
Returns: <tt>string</tt>; current action.
+
  
 +
{{Navbox Scripting reference}}
 
[[Category:Scripting Reference]]
 
[[Category:Scripting Reference]]

Latest revision as of 16:36, 25 May 2011


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.

What is Squirrel?

One of your first questions might be, "What does a rodent have to do with a penguin?" Squirrel 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 and worldmap files. The Console is a full-fledged Squirrel interpreter as well.

Squirrel, S-expr and SuperTux

I have no clue if the developers simply chose Squirrel just because the name so nicely integrates into the series of words "SuperTux" and "S-expr". 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:

(supertux-level
  (version 2)
  (name (_ "Go Blind"))
  (author "Team")
  (sector
    (name "main")
    (music "Annoying_penguin_gawking_sounds.ogg")

    ;; tilemaps, objects, whatever. (optional)
    ;...

    (init-script "
Effect.fade_out(2.5);
")

    ;; more tilemaps, objects, and whatever. (optional)
    ;...

  )
)

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...)

Object reference

If you are interested in an object and what cans of worms you can open with it, this section is for you.

"(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.

Classes

Classes
Globals This section contains all globally defined constants and functions
Player An object that is controlled by a (human) player
DisplayEffect An object that does graphical effects on the whole screen
Camera Control over the camera (what the player sees)
Level Control over the status the game keeps about the current level.
Level time Scripting interface to level time object
ScriptedObject Object in a level than can be manipulated from scripts
Text Display text in the top-center of the screen
FloatingImage Display an image floating in front of anything on-screen
Platform Scripting interface to Platform object
Tilemap Scripting interface to Tilemap object
Wind Scripting interface to Wind object
Candle Scripting interface to Candle object
Thunderstorm Scripting interface to Thunderstorm object
AmbientSound Scripting interface to AmbientSound object
Will-o-wisp Scripting interface to Will-o-wisp object
Sector Scripting interface to the Sector itself.

TODO: Improve format maybe?

Scripting reference
Ambient sound · Camera · Candle · Display effect · Floating image · Globals · Level · Level time · Path · Platform · Player · Scripted object · Sector · Sound · Text · Thunderstorm · Tilemap · Will-o-wisp · Wind