Revision as of 02:17, 15 June 2013

This page documents the TurboSphere API. Currently, it is up to date for TurboSphere version 0.3.0. It is sorted by which plugin the function is provided by, and contains lists for all the plugins included with the standard TurboSphere distribution.

Engine Functions

• RequireScript(filename)

Compiles the indicated script and executes it.

• GetVersion()

Returns a number representation of the version of TurboSphere. Until TurboSphere 1.0, this number does not have a fixed meaning.

• GetVersionString()

Returns a string representation of the version of TurboSphere. This number also represents the versions of all the default plugins (they all share this same version number). For example: "0.2.2a"

Time Functions

• GetTime()

Returns the number of milliseconds passed since a set point in time.

• Delay(ms)

Idles the engine for 'ms' seconds. This cedes CPU time to other programs, and allows TurboSphere to use less than 100% of available CPU time.

GraphicSDL Functions

Screen Control

• FlipScreen()

Draws the framebuffer to the screen. You must call this before anything you blit or draw will be visible.

• SetTitle(title)

Sets the title of the game window.

• GetScreenHeight()

Returns the height of the game window in pixels.

• GetScreenWidth()

Returns the width of the game window in pixels.

Colors

• Color(r, g, b [, a])

Creates a color object with the specified values. Alpha is optional.

Example

var Red = new Color(255, 0, 0); //Red's alpha channel defaults to 255.
var NoColor = new Color(0, 0, 0, 0); //Fully transparent!

Images

• Image(...)

Creates an image object that is held in video memory and handled by graphics hardware, if possible.

Example

var image1 = new Image("imagefile.png"); //Creates an Image of the file imagefile.png in the images folder.

//or...

var image2 = new Image(16, 16, new Color(255, 0, 0, 255)); //Creates an Image of size 16 by 16 pixels filled with a red color.

• image.blit(x, y)

Blits the image to the screen at 'x', 'y'.

• image.zoomBlit(x, y, f)

Blits the image to the screen with the upper left corner at 'x', 'y'. The image dimensions are scaled by 'f'. 1.0 is a normal blit, 2.0 doubles the size, 0.5 is half size, etc.

• image.stretchBlit(x, y, hf, vf)

Blits the image to the screen with the upper left corner at 'x', 'y'. The image's horizontal dimension scaled by 'hf', and the vertical dimension by 'vf'.

• image.rotateBlit(x, y, r)

Blits the image centered at 'x', 'y', rotated by 'r' radians (0 is no rotation).

• image.transformBlit(x1, y1, x2, y2, x3, y3, x4, y4)

blits the image with corners at each x and y coordinate. The corners are numbered as so, upper left: 1, upper right: 2, lower right: 3, lower left: 4.

• image.createSurface()

Returns a surface object with the same dimensions and pixel data as 'image'.

• image.clone()

Returns a copy of the image.

• image.save(filename)

Saves a copy of the image as 'filename'. Currently the only supported format is BMP.

• image.width

Value contains the image's width.

• image.height

Value contains the image's height.

• Surface

Creates a surface object that is held in system memory and modified in software. Surfaces are faster than Images to modify (ie, with surface.setPixel or surface.rectangle), but slower to blit to the screen. Blits of surfaces onto images or images onto surfaces are much slower than blitting images onto images or surfaces onto surfaces.

Example

var surface1 = new Surface("imagefile.png"); //Creates a Surface of the file imagefile.png in the images folder.

//or...

var surface2 = new Surface(16, 16, new Color(255, 0, 0, 255)); //Creates a Surface of size 16 by 16 pixels filled with a red color.

• surface_or_image.getPixel(x, y)

Returns a color object of the color of the Surface or Image at 'x', 'y'.

• surface_or_image.setPixel.(x, y, color)

Sets the color of the pixel x, y of surface_or_image to 'color'.

• surface_or_image.rectangle(x, y, w, h, color)

Draws a rectangle on surface_or_image at 'x', 'y', of width 'w' and height 'h' and fills it with 'color'.

• surface_or_image.zoomBlit(x, y, f)

Blits surface_or_image at x, y, zoomed by factor f. A factor of 1 is the same as a normal blit.

As of 0.2.2a, the surface is imperfectly drawn at factors not divisible by 1/2.

• surface_or_image.stretchBlit(x, y, hf, vh)

Blits surface_or_image at x, y, with a horizontal scaling factor of hf and a vertical scaling factor of vf. Factors of 1 are the same as a normal blit.

• surface.blitSurface(surface_or_image_object, x, y)

Blits surface_or_image_object onto surface_or_image at x, y.

• GetSystemArrow()

Returns an image of the system arrow. The image used is set in system/system.ini.

Graphics Primitives

• Line(x1, y1, x2, y2, color)

Draws a line of 'color' from x1, y1, to x2, y2.

• Point(x, y, color)

Draws a point of 'color' at x, y.

• Rectangle(x, y, w, h, color)

Draws a rectangle of 'color' width w and height h at x, y.

• GradientRectangle(x, y, w, h, c1, c2, c3, c4)

Draws a rectangle at x, y, with a width of w and a height of h. The color is faded from c1 to c4 around the corners, moving clockwise from the upper left corner.

• FilledCircle(x, y, r, color)

Draws a circle of radius r centered at x, y, filled with 'color'.

• OutlinedCircle(x, y, r, color

Draws an outline of a circle of radius r centered at x, y with 'color'.

BMPFontSDL

• Font(filename)

Creates a bmpfont object of the sphere rfn file 'filename' from the fonts folder.

var font1 = new Font("arial.rfn"); //font1 is a font object based on the font arial.rfn in the fonts folder.
var font2 = new Font("../../system/system.rfn"); //Opens the system rfn font. The actual; system font is not guaranteed to be this particular file.

• font.drawText(x, y, str)

Draws 'str' using 'font' at 'x', 'y'.

• font.gatStringWidth(str)

Returns the width of 'str' as drawn by 'font'.

• GetSystemFont()

Returns a Font object representing the system font. The system font can be specified in the system/system.ini file, but by default is system/system.rfn.

TTFFontSDL

• TTFFont(filename)

Creates a bmpfont object of the sphere rfn file 'filename' from the fonts folder.

var ttffont1 = new TTFFont("DejaVuSans.ttf"); //ttffont1 is a ttffont object based on the True Type font DejaVuSans.ttf in the fonts folder.

• ttffont.drawText(x, y, str)

Draws 'str' using 'ttffont' at 'x', 'y'.

InputSDL

KeyBoard

Key Constants

The following variables are defined for use as key constants:

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

Note that not all keys are available on all keyboards.

Keyboard Functions

• IsKeyPressed(key)

Checks whether or not 'key', as expressed by a key constant, is pressed.

• IsAnyKeyPressed()

Returns true if any key is pressed, false if not.

• GetKey()

Returns a key from the key buffer. If no keys are available, waits until one is.

• AreKeysLeft()

Checks whether there are keys in the key buffer.

Mouse

Mouse Button Constants

The following mouse button constants are defined:

MOUSE_LEFT
MOUSE_RIGHT
MOUSE_MIDDLE
MOUSE_SUP
MOUSE_SDOWN

Mouse Functions

• GetMouseX()

Returns the X coordinate of the mouse in the window.

• GetMouseY()

Returns the Y coordinate of the mouse in the window.

• IsMouseButtonPressed(button)

Checks whether or not 'button', as expressed by a mouse button constant, is pressed.

JoyStick Functions

Joystick Management

• GetNumJoysticks()

Returns the number of available joysticks.

• GetJoystickName(n)

Returns the name of joystick number 'n'.

Joystick Access

• GetNumJoystickButtons(n)

Returns the number of buttons on joystick number 'n'.

• GetNumJoystickAxes(n)

Returns the number of axes (ie, analog stick axes, analog triggers, throttles) on joystick number 'n'.

• IsJoystickButtonPressed(jsNum, buttonNum)

Checks whether or not button number 'buttonNum' is pressed on joystick number 'jsNum'.

• GetJoystickAxis(jsNum, axisNum)

Returns the position of axis number 'axisNum' on joystick number 'jsNum', between -32768 and 32767.

ScriptFS

FileSystem Function

• GetFileList(directory)

Returns an array of filenames in the given directory. The base directory is the save directory, but you can use '..' to go up levels. There is no sandboxing, and you can access the entire filesystem of the computer with this function.

• RemoveFile(filename)

Deletes the file 'filename'.

File Object

• File(filename)

Returns a file object of 'filename'. If the file doesn't exist, it creates it.

Example

var file1 = new File("save");

• file.read(key, default)

Gets the value assigned to 'key' from 'file'. If 'key' does not exist, it creates it with the value 'default'.

• file.write(key, value)

Writes 'value' and assigns it to 'key' in file. If the key already existed, it overwrites it.

• file.flush()

Flushes changes to file, in case you don't want wait. Normally changes are flushed in a timely manner, and whenever the file is closed.

• file.close()

Closes the handle to 'file', and flushes changes. 'file' can then be assigned a new value and used again.

Example

var file1 = new File("savefile1.save"); //create the file 'newfile.save' in the save directory.

file1.write("Lives", "3"); //write a value to the file.

file1.flush();
file1.close(); //Close the file.

//...

file1 = new File("savefile2.save"); //create another save file.


file1.write("Lives", "5"); //write a value to the file. Everyone knows the second save file is the best one.

file1.flush();
file1.close(); //Close the second file.

WindowStylesSDL

• WindowStyle(filename)

Creates a WindowStyle from 'filename' in the windowstyles directory.

Example

var ws1 = new WindowStyle("my_windowstyle.rws");

• windowstyle.drawWindow(x, y, w, h)

Draws 'windowstyle' at 'x', 'y', with a width of 'w' and a height of 'h'.

GetKeyString

• getkeystring(key [, shift])

Returns an ascii character that represents the key constant 'key'. If 'shift' is true, then it the character is represented as though the shift key is pressed.