Functions

Functions

The following functions are currently implemented in TurboSphere. This list is currently incomplete.

A list of functions available in any particular release is found at docs/API.txt.

Functions noted as constructors are for making new objects.

System Functions

SetTitle(title)
Sets the title of the SDL window to 'title'.

GetScreenWidth()
Returns the width of the SDL window.

GetScreenHeight()
Returns the height of the SDL window.

SetResolution(w, h)
Sets the size of the SDL window to w, h.

RequireScript(script_name)
Compiles and executes a script. The base directory is the 'script' directory in the game's folder. The filesystem is not sandboxed, and by using '../' to specify one level up, any file is accessible. It is recommended to use unix style slashes (/) even on Windows.

GetTime()
Returns the number of milliseconds from a fixed point in the past.

Delay(ms)
Idles the engine for 'ms' milliseconds. This cedes CPU time for other tasks, so that TurboSphere does not consume all available CPU time.

GetVersion()
Returns a number specifying the version of TurboSphere that is running. For compatibility with Sphere 1.x games, it will return 2.0.

GetVersionString()
Returns a string specifying the version of TurboSphere being run, for example 'v0.2.13'.

Graphics Functions

SetResolution(w, h)
Sets the resolution of the SDL window. This is only needed to change the size of the window. The size is set on startup by the SGM file, which is generated by the editor.

FlipScreen()
Draws the backbuffer to the screen and then clears the backbuffer. This is necessary to actually see anything that was drawn.

Rectangle(x, y, w, h, color)
Draws a rectangle of 'color' to the screen at x, y, with a width and height of w, h.

GradientRectangle(x, y, w, h, color1, color2, color3, color4)
Draws a rectangle to the screen at x, y, with a width and height of w, h. The corners are (from upper left, clockwise) color1, color2, color3, and color4, faded together in between.

FilledCircle(x, y, r, color)
Draws a filled circle of 'color' at x, y, of radius r.

OutlinedCircle(x, y, r, color)
Draws an outline of a circle of 'color' at x, y, of radius r.

Point(x, y, color)
Draws the pixel at x, y, in 'color'.

Line(x1, y1, x2, y2, color)
Draws the line from x1, y1 to x2, y2, in 'color'.

Surface and Image Functions

Surface(w, h, color)
This is a constructor. It makes a surface object of width and height w, h, and fills it with 'color'.

Surface(filename)
This is a constructor. It loads a surface object from 'file'. Currently, bmp, tga, and png files can be loaded. Image files are in the 'images' directory.

Image(w, h, color)
This is a constructor. It makes an image object of width and height w, h, and fills it with 'color'.

Image(filename)
This is a constructor. It loads an image object from 'file'. Currently, bmp, tga, and png files can be loaded. Image files are in the 'images' directory.

GetSystemArrow()
Creates a new image file with the system arrow image. The system arrow is at system/arrow.png, but this can be changed in system.ini.

surface_or_image.width
Returns the width of a surface or image. Read only.

surface_or_image.height
Returns the height of a surface or image. Read only.

surface_or_image.blit(x, y)
Blits the image or surface to the screen at x, y.

surface_or_image.zoomBlit(x, y, f)
Blits the image or surface to the screen at x, y, and zooms it at factor f. A factor of 1 is the same as a normal blit.

surface_or_image.stretchBlit(x, y, horizF, vertF)
Blits the image or surface to the screen at x, y, and stretches it horizontally by a factor of horzF and vertically by a factor vertF. A factor of 1 is the same as a normal blit.

surface_or_image.createSurface()
Creates a surface with the same pixel data as surface_or_image.

surface_or_image.createImage()
Creates an image with the same pixel data as surface_or_image.

surface_or_image.blitSurface(x, y, soi)
Blits the image or surface to the image or surface 'soi' at x, y on 'soi'.

surface_or_image.setPixel(x, y, color)
Sets the pixel at x, y to 'color'.

surface_or_image.getPixel(x, y, color)
Gets the color of pixel at x, y as a TurboSphere color object.

surface_or_image.Rectangle(x, y, w, h, color)
Draws a rectangle of width w and height h on surface 'soi' at x, y filled with 'color'.

surface_or_image.getPixel(x1, y1, x2, y2, color)
Draws a line from x1, y1, to x2, y2, of 'color'.

Color Functions

Color(r, g, b, [a])
This is a constructor. It makes a TurboSphere Color object, with red, green, blue, and alpha of r, g, b, a. The alpha parameter can be left out, in which case it defaults to 255. This object is used to define colors for graphics primitives. Each element can be modified:
Color.red
Color.green
Color.blue
Color.alpha

Font Functions

TTFFont(filename)
This is a constructor. It makes a new TTF (truetype or opentype) font object. Any font that is in a format that can be read by freetype can be used. Fonts are contained in the 'fonts' directory.
TTFFont.fontname - returns the name of the font.
TTFFont.size - read or write. Gets or sets the default scale of the font. Default is 10.

Font(filename)
This is a constructor. It makes a new BMP (file type inherited from Sphere) font object. Fonts are contained in the 'fonts' directory, and are the Sphere rfn filetype.

GetSystemFont()
Returns a new Font object based on the system font. The system font file is system/font.rfn, but this is configurable from the system.ini file.

font_object.drawText(x, y, s)
Uses the font 'font_object' to write the string 's' at x, y.

font_object.drawZoomedText(x, y, s, f)
Uses the font 'font_object' to write the string 's', scaled by factor 'f' at x, y.

font_object.getStringWidth(s)
Returns the width of string 's' when rendered by font 'font_object'.

WindowStyle Functions

WindowStyle(filename)
This is a constructor. It makes a new WindowStyle object, based on the file provided. WindowStyles are contained in the 'windowstyles' directory, and are the Sphere rws filetype.

GetSystemWindowStyle()
Returns a new WindowStyle object based on the system windowstyle. The system windowstyle file is system/system.rws, but this is configurable from the system.ini file.

windowstyle_object.drawWindow(x, y, w, h)
Draws a windowstyle window at x, y, with a width of w and a height of h.

Keyboard Functions

The following key constants are used:

KEY_ENTER
KEY_A
KEY_B
KEY_C
KEY_D
KEY_E
KEY_F
KEY_G
KEY_H
KEY_I
KEY_J
KEY_K
KEY_L
KEY_M
KEY_N
KEY_O
KEY_P
KEY_Q
KEY_R
KEY_S
KEY_T
KEY_U
KEY_V
KEY_W
KEY_X
KEY_Y
KEY_Z
KEY_TAB
KEY_ESCAPE
KEY_F1
KEY_F2
KEY_F3
KEY_F4
KEY_F5
KEY_F6
KEY_F7
KEY_F8
KEY_F9
KEY_F10
KEY_F11
KEY_F12
KEY_F13
KEY_F14
KEY_F15
KEY_TILDE
KEY_0
KEY_1
KEY_2
KEY_3
KEY_4
KEY_5
KEY_6
KEY_7
KEY_8
KEY_9
KEY_MINUS
KEY_EQUALS
KEY_BACKSPACE
KEY_SHIFT
KEY_RSHIFT
KEY_CAPSLOCK
KEY_NUMLOCK
KEY_SCROLLOCK
KEY_CTRL
KEY_RCTRL
KEY_ALT
KEY_RALT
KEY_SPACE
KEY_OPENBRACE
KEY_CLOSEBRACE
KEY_SEMICOLON
KEY_APOSTROPHE
KEY_COMMA
KEY_PERIOD
KEY_SLASH
KEY_BACKSLASH
KEY_INSERT
KEY_DELETE
KEY_HOME
KEY_END
KEY_PAGEUP
KEY_PAGEDOWN
KEY_UP
KEY_RIGHT
KEY_DOWN
KEY_LEFT
KEY_NUM_0
KEY_NUM_1
KEY_NUM_2
KEY_NUM_3
KEY_NUM_4
KEY_NUM_5
KEY_NUM_6
KEY_NUM_7
KEY_NUM_8
KEY_NUM_9
KEY_NUM_PERIOD
KEY_NUM_DIVIDE
KEY_NUM_MULTIPLY
KEY_NUM_MINUS
KEY_NUM_EQUALS
KEY_RMETA
KEY_LMETA
KEY_RSUPER
KEY_LSUPER
KEY_BREAK
KEY_MENU
KEY_POWER
KEY_EURO

GetKey()
Returns The first key constant from the keybuffer. If the buffer is empty, it waits until a key has been pressed.

IsKeyPressed(key)
Checks if key constant 'key' is pressed. Does not remove the key from the buffer.

IsAnyKeyPressed(key)
Checks if any key is pressed. Does not remove the key from the buffer.

AreKeysLeft()
Checks if any keys are left in the buffer. Does not remove any keys. Very useful in combination with GetKey().

GetKeyString(key_const [, shift])
Returns the string representation of the key key_const. If shift is true, it returns the key as if the shift key is pressed. If shift is false or not passed, returns the key without shift. Control keys like control, shift, and alt return empty strings.

Mouse Functions

The following mouse button constants are defined. Note that not all mice have all buttons.

MOUSE_LEFT
MOUSE_MIDDLE
MOUSE_RIGHT
MOUSE_SUP
MOUSE_SDOWN
MOUSE_SDIS

GetMouseX()
Returns the x coordinate of the pointer.

GetMouseY()
Returns the y coordinate of the pointer.

IsMouseButtonPressed(mouse)
Checks if mouse button constant 'mouse' button is pressed.

File Functions

File(filename)
This is a constructor. It makes a File object that is linked with file 'filename'. If the file does not exist, TurboSphere creates it. The root directory is the 'save' directory.

file_object.read(key)
Returns the value associated with 'key' in file_object.

RemoveFile(filename)
Deletes 'filename'.

GetFileList(directory)
Returns an array of strings containing the filenames in 'directory'.