Template:Doc functions.txt
From Spherical
Note
This article is meant for transclusion into Doc Functions and remains unedited for historical prosperity. Do not edit either article except to fix formatting!
Sphere function documentation
Go here for language specification: http://www.mozilla.org/js/language/
Descriptions by Rizen
Many thanks!
Edited and updated by Darklich and AegisKnight :)
*** general functions ***
GetVersion()
- Returns the current version of Sphere as a floating point number
(e.g. 1.0 or 1.1)
*** script functions ***
EvaluateScript(script)
- Reads the script in and uses it as if it were a part of the current script.
ex: EvaluateScript("myscript.js");
EvaluateSystemScript(script)
- Reads in one of the preset system scripts for use in the current script
ex: EvaluateSystemScript("menu.js");
RequireScript(script)
- Reads the script in and uses it as if it were a part of the current script.
But only if the script has not already been evaluated.
ex: RequireScript("myscript.js");
RequireSystemScript(script)
- Reads in one of the preset system scripts for use in the current script.
But only if the script has not already been evaluated.
ex: RequireSystemScript("menu.js");
GarbageCollect()
- invokes the JavaScript garbage collector
*** miscellaneous ***
CreateStringFromCode(code)
- creates a single-character string based on the code passed in, i.e. 65 is "A"
*** engine functions ***
GetVersionString()
- Returns the current Sphere version string
GetGameList()
- Returns array of game objects
- game.name Name of game
- game.directory Directory (project name) where game is stored
- game.author Who wrote it?
- game.description Bite-sized summary of game.
ExecuteGame(directory)
- executes the game in sphere/games/<directory>. This function
actually exits the first game and loads the one in 'directory'.
When the second game returns, the original is loaded again. (Note
that this is unlike Sphere 0.97, which returned directly from
ExecuteGame when the other game finished.)
RestartGame()
- restarts the current game
Exit()
- Exits the Sphere engine unconditionally
Abort(message)
- Exits the Sphere engine unconditionally, displays the 'message' to the
user
If you end the message with a newline it wont display the file/line
where the Abort occured.
e.g. Abort("Mistake here")
vs. Abort("Game over!\n");
*** debugging (the log object) ***
OpenLog(filename)
- opens a log file for use under the filename. If Sphere is unable to open
the file for logging, the engine will give an error message and exit.
If Sphere is successful in opening the file, it will return a log object
for use.
ex: var myLog = OpenLog("game.log");
log_object.write(text)
- writes a string of text under the current block.
ex: myLog.write("Starting system...");
log_object.beginBlock(name)
- creates a "block" which is indent inside the log with the name as the
title of the block. Any subsequent write commands will go under the newly
created block.
ex: myLog.beginBlock("Video Information");
log_object.endBlock()
- closes the current log block.
*** system interfaces ***
*** video ***
FlipScreen()
- displays the contents from the video buffer onto the screen. Then the
video buffer is cleared. You *need* to call this to make anything
you've drawn in code to appear on the screen.
SetClippingRectangle(x, y, w, h)
- Sets a clipping rectangle of width w and height h at (x, y) into the
video buffer. Anything drawn outside the rectangle is not drawn into
the video buffer.
GetClippingRectangle()
- Returns a rectangle object representing the clipping rectangle.
i.e.
var clip = GetClippingRectangle();
clip.x
clip.y
clip.width
clip.height
ApplyColorMask(color)
- fills the whole screen with the color specified. Note that the color
passed must have an alpha that is less than 255. Otherwise, it'll
just make the screen solidly that color.
ApplyColorMask tints the screen's current state
(meaning you'll have to call it every frame
if you want the effect to be permanent)
SetFrameRate(fps)
- allows you to set the maximum frames rendered per second that
the engine is allowed to draw at most. Set to 0 in order to
unthrottle the graphics renderer. Keep in mind that this
is not for the map engine, which uses the fps specified in the
MapEngine() call. This function only controls standard drawing
functions and FlipScreen() outside of the map engine. In short,
don't use this function if you plan to be doing rendering in your
own scripts in the map engine.
GetFrameRate()
- Returns the current fps (set by SetFrameRate... note: this is
not the same as the map engine frame rate)
GetScreenWidth()
- returns the width of the engine screen
GetScreenHeight()
- returns the height of the engine screen
*** graphic primitives ***
NOTE: Make sure to use FlipScreen() when you're done drawing
Point(x, y, color)
- plots a point onto the video buffer at (x, y) with the color
Line(x1, y1, x2, y2, color)
- draws a line from (x1, y1) to (x2, y2) with the color
GradientLine(x1, y1, x2, y2, color1, color2)
- Draws a line from (x1, y1) to (x2, y2) with a color fade from color1
to color2
Triangle(x1, y1, x2, y2, x3, y3, c)
- Draws a filled triangle with the points (x1, y1), (x2, y2), (x3, y3),
with the color c
GradientTriangle(x1, y1, x2, y2, x3, y3, c1, c2, c3)
- Draws a gradient triangle 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
Rectangle(x, y, w, h, c)
- Draws a rectangle at (x, y) of width w and height h, filled with color c.
GradientRectangle(x, y, w, h, c_ul, c_ur, c_lr, c_ll)
- Draws a gradient rectangle 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.
*** input ***
*** keyboard ***
AreKeysLeft()
- returns true or false depending if the there are keys from the key
input queue.
GetKey()
- returns the first key in the queue. If there are no keys in the queue,
Sphere will wait until there is a key in the queue.
IsKeyPressed(key)
- checks if the key has been pressed. Returns true if 'key' is
pressed....
IsAnyKeyPressed()
- checks if any key is pressed at the time.
GetKeyString(key, shift)
- converts the key into a string, KEY_A will become "a", etc.
- if shift is true, returns uppercase/special value of key
- control keys return ""
*** mouse ***
SetMousePosition(x, y)
- Sets the x and y of the mouse cursor
GetMouseX()
GetMouseY()
- returns the location of the mouse cursor within the engine screen
IsMouseButtonPressed(button)
- returns true if the button is pressed
allowed button values are: MOUSE_LEFT, MOUSE_RIGHT, MOUSE_MIDDLE
*** joystick ***
GetNumJoysticks()
- returns the number of joysticks available on the system
GetJoystickX(joy)
GetJoystickY(joy)
- returns the current joystick position in normalized
coordinates from -1 to 1 on both axes.
GetNumJoystickButtons(joy)
- returns the number of buttons available on this joystick
IsJoystickButtonPressed(joy, button)
- returns true if the button on joystick 'joy' is pressed
*** time ***
GetTime()
- returns the number of milliseconds since some arbitrary time.
ex:
var start = GetTime();
while (GetTime() < start + 1000) {}
*** MapEngine object ***
GetMapEngine()
- returns the mapengine object currently being used by the map engine.
mapengine_object.save(filename)
- saves the map to filename
*** ByteArray object ***
ByteArrays are pretty much only used for networking (see below for Network
stuff) or RawFiles (also below)
CreateByteArray(size)
- returns a ByteArray object of 'size' bytes
CreateByteArrayFromString(string)
- returns a ByteArray object from string 'string'
CreateStringFromByteArray(array)
- returns a string from a ByteArray
bytearray.length
- the length of the byte array
bytearray_object[index]
- returns the allows you to access the index in the array
bytearray.concat(bytearray_to_append)
- returns bytearray with bytearray_to_append attached to the end of it
bytearray.slice(start [, end])
- 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.
*** MD5 fingerprinting ByteArray objects ***
HashByteArray(byte_array)
- generates an MD5 fingerprint as a hexadecimal string whose output
is the same as the RSA reference implementation of RFC 1321 which
means that the unix md5 command will return the same string for the
identical input. The resulting string contains the hexadecimal
representation of the MD5 fingerprint for the specified byte
array object
*** networking ***
GetLocalName()
- returns a string with the local name of your computer
GetLocalAddress()
- returns a string with the IP address of your computer
OpenAddress(address, port)
- attempts to open a connection to the computer specified with 'address' on 'port'
returns a socket object
ListenOnPort(port)
- listens for connections on port, returns a socket object if successful
socket.isConnected()
- returns true if the socket is connected
socket.getPendingReadSize()
- returns the size of the next array to be read in the socket
socket.write(byte_array)
- writes a ByteArray object into the socket
socket.read(int size)
- reads from the socket, returns a ByteArray object
socket.close()
- closes the socket object, after this, the socket cannot be used.
*** sphere objects ***
*** colors ***
CreateColor(r, g, b [, a])
- returns a color object with the color r is Red, g is Green, b is Blue,
and a is alpha (translucency of the color).
Note + alpha of 0 = transparent, alpha of 255 = opaque
+ alpha is optional, and defaults to 255 if not specified
BlendColors(c1, c2)
- returns a color object that is the blended color of color c1 and c2
BlendColorsWeighted(c1, c2, c1_weight, c2_weight)
- blends two colors together, allowing you to specify the amount of each color
ex:
BlendColorsWeighted(a, b, 1, 1) // equal amounts (like BlendColors())
BlendColorsWeighted(a, b, 1, 2) // 33% a, 66% b
color_object.red
- the red component of a color object
color_object.green
- the green component of a color object
color_object.blue
- the blue component of a color object
color_object.alpha
- the alpha (translucency) component of a color object
+ all color components are from 0-255 (unsigned 8-bits each, 4x8bit == 32bit)
/* maps */
MapEngine(map, fps)
- starts the map engine with the map specified and runs at 'fps' frames per second
ChangeMap(map)
- changes current map
GetCurrentMap()
- Returns the current map, e.g. "noisyforest.rmp"
ExitMapEngine()
- Exits the map engine. Note: This tells the map engine to shut
down. This does not mean the engine shuts down immediately. You
must wait for the original call to MapEngine() to return before you
can start a new map engine.
IsMapEngineRunning()
- Returns true if the map engine is running, false if not
UpdateMapEngine()
- updates map engine (state of entities, color masks, etc.)
SetMapEngineFrameRate(fps)
- Sets the max frame rate (in frames per second) that the map engine will go at
GetMapEngineFrameRate()
- Returns the current map engine frames per second rate set by either MapEngine(map, fps) or SetMapEngineFrameRate(fps)
CallMapScript(which)
- calls a map's script from code
the six events are:
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
SetDefaultMapScript(which, script)
- set the default script that the map engine should call before calling the map's specific script
(The default map script is called, then the map specific script is called.)
The events are the same from CallMapScript.
The map engine doesn't have to be on to set a default script.
CallDefaultMapScript(which)
- call the default map script
The events are the same from CallMapScript.
The map engine doesn't have to be on to call a default script.
*** maps ***
GetNumLayers()
- get number of layers on map
- in the following functions, layer 0 is the bottommost layer.
- layer 1 is the next one up, etc.
GetLayerName(layer_index)
- returns the name of 'layer'
GetLayerWidth(layer_index)
- get width of 'layer'
GetLayerHeight(layer_index)
- get height of 'layer'
IsLayerVisible(layer_index)
- returns true if the layer is visible
SetLayerVisible(layer_index, visible)
- shows 'layer_index' if visible == true, and hides it if visible == false
e.g. SetLayerVisible(0, !IsLayerVisisble(0)); will toggle layer zero's visibility
IsLayerReflective(layer_index)
- returns true if the layer is reflective
SetLayerReflective(layer_index, reflective)
- sets whether layer should be reflective
SetLayerMask(layer_index, mask)
- set the color mask of 'layer' to 'mask'
e.g. SetLayerMask(0, CreateColor(255, 0, 0, 128)); will make the layer semi red
GetLayerMask(layer_index)
- get the color mask currently being used by 'layer'
SetLayerScaleFactorX(layer_index, factor_x)
- Sets the x zoom/scale factor for the layer 'layer_index' to 'factor_x'
e.g. SetLayerScaleFactor(0, 0.5); will make the layer zoom out to half the normal size
SetLayerScaleFactorY(layer_index, factor_y)
- Sets the y zoom/scale factor for the layer 'layer_index' to 'factor_y'
e.g. SetLayerScaleFactor(0, 2); will make the layer zoom in to twice the normal size
GetLayerAngle(layer_index)
- Gets the angle (in radians) for the layer 'layer_index'
e.g. var angle = GetLayerAngle(0) will get the angle for the first layer
An angle of 0.0 is not rotated at all.
SetLayerAngle(layer_index, angle)
- Sets the angle (in radians) for the layer 'layer_index' to 'angle'
e.g. SetLayerAngle(0, Math.PI) will make the layer rotate slightly
GetNumTiles()
- return number of tiles in map
SetTile(x, y, layer, tile)
- changes tile on map to 'tile'
GetTile(x, y, layer)
- returns tile on map
GetTileName(tile_index)
- returns the name of the tile 'tile_index'
GetTileWidth()
- returns width in pixels of tiles on current map
GetTileHeight()
- returns height in pixels of tiles on current map
GetTileImage(tile_index)
- returns the image of the tile 'tile_index'
SetTileImage(tile_index, image_object)
- sets the tile 'tile_index' to the image 'image_object'
GetTileSurface(tile_index)
- returns the surface of the tile 'tile_index'
SetTileSurface(tile_index, surface_object)
- sets the tile 'tile_index' to the surface 'surface_object'
GetTileDelay(tile)
- gets the animation delay of the tile 'tile'
If it returns 0, the tile is not animated
SetTileDelay(tile, delay)
- sets the animation delay of the tile 'tile' to 'delay'
A delay of 0 is considered not animated
GetNextAnimatedTile(tile)
- gets the next tile in the animation sequence of 'tile'
Note that if the return value is 'tile' the tile is not animated.
SetNextAnimatedTile(tile, next_tile)
- sets the next tile in the animation sequence of 'tile' to 'new_tile'
SetNextAnimatedTile(tile, tile) turns off the tile animation for 'tile'
ReplaceTilesOnLayer(layer, oldtile, newtile)
- Replaces all 'oldtile' tiles with 'newtile' on layer 'layer'
IsTriggerAt(map_x, map_y, layer)
- Returns true if there is a trigger at map_x, map_y on layer. map_x
and map_y are in map (per-pixel) coordinates.
(Currently the layer parameter is ignored, although it still must be valid.)
ExecuteTrigger(map_x, map_y, layer)
- activates the trigger positioned on map_x, map_y, layer if one exists.
map_x and map_y are in map (per-pixel) coordinates.
(Currently the layer parameter is ignored, although it still must be valid.)
AreZonesAt(map_x, map_y, layer)
- returns true if there are any zones at map_x, map_y on layer
(Currently the layer parameter is ignored, although it still must be valid.)
ExecuteZones(map_x, map_y, layer)
- executes all the zones that map_x, map_y, layer is within
map_x and map_y are in map (per-pixel) coordinates.
(Currently the layer parameter is ignored, although it still must be valid.)
GetNumZones()
- returns the amount of zones that there is
GetCurrentZone()
- best when called from inside a ZoneScript handler
it will return the index of the zone for which the current script
is running
GetZoneX(zone)
- gets the x value of zone 'zone'
GetZoneY(zone)
- gets the y value of zone 'zone'
GetZoneWidth(zone)
- gets the width value of zone 'zone'
GetZoneHeight(zone)
- gets the height value of zone 'zone'
GetZoneLayer(zone)
- gets the layer value of zone 'zone'
SetZoneLayer(zone, layer)
- sets the layer value of zone 'zone'
ExecuteZoneScript(zone)
- executes the script for the zone 'zone'
RenderMap()
- Renders the map into the video buffer
SetColorMask(color, num_frames)
- applies a color mask to things drawn by the map engine for 'num_frames' frames
SetDelayScript(num_frames, script)
- in 'num_frames' frames, runs 'script'
ex: SetDelayScript(60, "ChangeMap('forest.rmp')");
this tells the map engine to change to forest.rmp after 60 frames
*** input ***
BindKey(key, onkeydown, onkeyup)
- runs the 'onkeydown' script when the 'key' is pressed down and runs
'onkeyup' when the 'key' is released
ex: BindKey(KEY_SPACE, "mode = 'in';", "mode = 'out';");
refer to keys.txt for a list of key names
UnbindKey(key)
- unbinds a bound key
BindJoystickButton(joystick, button, onbuttondown, onbuttonup)
- runs the 'onbuttondown' script when the joystick 'button' is pressed down and runs
'onbuttonup' when the joystick 'button' is released
UnbindJoystickButton(joystick, button)
- unbinds a bound joystick button
AttachInput(person_entity)
- makes the 'person_entity' respond to the input
(up = KEY_UP, down = KEY_DOWN, left = KEY_LEFT, right = KEY_RIGHT)
DetachInput()
- releases input from the attached person entity
IsInputAttached()
- returns true if a person is attached to the input
GetInputPerson()
- returns a string with the name of the person who currently holds input
AttachPlayerInput(person_entity, player_index)
- makes the 'person_entity' respond to the input
Currenty player_index has to be from zero to four (max four players)
Note: AttachInput is equilivent to AttachPlayerInput(person_entity, 0)
DetachPlayerInput(person_entity)
- releases input from the attached person entity
SetUpdateScript(script)
// calls 'script' after each frame (don't draw stuff in here!)
SetRenderScript(script)
// calls 'script' after all map layers are rendered
SetLayerRenderer(layer, script)
- calls the rendering 'script' after 'layer' has been rendered. Only one
rendering script can be used for each layer of the map
*** camera ***
AttachCamera(person_name)
- Attaches the camera view to specified person
DetachCamera()
- Detaches camera so it can be controlled directly
IsCameraAttached()
- returns true if the camera is attached to a person, false if the
camera is floating
GetCameraPerson()
- returns a string with the name of the person whom the camera
is attached to
SetCameraX(x)
SetCameraY(y)
- sets the location of the camera object on the map (the center
of the screen if possible)
GetCameraX()
GetCameraY()
- returns the location of the camera object on the map (the center
of the screen if possible)
MapToScreenX(layer, x)
MapToScreenY(layer, y)
- returns screen coordinates of position on map
ScreenToMapX(layer, x)
ScreenToMapY(layer, y)
- returns map coordinates of position on screen
*** entities ***
*** persons ***
GetPersonList()
- returns an array of strings representing the current person entities
CreatePerson(name, spriteset, destroy_with_map)
- returns a person object with 'name' from 'spriteset'. If Sphere is
unable to open the file, the engine will give an error message and
exit. destroy_with_map is a boolean (true/false value), which the
spriteset is destroyed when the current map is changed if the flag
is set to true.
DestroyPerson(name)
- destroys the person with the name
SetPersonX(name, x)
SetPersonY(name, y)
SetPersonLayer(name, layer)
- sets the position of the person on the map
SetPersonXYFloat(name, x, y)
- sets the position of the person with floating point accuracy
SetPersonDirection(name, direction)
SetPersonFrame(name, frame)
- sets which frame from which direction to display
GetPersonX(name)
GetPersonY(name)
GetPersonLayer(name)
- Gets the position of the person on the map.
The position is based on the middle of the spriteset's base
rectangle.
GetPersonXFloat(name)
GetPersonYFloat(name)
- Gets the position of the person on the map in floating point
accuracy.
GetPersonDirection(name)
GetPersonFrame(name)
- gets the frame and direction that are currently being displayed
SetPersonSpeed(name, speed)
SetPersonSpeedXY(name, speed_x, speed_y)
- sets the speed at which a person moves at
GetPersonSpeedX(name)
GetPersonSpeedY(name)
- gets the speed at which a person moves at
SetPersonFrameRevert(name, delay)
- sets the delay between when the person last moved and returning to
first frame. The delay is in frames. 0 disables this behaviour.
GetPersonFrameRevert(name)
- gets the delay between when the person last moved and returning to
first frame. The delay is in frames. 0 disables this behaviour.
SetPersonScaleFactor(name, scale_w, scale_h)
- rescales the sprite to a certain scale specified by scale_w and scale_h.
Scaling is determined by floating point numbers like, 1.5 would scale
the person to 1.5 times its normal size based on his original sprite
size.
SetPersonScaleAbsolute(name, width, height)
- rescales the sprite to width pixels and height pixels.
GetPersonSpriteset(name)
- returns the person's spriteset.
SetPersonSpriteset(name, spriteset)
- set's the person's spriteset to spriteset
e.g. SetPersonSpriteset("Jimmy", LoadSpriteset("jimmy.running.rss"));
GetPersonBase(name)
- returns the person's base obstruction object.
GetPersonAngle(name)
- returns the person's angle that is used
SetPersonAngle(name, angle)
- sets the angle which the person should be drawn at
Note:
Zero is no rotation, and angles are in radians.
It does not rotate the spritesets obstruction base.
SetPersonMask(name, color)
- sets a color multiplier to use when drawing sprites. if the color is
RGBA:(255, 0, 0, 255), only the red elements of the sprite are drawn.
If the color is RGBA:(255, 255, 255, 128), the sprite is drawn at
half transparency.
GetPersonMask(name)
- returns the person's current mask
IsPersonVisible(name)
- returns the person's visible status
SetPersonVisible(name, visible)
- sets the person's visible status, true = visible, false = not visible
e.g. SetPersonVisible(GetCurrentPerson(), !IsPersonVisible(GetCurrentPerson()));
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
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.
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)
- adds a command to the person's command queue
the commands are:
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
(note: these *might* change in a future release
'immediate', if true, will execute the command go right away
if false, it will wait until the next frame)
QueuePersonScript(name, script, immediate)
- adds a script command to the person's queue
ClearPersonCommands(name)
- clears the command queue of sprite with the 'name'
IsCommandQueueEmpty(name)
- returns true if the person 'name' has an empty command queue
IsPersonObstructed(name, x, y)
// returns true if person 'name' would be obstructed at (x, y)
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
SetTalkActivationKey(key)
GetTalkActivationKey()
- set key used to activate talk scripts
SetTalkDistance(pixels)
GetTalkDistance()
- set distance to check for talk script activation
*** spritesets ***
LoadSpriteset(filename)
- returns a spriteset object from 'filename'. If Sphere is unable to open
the file, the engine will give an error message and exit.
spriteset.filename
- the filename that the spriteset was loaded with
spriteset.save(filename)
- saves the spriteset object to 'filename'
spriteset.clone()
- returns a copy of the spriteset object
spriteset_object.images
- array of image objects
spriteset_object.directions
- array of spriteset_direction objects
spriteset_object.base
- spriteset_base object
// spriteset_direction objects
spriteset_direction.name
- name of direction
spriteset_direction.frames
- array of spriteset_frame objects
// spriteset_frame objects
spriteset_frame.index
- index into images array
spriteset_frame.delay
- number of frames before animation should switch
// spriteset_base object
base.x1 }
base.y1 } the coordinates of the base rectangle
base.x2 }
base.y2 }
*** sounds ***
LoadSound(filename [, streaming])
- returns a sound object from 'filename'. If Sphere is unable to open
the file, the engine will give an error message and exit. If the optional
argument 'streaming' is true or unspecified, the sound is streamed from the
hard drive. Otherwise, it's loaded into memory.
sound_object.play(repeat)
- plays the sound. repeat is a boolean (true/false), that indicates if
the sound should be looped
sound_object.pause()
- pauses playback. call play() again to resume playback.
sound_object.stop()
- stops playback
sound_object.setVolume(volume)
- sets the volume for the sound (0-255)
sound_object.getVolume()
- returns the sound's volume (0-255)
sound_object.setPan(pan)
- pan can be from -255 to 255. -255 = left, 255 = right
sound_object.getPan()
- returns the current pan of the sound
sound_object.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
sound_object.getPitch()
- returns the current pitch
sound_object.isPlaying()
- returns true if the sound is currently playing
sound_object.isSeekable()
- returns true if the sound is seekable
Not all sound types are seekable, Ogg is.
sound_object.getPosition()
- returns the position of the sound
returns zero if the sound isn't seekable
sound_object.setPosition(pos)
- sets the position of the sound
if the sound isn't seekable, this does nothing
sound_object.getLength()
- gets the length of the sound
*** fonts ***
GetSystemFont()
- returns a font object of the font that the engine currently uses.
LoadFont(filename)
- returns a font object from 'filename'. If Sphere is unable to open
the file, the engine will give an error message and exit.
font_object.setColorMask(color)
- Sets the color mask for a font (see ApplyColorMask)
font_object.getColorMask()
- Gets the color mask being used by the font object
font_object.drawText(x, y, text)
- draws 'text' at x, y with the font
font_object.drawZoomedText(x, y, scale, text)
- draws scaled text (1.0 = normal) with (x,y) as the upper left corner
font_object.drawTextBox(x, y, w, h, offset, text)
- draws a word-wrapped text at (x, y) 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.
Note: 'text' can have the following special characters within it:
\n - newline
\t - tab
\" - double quote
\' - single quote
For example: font_object.drawTextBox(16, 16, 200, 200, 0, "Line One\nLine Two");
font_object.getHeight()
- returns the height of the font, in pixels
font_object.getStringWidth(string)
- returns the width of a given string, in pixels
font_object.getStringHeight(string, width)
- returns the height of the string as if it was drawn by drawTextBox
font_object.clone()
- returns a copy of 'font_object'
*** window styles ***
GetSystemWindowStyle()
- returns a windowstyle object of the windowstyle that the engine currently
uses.
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.
windowstyle_object.drawWindow(x, y, w, h)
- draws the window at (x, y) with the width and height of w and h.
Note that window corners and edges are drawn outside of the width
and height of the window.
windowstyle_object.setColorMask(color)
- sets the color mask for a windowstyle (see ApplyColorMask)
windowstyle_object.getColorMask()
- gets the color mask being used by the windowstyle object
*** images ***
GetSystemArrow()
- returns an image object of the System Arrow that the engine currently uses.
GetSystemUpArrow()
- returns an image object of the System Arrow(up) that the engine currently
uses.
GetSystemDownArrow()
- returns an image object of the System Arrow(down) that the engine
currently uses.
LoadImage(filename)
- returns an image object from 'filename'. If Sphere is unable to open or
read the image, the engine will give an error message and exit. The
image type that the engine supports are either PCX, BMP, JPG, and PNG.
GrabImage(x, y, w, h)
- returns an image object from a section of the video buffer
defined by the parameters
(see GrabSurface)
image_object.blit(x, y)
- draws the image onto the video buffer at x,y
image_object.blitMask(x, y, mask)
- draws the image into the video buffer, except that the color passed
as 'mask' tints the image
image_object.rotateBlit(x, y, radians)
- draws the image into the video buffer, except that the image is rotates
in anti-clockwise in radians, which have a range of 0-2*pi.
(x,y) is the center of the blit.
image_object.rotateBlitMask(x, y, radians, color)
- rotateBlit + mask
image_object.zoomBlit(x, y, factor)
- draws the image into the video buffer with zooming, with the scaling
depending on factor. Normally a factor of 1 will blit a normal looking
image. Between 0 and 1 will shrink the image. Any values greater than 1
will stretch the size of the image.
image_object.zoomBlitMask(x, y, factor, color)
- zoomBlit + mask
image_object.transformBlit(x1, y1, x2, y2, x3, y3, x4, y4)
- draws the image into the video buffer 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.
image_object.transformBlitMask(x1, y1, x2, y2, x3, y3, x4, y4, mask)
- transformBlit + blitMask
image_object.createSurface()
- returns a new surface object from the image
image_object.width
- the width of the image
image_object.height
- the height of the image
*** surfaces ***
CreateSurface(width, height, color)
- returns a surface object with width x height, filled with color
LoadSurface(filename)
- returns a surface object with an image with the 'filename'
GrabSurface(x, y, w, h)
- returns a surface object captured from an area of the video buffer,
at (x, y) with the width w and height h.
(see GrabImage)
surface_object.width
surface_object.height
- dimensions
surface_object.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.
e.g. var invert_lookup = [255, 254, 253, 252, 251, ..., 4, 3, 2, 1, 0];
surface_object.applyColorFX(x, y, w, h, colormatrix)
- Apply the colormatrix to the pixels contained in x, y, w, h
(see CreateColorMatrix)
surface_object.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)
surface_object.blit(x, y)
- draws the surface to the video buffer at (x,y)
surface_object.blitSurface(surface, x, y)
- draws 'surface' onto 'surface_object' at (x,y)
surface_object.createImage()
- returns an image object from the surface object
surface_object.setBlendMode(mode)
- pass it with either BLEND or REPLACE
REPLACE mode will make the surface erase the pixels needed when doing a
drawing operation (setpixel, line, rectangle...)
BLEND will blend the pixels needed when doing a drawing operation
surface_object.getPixel(x, y)
- returns the color of the pixel at (x,y)
surface_object.setPixel(x, y, color)
- sets the pixel at (x,y) to 'color'
surface_object.setAlpha(alpha)
- sets the alpha of the surface
surface_object.replaceColor(oldColor, newColor)
- replace all pixels of the color oldColor in the surface with newColor
surface_object.line(x1, y1, x2, y2, color)
- draws a line onto the surface starting from (x1, y1) to (x2, y2) with
the color
surface_object.rectangle(x, y, w, h, color)
- draws a filled rectangle onto the surface from (x, y) to (x+w, y+h)
with 'color'
surface_object.triangle(x1, y1, x2, y2, x3, y3, color)
- draws a filled triangle with the points (x1, y1), (x2, y2), (x3, y3),
with 'color'
surface_object.rotate(radians, resize)
- rotates the surface anti-clockwise with the range 0 - 2*pi. The resize
flag is a boolean to tell the engine to resize the surface if needed
to accomodate the rotated image.
surface_object.resize(w, h)
- resizes the surface images. This does not stretch or shrink the image
inside the surface.
surface_object.rescale(w, h)
- stretches or shrinks the surface to the new width w and height h
surface_object.flipHorizontally()
- flips the surface horizontally
surface_object.flipVertically()
- flips the surface vertically
surface_object.clone()
- returns a surface object, which is a copy of this surface object
surface_object.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.
surface_object.drawText(font, x, y, text)
- draws 'text' at x, y with the font onto the surface_object
surface_object.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_object.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.
surface_object.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 matrix ***
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 applyColorFX and applyColorFX4)
*** 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
animation_object.width
- returns the width of the animation
animation_object.height
- returns that height of the animation
animation_object.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_object.getDelay()
- returns the delay between frames, in milliseconds
animation_object.readNextFrame()
- readies the next frame for drawing
animation_object.drawFrame(x, y)
- draws the current frame into the video buffer
animation_object.drawZoomedFrame(x, y, scale);
- draws the current frame into the video buffer with a specified
zoom scale
*** 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.
file_object.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_object.write(key, value)
- writes a value (string, number, boolean) to the file under the key name
file_object.getNumKeys()
- returns the number of keys in the file
file_object.getKey(index)
- returns a string of the key at 'index'
file_object.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
*** raw files ***
OpenRawFile(filename [, writeable])
- opens a file with the filename.
Unless writeable is true, the file *must* exist and reside
in the "other" directory of the game otherwise Sphere will give an error.
If the file is opened successfully, the function will return a rawfile
object. If the optional argument 'writeable' is true,
the conents of the file will be destroyed,
and you will be able to write to the file.
rawfile_object.setPosition(position)
- sets the position that the file will be read from
rawfile_object.getPosition()
- returns the current position which the data is read from
rawfile_object.getSize()
- returns the number of bytes in the file
rawfile_object.read(num_bytes)
- reads the number of bytes that is specified by num_bytes. It will create
and return an array of data the rawfile object has read. The array of
data are numbers representation of each byte (0-255). Note that if the
number of bytes that will be read, exceeds the filesize from the current
position, it will only return an array of data of that is
actually read. The returned object is a ByteArray, so you can do
the same things with it as you can with any other ByteArray.
rawfile_object.write(byte_array)
- writes the byte array to the file at the current position
The file must have been opened as writeable for this to work.
rawfile_object.close()
- closes the rawfile object, after this, the rawfile_object cannot be used anymore.
*** MD5 fingerprinting rawfiles ***
HashFromFile(filename)
- generates an MD5 of the specified raw file, which, by backtracking
with a ../ may refer to any file within the game directory structure.
The result is a 32 character string containing the hexadecimal
representation of the resulting 128-bit MD5 fingerprint. Identical
files produce the same MD5 hash so it is an effective way to determine
if a file has become corrupt or altered
*** 3d Functions ***
*** All 3d functions (currently) require sphere_gl to be used as the video driver ***
SwitchProjectMode(integer)
- Sets the drawing mode to 2d if integer is 0, 3d if 1. All 3d drawing
must be done while in 3d mode, and likewise for 2d. When done drawing
in 3d, the mode must be set back to 2d.
PRenderMap()
- Renders the map as a 3d image.
image_object.transform3DBlit(x1, y1, z1, x2, y2, z2, x3, y3, z3, x4, y4, z4)
- Blits the image to the coordinates given. Point 1 is the upper left
corner of the image, 2 is the upper right, 3 is the lower right,
and 4 is the bottom left
image_object.triangle3DBlit(sx1,sy1,x1,y1,z1,sx2,sy2,x2,y2,z2,sx3,sy3,x3,y3,z3)
- Blits the triangle (sx1, sy1) (sx2, sy2) (sx3, sy3) part of the image, given
in terms of the image size, to the 3 points (x1,y1,z1) (x2,y2,z2) (x3,y3,z3)
respectively.
Set3DCameraPosition(x,y,z)
- Sets the 3d camera to the point (x,y,z).
Set3DCameraAngles(x_angle, y_angle, z_angle)
- Sets the 3d camera angles to x_angle, y_angle, and z_angle, with respect
to the corresponding x,y, and z axis. Input is given in terms of degrees.
Get3DCameraX()
- Returns the cameras current x position.
Get3DCameraY()
- Returns the cameras current y position.
Get3DCameraZ()
- Returns the cameras current z position.
Get3DCameraAngleX()
- Returns the cameras current x angle.
Get3DCameraAngleY()
- Returns the cameras current y angle.
Get3DCameraAngleZ()
- Returns the cameras current z angle.
