User:Flying Jester/TurboSphere API
From Spherical
< User:Flying Jester
Revision as of 02:46, 15 June 2013 by Flying Jester (talk | contribs)
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.
Contents
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
- Creates a color object with the specified values. Alpha is optional.
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
- Creates an image object that is held in video memory and handled by graphics hardware, if possible.
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 format is BMP.
- 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
- 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.
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)
- 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'.
- 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.setAlpha(a)
- Sets the alpha of the surface to 'a'.
- 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
- Sets the clipping rectangle of the surface. Anything drawing operations that are outside the clipping rectangle are ignored.
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'.
- 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.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.
- 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.
- 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'.
- Draws a triangle with vertices 'x1', 'y1', 'x2', 'y2', 'x3', 'y3', fading between the colors.
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.
JoyStick
JoyStick Functions
- GetNumJoysticks()
- Returns the number of usable joysticks connected to the computer.
- GetJoystickName(jsnum)
- Returns the name of joystick number 'jsnum'.
- GetNumJoystickButtons(jsnum)
- Returns the number of buttons on joystick number 'jsnum'.
- GetNumJoystickAxes(jsnum)
- Returns the number of axes on joystick number 'jsnum'.
- IsJoystickButtonPressed(jsnum, button)
- Checks whether or not button number 'button' is pressed on joystick number 'jsnum'.
- GetJoystickAxis(jsnum, axis)
- Returns the value for axis number 'axis' on joystick number 'jsnum'.
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
- Returns a file object of 'filename'. If the file doesn't exist, it creates it.
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
- Closes the handle to 'file', and flushes changes. 'file' can then be assigned a new value and used again.
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
- Creates a WindowStyle from 'filename' in the windowstyles directory.
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.