Latest revision as of 16:24, 5 August 2017

This is a definitive reference of the **legacy** Sphere 1.5 API. In other words, the functions that Sphere 1.5 uses in its JavaScript engine.

For the newer Sphere 2 API, please check API:Functions.

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

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

Graphics primitives

NOTE: Be sure to use FlipScreen() when you are done drawing.

• Point(x, y, color): Plot a point with color.
• PointSeries(array, color'): Plot a series of points from an array of objects using color.
• Line(x1, y1, x2, y2, color): Draw a line with color.
• GradientLine(x1, y1, x2, y2, color1, color2): Draw a line that fades between colors.
• LineSeries(array, color [, type]): Draws a series of lines from an array of objects using color
• BezierCurve(color, step, Ax, Ay, Bx, By, Cx, Cy [, Dx, Dy]): Draws a series of points of the given color along a Bezier curve from A to C, controlled by B (A's control point) and D (optional, C's control point).

  step (0, 1] controls how many points are plotted (smaller step == more points).

• Polygon(array, color [, invert]): Draws a color-filled polygon using the array of objects (each object must have a 'x' and 'y' property).

  If invert is true, all points in the bounding box of the polygon, but not in the polygon will be colored.

• Triangle(x1, y1, x2, y2, x3, y3, color): Draw a triangle with color.
• GradientTriangle(x1, y1, x2, y2, x3, y3, color1, color2, color3): Draw a filled triangle that smoothly changes colors between the vertices.

• Rectangle(x, y, width, height, color): Draw a rectangle filled with color.
• OutlinedRectangle(x, y, width, height, color [, size]): Draws the outline of a rectangle.
• GradientRectangle(x, y, width, height, color_ul, color_ur, color_lr, color_ll): Draw a rectangle filled with gradient colors.

• FilledCircle(x, y, radius, color [, antialias]): Draws a circle filled with color.
• OutlinedCircle(x, y, radius, color [, antialias]): Draws the outline of a circle with color.
• GradientCircle(x, y, radius, color1, color2 [, antialias]): Draws a circle filled with gradient colors.
• FilledEllipse(x, y, rx, ry, color): Draws an ellipse filled with color.
• OutlinedEllipse(x, y, rx, ry, color): Draws the outline of an ellipse with color.

• FilledComplex(rx, ry, rw, rh, cx, cy, cr, ca, cf, fill_empty, color1, color2): Draws a filled rectangle at (rx, ry) with rw width and rh height colored with 'color1', with a circle with the radius cr and the color 'color2' drawn onto it.

  Part of the circle can be filled in by specifying the angular offset 'ca' and angular size 'cf'.

  If fill_empty is true, any part of the rectangle not filled by the arc will be filled with 'color1' instead of being left transparent.

• OutlinedComplex(rx, ry, rw, rh, cx, cy, cr, color [, antialias]): Draws a filled rectangle at (rx, ry) with rw width and rh height colored with color, with a circle with the radius cr cut out at (cx, cy) onto the video buffer.
• GradientComplex(rx, ry, rw, rh, cx, cy, cr, ca, cf, fill_empty, color1, color2, color3): Similar to FilledComplex, but fills the circle/arc with a gradient from color2 (center) to color3 (edge). All other arguments are identical.

Input

Player Input

• GetPlayerKey(player, player_key): Returns the key constant associated with the configurable player key of 'player'.
  • Allowed 'player' values are 0 - 3 or:

    PLAYER_1

    PLAYER_2

    PLAYER_3

    PLAYER_4

  • Allowed 'player_key' values are:

    PLAYER_KEY_MENU

    PLAYER_KEY_UP

    PLAYER_KEY_DOWN

    PLAYER_KEY_LEFT

    PLAYER_KEY_RIGHT

    PLAYER_KEY_A

    PLAYER_KEY_B

    PLAYER_KEY_X

    PLAYER_KEY_Y

API:Functions/Input/Keyboard

API:Functions/Input/Mouse

API:Functions/Input/Joystick

Networking

• GetLocalAddress(): Get the local IP address.
• GetLocalName(): Get the local computer name.
• ListenOnPort(port): Wait for a connection and return a socket for it.
• OpenAddress(address, port): Connect to address on port.

API:Functions/Networking/Socket

Map Engine

Map and map engine control

• MapEngine(map_filename, fps): Start the map engine at map_filename at speed fps.
• GetCurrentMap(): Get the filename of the loaded map.
• ChangeMap(map_filename): Change the current map of the map engine.
• IsMapEngineRunning(): Check if the map engine is running or not.
• UpdateMapEngine(): Update state of map entities, animations and events in map engine.
• ExitMapEngine(): Flag the map engine to exit on the next update.

• RenderMap(): Draw all map layers and persons to the back buffer.
• GetMapEngineFrameRate(): Get the frames per second the map engine is running at.
• SetMapEngineFrameRate(fps): Change map engine frame rate.
• SetColorMask(color, frames): Draws color over the map engine for frames duration.

Map object

• Sphere Map object: Holds map data.

• GetMapEngine(): Obtain the current Map object.
• Map.save(filename): Save a Map object to filename.
• Map.layerAppend(layer_width, layer_height, tile_index): Adds a new layer to the Map object.

Map scripts

• SetRenderScript(script): Set script to run after each time the map is drawn.
• SetUpdateScript(script): Set script to run after each map engine update.

• CallMapScript(map_event): Call map script associated with the current map.
• CallDefaultMapScript(map_event): Call map script set by SetDefaultMapScript().
• SetDefaultMapScript(map_event, script): Set map engine to run script when map_event occurs for any map.
  • Map event constants:

    SCRIPT_ON_ENTER_MAP

    SCRIPT_ON_LEAVE_MAP

    SCRIPT_ON_LEAVE_MAP_NORTH

    SCRIPT_ON_LEAVE_MAP_EAST

    SCRIPT_ON_LEAVE_MAP_SOUTH

    SCRIPT_ON_LEAVE_MAP_WEST

• SetDelayScript(frames, script): Run script after frames delay.

Map Elements

Zones

• AreZonesAt(x, y, layer): Check if there are any zones at (x, y) on layer.
• ExecuteZones(x, y, layer): Run all scripts for zones that (x, y) on layer is in.
• GetNumZones(): Get the number of zones on the current map.

For each zone

• GetCurrentZone(): Get the current zone index in a zone script.
• ExecuteZoneScript(zone): Execute the script of zone.

Zone position

• GetZoneX(zone): Get the X coordinate of zone on the map.
• GetZoneY(zone): Get the Y coordinate of zone on the map.
• GetZoneWidth(zone): Get the pixel width of zone.
• GetZoneHeight(zone): Get the pixel height of zone.

• GetZoneLayer(zone): Get the map layer index of zone.
• SetZoneLayer(zone, layer): Sets the map layer of zone to layer.

Triggers

• IsTriggerAt(x, y, layer): Check if there is a trigger at pixel coords (x, y) on layer.
• ExecuteTrigger(x, y, layer): Activate the trigger at (x, y) on layer if one exists.

Layers

• GetNumLayers(): Get number of layers in the current map.

• GetLayerName(layer): Get the name of layer.

• GetLayerWidth(layer): Get width of layer in tiles.
• GetLayerHeight(layer): Get height of layer in tiles.
• SetLayerWidth(layer, width): Set width of layer in tiles.
• SetLayerHeight(layer, height): Set height of layer in tiles.
• GetLayerAngle(layer): Get layer angle in radians.
• SetLayerAngle(layer, angle): Set layer rotation to angle radians.

• GetLayerMask(layer): Get Color mask of layer.
• SetLayerMask(layer, color_mask): Mask the layer with color_mask.

• IsLayerReflective(layer): Find if layer shows person entity reflections.
• SetLayerReflective(layer, reflect): Set reflectivity of layer.
• IsLayerVisible(layer): Find if layer is visible.
• SetLayerVisible(layer, visible): Set visibility of layer.

• SetLayerScaleFactorX(layer, factor): Set width scaling of layer to factor.
• SetLayerScaleFactorY(layer, factor): Set height scaling of layer to factor.

• SetLayerRenderer(layer, script): Run script after layer has been rendered.

Tiles

• GetNumTiles(): Get the number of tiles in the current map tileset.
• GetTileWidth(): Get the image width of tiles in the current map tileset.
• GetTileHeight(): Get the image height of tiles in the current map tileset.

• GetTile(tile_x, tile_y, layer): Get the tileset index of the tile at the given map position.
• SetTile(tile_x, tile_y, layer, tile): Plot a tile at the given map location.
• ReplaceTilesOnLayer(layer, old_tile, new_tile): Substitute all old_tile with new_tile on layer.

• GetTileName(tile): Get the name of tile.
• GetTileImage(tile): Get the Image of tile in the current map tileset.
• SetTileImage(tile, image): Change the Image of tile.
• SetTileSurface(tile, surface): Change the Surface of tile.

Tile animations

• GetNextAnimatedTile(tile): Get next tile index of animation from tile.
• SetNextAnimatedTile(tile, next): Set next tile in a tile animation sequence.

• GetTileDelay(tile): Get frame delay of animated tile.
• SetTileDelay(tile, delay): Set a frame delay for this tile animation frame.

Input

Player input

• GetInputPerson(): Get the name of the person who holds player input.
• IsInputAttached(): Check if input is attached to a person or not.
• AttachInput(person): Give input control of person to the player.
• DetachInput(): Remove input control given by AttachInput() or AttachPlayerInput().
• AttachPlayerInput(person, player): Give input control of person to player.
• DetachPlayerInput(person): Remove input control from person given to a player.

Binding scripts to input devices

Note: Binding a key or joystick button overrides whatever input has already been associated with it via AttachInput or AttachPlayerInput!

• BindKey(key, on_key_down, on_key_up): Bind scripts to key events.
• UnbindKey(key): Remove script binding from the given key.

• BindJoystickButton(joystick, button, on_button_down, on_button_up): Bind scripts to joystick button events.
• UnbindJoystickButton(joystick, button): Unbind joystick buttons from scripts.

Camera

Following entities

• GetCameraPerson(): Get the name of the person the camera is attached to.
• IsCameraAttached(): Check if the camera is attached to a person.
• AttachCamera(person): Make the camera follow person.
• DetachCamera(): Stop the camera from following any person.

Camera position

• GetCameraX(): Get the map X coordinate the camera is focusing on.
• SetCameraX(x_pos): Set the X coordinate of the camera.
• GetCameraY(): Get the map Y coordinate the camera is focusing on.
• SetCameraY(y_pos): Set the Y coordinate of the camera.

Coordinate conversion

Coordinate conversion translates the current map position to screen coordinates based on the current camera position, and vice versa. Some functions (like checking obstructions) require map coordinates, while others (like image blitting) require screen coordinates. Both map and screen coordinates consider the top-left corner to be (0,0) and extend right-ward and down-ward for X and Y position, respectively.

• MapToScreenX(layer, x): Convert a map X coordinate to screen X.
• MapToScreenY(layer, y): Convert a map Y coordinate to screen Y.
• ScreenToMapX(layer, x): Convert a screen X coordinate to map layer X.
• ScreenToMapY(layer, y): Convert a screen Y coordinate to map layer Y.

Persons

NOTE: Entities are known in script as "persons" for legacy reasons.

• GetPersonList(): Get an array of all named persons on the current map.
• CreatePerson(name, spriteset, destroy_with_map): Create a new person called name with spriteset (filename).
• DestroyPerson(name): Destroy the person called name.
• FollowPerson(name, leader, pixels): Makes a sprite follow behind another sprite.

Entity position

• GetPersonX(name): Get the map X coordinate of name.
• GetPersonY(name): Get the map Y coordinate of name.
• GetPersonLayer(name): Get the map layer index of name.

• SetPersonX(name, x): Set the map X of name to x.
• SetPersonY(name, y): Set the map Y of name to y.
• SetPersonLayer(name, layer): Set the map layer of name to layer.

• GetPersonXFloat(name): Get the map X of name to floating point accuracy.
• GetPersonYFloat(name): Get the map Y of name to floating point accuracy.
• SetPersonXYFloat(name, x, y): Set the position of name with floating point accuracy.

Directions and animations

• GetPersonDirection(name): Get the animation direction of person name.
• SetPersonDirection(name, direction): Set animation direction of person name to direction.

• GetPersonFrame(name): gets the frame and direction that are currently being displayed.
• SetPersonFrame(name, frame): sets which frame from which direction to display.

• SetPersonFrameRevert(name, delay): sets the delay between when the person last moved and returning to first frame.
• GetPersonFrameRevert(name): gets the delay between when the person last moved and returning to first frame.

Movement speed

• GetPersonSpeedX(name): gets a person's x speed.
• GetPersonSpeedY(name): gets a person's y speed.

• SetPersonSpeed(name, speed): sets the person's speed.
• SetPersonSpeedXY(name, speed_x, speed_y): sets the person's x and y speed independently.

Appearance

• GetPersonOffsetX(name): gets the horizontal offset used for blitting frames
• SetPersonOffsetX(name, x): sets the horizontal offset to use for blitting frames; e.g. setting it to 10 would result in the person frame blitted always 10 pixels to the right, while the person's x-position would remain unchanged.
• GetPersonOffsetY(name): gets the vertical offset used for blitting frames
• SetPersonOffsetY(name, y): sets the vertical offset to use for blitting frames; e.g. setting it to 10 would result in the person frame blitted always 10 pixels to the bottom, while the person's y-position would remain unchanged.
• GetPersonAngle(name): Get the rotation angle of the person name.
• SetPersonAngle(name, angle): Set the rotation angle of person name to angle radians.

• GetPersonMask(name): Get the masking color of the person name.
• SetPersonMask(name, color): Set the color-channel multiplying mask color of the person name.

• SetPersonScaleFactor(name, scale_w, scale_h): Rescales the sprite of person name by relative factors scale_w and scale_h.
• SetPersonScaleAbsolute(name, width, height): Rescales the sprite of person name to width * height pixels.

• GetPersonSpriteset(name): Get the spriteset of person name.
• SetPersonSpriteset(name, spriteset): Set the spriteset of person name to spriteset (Sphere Spriteset object).

• IsPersonVisible(name): Check if the person with name is visible or not.

  true: visible, false: not visible.

• SetPersonVisible(name, visible): Make person name visible or invisible.

  true: visible, false: not visible.

Obstruction

• GetPersonBase(name): Get a person's spriteset obstruction base.
• IsPersonObstructed(name, x, y): Check if person "name" would be obstructed at (x, y).

• IgnoreTileObstructions(person, ignore): Sets whether person "person" ignores tile obstructions.
• IsIgnoringTileObstructions(person): Checks whether "person" is ignoring tile obstructions.

• GetObstructingTile(name, x, y): returns the tile index of the tile if name is obstructed at x, y

  returns -1 if name isn't obstructed by a tile at x, y,

• GetObstructingPerson(name, x, y): returns the name of the person if name is obstructed at x, y

  returns "" if name isn't obstructed by any person at x, y,

• IgnorePersonObstructions(person, ignore): Sets whether 'person' should ignore other spriteset bases
• IsIgnoringPersonObstructions(person): Returns true if 'person' is ignoring person obstructions, else false
• GetPersonIgnoreList(person): Returns a list of people that 'name' is ignoring
• SetPersonIgnoreList(person, ignore_list): Tells 'person' to ignore everyone in ignore_list; e.g. SetPersonIgnoreList("White-Bomberman", ["bomb", "powerup"]); tells White-Bomberman to not be obstructed by bombs or powerups

Talk interaction

• SetTalkActivationKey(key): set key used to activate talk scripts
• GetTalkActivationKey(): return the key code used to activate talk scripts
• SetTalkDistance(pixels): set maximum distance to check for talk script activation
• GetTalkDistance(): return the maximum distance to check for talk script activation

Entity data

• GetPersonData(name): gets a data object associated with the person 'name'

  There are certain default properties/values filled in by the engine, they are:

  num_frames - the number of frames for the person's current direction

  num_directions - the number of directions for the person

  width - the width of the spriteset's current frame

  height - the height of the spriteset's current frame

  leader - the person that this person is following, or "" if no-one...

  Any other properties are free for you to fill with values, e.g.
  

  var data = GetPersonData("Jimmy"); var num_frames = data["num_frames"];

• SetPersonData(name, data): sets the 'data' object associated with the person 'name'; e.g.
  

  var data = GetPersonData("Jimmy"); data["talked_to_jimmy"] = true; SetPersonData("Jimmy", data);

• SetPersonValue(name, key, value)
  - SetPersonValue("Jimmy", "talked_to_jimmy", true); // same as code above
• GetPersonValue(name, key)
  - GetPersonValue("Jimmy", "num_frames"); // same as previous code above

Controlling entities in script

• GetCurrentPerson()
• SetPersonScript(name, which, script)
  • Available Person scripts:

    SCRIPT_ON_CREATE

    SCRIPT_ON_DESTROY

    SCRIPT_ON_ACTIVATE_TOUCH

    SCRIPT_ON_ACTIVATE_TALK

    SCRIPT_COMMAND_GENERATOR

• CallPersonScript(name, which)

• QueuePersonCommand(name, command, immediate): add a command to the person's command queue.
  • Available Person commands:

    COMMAND_WAIT

    COMMAND_ANIMATE

    COMMAND_FACE_NORTH

    COMMAND_FACE_NORTHEAST

    COMMAND_FACE_EAST

    COMMAND_FACE_SOUTHEAST

    COMMAND_FACE_SOUTH

    COMMAND_FACE_SOUTHWEST

    COMMAND_FACE_WEST

    COMMAND_FACE_NORTHWEST

    COMMAND_MOVE_NORTH

    COMMAND_MOVE_EAST

    COMMAND_MOVE_SOUTH

    COMMAND_MOVE_WEST

• QueuePersonScript(name, script, immediate): Queue a script command on the command queue of name.
• IsCommandQueueEmpty(name): Check if the command queue of the person is empty.
• ClearPersonCommands(name): Clears the command queue of the named person.

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.

Sounds

• Sphere Sound object: Holds a sound or piece of music that can be played.
• Sphere SoundEffect object: Holds a sound that can be played. This powerful object is designed mainly for sound effects.
• LoadSound(filename [, streaming]): Load a sound from filename, streaming from disk optional.

Sound object

• Sound.play(repeat): Play the sound, loop if repeat is true.
• Sound.pause(): Pause playback of the sound. Call Sound.play() to resume.
• Sound.stop(): Stop playback of the sound.

• Sound.reset(): Resets playback. No effect on MIDIs.
• Sound.setRepeat(repeat): Sets if the sound should be repeated.
• Sound.getRepeat(): Returns true if sound is set to repeat, otherwise false.

• Sound.isPlaying(): Check if the sound is currently playing.
• Sound.isSeekable(): Returns true if the sound is seekable. Not all sound types are seekable, Ogg is.
• Sound.getLength(): Gets the length of the sound.
• Sound.clone(): Returns a copy of the sound object.
• Sound.getPosition(): Returns the position of the sound, zero if the sound isn't seekable.
• Sound.setPosition(position): Sets the position of the sound. Does nothing if the sound isn't seekable.

• Sound.getVolume(): Get the volume of the sound (0-255). No effect on MIDIs.
• Sound.setVolume(volume): Set the volume of the sound (0-255). No effect on MIDIs.
• Sound.setPan(pan): Pan can be from -255 to 255. -255 = left, 255 = right. No effect on MIDIs.
• Sound.getPan(): Returns the current pan of the sound. No effect on MIDIs.
• Sound.setPitch(pitch): Sets the pitch for a sound. No effect on MIDIs.
• Sound.getPitch(): Returns the current pitch. No effect on MIDIs.

Sound Effect object

• Sphere SoundEffect object
• LoadSoundEffect(filename [, type]): returns a SoundEffect object from 'filename'. If Sphere is unable to open the file, the engine will give an error message and exit. There are two types of sound effects: SE_SINGLE and SE_MULTIPLE.
  • SE_SINGLE sound effects only allow the sound to be played once at a time.
  • SE_MULTIPLE sound effects always open a new stream to the audio device for each time it is played (cleaning up or reusing old streams if possible).
• SoundEffect.play(): plays the sound effect.
  • If the sound effect is of type SE_SINGLE, this plays the sound if it isn't playing yet, and starts it again if it is.
  • If the sound effect is of type SE_MULTIPLE, play() simply starts playing the sound again.
• SoundEffect.stop(): stops playback
  • If the sound is of type SE_SINGLE, stop the sound.
  • If it is of type SE_MULTIPLE, stop all playing instances of the sound.
• SoundEffect.setVolume(volume): sets the volume for the sound effect (0-255)
• SoundEffect.getVolume(): returns the sound effect's volume (0-255)
• SoundEffect.setPan(pan): pan ranges from -255 to 255. -255 = left, 255 = right. pan defaults to 0 (center).
• SoundEffect.getPan(): returns the current pan of the sound effect
• SoundEffect.setPitch(pitch): pitch ranges from 0.5 to 2.0. 0.5 is an octave down (and half as fast) while 2.0 is an octave up (and twice as fast). pitch defaults to 1.0
• SoundEffect.getPitch(): returns the current pitch

Colors

• Sphere Color object: Holds RGBA data for a color.
• CreateColor(red, green, blue[, alpha]): Create a new Color object.

Blending colors

• BlendColors(c1, c2): Mix two Colors evenly.
• BlendColorsWeighted(c1, c2, c1_weight, c2_weight): Mix two Colors in given proportions.

Color matrices

• Sphere ColorMatrix object used to transform colors
• CreateColorMatrix(rn, rr, rg, rb, gn, gr, gg, gb, bn, br, bg, bb): Creates a ColorMatrix that is used to transform the colors contained in a pixel with the following formula:

  newcolor.red = rn + (rr * oldcolor.red + rg * oldcolor.green + rb * oldcolor.blue) / 255;

  newcolor.green = gn + (gr * oldcolor.red + gg * oldcolor.green + gb * oldcolor.blue) / 255;

  newcolor.blue = bn + (br * oldcolor.red + bg * oldcolor.green + bb * oldcolor.blue) / 255;

(see Surface.applyColorFX and Surface.applyColorFX4)

Spritesets

• Sphere Spriteset object: Holds appearance, direction and base data for a map person.

• Spriteset.images[]: an array of all images in the spriteset.
• Sphere Spriteset.base: contains a SpritesetBase object which holds coordinates of the spriteset's collision box/obstruction base relative to the Spriteset dimensions.
• Sphere Spriteset.directions[]: an array of SpritesetDirection objects, each of which containing a direction name and a sequence of SpritesetFrame objects determining the order of images used and delays between animation.

• LoadSpriteset(filename): Load a Sphere Spriteset from filename.
• CreateSpriteset(frame_width, frame_height, num_images, num_directions, num_frames): returns a blank spriteset object with the given dimensions
• Spriteset.save(filename): saves the spriteset object to 'filename'
• Spriteset.clone(): returns a copy of the spriteset object

Fonts

• Sphere Font object: The graphical representation of text.
• GetSystemFont(): Load the default system font.
• LoadFont(): Load a font file.

Font object

• Font.clone(): returns a copy of 'font_object'

Drawing text

• Font.drawText(x, y, text): Draw text at (x, y) using the font.
• Font.drawTextBox(x, y, width, height, y_offset, text): Draw wrapped text, shifted up/down by y_offset, in the box (x, y, width, height).
• Font.drawZoomedText(x, y, scale, text): Draw scaled text with upper-left corner (x, y) using the font.
• Font.wordWrapString(string, width): Splits a string into an array of lines as if it were wrapped using Font.drawTextBox().

Font size info

• Font.getHeight(): Get the height of chars in the font, in pixels.

• Font.getStringWidth(string): Determine the width of a string drawn with the font, in pixels.
• Font.getStringHeight(string, width): Determine the height of the string as if it was drawn by Font.drawTextBox() with width.

Font color masking

• Font.getColorMask(): Get the color mask being used by the font.
• Font.setColorMask(color): Set the color mask for a font to color (see color masking).

Font characters

• Font.getCharacterImage(code): returns the image in the font_object of the character based on the code, e.g. 65 is 'A'
• Font.setCharacterImage(code, image): sets the character image in the font_object based on the code

Saving to disk

• Font.save(filename): saves the Font_object as a font using the filename 'filename'

WindowStyles

• Sphere WindowStyle object: holds a windowstyle for drawing.
• GetSystemWindowStyle(): Get the default window style that comes with the Sphere engine.
• LoadWindowStyle(filename): returns a windowstyle object from 'filename'.

WindowStyle object

Drawing windows

• WindowStyle.drawWindow(x, y, w, h): Draw a window (x, y, w, h) with external borders.

WindowStyle color masking

• WindowStyle.getColorMask(): gets the color mask being used by the windowstyle object
• WindowStyle.setColorMask(color): sets the color mask for a windowstyle (see ApplyColorMask)

Images

• Sphere Image object: Holds a 2D bitmap for displaying.
• LoadImage(filename): Load an image from filename.
• GrabImage(x, y, width, height): Grab the screen contents at (x, y, width, height) and store it in a new Image object.

System images

• GetSystemArrow(): Get the right-pointing arrow image that comes with the Sphere engine.
• GetSystemUpArrow(): Get the up-pointing arrow image that comes with the Sphere engine.
• GetSystemDownArrow(): Get the down-pointing arrow image that comes with the Sphere engine.

Image object

• Image.clone(): returns a copy of 'image_object'

Blitting (drawing) images

• Image.blit(x, y): Draw the image with the top-left corner at (x, y).
• Image.blitMask(x, y, mask): Draw the image at (x, y) with mask as the tinting color.
• Image.rotateBlit(center_x, center_y, angle): Draw the image centered at (center_x, center_y), rotated by angle radians.
• Image.rotateBlitMask(center_x, center_y, angle, mask): rotateBlit + mask.
• Image.zoomBlit(x, y, factor): Draw the image zoomed by factor with the top-left corner at (x, y).
• Image.zoomBlitMask(x, y, factor, mask): zoomBlit + mask.
• Image.transformBlit(x1, y1, x2, y2, x3, y3, x4, y4): Draw the image with top-left (x1, y1), top-right (x2, y2), bottom-right (x3, y3) and bottom-left (x4, y4).
• Image.transformBlitMask(x1, y1, x2, y2, x3, y3, x4, y4, mask): Draw the image stretched to fit 4 coordinates clockwise from the top-left, with a masking color.