Difference between revisions of "Legacy:Functions"

From Spherical
Jump to: navigation, search
(Colors: API links)
(Added category and warning)
 
(33 intermediate revisions by 2 users not shown)
Line 1: Line 1:
[[Category:Functions]]
+
{{LegacyWarning}}
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 <code>docs/development/api.txt</code>, but is undergoing reorganisation.
+
 
 +
 
 +
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 [[Doc Functions|API text file]] mirror itself.
 
Alternatively, the whole Sphere API, sorted by category, with brief descriptions of the functions is available in the [[Doc Functions|API text file]] mirror itself.
Line 8: Line 12:
 
*https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference - Mozilla JavaScript Reference
 
*https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference - Mozilla JavaScript Reference
  
 
+
<noinclude>
 
{{section|sph-section-green|Making new function/object pages|Simple steps:
 
{{section|sph-section-green|Making new function/object pages|Simple steps:
 
#Click a red link.
 
#Click a red link.
Line 27: Line 31:
 
</div>
 
</div>
 
-->
 
-->
 +
</noinclude>
  
 
__TOC__
 
__TOC__
  
= General functions =
+
= Engine functions =
  
* [[CreateStringFromCode]](''ascii_code''): Translate a number to the matching character.
+
* [[Legacy:GetVersion|GetVersion]](): Get the version of Sphere as a number.
* [[GetVersion]](): Get the version of Sphere as a number.
+
* [[Legacy:GetVersionString|GetVersionString]](): Get the full Sphere version.
  
= Script functions =
+
== Game control ==
  
* [[GarbageCollect]](): Run JavaScript's garbage collector to free memory.
+
* [[Legacy:Abort|Abort]](): Exit with a message.
 +
* [[Legacy:Exit|Exit]](): Exit unconditionally.
 +
* [[Legacy:RestartGame|RestartGame]](): Restarts the game.
  
== File inclusion ==
+
== Accessing installed games ==
  
* [[EvaluateScript]](''filename''): Include a script file unconditionally.
+
* Sphere [[Legacy:Game|Game]] object: Holds info about an installed Sphere game.
* [[EvaluateSystemScript]](''filename''): Include a system script file unconditionally.
+
* [[Legacy:GetGameList|GetGameList]](): Get a list of installed Sphere games.
* [[RequireScript]](''filename''): Include a script file once.
+
* [[Legacy:ExecuteGame|ExecuteGame]](''directory''): Execute Sphere game installed in ''directory''.
* [[RequireSystemScript]](''filename''): Include a system script file once.
 
  
= Engine functions =
+
= Script functions =
  
* [[GetVersionString]](): Get the full Sphere version.
+
* [[Legacy:GarbageCollect|GarbageCollect]](): Run JavaScript's garbage collector to free memory.
  
== Game control ==
+
== File inclusion ==
  
* [[Abort]](): Exit with a message.
+
* [[Legacy:EvaluateScript|EvaluateScript]](''filename''): Include a script file unconditionally.
* [[Exit]](): Exit unconditionally.
+
* [[Legacy:EvaluateSystemScript|EvaluateSystemScript]](''filename''): Include a system script file unconditionally.
* [[RestartGame]](): Restarts the game.
+
* [[Legacy:RequireScript|RequireScript]](''filename''): Include a script file once.
 +
* [[Legacy:RequireSystemScript|RequireSystemScript]](''filename''): Include a system script file once.
  
== Acessing installed games ==
+
== Time ==
 +
* [[Legacy:GetTime|GetTime]](): Get the number of milliseconds since an arbitrary point in time.
  
* Sphere [[Object-Game|Game]] object: Holds info about an installed Sphere game.
+
== Conversion ==
* [[GetGameList]](): Get a list of installed Sphere games.
+
* [[Legacy:CreateStringFromCode|CreateStringFromCode]](''ascii_code''): Translate a number to the matching character.
* [[ExecuteGame]](''directory''): Execute Sphere game installed in ''directory''.
 
  
 
= System interfaces =
 
= System interfaces =
Line 66: Line 73:
 
== Video ==
 
== Video ==
  
* [[ApplyColorMask]](''color''): Fills the whole screen with ''color''.
+
* [[Legacy:FlipScreen|FlipScreen]](): Show the results of drawing to the screen.
* [[FlipScreen]](): Show the results of drawing to the screen.
+
* [[Legacy:GetFrameRate|GetFrameRate]](): Get the frame rate that limits [[Legacy:FlipScreen|FlipScreen]]() call rate.
 +
* [[Legacy:SetFrameRate|SetFrameRate]](''frames_per_second''): Limit the rate of [[Legacy:FlipScreen|FlipScreen]]() calls.
 +
* [[Legacy:ApplyColorMask|ApplyColorMask]](''color''): Fills the whole screen with ''color''.
  
=== Clipping ===
+
=== Screen size ===
  
* Sphere [[Object-Rectangle|Rectangle]] object: Holds dimensions for clipping rectangle functions.
+
* [[Legacy:GetScreenWidth|GetScreenWidth]](): Get the width of the screen.
* [[GetClippingRectangle]](): Get the rectangle in which drawing is being clipped on screen.
+
* [[Legacy:GetScreenHeight|GetScreenHeight]](): Get the height of the screen.
* [[SetClippingRectangle]](''x'', ''y'', ''width'', ''height''): Set a rectangle to clip screen drawing.
 
  
=== Frame rate control ===
+
=== Clipping ===
  
* [[GetFrameRate]](): Get the frame rate that limits [[FlipScreen]]() call rate.
+
* Sphere [[Legacy:ClippingRectangle|ClippingRectangle]] object: Holds dimensions for clipping rectangle functions.
* [[SetFrameRate]](''frames_per_second''): Limit the rate of [[FlipScreen]]() calls.
+
* [[Legacy:GetClippingRectangle|GetClippingRectangle]](): Get the rectangle in which drawing is being clipped on screen.
 +
* [[Legacy:SetClippingRectangle|SetClippingRectangle]](''x'', ''y'', ''width'', ''height''): Set a rectangle to clip screen drawing.
  
 
=== Graphics primitives ===
 
=== Graphics primitives ===
  
'''NOTE:''' Be sure to use [[FlipScreen]]() when you are done drawing.
+
{{Legacy:Functions/Primitives}}
  
* [[Point]](''x'', ''y'', ''color''): Plot a point with ''color''.
+
{{Legacy:Functions/Input}}
   
 
* [[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''.
+
{{Legacy:Functions/Networking}}
  
* [[GradientLine]](''x1'', ''y1'', ''x2'', ''y2'', ''color1'', ''color2''): Draw a line that fades between colors.
+
= Map Engine =
  
* [[LineSeries]](''array'', ''color'' [, ''type'']): Draws a series of lines from an array of objects using ''color''
+
{{Legacy:Functions/Map}}
  
  [[BezierCurve]](color, step, Ax, Ay, Bx, By, Cx, Cy [, Dx, Dy])
+
= Sphere objects =
    - 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 ===
 
 
 
* [[GetScreenWidth]](): Get the width of the screen.
 
* [[GetScreenHeight]](): Get the height of the screen.
 
 
 
== 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 ====
 
 
 
* [[IsAnyKeyPressed]](): Check if any key is being held down.
 
* [[IsKeyPressed]](''key''): Check if the given ''key'' is being held down.
 
 
 
* [[GetToggleState]](''key''): Checks if Caps Lock, Num Lock or Scroll Lock are active.
 
* Allowed key values:
 
** <var>KEY_CAPSLOCK</var>
 
** <var>KEY_NUMLOCK</var>
 
** <var>KEY_SCROLLOCK (Note: only two Ls)</var>
 
 
 
==== 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 ====
+
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.
  
* [[IsMouseButtonPressed]](''mouse_button''): Check if a mouse button is being held down.
+
{{Legacy:Functions/Sounds}}
  
==== Mouse wheel event queue ====
+
{{Legacy:Functions/Colors}}
  
* [[GetMouseWheelEvent]](): Returns a single mouse wheel event.
+
{{Legacy:Functions/ColorMatrices}}
* [[GetNumMouseWheelEvents]](): Returns the length of the mouse wheel event queue.
 
  
=== Joystick ===
+
{{Legacy:Functions/Spritesets}}
  
* [[GetNumJoysticks]](): Returns the number of joysticks available on the system.
+
{{Legacy:Functions/Fonts}}
* [[GetNumJoystickButtons]](''joystick''): Returns the number of buttons available on this joystick.
 
* [[GetNumJoystickAxes]](''joystick''): Returns the number of available axes on the given joystick.
 
  
* [[GetTalkActivationButton]](): Get joystick button used to activate talk scripts.
+
{{Legacy:Functions/WindowStyles}}
* [[SetTalkActivationButton]](''button''): Set joystick button used to activate talk scripts.
 
  
==== Button status ====
+
{{Legacy:Functions/Images}}
  
* [[IsJoystickButtonPressed]](''joystick'', ''button''): Find if a button on a joystick is being held down.
+
{{Legacy:Functions/Surfaces}}
  
==== Orientation ====
+
{{Legacy:Functions/Animations}}
  
* [[GetJoystickAxis]](''joystick'', ''axis''): Returns the current joystick axis position in normalized coordinates fro -1 to 1.
+
{{Legacy:Functions/Filesystem}}
* Allowed axis values:
 
** <var>JOYSTICK_AXIS_X</var>
 
** <var>JOYSTICK_AXIS_Y</var>
 
** <var>JOYSTICK_AXIS_Z</var>
 
** <var>JOYSTICK_AXIS_R (rotation)</var>
 
  
== Time ==
+
{{Legacy:Functions/Files}}
  
* [[GetTime]](): Get the number of milliseconds since an arbitrary point in time.
+
{{Legacy:Functions/Log}}
  
== Map object ==
 
 
* Sphere [[Object-Map|Map]] object: Holds map data.
 
 
* [[GetMapEngine]](): Obtain the current [[Object-Map|Map]] object.
 
* [[Map.save]](''filename''): Save a [[Object-Map|Map]] object to ''filename''.
 
* [[Map.layerAppend]](''layer_width'', ''layer_height'', ''tile_index''): Adds a new layer to the [[Object-Map|Map]] object.
 
  
 
== ByteArray object ==
 
== ByteArray object ==
  
* Sphere [[Object-ByteArray|ByteArray]] object: Holds an array of bytes.
+
* Sphere [[Legacy:ByteArray|ByteArray]] object: Holds an array of bytes.
* [[CreateByteArray]](''length''): Create a new [[Object-ByteArray|ByteArray]].
+
* [[Legacy:CreateByteArray|CreateByteArray]](''length''): Create a new [[Legacy:ByteArray|ByteArray]].
* [[bytearray.concat]](''byte_array_object'', ''byte_array_to_append''): Returns bytearray with byte_array_to_append attached to the end of it
+
* [[Legacy:ByteArray/concat|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.
+
* [[Legacy:ByteArray/slice|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 ===
+
=== Conversion ===
  
* [[CreateByteArrayFromString]](''string''): Create a [[Object-ByteArray|ByteArray]] from ''string''.
+
* [[Legacy:CreateByteArrayFromString|CreateByteArrayFromString]](''string''): Create a [[Legacy:ByteArray|ByteArray]] from ''string''.
* [[CreateStringFromByteArray]](''byte_array''): Convert a [[Object-ByteArray|ByteArray]] into a string.
+
* [[Legacy:CreateStringFromByteArray|CreateStringFromByteArray]](''byte_array''): Convert a [[Legacy:ByteArray|ByteArray]] into a string.
  
 
=== Data hashing ===
 
=== Data hashing ===
  
* [[HashByteArray]](''byte_array''): Calculate MD5 'fingerprint' of data in ''byte_array''.
+
* [[Legacy:HashByteArray|HashByteArray]](''byte_array''): Calculate MD5 'fingerprint' of data in ''byte_array''.
  
== Networking ==
 
  
* [[GetLocalAddress]](): Get the local IP address.
+
[[Category:Functions]]
* [[GetLocalName]](): Get the local computer name.
+
[[Category:Sphere 1]]
* [[ListenOnPort]](''port''): Wait for a connection and return a socket for it.
 
* [[OpenAddress]](''address'', ''port''): Connect to ''address'' on ''port''.
 
 
 
=== Socket object ===
 
 
 
* Sphere [[Object-Socket|Socket]] object: Has the ability to send/receive data over a network.
 
* [[Socket.close]](): Close the socket.
 
* [[Socket.getPendingReadSize]](): Get size of next incoming data block in bytes.
 
* [[Socket.isConnected]](): Find if the socket is connected or not.
 
* [[Socket.read]](''size''): Read ''size'' number of bytes into a [[Object-ByteArray|ByteArray]] from socket.
 
* [[Socket.write]](''data''): Send a [[Object-ByteArray|ByteArray]] into the socket.
 
 
 
= 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 ==
 
 
 
* [[GetMapEngineFrameRate]](): Get the frames per second the map engine is running at.
 
* [[SetMapEngineFrameRate]](''fps''): Change map engine frame rate.
 
* [[RenderMap]](): Draw all map layers and persons.
 
* [[UpdateMapEngine]](): Update state of map entities, animations and events in map engine.
 
 
 
== 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.
 
 
 
* [[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:
 
** <var>SCRIPT_ON_ENTER_MAP</var>
 
** <var>SCRIPT_ON_LEAVE_MAP</var>
 
** <var>SCRIPT_ON_LEAVE_MAP_NORTH</var>
 
** <var>SCRIPT_ON_LEAVE_MAP_EAST</var>
 
** <var>SCRIPT_ON_LEAVE_MAP_SOUTH</var>
 
** <var>SCRIPT_ON_LEAVE_MAP_WEST</var>
 
 
 
* [[SetDelayScript]](''frames'', ''script''): Run ''script'' after ''frames'' delay.
 
 
 
== 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 =====
 
 
 
* [[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''.
 
 
 
===== For each trigger =====
 
 
 
* [[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.
 
 
 
===== For each layer =====
 
 
 
* [[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.
 
 
 
* [[SetTile]](''tile_x'', ''tile_y'', ''layer'', ''tile''): Plot a tile at the given map location.
 
 
 
* [[GetLayerAngle]](''layer''): Get ''layer'' angle in radians.
 
* [[SetLayerAngle]](''layer'', ''angle''): Set ''layer'' rotation to ''angle'' radians.
 
 
 
* [[GetLayerMask]](''layer''): Get [[Object-Color|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.
 
* [[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 =====
 
 
 
* [[GetTileName]](''tile''): Get the name of ''tile''.
 
 
 
* [[GetTileImage]](''tile''): Get the [[Object-Image|Image]] of ''tile'' in the current map tileset.
 
* [[SetTileImage]](''tile'', ''image''): Change the [[Object-Image|Image]] of ''tile''.
 
 
 
* [[SetTileSurface]](''tile'', ''surface''): Change the [[Object-Surface|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 ====
 
 
 
* [[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.
 
 
 
* [[IsInputAttached]](): Check if input is attached to a person or not.
 
* [[GetInputPerson]](): Get the name of the person who holds 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 ====
 
 
 
* [[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 persons ====
 
 
 
* [[AttachCamera]](''person''): Make the camera follow ''person''.
 
* [[DetachCamera]](): Stop the camera from following any person.
 
 
 
* [[IsCameraAttached]](): Check if the camera is attached to a person.
 
* [[GetCameraPerson]](): Get the name of the person the camera is attached to.
 
 
 
==== 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 ====
 
 
 
* [[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 ====
 
 
 
* [[SetPersonSpeed]](''name'', ''speed''): sets the person's speed.
 
* [[SetPersonSpeedXY]](''name'', ''speed_x'', ''speed_y''): sets the person's x and y speed individually.
 
 
 
* [[GetPersonSpeedX]](''name''): gets a person's x speed.
 
* [[GetPersonSpeedY]](''name''): gets a person's y 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.
 
 
 
* [[GetPersonMask]](''name''): Get the masking [[Object-Color|color]] of the person ''name''.
 
* [[SetPersonMask]](''name'', ''color''): Set the color-channel multiplying mask ''[[Object-Color|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 [[Object-Spriteset|Spriteset]] object).
 
 
 
* [[IsPersonVisible]](''name''): Check if the person with ''name'' is visible or not. <code>true</code>: visible, <code>false</code>: not visible.
 
* [[SetPersonVisible]](''name'', ''visible''): Make person ''name'' visible or invisible. <code>true</code>: visible, <code>false</code>: 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 -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)
 
 
 
* [[GetCurrentPerson]]()
 
 
 
* [[QueuePersonCommand]](''name'', ''command'', ''immediate''): add a command to the person's command queue.
 
* Person commands:
 
** <var>COMMAND_WAIT</var>
 
** <var>COMMAND_ANIMATE</var>
 
** <var>COMMAND_FACE_NORTH</var>
 
** <var>COMMAND_FACE_NORTHEAST</var>
 
** <var>COMMAND_FACE_EAST</var>
 
** <var>COMMAND_FACE_SOUTHEAST</var>
 
** <var>COMMAND_FACE_SOUTH</var>
 
** <var>COMMAND_FACE_SOUTHWEST</var>
 
** <var>COMMAND_FACE_WEST</var>
 
** <var>COMMAND_FACE_NORTHWEST</var>
 
** <var>COMMAND_MOVE_NORTH</var>
 
** <var>COMMAND_MOVE_EAST</var>
 
** <var>COMMAND_MOVE_SOUTH</var>
 
** <var>COMMAND_MOVE_WEST</var>
 
* [[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 =
 
 
 
== Colors ==
 
 
 
* Sphere [[API:Color|Color]] object: Holds RGBA data for a color.
 
* [[API:CreateColor|CreateColor]](''red'', ''green'', ''blue''[, ''alpha'']): Create a new [[API:Color|Color]] object.
 
 
 
=== Blending colors ===
 
 
 
* [[API:BlendColors|BlendColors]](''c1'', ''c2''): Mix two [[API:Color|Color]]s evenly.
 
* [[API:BlendColorsWeighted|BlendColorsWeighted]](''c1'', ''c2'', ''c1_weight'', ''c2_weight''): Mix two [[API:Color|Color]]s in given proportions.
 
 
 
== Log object (debugging) ==
 
 
 
* [[OpenLog]](''filename''): Create a new log file.
 
 
 
* Sphere [[Object-Log|Log]] object: Traces script execution by putting messages in a log file.
 
* [[Log.beginBlock]](''name''): Create an indented block with ''name'' as title.
 
* [[Log.endBlock]](): Close an open block.
 
* [[Log.write]](''message''): Write a message to the log.
 
 
 
== Spritesets ==
 
 
 
* Sphere [[Object-Spriteset|Spriteset]] object: Holds appearance, direction and base data for a map person.
 
* Sphere [[Object-SpritesetBase|SpritesetBase]] object: Determines a person's collision box.
 
* Sphere [[Object-SpritesetDirection|SpritesetDirection]] object: Holds a direction name and animation sequence.
 
* Sphere [[Object-SpritesetFrame|SpritesetFrame]] object: A frame (image index, delay) in a [[Object-SpritesetDirection|SpritesetDirection]].
 
 
 
* [[LoadSpriteset]](''filename''): Load a Sphere [[Object-Spriteset|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
 
 
 
== Sounds ==
 
 
 
* Sphere [[API:Sound|Sound]] object: Holds a sound or piece of music that can be played.
 
* Sphere [[Object-SoundEffect|SoundEffect]] object: Holds a sound that can be played. This powerful object is designed mainly for sound effects.
 
 
 
=== Sound object ===
 
 
 
* [[API:LoadSound|LoadSound]](''filename'' [, ''streaming'']): Load a sound from ''filename'', ''streaming'' from disk optional.
 
* [[API:Sound/play|Sound.play]](''repeat''): Play the sound, loop if ''repeat'' is true.
 
* [[API:Sound/pause|Sound.pause]](): Pause playback of the sound. Call [[API:Sound/play|Sound.play]]() to resume.
 
* [[API:Sound/stop|Sound.stop]](): Stop playback of the sound.
 
 
 
* [[API:Sound/reset|Sound.reset]](): Resets playback. No effect on MIDIs.
 
* [[API:Sound/setRepeat|Sound.setRepeat]](repeat): Sets if the sound should be repeated.
 
* [[API:Sound/getRepeat|Sound.getRepeat]](): Returns true if sound is set to repeat, otherwise false.
 
 
 
* [[API:Sound/isPlaying|Sound.isPlaying]](): Check if the sound is currently playing.
 
* [[API:Sound/isSeekable|Sound.isSeekable]](): Returns true if the sound is seekable. Not all sound types are seekable, Ogg is.
 
* [[API:Sound/getLength|Sound.getLength]](): Gets the length of the sound.
 
* [[API:Sound/clone|Sound.clone]](): Returns a copy of the sound object.
 
* [[API:Sound/getPosition|Sound.getPosition]](): Returns the position of the sound, zero if the sound isn't seekable.
 
* [[API:Sound/setPosition|Sound.setPosition]](''position''): Sets the position of the sound. Does nothing if the sound isn't seekable.
 
 
 
* [[API:Sound/getVolume|Sound.getVolume]](): Get the volume of the sound (0-255). No effect on MIDIs.
 
* [[API:Sound/setVolume|Sound.setVolume]](''volume''): Set the volume of the sound (0-255). No effect on MIDIs.
 
* [[API:Sound/setPan|Sound.setPan]](pan): Pan can be from -255 to 255.  -255 = left, 255 = right. No effect on MIDIs.
 
* [[API:Sound/getPan|Sound.getPan]](): Returns the current pan of the sound. No effect on MIDIs.
 
* [[API:Sound/setPitch|Sound.setPitch]](''pitch''): Sets the pitch for a sound. No effect on MIDIs.
 
* [[API:Sound/getPitch|Sound.getPitch]](): Returns the current pitch. No effect on MIDIs.
 
 
 
 
 
=== Sound Effect object ===
 
 
 
  [[LoadSoundEffect]](filename [, type])
 
    - returns a sound effect 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 can be 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
 
 
 
== Fonts ==
 
 
 
* Sphere [[Object-Font|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 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 [[Object-Image|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.
 
 
 
==== Surface conversion ====
 
 
 
* [[Image.createSurface]](): Create a new [[Object-Surface|Surface]] using the picture data in the image.
 
 
 
== Surfaces ==
 
 
 
* [[CreateSurface]](''width'', ''height'', ''color''): Create a [[Object-Surface|Surface]] of dimensions (''width'', ''height''), filled with ''color''.
 
 
 
* [[LoadSurface]](''filename''): Create a [[Object-Surface|Surface]] from an image given by ''filename''.
 
 
 
* [[GrabSurface]](''x'', ''y'', ''width'', ''height''): Grab the screen contents at (''x'', ''y'', ''width'', ''height'') and store it in a new Surface.
 
 
 
=== Surface object ===
 
 
 
* Sphere [[Object-Surface|Surface]] object: A picture canvas in memory that can be drawn to.
 
 
 
  [[Surface.setAlpha]](alpha)
 
    - sets the alpha of the surface
 
 
 
* [[Surface.clone]](): Create a copy of the surface object.
 
 
 
  [[Surface.cloneSection]](x, y, w, h)
 
    - returns a new surface object with the height and width of h and w, with
 
      part of image at (x,y) from the surface_object with the width w and
 
      height h.
 
 
 
==== Drawing on surfaces ====
 
 
 
* [[Blend Modes]]
 
** BLEND (default for drawing)
 
** REPLACE
 
** RGB_ONLY
 
** ALPHA_ONLY
 
** ADD
 
** SUBTRACT
 
** MULTIPLY (default for masking)
 
** AVERAGE
 
** INVERT
 
 
 
  [[Surface.setBlendMode]](mode)
 
    - Sets the blend mode of the surface, which will affect any drawing operation on the surface.
 
      'mode' must be one of the available blend modes for surfaces.
 
 
 
* [[Surface.getPixel]](''x'', ''y''): Get the color of the pixel at (''x'', ''y'') on the surface.
 
* [[Surface.setPixel]](x, y, color): Set the pixel (''x'', ''y'') on the surface to ''color''.
 
    - sets the pixel at (x,y) to 'color'
 
 
 
  [[Surface.replaceColor]](oldColor, newColor)
 
    - replace all pixels of the color oldColor in the surface with newColor
 
 
 
===== Primitives on surfaces =====
 
 
 
  [[Surface.pointSeries]](array, color)
 
    - plots a series of points colored with color onto the surface
 
      with array filled with objects (each object must have a 'x' and 'y' property)
 
 
 
* [[Surface.line]](''x1'', ''y1'', ''x2'', ''y2'', ''color''): Draw a line onto the surface starting from (''x1'', ''y1'') to (''x2'', ''y2'') with ''color''.
 
* [[Surface.gradientLine]](''x1'', ''y1'', ''x2'', ''y2'', ''color1'', ''color2''): Draw a line onto the surface starting from (''x1'', ''y1'') to (''x2'', ''y2'') with a color fade from ''color1'' to ''color2''.
 
 
 
  [[Surface.lineSeries]](array, color [, type])
 
    - draws a series of lines colored with color onto the surface
 
      with array filled with objects (each object must have a 'x' and 'y' property)
 
 
 
  [[Surface.bezierCurve]](color, step, Ax, Ay, Bx, By, Cx, Cy [, Dx] [, Dy])
 
    - Draws a Bezier curve colored with color onto the surface
 
      with step being a floating point number in the range 0 < step <= 1.0
 
      and the points (Ax, Ay: coordinates of the endpoint A),
 
      (Bx, By: coordinates of A's control point B)
 
      (Cx, Cy: coordinates of the endpoint C)
 
      (Dx, Dy: optional, coordinates of C's control point D - if omitted, B is also C's control point)
 
 
 
* [[Surface.outlinedRectangle]](''x'', ''y'', ''width'', ''height'', ''color'' [, ''size'']): Draw an outlined rectangle onto the surface at (''x'', ''y'') of ''width'' and ''height'' colored with ''color'' and with ''size'' determining the thickness.
 
 
 
* [[Surface.rectangle]](''x1'', ''y1'', ''x2'', ''y2'', ''color''): Draw a filled rectangle on the surface from (''x1'', ''y1'') to  (''x2'', ''y2'') with ''color''.
 
 
 
  [[Surface.gradientRectangle]](x, y, w, h, c_ul, c_ur, c_lr, c_ll)
 
    - Draws a gradient rectangle onto the surface at (x,y) with the height h and width w.
 
      Each corner of a rectangle (c_ul = color of upper left corner,
 
      c_ur = color of upper right corner, c_lr = color of lower right corner,
 
      c_ll = color of lower left corner) accepts a color information to
 
      generate the gradient of the rectangle.
 
 
 
* [[Surface.triangle]](''x1'', ''y1'', ''x2'', ''y2'', ''x3'', ''y3'', ''color''): Draw a filled triangle with points (''x1'', ''y1''), (''x2'', ''y2''), (''x3'', ''y3'') with ''color''.
 
 
 
  [[Surface.gradientTriangle]](x1, y1, x2, y2, x3, y3, c1, c2, c3)
 
    - Draws a gradient triangle onto the surface with the points (x1, y1), (x2, y2), (x3, y3),
 
      with each point (c1 = color of (x1, y1), c2 = color of (x2, y2), c3 = color
 
      of (x3, y3)) having a color to generate the gradient of the triangle
 
 
 
  [[Surface.polygon]](array, color [, invert])
 
    - draws a filled polygon colored with color onto the surface
 
      with array filled with 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.
 
 
 
  [[Surface.outlinedEllipse]](x, y, rx, ry, c)
 
    - Draws an outlined ellipse at (x, y) with rx being the horizontal radius
 
      and ry the vertical radius onto the surface with the color c
 
 
 
  [[Surface.filledEllipse]](x, y, rx, ry, c)
 
    - Draws a filled ellipse at (x, y) with rx being the horizontal radius
 
      and ry the vertical radius onto the surface with the color c
 
 
 
  [[Surface.outlinedCircle]](x, y, radius, color [, antialias])
 
    - Draws an outlined circle at (x, y) colored with color onto the surface
 
      if antialias is true, the circle will be antialiased
 
 
 
  [[Surface.filledCircle]](x, y, radius, color [, antialias])
 
    - Draws a filled circle at (x, y) colored with color onto the surface
 
      if antialias is true, the circle will be antialiased
 
 
 
  [[Surface.gradientCircle]](x, y, radius, color1, color2 [, antialias])
 
    - Draws a gradient circle at (x, y) onto the surface
 
      colored with a fading color from color1 to color2
 
      if antialias is true, the circle will be antialiased
 
 
 
===== Text on surfaces =====
 
 
 
  [[Surface.drawText]](font, x, y, text)
 
    - draws 'text' at x, y with the font onto the surface_object
 
 
 
  [[Surface.drawZoomedText]](font, x, y, scale, text)
 
    - draws scaled text (1.0 = normal) with (x,y) as the upper left corner
 
      onto the surface_object
 
 
 
  [[Surface.drawTextBox]](font, x, y, w, h, offset, text)
 
    - draws a word-wrapped text at (x, y) onto the surface_object with the width w and height h.
 
      The offset is the number of pixels which the number of pixels from y which
 
      the actual drawing starts at.
 
      See font_object.drawTextBox for more detail.
 
 
 
==== Manipulating surfaces ====
 
 
 
* [[Surface.rotate]](''angle'', ''resize''): Rotate the surface by ''angle'' radians, ''resize'' to fit if requested.
 
 
 
  [[Surface.resize]](w, h)
 
    - resizes the surface images. This does not stretch or shrink the image
 
      inside the surface.
 
 
 
  [[Surface.rescale]](w, h)
 
    - stretches or shrinks the surface to the new width w and height h
 
 
 
  [[Surface.flipHorizontally]]()
 
    - flips the surface horizontally
 
 
 
  [[Surface.flipVertically]]()
 
    - flips the surface vertically
 
 
 
===== Color effects =====
 
 
 
  [[Surface.applyLookup]](x, y, w, h, red_lookup, green_lookup, blue_lookup, alpha_lookup)
 
    - Apply a lookup table transformation to the pixels contained in x, y, w, h
 
      The lookup parameters are arrays of 256 elements containg the new pixel values.
 
      ex: var invert_lookup = [255, 254, 253, 252, 251, ..., 4, 3, 2, 1, 0];
 
 
 
  [[Surface.applyColorFX]](x, y, w, h,  colormatrix)
 
    - Apply the colormatrix to the pixels contained in x, y, w, h
 
      (see CreateColorMatrix)
 
 
 
  [[Surface.applyColorFX4]](x, y, w, h,  cm_upperleft, cm_upperright, cm_lowerleft, cm_lowerright)
 
    - Apply 4 color matrixes. Each corner has a seperate color matrix.
 
      (see CreateColorMatrix)
 
 
 
==== Drawing (blitting) surfaces ====
 
 
 
* [[Surface.blit]](''x'', ''y''): Draw the surface on the screen at (''x'', ''y'').
 
 
 
  [[Surface.blitSurface]](surface, x, y)
 
    - draws 'surface' onto 'surface_object' at (x,y)
 
 
 
  [[Surface.blitImage]](''image_object'', ''x'', ''y'')
 
    - draws 'image' onto 'surface_object' at (x,y)
 
 
 
  [[Surface.blitMaskSurface]](surface, x, y, mask [, mask_blend_mode])
 
    - draws 'surface' onto the surface_object at (x, y), except that the color passed
 
      as 'mask' tints 'surface'
 
      optionally you can pass one of the blend modes for masking as mask_blend_mode
 
 
 
  [[Surface.rotateBlitSurface]](surface, x, y, angle)
 
    - draws 'surface' onto the surface_object at (x, y), except that 'surface' is rotated
 
      anti-clockwise in radians, with -2*PI <= angle <= 2*PI
 
 
 
  [[Surface.rotateBlitMaskSurface]](surface, x, y, angle, mask [, mask_blend_mode])
 
    - rotateBlitSurface + blitMaskSurface
 
 
 
  [[Surface.zoomBlitSurface]](surface, x, y, factor)
 
    - draws 'surface' onto the surface_object at (x, y) with zooming, with the scaling
 
      depending on factor. Normally a factor of 1 will draw a normal looking
 
      'surface' and between 0 and 1 will shrink it. Any values greater than 1
 
      will stretch it's size.
 
 
 
  [[Surface.zoomBlitMaskSurface]](surface, x, y, factor, mask [, mask_blend_mode])
 
    - zoomBlitSurface + blitMaskSurface
 
 
 
  [[Surface.transformBlitSurface]](surface, x1, y1, x2, y2, x3, y3, x4, y4)
 
    - draws 'surface' onto the surface_object with "transformation", where
 
      (x1, y1) is the upper left corner, (x2, y2) the upper right corner,
 
      (x3, y3) is the lower right corner, and (x4, y4) is the lower left
 
      corner.
 
 
 
  [[Surface.transformBlitMaskSurface]](surface, x1, y1, x2, y2, x3, y3, x4, y4, mask [, mask_blend_mode])
 
    - transformBlitSurface + blitMaskSurface
 
 
 
==== Conversion to image ====
 
 
 
* [[Surface.createImage]](): Create a new [[Object-Image|Image]] with the picture data in the surface.
 
 
 
==== Saving to disk ====
 
 
 
  [[Surface.save]](filename)
 
    - saves the surface_object as an image using the filename 'filename'
 
      the image type is determined by the extension of the file
 
      e.g. surface.save("test.png") saves a png image called test.png
 
 
 
== Color matrices ==
 
 
 
  [[CreateColorMatrix]](rn, rr, rg, rb,  gn, gr, gg, gb,  bn, br, bg, bb)
 
    - Creates a [[Object-ColorMatrix|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]])
 
 
 
== Animations ==
 
 
 
* [[Object-Animation|Animation object]]
 
* [[LoadAnimation]](filename): Load animation file and return an usable Animation object.
 
 
 
==== Animation frames ====
 
* [[Animation.getNumFrames]](): Returns the number of frames the animation contains.
 
* [[Animation.getDelay]](): Returns the delay between frames, in milliseconds.
 
* [[Animation.readNextFrame]](): Readies the next frame for drawing.
 
 
 
==== Drawing animation frames ====
 
 
 
* [[Animation.drawFrame]](x, y): Draws the current frame into the video buffer.
 
* [[Animation.drawZoomedFrame]](x, y, scale): Draws the current frame into the video buffer with a specified zoom scale.
 
 
 
== Directories ==
 
 
 
* [[GetDirectoryList]](''directory'') ''directory'' = directory in which to enumerate directories, the current game's directory if not specified. Returns an array of strings, which contain the directory names that reside in the ''directory'' directory of the game.
 
 
 
* [[Rename]](''old'', ''new''): Renames or moves a file or directory.
 
 
 
* [[CreateDirectory]](''directory''): Creates a new directory.
 
 
 
* [[RemoveDirectory]](''directory''): Removes a directory.
 
 
 
== Files ==
 
 
 
* [[RemoveFile]](''filename''): Deletes a file.
 
 
 
* [[GetFileList]](''directory''): Gets an array of strings containing the filenames in 'directory'.
 
 
 
* [[OpenFile]](''filename''): Returns a file object with the filename.
 
 
 
* [[OpenRawFile]](''filename'' [, ''writeable'']): Open or create a file, and grab a [[Object-RawFile|RawFile]] handle to it.
 
 
 
=== File object ===
 
 
 
  [[File.read]](key, default)
 
    - reads a value from the key
 
      the value type returned depends on the default value.
 
      + if the default is a number, read will return a number.
 
      + if the default is a text or string, read will return a string.
 
      + if the default is a boolean, read will return a boolean
 
      + if the key is not present in the file, it will return the default value.
 
 
 
  [[File.write]](key, value)
 
    - writes a value (string, number, boolean) to the file under the key name
 
 
 
  [[File.flush]]()
 
    - writes the file to disk immediately...  this way you don't have
 
      to wait for it to save when the file object is garbage collected
 
 
 
  [[File.close]]()
 
    - closes the File object, after which it cannot be used anymore.
 
      Always remember to close opened files.
 
 
 
==== File keys ====
 
 
 
  [[File.getNumKeys]]()
 
    - returns the number of keys in the file
 
   
 
  [[File.getKey]](index)
 
    - returns a string of the key at 'index'
 
 
 
=== RawFile object ===
 
 
 
* [[RawFile.read]](''num_bytes''): Read ''num_bytes'' from the file, and return that data as a [[Object-ByteArray|ByteArray]].
 
* [[RawFile.write]](''byte_array''): Write the data in ''byte_array'' into the file.
 
 
 
* [[RawFile.close]](): Close (and flush) the [[Object-RawFile|RawFile]] object.
 
 
 
==== Size ====
 
 
 
* [[RawFile.getSize]](): Get the size of the file in bytes.
 
 
 
==== File pointer position ====
 
 
 
* [[RawFile.getPosition]](): Get the current position which the data is read from.
 
* [[RawFile.setPosition]](''position''): Set the position that the file will be read from.
 
 
 
==== Hashing raw files ====
 
 
 
* [[HashFromFile]](''filename''): Generate the MD5 'fingerprint' of a file. Identical files produce the same MD5 hash.
 

Latest revision as of 16:24, 5 August 2017

Warning.svg

Warning: Legacy code ahead

This page has been written for the legacy Sphere 1.x API. While this API is supported in miniSphere, it is generally recommended to use the new Sphere 2 API.

You can mix old and new API functions, but please be aware that Sphere 2 objects are different from Sphere 1 objects, so they cannot be used interchangeably.


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:


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.



Contents

Engine functions

Game control

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

File inclusion

Time

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

Conversion

System interfaces

Video

Screen size

Clipping

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

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.

Map object

  • Sphere Map object: Holds map data.

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

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
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.
  • ExecuteTrigger(x, y, layer): Activate the trigger at (x, y) on layer if one exists.

Layers

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

Camera

Following entities

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

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

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

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

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.

Fonts

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

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 color masking

Font characters

Saving to disk

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

WindowStyles

WindowStyle object

Drawing windows

WindowStyle color masking

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

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.

Surface conversion

Surfaces

  • CreateSurface(width, height, color): Create a Surface of dimensions (width, height), filled with color.
  • GrabSurface(x, y, width, height): Grab the screen contents at (x, y, width, height) and store it in a new Surface.

Surface object

  • Sphere Surface object: A picture canvas in memory that can be drawn to.
  • Surface.setAlpha(alpha): sets the alpha of the surface
  • Surface.clone(): Create a copy of the surface object.
  • Surface.cloneSection(x, y, w, h): returns a new surface object with the height and width of h and w, with part of image at (x,y) from the surface_object with the width w and height h.

Drawing on surfaces

  • Blend modes
    • BLEND (default for drawing)
    • REPLACE
    • RGB_ONLY
    • ALPHA_ONLY
    • ADD
    • SUBTRACT
    • MULTIPLY (default for masking)
    • AVERAGE
    • INVERT
  • Surface.setBlendMode(mode): Sets the blend mode of the surface, which will affect any drawing operation on the surface. 'mode' must be one of the available blend modes for surfaces.
  • Surface.getPixel(x, y): Get the color of the pixel at (x, y) on the surface.
  • Surface.setPixel(x, y, color): Set the pixel at (x, y) on the surface to color.
  • Surface.replaceColor(oldColor, newColor): replace all pixels of the color oldColor in the surface with newColor
Primitives on surfaces
  • Surface.pointSeries(array, color): plots a series of points colored with color onto the surface with array filled with objects (each object must have a 'x' and 'y' property)
  • Surface.line(x1, y1, x2, y2, color): Draw a line onto the surface starting from (x1, y1) to (x2, y2) with color.
  • Surface.gradientLine(x1, y1, x2, y2, color1, color2): Draw a line onto the surface starting from (x1, y1) to (x2, y2) with a color fade from color1 to color2.
  • Surface.lineSeries(array, color [, type]): draws a series of lines colored with color onto the surface with array filled with objects (each object must have a 'x' and 'y' property)
  • Surface.bezierCurve(color, step, Ax, Ay, Bx, By, Cx, Cy [, Dx] [, Dy]): Draws a Bezier curve colored with color onto the surface with step being a floating point number in the range 0 < step <= 1.0 and the points:
    (Ax, Ay: coordinates of the endpoint A),
    (Bx, By: coordinates of A's control point B)
    (Cx, Cy: coordinates of the endpoint C)
    (Dx, Dy: optional, coordinates of C's control point D - if omitted, B is also C's control point)
  • Surface.outlinedRectangle(x, y, width, height, color [, size]): Draw an outlined rectangle onto the surface at (x, y) of width and height colored with color and with size determining the thickness.
  • Surface.rectangle(x1, y1, x2, y2, color): Draw a filled rectangle on the surface from (x1, y1) to (x2, y2) with color.
  • Surface.gradientRectangle(x, y, w, h, c_ul, c_ur, c_lr, c_ll): Draws a gradient rectangle onto the surface at (x,y) with the height h and width w and a gradient of colors graduating from each corner of the rectangle as follows:
    c_ul = color of upper left corner
    c_ur = color of upper right corner
    c_lr = color of lower right corner
    c_ll = color of lower left corner
  • Surface.triangle(x1, y1, x2, y2, x3, y3, color): Draw a filled triangle with points (x1, y1), (x2, y2), (x3, y3) with color.
  • Surface.gradientTriangle(x1, y1, x2, y2, x3, y3, c1, c2, c3): Draws a gradient triangle onto the surface with the points (x1, y1), (x2, y2), (x3, y3), with each point (c1 = color of (x1, y1), c2 = color of (x2, y2), c3 = color of (x3, y3)) having a color to generate the gradient of the triangle
  • Surface.polygon(array, color [, invert]): draws a filled polygon colored with color onto the surface with array filled with 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.
  • Surface.outlinedEllipse(x, y, rx, ry, c): Draws an outlined ellipse at (x, y) with rx being the horizontal radius and ry the vertical radius onto the surface with the color c
  • Surface.filledEllipse(x, y, rx, ry, c): Draws a filled ellipse at (x, y) with rx being the horizontal radius and ry the vertical radius onto the surface with the color c
  • Surface.outlinedCircle(x, y, radius, color [, antialias]): Draws an outlined circle at (x, y) colored with color onto the surface if antialias is true, the circle will be antialiased
  • Surface.filledCircle(x, y, radius, color [, antialias]): Draws a filled circle at (x, y) colored with color onto the surface if antialias is true, the circle will be antialiased
  • Surface.gradientCircle(x, y, radius, color1, color2 [, antialias]): Draws a gradient circle at (x, y) onto the surface colored with a fading color from color1 to color2 if antialias is true, the circle will be antialiased
Text on surfaces
  • Surface.drawText(font, x, y, text): draws 'text' at x, y with the font onto the surface_object
  • Surface.drawZoomedText(font, x, y, scale, text): draws scaled text (1.0 = normal) with (x,y) as the upper left corner onto the surface_object
  • Surface.drawTextBox(font, x, y, w, h, offset, text): draws a word-wrapped text at (x, y) onto the surface_object with the width w and height h. The offset is the number of pixels which the number of pixels from y which the actual drawing starts at. See Font.drawTextBox for more detail.

Manipulating surfaces

Color effects
  • Surface.applyLookup(x, y, w, h, red_lookup, green_lookup, blue_lookup, alpha_lookup): Apply a lookup table transformation to the pixels contained in x, y, w, h
    The lookup parameters are arrays of 256 elements containg the new pixel values, ex: var invert_lookup = [255, 254, 253, 252, 251, ..., 4, 3, 2, 1, 0];
  • Surface.applyColorFX(x, y, w, h, colormatrix): Apply the colormatrix to the pixels contained in x, y, w, h (see CreateColorMatrix)
  • Surface.applyColorFX4(x, y, w, h, cm_upperleft, cm_upperright, cm_lowerleft, cm_lowerright): Apply 4 color matrices. Each corner has a separate color matrix. (see CreateColorMatrix)

Drawing (blitting) surfaces

Conversion to image

Saving to disk

  • Surface.save(filename): saves the surface_object as an image using the filename 'filename'; the image type is determined by the extension of the file, e.g. surface.save("test.png") saves a png image called test.png

Animations

Animation frames

Filesystem

  • GetDirectoryList(directory) directory = directory in which to enumerate directories, the current game's directory if not specified. Returns an array of strings, which contain the directory names that reside in the directory directory of the game.
  • GetFileList(directory): Gets an array of strings containing the filenames in 'directory'.
  • RemoveFile(filename): Deletes a file.
  • Rename(old, new): Renames or moves a file or directory.
  • CreateDirectory(directory): Creates a new directory.
  • RemoveDirectory(directory): Removes a directory.

Files

  • Sphere File object is a handle to an INI-like key=value structured text file.
  • Sphere RawFile object is a handle to a raw file with no inference as to structure and by default processes as binary; scripts have been written to process RawFiles according to their proper formats.
  • OpenFile(filename): Returns a Sphere File object with the filename.
  • OpenRawFile(filename [, writeable]): Open or create a file, and grab a RawFile handle to it.

File object

  • File.read(key, default): reads a value from the key; the value type returned depends on the default value:
    • if the default is a number, read will return a number.
    • if the default is a text or string, read will return a string.
    • if the default is a boolean, read will return a boolean
    • if the key is not present in the file, it will return the default value.
  • File.write(key, value): writes a value (string, number, boolean) to the file under the key name
  • File.flush(): writes the file to disk immediately; this way you don't have to wait for it to save when the file object is garbage collected
  • File.close(): closes the File object, after which it cannot be used anymore.
    Always remember to close opened files.

File keys

RawFile object

Size

File pointer position

Hashing raw files

  • HashFromFile(filename): Generate the MD5 'fingerprint' of a file. Identical files produce the same MD5 hash.

Log object (debugging)

  • OpenLog(filename): Create a new log file.
  • Sphere Log object: Traces script execution by putting messages in a log file.
  • Log.beginBlock(name): Create an indented block with name as title.
  • Log.endBlock(): Close an open block.
  • Log.write(message): Write a message to the log.


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

Data hashing

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