Difference between revisions of "Scripting reference"

Revision as of 19:40, 17 April 2006

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

    (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. (You can expect Win32 users to happily ignore this, since they tend to simply start the application by opening it with Explorer. Unix users, on the other hand, like starting things from the Console, so it's better if you don't use non-existent functions in your scripts.)

Classes

TODO: Convert the rest of the scripting docu to the new format (and improve format maybe?)

Global Constants

These constants can be accessed from anywhere in the game code.

KEY_BRASS

Type: integer

Value: 1

Represents the brass key.

Used in: add_key as argument 1

KEY_IRON

Type: integer

Value: 2

Represents the iron key.

Used in: add_key as argument 1

KEY_BRONZE

Type: integer

Value: 4

Represents the bronze key.

Used in: add_key as argument 1

KEY_SILVER

Type: integer

Value: 8

Represents the silver key.

Used in: add_key as argument 1

KEY_GOLD

Type: integer

Value: 16

Represents the gold key.

Used in: add_key as argument 1

ANCHOR_TOP

Type: integer

Value: 16

Represents the top center anchor point.

Used in: FloatingImage.set_anchor_point as argument 1
Returned by: FloatingImage.get_anchor_point

ANCHOR_BOTTOM

Type: integer

Value: 32

Represents the top center anchor point.

Used in: FloatingImage.set_anchor_point as argument 1
Returned by: FloatingImage.get_anchor_point

ANCHOR_LEFT

Type: integer

Value: 1

Represents the top center anchor point.

Used in: FloatingImage.set_anchor_point as argument 1
Returned by: FloatingImage.get_anchor_point

ANCHOR_RIGHT

Type: integer

Value: 2

Represents the top center anchor point.

Used in: FloatingImage.set_anchor_point as argument 1
Returned by: FloatingImage.get_anchor_point

ANCHOR_MIDDLE

Type: integer

Value: 0

Represents the top center anchor point.

Used in: FloatingImage.set_anchor_point as argument 1
Returned by: FloatingImage.get_anchor_point

ANCHOR_TOP_LEFT

Type: integer

Value: 17

Represents the top center anchor point.

Used in: FloatingImage.set_anchor_point as argument 1
Returned by: FloatingImage.get_anchor_point

ANCHOR_TOP_RIGHT

Type: integer

Value: 18

Represents the top center anchor point.

Used in: FloatingImage.set_anchor_point as argument 1
Returned by: FloatingImage.get_anchor_point

ANCHOR_BOTTOM_LEFT

Type: integer

Value: 33

Represents the top center anchor point.

Used in: FloatingImage.set_anchor_point as argument 1
Returned by: FloatingImage.get_anchor_point

ANCHOR_BOTTOM_RIGHT

Type: integer

Value: 34

Represents the top center anchor point.

Used in: FloatingImage.set_anchor_point as argument 1
Returned by: FloatingImage.get_anchor_point

Global Functions

These global functions access basic or generic methods of SuperTux. They are called without an object name.

display

Usage: display(*** object)

Displays the string value of object in the Console. Object can be of any data type.

display_text_file

Usage: display_text_file(string filename)

Displays the SuperTux text file named filename. (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: load_worldmap(string filename)

Loads and runs the worldmap specified in filename. (The path is relative to the data root.)

load_level

Usage: load_level(string filename)

Loads and runs the level specified in filename. (The path is relative to the data root.)

wait

Usage: wait(float time)

Pauses execution of the Squirrel code for time seconds.

wait_for_screenswitch

Usage: wait_for_screenswitch()

Pauses execution of the Squirrel code until a new screen is displayed (e.g. menu → worldmap or worldmap → level).

exit_screen

Usage: exit_screen()

Exits the current screen, returning to the previous one or, if the active screen is the last one, exiting SuperTux.

translate

Usage: translate(string text)

Returns: translated string

Translates text 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: import(string filename)

Imports and runs the Squirrel script filename. (The path is relative to the data root.)

save_status

Usage: save_status()

Dumps the current state into the user's save game file.

add_key

Usage: add_key(int key)

Adds or removes a key from the player's posession. key should be replaced with one of the KEY_ constants.

See also: src/player_status.hpp

DisplayEffect

DisplayEffect is an interface for toying with the display. It has to be instantiated; for your convenience, SuperTux creates an instance named Effect when starting the scripting engine. Its usage is preferred.

fade_out

Usage: Effect.fade_out(float fadetime)

Gradually fades out the screen to black for the next fadetime seconds.

fade_in

Usage: Effect.fade_in(float fadetime)

Gradually fades in the screen from black for the next fadetime seconds.

set_black

Usage: Effect.set_black(bool black)

Blackens or un-blackens the screen (depending on the value of black).

is_black

Usage: Effect.is_black()

Returns: bool; has the screen been blackened by set_black?

Note: Calling fade_in or fade_out resets the return value to false.

sixteen_to_nine

Usage: Effect.sixteen_to_nine()

Sets the display ratio to 16:9, effectively adding black bars at the top and bottom of the screen. Should be used before cutscenes.

four_to_three

Usage: Effect.four_to_three()

Sets the display ratio to 4:3, removing the black bars added by sixteen_to_nine(). Should be used after cutscenes.

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

Usage: Camera.set_mode(string modestring)

This function sets the camera mode. Valid values for modestring are "normal" and "manual".

scroll_to (NYI)

Usage: Camera.scroll_to(float x, float y, float time)

Scrolls the camera to (x, y) within time seconds.

Level

The Level class provides basic controlling functions for the current level.

finish

Usage: Level.finish(bool win)

Ends the current level. If you set win to true, the level is marked 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)

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

flip_vertically

Usage: Level.flip_vertically()

Flips the level vertically (i.e. top is now bottom and vice versa). Call again to revert the effect.

Tip: Make sure the player can land on something after the level is flipped!

Sound

This class provides a very simple interface to the audio subsystem.

play_music

Usage: Sound.play_music(string track_name)

Plays the selected music track (automatically prepending the path to the music folder and appending the .ogg extension).

play

Usage: Sound.play(string sound_name)

Plays the sound specified in sound_name (that is identical to the filename of the sound without the .wav extension).

Text

This module provides access to methods reponsible for displaying text on-screen.

set_text

Usage: Text.set_text(string text)

Sets the text string to be displayed to text.

set_font

Usage: Text.set_font(string font)

Sets the font of the text to be displayed to text. Currently valid values are gold, white, blue, gray, big and small.

fade_in

Usage: Text.fade_in(float time)

Fades in the specified text for the next time seconds.

fade_out

Usage: Text.fade_out(float time)

Just the opposite of fade_out.

set_visible

Usage: Text.set_visible(bool visible)

Shows or hides the text abruptly (drastic counterpart to fade_in and fade_out).

set_centered

Usage: Text.set_centered(bool centered)

If centered is true, the text will be centered on the screen. Otherwise, it will be left-aligned.

Player

This module contains methods controlling the player. (No, SuperTux doesn't use mind control. Player refers to the type of the player object.)

Once again, just like with ScriptedObject, note that Player is only the object type. Since SuperTux is currently single-player only, use Tux to make changes to the player object, such as Tux.deactivate().

add_bonus

Usage: <player>.add_bonus(string bonusname)

Gives Tux the specified bonus. Replace bonusname with either of "grow", "fireflower" or "iceflower".

add_coins

Usage: <player>.add_coins(int number)

Gives Tux number coins.

Tip: Tux has to pay 25 coins to be revived at the last firefly he visited. If he doesn't have enough coins, the player has to play the whole level again.

make_invincible

Usage: <player>.make_invincible(float time)

Makes the player invincible for either a custom or a predefined amount of time.

See also: TUX_INVINCIBLE_TIME in src/object/player.hpp for the amount of seconds that the player becomes invincible in case time is not specified.

deactivate

Usage: <player>.deactivate()

Stops the player and blocks the movement controls.

Tip: Don't call this in front of a horde of badguys.

activate

Usage: <player>.activate()

Reactivates the player's movement controls.

walk

Usage: <player>.walk(float velocity)

Makes the player move in a certain horizontal velocity (specified by velocity). A negative velocity moves the player to the left.

set_visible

Usage: <player>.set_visible(bool visible)

Shows or hides Tux according to the value of visible.

get_visible

Usage: <player>.get_visible()

Returns: bool; is Tux visible?

FloatingImage

The FloatingImage class contains methods for handling an image floating in mid-air, such as the SuperTux logo.

Constructor

Usage: <floatimage> <- FloatingImage(string filename)

Creates a FloatingImage from filename (which is relative to the data root).

set_layer

Usage: <floatimage>.set_layer(int layer)

Puts the image on layer.

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

set_layer

Usage: <floatimage>.get_layer()

Returns: int; the layer the floating image is on.

set_pos

Usage: <floatimage>.set_pos(float x, float y)

Move the image in relation to the current anchor point.

get_pos_x

Usage: <floatimage>.get_pos_x()

Get the image's X coordinate relative to the current anchor point.

get_pos_y

Usage: <floatimage>.get_pos_y()

Get the image's Y coordinate relative to the current anchor point.

set_anchor_point

Usage: <floatimage>.set_anchor_point(int anchorpt)

Set the image's anchor point. Possible values are represented by the ANCHOR_* constants.

get_anchor_point

Usage: <floatimage>.get_anchor_point()

Returns: int; the current anchor point

set_visible

Usage: <floatimage>.set_visible(bool visible)

Set the image visibility according to visible.

get_visible

Usage: <floatimage>.get_visible()

Returns: bool; is the image visible?