From f9a61884a5ded0a63872fd24be30ed7aa74588d7 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Ond=C5=99ej=20Ho=C5=A1ek?= Date: Tue, 10 May 2005 15:10:59 +0000 Subject: [PATCH] Added a WIP document about the scripting API. In case of questions, edit my SuperTux Wiki user talk page (User_talk:RavuAlHemio). SVN-Revision: 2461 --- docs/scripting/scripting.xml | 196 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 docs/scripting/scripting.xml diff --git a/docs/scripting/scripting.xml b/docs/scripting/scripting.xml new file mode 100644 index 000000000..e873dca32 --- /dev/null +++ b/docs/scripting/scripting.xml @@ -0,0 +1,196 @@ + + + + + +
+ + +SuperTux Scripting Documentation +OndraHosek + +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 files. + +Squirrel, Scheme 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 "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: +(supertux-level + (version 2) + (name _("Go Blind")) + (author "Team") + (sector + (name "main") + (music "Annoying_penguin_gawking_sounds.mod") + + ;; (Tilemaps, objects, whatever.) + + (init-script " +DisplayEffect.fade_out(2.5); +") + ) +) +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. (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.) + +DisplayEffect +DisplayEffect is an interface for toying with the display. +fade_out +Usage: DisplayEffect.fade_out(float fadetime) +Effect: Gradually fades out the screen to black for the next fadetime seconds. + + +fade_in +Usage: DisplayEffect.fade_in(float fadetime) +Effect: Gradually fades in the screen from black for the next fadetime seconds. + + +set_black +Usage: DisplayEffect.set_black(bool black) +Effect: Blackens or un-blackens the screen (depending on the value of black). + + +is_black +Usage: DisplayEffect.is_black() +Returns: bool +Effect: Returns true if the screen has been blackened by set_black. Calling fade_in or fade_out resets the return value to false. + + + + +Camera +Camera is an interface to manipulate the camera. + +shake (NYI) +Usage: Camera.shake(float time, float x, float y) +Warning: This function has not yet been implemented. + + +set_pos (NYI) +Usage: Camera.set_pos(float x, float y) +Warning: This function has not yet been implemented. + + +set_mode (NYI) +Usage: Camera.set_mode(string modestring) +Warning: This function has not yet been implemented. + + + + +Level +The Level class provides pretty basic controlling functions for the current level. + +finish +Usage: Level.finish() +Effect: Ends the current level and marks it as completed if launched from a worldmap. +Tip: Very useful if you have created a frustrating level and want to, at some point, save the player from agony. + + +spawn +Usage: Level.spawn(string sectorname, string spawnpointname) +Effect: Respawns Tux in the sector sectorname at the spawnpointname spawnpoint. +Exceptions: If sectorname or spawnpointname 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 main. If this spawnpoint doesn't exist either, Tux will simply end up at the origin (top-left 0, 0). + + + + +ScriptedObject +A ScriptedObject 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. + +Usage notes +Since a ScriptedObject is a reference object and not an active object, you will have to build it into your level file, where a scriptedobject is a child of sector. This is an example definition: + +(scripted-object + (name "WOOT") + (x 420) + (y 94) + (sprite "snowball") + (solid #t) + (physic-enabled #f) + (visible #t) +) + + +Now, the object can be accessed in code using the WOOT identifier like so: + +WOOT.set_animation("left"); + + + + + + +set_animation + + +get_animation + + +move + + +set_pos + + +get_pos_x + + +get_pos_y + + +set_velocity + + +get_velocity_x + + +get_velocity_y + + +set_visible + + +is_visible + + +get_name + + + + + +Sound + + +Text + + + + +
-- 2.11.0