Function List

This page lists script-side functions, objects, and types exposed by the core TurboSphere plugins and the engine proper. Ideally, when you add or modify the script-side usage of a function, object, or type, you should update this page.

This page is called the Function List, even though it also contains objects and types. It's because of how SphereDev terms things, which is because Sphere of yore was more procedurally oriented. Don't worry about it.

Do not put planned features here. It should reflect what TurboSphere is in the git repo.

Functions

Engine Functions

• RequireScript

  Usage: RequireScript(script_filename);

  Compiles and runs script_filename if it has not been RequireScript'd before. The base directory for this is scripts in the game root directory.

• EvaluateScript

  Usage: EvaluateScript(script_filename);

  Compiles and runs script_filename unconditionally. The base directory for this is scripts in the game root directory.

• RequireSystemScript

  Usage: RequireSystemScript(script_filename);

  Compiles and runs script_filename from the system script folder if it has not been RequireSystemScript'd before. The base directory for this is system/scripts in the TurboSphere root directory.

• EvaluateSystemScript

  Usage: EvaluateSystemScript(script_filename);

  Compiles and runs script_filename from the system script folder unconditionally. The base directory for this is system/scripts in the TurboSphere root directory.

ScriptFS

• IsFile

  Usage: IsFile(path);

  Returns true if path is a file, and false otherwise. The path is relative to other in the game root directory.

• IsDir

  Usage: IsDir(path);

  Returns true if path is a directory, and false otherwise. The path is relative to other in the game root directory.

Chrono

• Delay

  Usage: Delay(milliseconds);

  Causes the engine to sleep for milliseconds. This cedes CPU time from TurboSphere, allowing a game to use less than 100% of available CPU if it is not necessary. This may provide a hint to the JS engine to do garbage collection.

• GetTime

  Usage: GetTime();

  Returns the number of milliseconds (as an whole number) since some arbitrary point in time. This is intended to be a simpler alternative to GetSeconds().

• GetSeconds

  Usage: GetSeconds();

  Returns the number of seconds (as a floating point number) since some arbitrary point in time. This function is guaranteed to have at least microsecond accuracy, and is useful for more fine-grained timing than GetTime().

Sapphire

• FlipScreen

  Usage: FlipScreen();

  Calling this function signals that an entire frame has been specified. Ordinarily, you will perform some drawing operations using one or more Group objects and call FlipScreen() at the end of one frame's worth of drawing.

• SurfaceFromArrayBuffer

  Usage: SurfaceFromArrayBuffer(width, height, buffer);

  Returns a Surface that uses buffer as its pixel data. Buffer must be at least width times height times 4 bytes long. The data is interpreted as big-endian (0xRRGGBBAA) RGBA data.

  Modifications to buffer after this call do not change the data of the constructed Surface.

• ImageFromArrayBuffer

  Usage: ImageFromArrayBuffer(width, height, buffer);

  Returns an Image that uses buffer as its pixel data. Buffer must be at least width times height times 4 bytes long. The data is interpreted as big-endian (0xRRGGBBAA) RGBA data.

  Modifications to buffer after this call do not change the data of the constructed Image.

• GetDefaultShaderProgram

  Usage: GetDefaultShaderProgram();

  Returns the default ShaderProgram. This is currently the only method for obtaining a ShaderProgram, which is required for creating a Group object.

• GetScreenWidth

  Usage: GetScreenWidth();

  Returns the width of the screen/window.

• GetScreenHeight

  Usage: GetScreenHeight();

  Returns the height of the screen/window.

InputSDL2

• IsKeyPressed

  Usage: IsKeyPressed(key);

  Returns true if key is pressed and false otherwise. key should one of InputSDL2's Key Constants.

• IsAnyKeyPressed

  Usage: IsAnyKeyPressed();

  Returns true if any key is pressed and false otherwise.

• GetKey

  Usage: GetKey();

  Returns the Key Constant of the next key that is pressed. Keys can be queued up in between calls to GetKey. If no keys have been queued yet, this function will block until the next key is pressed.

• GetClick

  Usage: GetClick();

  Returns the Mouse Button Constant of the next mouse button that is pressed. Mouse buttons can be queued up in between calls to GetClick. If no mouse buttons have been queued yet, this function will block until the next mouse button is pressed.

• GetNumMouseWheelEvents

  Usage: GetNumMouseWheelEvents();

  Returns the number of pending Mouse Wheel events.

• GetMouseWheelEvent

  Usage: GetMouseWheelEvent();

  Returns the Mouse Wheel Constant of the next mouse button that is pressed. Wheel events can be queued up in between calls to GetMouseWheelEvent. If no mouse wheel events have been queued yet, this function will block until the next mouse wheel change happens.

• AreKeysLeft

  Usage: AreKeysLeft();

  Returns true if there are one or more pending keys for GetKey() and false otherwise.

• AreClicksLeft

  Usage: AreClicksLeft();

  Returns true if there are one or more pending mouse buttons for GetClicks() and false otherwise.

• GetMouseX

  Usage: GetMouseX();

  Returns the current X position of the mouse cursor.

• GetMouseY

  Usage: GetMouseY();

  Returns the current Y position of the mouse cursor.

• IsMouseButtonPressed

  Usage: IsMouseButtonPressed(button);

  Returns true if the Mouse Button Constant button is pressed and false otherwise.

• GetNumJoysticks

  Usage: GetNumJoysticks();

  Returns the number of joysticks usable for the game.

• GetJoystickName

  Usage: GetJoystickName(joy_number);

  Returns the name of joystick number number.

• GetNumJoystickButtons

  Usage: GetNumJoystickButtons(joy_number);

  Returns the number of buttons usable for joystick number number.

• GetNumJoystickAxes

  Usage: GetNumJoystickAxes(joy_number);

  Returns the number of axes (for instance: analog sticks, triggers, accelerometers) usable for joystick number number.

• IsJoystickButtonPressed

  Usage: IsJoystickButtonPressed(joy_number, button_number);

  Returns true if the button number button_number is pressed on joystick number joy_number, and false if it is not.

• GetJoystickAxis

  Usage: GetJoystickAxis(joy_number, axis_number);

  Returns a floating-point number between -1.0 and 1.0 representing the position of joystick axis number axis_number on joystick number joy_number.

  Note that it may be a good idea to allow calibration of joysticks, since it is not always possible to tell if a joystick axis can actually reach 1.0 or -1.0.

Network

• GetLocalName

  Usage: GetLocalName();

  Returns a string containing the local machine's name.

• GetLocalAddress

  Usage: GetLocalAddress();

  Returns a string containing the local machine's address.

Objects

InputSDL2

• Key Constants

  The following key constants exist, representing keys on the keyboard:

  • 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_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_TAB
  • 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_SHIFT
  • KEY_RSHIFT
  • KEY_CTRL
  • KEY_RCTRL
  • KEY_ALT
  • KEY_LALT
  • KEY_SPACE
  • KEY_OPENBRACE
  • KEY_CLOSEBRACE
  • KEY_SEMICOLON
  • KEY_APOSTROPHE
  • KEY_COMMA
  • KEY_PERIOD
  • KEY_SLASH
  • KEY_BACKSLASH
  • KEY_ENTER
  • KEY_RETURN
  • 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_CAPSLOCK
  • KEY_NUMLOCK
  • KEY_SCROLLOCK
  • KEY_SCROLLLOCK

• Mouse Button Constants

  The following mouse button constants exist, representing buttons on the mouse:

  • MOUSE_LEFT
  • MOUSE_RIGHT
  • MOUSE_MIDDLE

• Mouse Wheel Constants

  The following mouse wheel constants exist, representing actions of the mouse wheel:

  • MOUSE_WHEEL_UP
  • MOUSE_WHEEL_DOWN
  • MOUSE_WHEEL_LEFT
  • MOUSE_WHEEL_RIGHT

Types

ScriptFS

RawFile

An object used to read or write to a file.

---

Constructor

• new RawFile(path [, writeable]);

  Opens a RawFile from path relative to other in the game root directory.. If writeable is false or not specified, the file is read-only.

---

Methods

• read(length);

  Returns a Uint8Array representing the contents of the file from the current position for length bytes.

• write(buffer, length);

  Writes length bytes from buffer to the file at the current position. This is not possible for read-only files.

• getSize();

  Returns the total length of the file in bytes.

  This method is deprecated. Use the 'size' member instead.

• getPosition();

  Returns the current position in the file in bytes. It is possible to read() the size of the file minus this value.

  This method is deprecated. Use the 'position' member instead.

• setPosition(offset);

  Sets the current position to offset bytes after the beginning of the file. It is an error to set the position past the end of the file.

  This method is deprecated. Use the 'position' member instead.

---

Members

• size

  A read-only value representing the length of the file in bytes.

• position

  A read-write value representing the current position in the file. It is an error to set this past the end of the file. This value will always be positive.

Sapphire

Image

An object representing an image that can be used to texture a Shape. In order to actually use an Image, you must use it as a texture for a Shape object.

---

Constructor

• new Image(path);

  Opens an Image from path, relative to images in the game root directory.

• new Image(surface);

  Creates an Image that has the same data as surface. Later changes to surface do not affect the constructed image.

• new Image(width, height, color);

  Creates an Image of width and height filled with color.

---

Methods

• createSurface();

  Constructs a Surface using this image as its initial data.

• update(surface_object);

  Updates the Image's pixel data to reflect surface_object. Will resize the Image to match the dimensions of the Image.

---

Fields

• width

  A read-only value representing the width of the Image.

• height

  A read-only value representing the height of the Image.

Surface

An object representing an image. While an Image is primarily used for texturing, a Surface is used for modifying the image before use.

---

Constructor

• new Surface(path);

  Opens an Image from path, relative to images in the game root directory.

• new Surface(width, height, color);

  Creates an Surface of width and height filled with color.

---

Methods

• save(path);

  Saves the surface to the file path relative to images in the game directory.

  TurboSphere currently supports saving BMP, PNG, TGA, and JPG files.

• setPixel(x, y, color);

  Sets the pixel at x, y to color.

• blitSurface(surface, x, y);

  Blits surface onto this Surface at x, y.

• line(x1, y1, x2, y2, color);

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

• gradientLine(x1, y1, x2, y2, color1, color2);

  Draws a line from x1, y1 to x2, y2 fading from color1 to color2.

• triangle(x1, y1, x2, y2, x3, y3, color);

  Draws a triangle with points at x1, y1, x2, y2, and x3, y3 with color.

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

  Draws a triangle with points at x1, y1, x2, y2, and x3, y3 fading between color1, color2, and color3.

• outlinedTriangle(x1, y1, x2, y2, x3, y3, color);

  Draws a the outline of a triangle with points at x1, y1, x2, y2, and x3, y3 using color.

• rectangle(x, y, w, h, color);

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

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

  Draws a rectangle at x, y, with a width of w and height of h using fading between color1, color2, color3, color4.

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

  Draws a the outline of a rectangle at x, y, with a width of w and height of h using color.

• circle(x, y, r, color);

• filledCircle(x, y, r, color);

  Draws a circle with a center a x, y, of radius r using color.

• gradientCircle(x, y, r, color1, color2);

  Draws a circle with a center a x, y, of radius r fading between color1 and color2.

• outlinedCircle(x, y, r, color);

  Draws the outline of a circle with a center a x, y, of radius r using color.

---

Fields

• width

  A read-only value representing the width of the Surface.

• height

  A read-only value representing the height of the Surface.

Color

An object representing color. Data is stored as red, green, blue, and alpha channels with values from 0 to 127. All Colors have alpha, and all Colors are in this format.

---

Constructor

• new Color(red, green, blue [, alpha]);

  Constructs a Color with red, green, blue, and alpha. If alpha is unspecified, it is set to 255.

---

Fields

• red

  A read-write value representing the red channel.

• green

  A read-write value representing the green channel.

• blue

  A read-write value representing the blue channel.

• alpha

  A read-write value representing the alpha channel.

Shape

An object with a set of vertices in XY space, optionally with UV and Color attributes, and a textute to apply to this shape. To actually view an Image or Surface, it must be used to texture a Shape, which itself must be added to a Group.

A Shape can belong to a single Group, multiple Groups at once, or no Groups at all.

---

Constructor

• new Shape(vertices, image);

  Constructs a Shape that has vertices and is textured by image. vertices must be an array of objects. Each element of vertices must have a number x and y property, representing the position of the vertex relative to the Shape's origin. Vertices may optionally have a color property representing an additive color mask, and numeric u and v properties representing UV coordinates for the vertex relative to image.

  In the simplest case, each vertex needs only a numeric x and y property, in which case no color mask and no special UV mapping will be applied.

---

Fields

• image

  A read-write property representing the Image to use to texture this Shape. This can be changed at any time.

Group

An object containing a set of Shapes, a ShaderProgram to draw the Shapes, and several parametric modifications to the Shapes. To be draw, a Shape must be a part of a Group that is drawn in between FlipScreen() calls.

Groups are the only way to draw to the screen. A Group can be used to construct any primitive shape, and any texture. The Vertex/Shape+Image/Group+ShaderProgram is the only graphical API in TurboSphere, and replaces the all other drawing functions from older versions of TurboSphere and Sphere. Don't Panic.

---

Constructor

• new Group(shapes, shader_program);

  Creates a Group object with shapes and shader_program. shapes must be an Array of Shape objects.

---

Methods

• draw();

  Adds this Group to the current scene. The next call to FlipScreen will draw this shape.

---

Fields

• x

  The X-offset at which to draw this Group. This number is added to the X-properties of all corresponding Shape objects vertices when drawn with this Group. Translation is applied before rotation.

• y

  The Y-offset at which to draw this Group. This number is added to the Y-properties of all corresponding Shape objects vertices when drawn with this Group. Translation is applied before rotation.

• rotX

  The X-offset at which angle is applied.

• rotY

  The Y-offset at which angle is applied.

• angle

  An angle in radians to rotate the Group by. Rotation is applied after translation.

• clipX

  The X coordinate of the clipping rectangle. Coordinates are relative to the screen.

• clipY

  The Y coordinate of the clipping rectangle. Coordinates are relative to the screen.

• clipW

  The W coordinate of the clipping rectangle. Coordinates are relative to the screen.

• clipH

  The H coordinate of the clipping rectangle.

• shader_program

  The ShaderProgram to draw this Group using.

• shapes

  A read-write Array of Shapes that this group contains.

ShaderProgram

TODO: GetDefaulShaderProgram()

Network

Socket

An object representing a network socket, which is a port and address of a machine. This can refer to a network destination, or an address on the local machine.

---

Constructor

• new Socket(address, port);

  Creates a socket that connects to address on port. The address can be a hostname or an IPv4 address. On some systems IPv6 works, but it is not guaranteed.

---

Methods

• getPendingReadSize();

  Gets a size in bytes that can be read from the socket.

• isConnected();

  Checks if the socket is connected and valid to read or write to.

• close();

  Closes the connection. It is safe to call this on a disconnected socket, in which case it has no effect.

• read(size);

  Returns an ArrayBuffer containing size bytes read from the socket. It is recommended to use getPendingReadSize to determine how many bytes to read.

• write(buffer);

  Writes buffer to the socket.

ListeningSocket

An object representing a network socket that listens for incoming connections. A ListeningSocket is not used for reading or writing to a remote connection, but rather for accepting incoming connections.

---

Constructor

• new ListeningSocket(port);

  Creates a ListeningSocket that accepts incoming connections on port number port.

---

Methods

• accept();

  If any incoming connections are pending, returns a Socket object. Otherwise returns null.

• close();

  Closes the ListeningSocket, dropping all pending connections.