Legacy:Functions

This is a definitive reference of the Sphere API: in other words, the functions that Sphere uses in its JavaScript engine. The page currently mimics the layout of docs/development/api.txt, but is undergoing reorganisation.

Alternatively, the whole Sphere API, sorted by category, with brief descriptions of the functions is available in the API text file mirror itself.

For assistance with using JavaScript itself, consult these links:

• https://developer.mozilla.org/en/Core_JavaScript_1.5_Guide - Mozilla JavaScript Guide
• https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference - Mozilla JavaScript Reference

Making new function/object pages

Simple steps:

1. Click a red link.
2. Place the following code in the empty edit box: {{subst:functemp}} for a new function, or {{subst:objecttemp}} for a new object.
3. Check the minor edit flag and save.
4. Click 'edit' at the top of the page to add content.
5. Try to be objective when writing, and save when you're done.
6. Remove description from this page, add page link to list at the top of the matching section.

Engine functions

• GetVersion(): Get the version of Sphere as a number.
• GetVersionString(): Get the full Sphere version.

Game control

• Abort(): Exit with a message.
• Exit(): Exit unconditionally.
• RestartGame(): Restarts the game.

Accessing installed games

• Sphere Game object: Holds info about an installed Sphere game.
• GetGameList(): Get a list of installed Sphere games.
• ExecuteGame(directory): Execute Sphere game installed in directory.

Script functions

• GarbageCollect(): Run JavaScript's garbage collector to free memory.

File inclusion

• EvaluateScript(filename): Include a script file unconditionally.
• EvaluateSystemScript(filename): Include a system script file unconditionally.
• RequireScript(filename): Include a script file once.
• RequireSystemScript(filename): Include a system script file once.

Time

• GetTime(): Get the number of milliseconds since an arbitrary point in time.

Conversion

• CreateStringFromCode(ascii_code): Translate a number to the matching character.

System interfaces

Video

• FlipScreen(): Show the results of drawing to the screen.
• GetFrameRate(): Get the frame rate that limits FlipScreen() call rate.
• SetFrameRate(frames_per_second): Limit the rate of FlipScreen() calls.
• ApplyColorMask(color): Fills the whole screen with color.

Screen size

• GetScreenWidth(): Get the width of the screen.
• GetScreenHeight(): Get the height of the screen.

Clipping

• Sphere Rectangle object: Holds dimensions for clipping rectangle functions.
• GetClippingRectangle(): Get the rectangle in which drawing is being clipped on screen.
• SetClippingRectangle(x, y, width, height): Set a rectangle to clip screen drawing.

Sphere objects

Besides the above, Sphere has a set of built-in objects for more generalized use within projects. Most are loaded from external resource files, but a few (Color, ColorMatrix) are defined solely in script and remain only in-memory during the running of the project.

ByteArray object

• Sphere ByteArray object: Holds an array of bytes.
• CreateByteArray(length): Create a new ByteArray.
• bytearray.concat(byte_array_object, byte_array_to_append): Returns bytearray with byte_array_to_append attached to the end of it
• bytearray.slice(start_slice [, end_slice]): 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.

Conversion to and from strings

• CreateByteArrayFromString(string): Create a ByteArray from string.
• CreateStringFromByteArray(byte_array): Convert a ByteArray into a string.

Data hashing

• HashByteArray(byte_array): Calculate MD5 'fingerprint' of data in byte_array.