Legacy:Functions

From Spherical
Revision as of 18:29, 22 May 2013 by Apollolux (talk | contribs) (Sphere objects: reorder, description)
Jump to: navigation, search

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:


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.



General functions

Script functions

File inclusion

Engine functions

Game control

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

System interfaces

Video

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.

Frame rate control

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 along a Bezier curve from A to C, controlled
     by B (A's control point) and D (optional, C's control point), with
     the color. step (0, 1] controls how many points are plotted
     (smaller step == more points).
  • 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.
 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.
  • OutlinedRectangle(x, y, width, height, color [, size]): Draws the outline of a rectangle.
  • Rectangle(x, y, width, height, color): Draw a rectangle filled with color.
  • GradientRectangle(x, y, width, height, color_ul, color_ur, color_lr, color_ll): Draw a rectangle filled with gradient colors.
  • OutlinedEllipse(x, y, rx, ry, color): Draws the outline of an ellipse with color.
  • FilledEllipse(x, y, rx, ry, color): Draws an ellipse filled with color.
  • OutlinedCircle(x, y, radius, color [, antialias]): Draws the outline of a circle with color.
  • FilledCircle(x, y, radius, color [, antialias]): Draws a circle filled with color.
  • GradientCircle(x, y, radius, color1, color2 [, antialias]): Draws a circle filled with gradient colors.
 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.
 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.
 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.

Screen size

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

Keyboard

Key code translation

  • GetKeyString(key, shift): Converts the given key into a string, KEY_A will become "a", etc. If shift is true, returns uppercase/special value of key. Control keys return an empty string.

Key status

  • GetToggleState(key): Checks if Caps Lock, Num Lock or Scroll Lock are active.
  • Allowed key values:
    • KEY_CAPSLOCK
    • KEY_NUMLOCK
    • KEY_SCROLLOCK (Note: only two Ls)

Key queue

  • AreKeysLeft(): Check if keys are left in the key buffer.
  • GetKey(): Get a key from the key buffer, waits for one if there isn't.

Mouse

Cursor location

  • GetMouseX(): Get X coordinate of mouse cursor on the screen.
  • GetMouseY(): Get Y coordinate of mouse cursor on the screen.
  • SetMousePosition(x, y): Set mouse cursor location.

Mouse button status

Mouse wheel event queue

Joystick

Button status

Orientation

  • GetJoystickAxis(joystick, axis): Returns the current joystick axis position in normalized coordinates fro -1 to 1.
  • Allowed axis values:
    • JOYSTICK_AXIS_X
    • JOYSTICK_AXIS_Y
    • JOYSTICK_AXIS_Z
    • JOYSTICK_AXIS_R (rotation)

Time

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

Map object

  • Sphere Map object: Holds map data.

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

Data hashing

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

Networking

Socket object

Map Engine

  • MapEngine(map_filename, fps): Start the map engine at map_filename at speed fps.
  • IsMapEngineRunning(): Check if the map engine is running or not.
  • ExitMapEngine(): Flag the map engine to exit on the next update.

Engine control

Map control

  • GetCurrentMap(): Get the filename of the loaded map.
  • ChangeMap(map_filename): Change the current map of the map engine.

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

Within the map engine

  • SetColorMask(color, frames): Draws color over the map engine for frames duration.

Maps

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

Triggers

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

Layers

For each layer
  • SetTile(tile_x, tile_y, layer, tile): Plot a tile at the given map location.

Tiles

  • GetNumTiles(): Get the number 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.
  • GetTileWidth(): Get the image width of tiles in the current map tileset.
  • GetTileHeight(): Get the image height of tiles in the current map tileset.
  • ReplaceTilesOnLayer(layer, old_tile, new_tile): Substitute all old_tile with new_tile on layer.
For each tile
Tile animations
  • GetTileDelay(tile): Get frame delay of animated tile.
  • SetTileDelay(tile, delay): Set a frame delay for this tile animation frame.

Input

Player input

Binding scripts to keys

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

Binding scripts to joystick buttons

Camera

Following persons

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

  • 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

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

Person position

  • 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

  • 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

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

 GetObstructingTile(name, x, y)
   - returns -1 if name isn't obstructed by a tile at x, y,
   - returns the tile index of the tile if name is obstructed at x, y
 GetObstructingPerson(name, x, y)
   - returns "" if name isn't obstructed by person at x, y,
   - returns the name of the person if name is obstructed 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)
 GetTalkActivationKey()
   - set key used to activate talk scripts
 SetTalkDistance(pixels)
 GetTalkDistance()
   - set distance to check for talk script activation

Following other persons

  • FollowPerson(name, leader, pixels): Makes a sprite follow behind another sprite.

Person data

 GetPersonData(name)
   - gets a data object assiocated 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 assiocated 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

Person control

  • SetPersonScript(name, which, script)
  • 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.
  • 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.

API:Functions/Sounds

API:Functions/Colors

API:Functions/ColorMatrices

API:Functions/Spritesets

API:Functions/Fonts

API:Functions/WindowStyles

API:Functions/Images

API:Functions/Surfaces

API:Functions/Animations

API:Functions/Filesystem

API:Functions/Files

API:Functions/Log