Functions

From Spheriki

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.


Contents

[edit]

General functions

[edit]

Script functions

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

File inclusion

[edit]

Engine functions

[edit]

Game control

[edit]

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.
[edit]

System interfaces

[edit]

Video

[edit]

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.
[edit]

Frame rate control

[edit]

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)
   - Plots a series of points colored with color onto the video buffer
     with array filled with objects (each object must have a 'x' and 'y' property).
  • 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 colored with color onto the video buffer
     with array filled with objects (each object must have a 'x' and 'y' property).
     'type' must be one of:
         LINE_MULTIPLE - Every two points draws a line.
         LINE_STRIP - One long line is drawn.
         LINE_LOOP - Like LINE_STRIP but a line connects the end and start.

 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 at (x, y) with width * height
     dimensions with the color. size determines the line thickness.
  • 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, c)
   - Draws an outlined ellipse at (x, y) with rx being the horizontal radius 
     and ry the vertical radius onto the video buffer with the color c

 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 video buffer with the color c

 OutlinedCircle(x, y, radius, color [, antialias])
   - Draws an outlined circle at (x, y) colored with color onto the
     video buffer. If antialias is true, the circle edge will be
     antialiased.

 FilledCircle(x, y, radius, color [, antialias])
   - Draws a filled circle at (x, y) colored with color onto the
     video buffer. If antialias is true, the circle edge will be
     antialiased.

 GradientCircle(x, y, radius, color1, color2 [, antialias])
   - Draws a gradient circle at (x, y) onto the video buffer
     colored with a gradient from color1 (center) to color2 (edge).
     If antialias is true, the circle edge will be antialiased.

 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.
[edit]

Screen size

[edit]

Input

[edit]

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
[edit]

Keyboard

[edit]

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.
[edit]

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)
[edit]

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.
[edit]

Mouse

[edit]

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.
[edit]

Mouse button status

[edit]

Mouse wheel event queue

[edit]

Joystick

[edit]

Button status

[edit]

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)
[edit]

Time

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

Map object

  • Sphere Map object: Holds map data.
[edit]

ByteArray object

[edit]

Conversion to and from strings

[edit]

Data hashing

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

Networking

[edit]

Socket object

[edit]

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.
[edit]

Engine control

[edit]

Map control

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

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
[edit]

Within the map engine

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

Maps

[edit]

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.
[edit]
For each zone
[edit]
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.
[edit]

Triggers

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

Layers

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

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.
[edit]
For each tile
[edit]
Tile animations
  • GetTileDelay(tile): Get frame delay of animated tile.
  • SetTileDelay(tile, delay): Set a frame delay for this tile animation frame.
[edit]

Input

[edit]

Player input

[edit]

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.
[edit]

Binding scripts to joystick buttons

[edit]

Camera

[edit]

Following persons

[edit]

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.
[edit]

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.
[edit]

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.
[edit]

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.
[edit]

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.
[edit]

Movement speed

[edit]

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.
[edit]

Obstruction

  • GetPersonBase(name): Get a person's spriteset obstruction base. 
 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

 IgnoreTileObstructions(person, ignore)
   - Sets whether 'person' should ignore tile obstructions
 
 IsIgnoringTileObstructions(person)
   - Returns true if 'person' is ignoring tile 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
[edit]

Talk interaction 

 SetTalkActivationKey(key)
 GetTalkActivationKey()
   - set key used to activate talk scripts

 SetTalkDistance(pixels)
 GetTalkDistance()
   - set distance to check for talk script activation
[edit]

Following other persons 

 FollowPerson(name, leader, pixels)
   - makes the sprite 'name' follow 'pixels' pixels behind sprite 'leader'.
     If this function is called like:
     FollowPerson(name, "", 0),
     the person will detach from anyone it is following.
[edit]

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
[edit]

Person control 

 SetPersonScript(name, which, script)
   - sets 'script' as the thing 'name' does in a certain event
     the five events are
       SCRIPT_ON_CREATE
       SCRIPT_ON_DESTROY
       SCRIPT_ON_ACTIVATE_TOUCH
       SCRIPT_ON_ACTIVATE_TALK
       SCRIPT_COMMAND_GENERATOR
       (SCRIPT_COMMAND_GENERATOR will be called when the command queue for
       the person runs out (for random movement thingies, etc))
 
 CallPersonScript(name, which)
   - calls a person's script from code
     'which' constants are the same as for SetPersonScript()

 GetCurrentPerson()
   - best when called from inside a PersonScript handler
     it will return the name of the person for whom the current script 
     is running
  • 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.
[edit]

Sphere objects

[edit]

Colors

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

Blending colors

[edit]

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.
[edit]

Spritesets 

 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
[edit]

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.
[edit]

Sound object

  • LoadSound(filename [, streaming]): Load a sound from filename, streaming from disk optional.
  • Sound.play(repeat): Play the sound, loop if repeat is true.
  • Sound.pause(): Pause playback of the sound. Call Sound.play() to resume.
  • Sound.stop(): Stop playback of the sound. 
 Sound.reset()
   - Resets playback. No effect on MIDIs.

 Sound.setRepeat(repeat)
   - Sets if the sound should be repeated.
 
 Sound.getRepeat()
   - Returns true if sound is set to repeat, otherwise false.
  • Sound.isPlaying(): Check if the sound is currently playing.
  • Sound.isSeekable(): Returns true if the sound is seekable. Not all sound types are seekable, Ogg is.
  • Sound.getLength(): Gets the length of the sound.
  • Sound.clone(): Returns a copy of the sound object.
  • Sound.getPosition(): Returns the position of the sound, zero if the sound isn't seekable.
  • Sound.setPosition(position): Sets the position of the sound. Does nothing if the sound isn't seekable.
  • Sound.getVolume(): Get the volume of the sound (0-255). No effect on MIDIs.
  • Sound.setVolume(volume): Set the volume of the sound (0-255). No effect on MIDIs. 
 Sound.setPan(pan)
   - Pan can be from -255 to 255.  -255 = left, 255 = right. No effect on MIDIs.
 
 Sound.getPan()
   - Returns the current pan of the sound. No effect on MIDIs.
  • Sound.setPitch(pitch): Sets the pitch for a sound. No effect on MIDIs. 
 Sound.getPitch()
   - Returns the current pitch. No effect on MIDIs.


[edit]

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
[edit]

Fonts

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

Font object 

 Font.clone()
   - returns a copy of 'font_object'
[edit]

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().
[edit]

Font size info

[edit]

Font color masking

[edit]

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
[edit]

WindowStyles 

 LoadWindowStyle(filename)
   - returns a windowstyle object from 'filename'. If Sphere is unable to open
     the file, the engine will give an error message and exit.
[edit]

WindowStyle object

[edit]

Drawing windows

[edit]

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)
[edit]

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.
[edit]

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.
[edit]

Image object

[edit]

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.
[edit]

Surface conversion

[edit]

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.
[edit]

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.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.
[edit]

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.

   - sets the pixel at (x,y) to 'color'

 Surface.replaceColor(oldColor, newColor)
   - replace all pixels of the color oldColor in the surface with newColor
[edit]
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)
   - draws a line onto the surface starting from (x1, y1) to (x2, y2) with 
     the color

 Surface.gradientLine(x1, y1, x2, y2, color1, color2)
   - draws 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])
   - draws an outlined rectangle at (x, y) of w width and h height colored with color
     and with size determining the thickness onto the surface
  • 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
[edit]
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.
[edit]

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
[edit]
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)
[edit]

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.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
[edit]

Conversion to image

[edit]

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
[edit]

Color matrices 

 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)
[edit]

Animations 

 LoadAnimation(filename)
   - Returns an animation object with the filename. If Sphere is unable to 
     open the file, the engine will give an error message and exit. Sphere 
     supports animation formats of .flic, .fli, .flc and .mng
[edit]

Animation object 

 Animation.width
   - returns the width of the animation
 
 Animation.height
   - returns that height of the animation
[edit]

Animation frames 

 Animation.getNumFrames()
   - returns the number of frames the animation contains.  If the
     animation is an MNG file, the number of frames is unknown, and
     this function returns 0.
 
 Animation.getDelay()
   - returns the delay between frames, in milliseconds
 
 Animation.readNextFrame()
   - readies the next frame for drawing
[edit]

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


[edit]

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 and returns true on success, or false otherwise.

 CreateDirectory(directory)
   - Creates a new directory and returns true on success, or false otherwise.

 RemoveDirectory(directory)
   - Removes the directory 'directory' and returns true on success, or false otherwise.
[edit]

Files 

 GetFileList(directory)
   - directory = directory in which to enumerate files, "save" if not specified
   - returns an array of strings, which contains the filenames that resides
     in the 'directory' directory of the game.

 OpenFile(filename)
   - Returns a file object with the filename. The file is created/loaded 
     from the "save" directory of the game. Note that any changes in the keys
     will not be saved until the file object is destroyed.
   - Use the prefix "/common/" to open files within the common directory in ~/sphere.
  • OpenRawFile(filename [, writeable]): Open or create a file, and grab a RawFile handle to it.
[edit]

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.
[edit]

File keys 

 File.getNumKeys()
   - returns the number of keys in the file
   
 File.getKey(index)
   - returns a string of the key at 'index'
[edit]

RawFile object

[edit]

Size

[edit]

File pointer position

[edit]

Hashing raw files

  • HashFromFile(filename): Generate the MD5 'fingerprint' of a file. Identical files produce the same MD5 hash.
Retrieved from "http://www.spheredev.org/wiki/Functions"
Views