Revision as of 00:51, 20 November 2013

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

Note that while functions and objects are linked to by this page, all pages prefixed with 'API' refer to the Sphere versions of the objects and functions. The descriptions and examples for Sphere functions and objects are generally analogous to the TurboSphere versions, but not exactly the same.

Engine Functions

• EvaluateScript(filename)

Compiles the indicated script and executes it.

• RequireScript(filename)

Compiles the indicated script and executes it if it has not been required previously.

• RequireSystemScript(filename)

Requires a script in the system/script directory.

• 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"

• Exit()

Unconditionally exits the engine.

• Abort(message)

Aborts execution and displays 'message'.

• GarbageCollect()

Attempts to trigger garbage collection of the JS environment. This function is primarily kept for compatibility. Garbage collection may or may not actually take place when it is called.

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.

• GetScreenHeight()

Returns the height of the game window in pixels.

• GetScreenWidth()

Returns the width of the game window in pixels.

• SetClippingRectangle(x, y, w, h)

Sets the clipping rectangle on the screen.

• GetClippingRectangle()

Returns an object with the properties x, y, w, h, that describes the current clipping rectangle of the screen.

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.blitMask(x, y, color)

Blits the image to the screen at 'x', 'y', and tinted by 'color'.

• 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.zoomBlitMask(x, y, f, color)

Blits the image to the screen with the upper left corner at 'x', 'y', and tinted by 'color'. 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.stretchBlitMask(x, y, hf, vf, color)

Blits the image to the screen with the upper left corner at 'x', 'y', and tinted by 'color'. 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.rotateBlitMask(x, y, r, color)

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

• 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.transformBlitMask(x1, y1, x2, y2, x3, y3, x4, y4, color)

blits the image with corners at each x and y coordinate, and tinted by 'color'. 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 formats are BMP and TGA (with RLE compression). Some versions (particularly on Unix-like platforms) support saving to PNG.

• GrabImage(x, y, w, h)

Returns a new image object containing the contents of the screen in the specified area. Contents of the screen are cleared by FlipScreen calls, so something must have been drawn in the specified are since the last call to FlipScreen for the surface to contain anything but black.

• image.width

Value contains the image's width.

• image.height

Value contains the image's height.

Surfaces

• 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.blit(x, y)

Blits the surface at 'x', 'y'. Surfaces are slower to blit than images. If you plan on blitting a surface more than once, consider converting it to an image with surface.createImage().

• surface.setAlpha(a)

Sets the alpha of the surface to 'a'.

• surface.blitSurface(surface_object, x, y)

Blits surface_object onto surface at x, y.

• surface.cloneSection(x, y, w, h)

Returns a surface object that contains the section of surface at x, y, and is w by h.

• surface.setClippingRectangle(x, y, w, h)

Sets the clipping rectangle of the surface. Anything drawing operations that are outside the clipping rectangle are ignored.

Example

var surface = new Surface(16, 16, new Color(255, 0, 0, 255)); //Create a red surface.

surface.rectangle(0, 0, 16, 8, new Color(0, 0, 255, 255)); //Make the top half of the surface blue.

surface.setClippingRectangle(8, 0, 8, 16); //Set the clipping rectangle of the surface to be the right half.

surface.rectangle(0, 0, 16, 16, new Color(0, 255, 0, 255)); //Try and fill the rectangle with green. Only the right half will be changed!

The clipping rectangle can be reset as so

surface.setCLippingRectangle(0, 0, surface.width, surface.height); //Set the clipping rectangle to be from 0, 0, to the edges.

• surface.getClippingRectangle()

Returns a JS object that represents the surface's clipping rectangle, with properties 'x', 'y', 'w', and 'h'.

• surface.save(filename)

Saves 'surface' to 'filename' in the images directory. Extensions are not automatically appended to 'filename', the filename will be exactly as specified. Currently the only supported formats are BMP and TGA (with RLE compression). Some versions (particularly on Unix-like platforms) support saving to PNG.

• GrabSurface(x, y, w, h)

Returns a new surface object containing the contents of the screen in the specified area. Contents of the screen are cleared by FlipScreen calls, so something must have been drawn in the specified are since the last call to FlipScreen for the surface to contain anything but black.

• surface.createImage()

Returns a new image that has the same pixel properties as 'surface'. Use of this call should be limited so as to not waste processing time and graphics RAM.

Surface Pixel Access

• surface.setPixel(x, y, color)

Sets the pixel of 'surface' at 'x', 'y', to 'color'. No blending is performed.

• surface.getPixel(x, y)

Returns the color of the pixel at 'x', 'y', on 'surface'.

Surface Primitives

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

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

• surface.line(x1, y1, x2, y2, color)

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

• surface.outlinedCircle(x, y, r, color)

Draws an outline of a circle on 'surface' of radius 'r', centered on 'x', 'y', of 'color'

• surface.filledCircle(x, y, r, , color)

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

• surface.gradientRectangle(x, y, w, h, color1, color2, color3, color4)

Draws a rectangle at 'x', 'y', of width 'w' and height 'h' on 'surface'. The corners are color (clockwise from the upper left) by the colors, and the colors are faded into each other in the rectangle.

Surface Properties

• surface.width

Value contains the width of the surface.

• surface.height

Value contains the height of the surface.

Graphics Primitives

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

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

• GradientLine(x1, y1, x2, y2, color1, color2)

Draws a line of from x1, y1, to x2, y2 fading between 'color1' and 'color2'.

• 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, color1, color2, color3, color4)

Draws a rectangle at 'x', 'y', of width 'w' and height 'h'. The corners are color (clockwise from the upper left) by the colors, and the colors are faded into each other in the rectangle.

• OutlinedRectangle(x, y, w, h, color [, thickness])

Draws an outline of a rectangle of 'color' width w and height h at x, y. The edges are drawn of 'thickness'. If thickness is not provided, it is one pixel.

• Triangle(x1, y1, x2, y2, x3, y3, , color)

Draws a triangle with vertices 'x1', 'y1', 'x2', 'y2', 'x3', 'y3', filled with 'color'.

• GradientTriangle(x1, y1, x2, y2, x3, y3, color1, color2, color3)

Draws a triangle with vertices 'x1', 'y1', 'x2', 'y2', 'x3', 'y3', fading between the colors.

• Polygon(array, color)

Draws a polygon described by array, filled with 'color'. The elements of 'array' must have x and y properties.

• FilledCircle(x, y, rad, color)

Draws a circle of radius 'rad' centered at 'x', 'y', filled with 'color'. Negative radii are treated as absolute values.

• OutlinedCircle(x, y, rad, color)

Draws an outline of a circle of radius 'rad' centered at 'x', 'y', with 'color'. Negative radii are treated as absolute values.

• GradientCircle(x, y, rad, color1, color2)

Draws a circle of radius 'rad' centered at 'x', 'y'. The color is faded from 'color1' at the center of the circle to 'color2' at the edges. Negative radii are treated as absolute values.

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.drawZoomedText(x, y, str, f)

Draws 'str' using 'font' at 'x', 'y', zoomed by factor 'f'.

• font.drawTextBox(x, y, w, h, y_offset, str)

Draws 'str' using 'font' inside the box described by 'x', 'y', 'w', 'h', and offset vertically by 'y_offset'.

• font.wordWrapString(str)

Returns an array of strings, breaking up 'str' as though font.drawTextBox was called, and each element of the array is a line of text to be drawn.

• font.getStringWidth(str)

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

• font.getHeight()

Returns the max height of the fonts characters.

• font.setColorMask(color)

Sets the mask of 'font'.

• font.getColorMask()

Returns the color mask of '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'.

• ttffont.drawZoomedText(x, y, f, str)

Draws 'str' using 'ttffont' at 'x', 'y', zoomed by factor of 'f'. A factor of 1.0 is normal sized.

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

• DoesFileExist(filename)

Checks if 'filename' exists.

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 'savefile1.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.

ByteArray Object

• ByteArray(size)

Returns a ByteArray object of size 'size'. The ByteArray contains all zeros by defualt.

Example

var rawfile1 = new RawFile("save.raw");

• bytearray.concat(bytes)

Appends 'bytes' to the end of 'bytearray'.

• bytearray.slice(start [, end])

Returns a slice of the bytearray starting at 'start', and ending at 'end' or the end of the bytearray if end is omitted. If 'end' is a negative number, the end point is started from the end of the bytearray.

ByteArray Conversion

• CreateByteArrayFromString(str)

Returns a new ByteArray object from 'str'.

• CreateStringFromByteArray(bytes)

Returns string from bytes.

RawFile Object

• RawFile(filename)

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

Example

var rawfile1 = new RawFile("save.raw");

• rawfile.read(num)

Reads 'num' bytes from 'rawfile' as a ByteArray.

• rawfile.write(bytes)

Writes 'bytes' to 'rawfile'.

• rawfile.close()

Closes 'rawfile'.

• rawfile.getPosition()

Returns the current reading position of 'rawfile'.

• rawfile.setPosition(pos)

Sets the current reading position of 'rawfile' to 'pos'.

• rawfile.getSize()

Returns the size of 'rawfile'.

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.

AudioBass

Sound Object

• Sound(filename)

Creates a sound object from the file 'filename'. In 0.3.0 and later, all sounds are streamed by default.

• sound.play([loop])

Plays the sound. If 'loop' is false or no parameter is given, the sound is played once. If 'loop' is true then the sound is played until stop() is called. If the sound is already playing, it is restarted from the beginning.

• sound.stop()

Stops playing a sound. The sound will be started from the beginning next time play() is called.

• sound.pause()

Stops playing a sound. Playback will resume from the pausing point next time play() is called.

• sound.getLength()

Returns the length of 'sound' in milliseconds.

• sound.isPlaying()

Checks if the sound is currently playing.

• sound.setVolume(vol)

Sets the volume of 'sound' to 'vol'. 'vol' must be a number between 0 (mute) and 255 (full volume).

• sound.getVolume()

Returns the current volume of 'sound'.

SoundEffect Object

• SoundEffect(filename)

Creates a soundeffect object from the file 'filename'.

• soundeffect.play([loop])

Plays the soundeffect. If 'loop' is false or no parameter is given, the sound is played once. If 'loop' is true then the sound is played until stop() is called. A soundeffect may be played as many times simultaneously as desired.

• soundeffect.stop()

Stops playing all instances of 'soundeffect'.

• soundeffect.getLength()

Returns the length of 'soundeffect' in milliseconds.

• soundeffect.isPlaying()

Checks if the soundeffect is currently playing.

• soundeffect.setVolume(vol)

Sets the volume of 'soundeffect' to 'vol'. 'vol' must be a number between 0 (mute) and 255 (full volume). Affects all instances of 'soundeffect', including ones currently playing.

• soundeffect.getVolume()

Returns the current volume of 'soundeffect'.