Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
2340 lines (1712 sloc) 80.8 KB
Sphere API (function list)
--------
For help with the JavaScript language, head to:
http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Guide
To look up specifics about the JavaScript language:
http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Reference
And for longer descriptions, examples and notes about each of the
functions listed here, head to the Spheriki:
http://www.spheredev.org/
Credits
--------
Descriptions by Rizen (Many thanks!)
Edited and updated by Darklich and AegisKnight
Now managed by the Spherical community (http://www.spheredev.org/)
*** general functions ***
GetVersion()
- Returns the current version of Sphere as a floating point number
(e.g. 1.0 or 1.1)
GetVersionString()
- Returns the current Sphere version string
*** 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"
Do not use this function, use String.fromCharCode(code) instead...
e.g. String.fromCharCode(65) == "A"
*** engine functions ***
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
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)
- 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
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 is 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, 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
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, 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.
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.
*** input ***
*** player input ***
GetPlayerKey(player, player_key_constant)
- 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_constant 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 ***
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.
GetToggleState(key)
- checks if Caps Lock, Num Lock or Scroll Lock are active.
Allowed key values are:
KEY_CAPSLOCK
KEY_NUMLOCK
KEY_SCROLLOCK (note: only two Ls)
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
GetMouseWheelEvent()
- returns a single mouse wheel event
possible values are: MOUSE_WHEEL_UP, MOUSE_WHEEL_DOWN
GetNumMouseWheelEvents()
- returns the length of the mouse wheel event queue
*** joystick ***
GetTalkActivationButton()
- returns the joystick button used to activate talk scripts
SetTalkActivationButton()
- sets the joystick button used to activate talk scripts
GetNumJoysticks()
- returns the number of joysticks available on the system
GetJoystickAxis(joy, 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)
GetNumJoystickAxes(joy)
- returns the number of available axes on the given joystick
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
mapengine_object.layerAppend(width, height, tile)
- Adds a new layer filled with tile index
*** 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
*** map background music ***
nameBgm()
- Returns the name of the current map background music (could be a m3u list)
validBgm()
- Returns the type of the current map background music: 0: none 1: midi 2: wav/mp3/it/xm
playBgm()
- Starts the current map background music. If it is already playing, or doesnt exist,
it does nothing.
Returns true if the music is playing
stopBgm()
- Stops the current map background music. If it is already stopped, or doesnt exist,
it does nothing.
Returns true if the music is stopped
isPlayingBgm()
- Tells us if the background music is playing
resetBgm()
- Rewind the background music. (Can be slow on streamed music)
setRepeatBgm(boolean onoff)
- Enable/Disable Loop the current background music (it is repeated by default)
Returns true if it succeeded setting the boolean value.
getRepeatBgm()
- Returns true if the current background music is looped. False if not.
setVolumeBgm(int volume)
- Sets the volume of the current background music. The volume can be 0 to 255.
no effect on MIDIs.
getVolumeBgm()
- Gets the volume of the current background music. The volume can be 0 to 255.
no effect on MIDIs.
setPanBgm(int pan)
- pan can be from -255 to 255. -255 = left, 255 = right. pan defaults to 0 (center).
no effect on MIDIs.
getPanBgm()
- returns the current pan of the sound (-255 to 255)
no effect on MIDIs.
setPitchBgm(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
no effect on MIDIs.
getPitchBgm()
- returns the current pitch
no effect on MIDIs.
isSeekableBgm()
- returns true if the background music is seekable
getLengthBgm()
- returns the length the background music. Music must be seekable.
setPositionBgm(int pos)
- sets the position of the sound
if the sound isn't seekable, this does nothing
getPositionBgm()
- gets the position of the sound
if the sound isn't seekable, this does nothing
*** 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)
- makes 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
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 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 blitted always 10 pixels
to the bottom, while the person's y-position would remain unchanged.
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.
CreateSpriteset(frame_width, frame_height, num_images, num_directions, num_frames)
- returns a blank spriteset object with the given dimensions
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.
CreateSound(byte_array [, streaming])
- returns a sound from bytearray.
sound_object.play(repeat)
- plays the sound. repeat is a boolean (true/false), that indicates if
the sound should be looped
- call play() without the 'repeat' parameter to resume any previously paused sound.
sound_object.pause()
- pauses playback. call play() to resume playback afterwards.
sound_object.stop()
- stops playback
sound_object.reset()
- resets playback
no effect on MIDIs
sound_object.setRepeat(repeat)
- sets if the sound should be repeated
sound_object.getRepeat()
- returns true if sound is set to repeat, otherwise false
sound_object.setVolume(volume)
- sets the volume for the sound (0-255)
- no effect on MIDIs.
sound_object.getVolume()
- returns the sound's volume (0-255)
- no effect on MIDIs.
sound_object.setPan(pan)
- pan can be from -255 to 255. -255 = left, 255 = right
- no effect on MIDIs.
sound_object.getPan()
- returns the current pan of the sound
- no effect on MIDIs.
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
- no effect on MIDIs.
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
sound_object.clone()
- returns a copy of the sound object
*** sound effects ***
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).
CreateSoundEffect(byte_array)
- returns a sound effect from a bytearray.
sound_effect_object.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.
sound_effect_object.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.
sound_effect_object.setVolume(volume)
- sets the volume for the sound effect (0-255)
sound_effect_object.getVolume()
- returns the sound effect's volume (0-255)
sound_effect_object.setPan(pan)
- pan can be from -255 to 255. -255 = left, 255 = right. pan defaults to 0 (center).
sound_effect_object.getPan()
- returns the current pan of the sound effect
sound_effect_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.0
sound_effect_object.getPitch()
- returns the current pitch
*** sfxr ***
CreateSfxr()
- returns an Sfxr object. The parameters are optional and can be set later on.
bitrate, samplerate, soundvolume, wavetype, basefrequency, minfrequency,
frequencyslide, frequencyslidedelta, squareduty, squaredutysweep, vibratodepth,
vibratospeed, attack, sustain, detay, release, filter, lowpassfiltercutoff,
lowpassfiltercutoffsweep, filterresonance, highpassfiltercutoff, highpassfiltercutoffsweep,
phaseroffset, phaseroffsetsweep, repeatspeed, arpeggio, arpeggiospeed
sfxr.saveWav(string filename)
- saves the sfxr as a wav file
It will use the ./sounds/ directory by default
sfxr.reset()
- resets all the values of the sfxr object
sfxr.getSoundEffect([int type])
- Creates a soundeffect. The parameter can be SE_MULTIPLE or SE_SINGLE
sfxr.calcSampleSize()
- Get the sample size
sfxr.setMasterVolume(volume)
- Set the master volume of the sfxr object
sfxr.getMasterVolume()
- Get the master volume of the sfxr object
sfxr.getSoundVolume()
- Get the volume of the sfxr object
sfxr.setSoundVolume(v)
- Set the volume of the sfxr object
sfxr.getBitrate()
- Get the bitrate of the sfxr object
This value can be 8 or 16
sfxr.setBitrate(int v)
- Set the bitrate of the sfxr object
This value can be 8 or 16
sfxr.getSampleRate()
- Get the samplerate of the sfxr object
sfxr.setSampleRate(int v)
- Set the sample rate of the sfxr object
For example: 44100, 22500, 11000 or 8000.
Changing the samplerate effectively changes the pitch
sfxr.getWaveType()
- Get the wave type of the sfxr object
sfxr.setWaveType(int wavetype)
- Set the wave type of the sfxr object
Valid values are: SQUAREWAVE, SAWTOOTH, SINEWAVE and NOISE
sfxr.getBaseFrequency()
- Get the base frequency of the sfxr object
sfxr.setBaseFrequency(v)
- Set the base frequency of the sfxr object
This is for sliding the sound in pitch
Value must be between 0 and 1
sfxr.getMinFrequency()
- Get the minimal frequency of the sfxr object
sfxr.setMinFrequency(v)
- Set the minimal frequency of the sfxr object
Value must be between 0 and 1
sfxr.getFrequencySlide()
- Get the frequency slide of the sfxr object
sfxr.setFrequencySlide(v)
- Set the frequency slide of the sfxr object
Value must be between -1 and 1
sfxr.getFrequencySlideDelta()
- Get the frequency slide delta of the sfxr object
sfxr.setFrequencySlideDelta(v)
- Set the frequency slide delta of the sfxr object
Value must be between -1 and 1
sfxr.getSquareDuty()
- Get the square duty of the sfxr object
sfxr.setSquareDuty(v)
- Set the square duty of the sfxr object
Value must be between 0 and 1
sfxr.getSquareDutySweep()
- Get the square duty sweep of the sfxr object
sfxr.setSquareDutySweep(v)
- Set the square duty sweep of the sfxr object
Value must be between 0 and 1
sfxr.getVibratoDepth()
- Get the vibrato depth of the sfxr object
sfxr.setVibratoDepth(v)
- Set the vibrato depth of the sfxr object
Value must be between 0 and 1
sfxr.getVibratoSpeed()
- Get the vibrato speed of the sfxr object
sfxr.setVibratoSpeed(v)
- Set the vibrato speed of the sfxr object
Value must be between 0 and 1
sfxr.getVibratoDelay()
- Get the vibrato delay of the sfxr object
sfxr.setVibratoDelay(v)
- Set the vibrato delay of the sfxr object
Value must be between 0 and 1
sfxr.getAttack()
- Get the attack envelope of the sfxr object
sfxr.setAttack(v)
- Set the attack envelope of the sfxr object
Value must be between 0 and 1
sfxr.getSustain()
- Get the sustain envelope of the sfxr object
sfxr.setSustain(v)
- Set the sustain envelope of the sfxr object
Value must be between 0 and 1
sfxr.getDecay()
- Get the decay envelope of the sfxr object
sfxr.setDecay(v)
- Set the decay envelope of the sfxr object
Value must be between 0 and 1
sfxr.getRelease()
- Get the release envelope of the sfxr object
sfxr.setRelease(v)
- Set the release envelope of the sfxr object
Value must be between 0 and 1
sfxr.getFilter()
- Get the filter of the sfxr object
sfxr.setFilter(boolean isOn)
- Set the filter of the sfxr object
Not sure what this does
sfxr.getLowPassFilterCutoff()
- Get the low pass filter cutoff of the sfxr object
sfxr.setLowPassFilterCutoff(v)
- Set the low pass filter cutoff of the sfxr object
Value must be between 0 and 1
sfxr.getLowPassFilterCutoffSweep()
- Get the low pass filter cutoff sweep of the sfxr object
sfxr.setLowPassFilterCutoffSweep(v)
- Set the low pass filter cutoff sweep of the sfxr object
Value must be between -1 and 1
sfxr.getFilterResonance()
- Get the filter resonance of the sfxr object
sfxr.setFilterResonance(v)
- Set the filter resonance of the sfxr object
Value must be between 0 and 1
sfxr.getHighPassFilterCutoff()
- Get the high pass filter cutoff of the sfxr object
sfxr.setHighPassFilterCutoff(v)
- Set the high pass filter cutoff of the sfxr object
Value must be between 0 and 1
sfxr.getHighPassFilterCutoffSweep()
- Get the high pass filter cutoff sweep of the sfxr object
sfxr.setHighPassFilterCutoffSweep(v)
- Set the high pass filter cutoff sweep of the sfxr object
Value must be between -1 and 1
sfxr.getPhaserOffset()
- Get the phaser offset of the sfxr object
sfxr.setPhaserOffset(v)
- Set the phaser offset of the sfxr object
Value must be between -1 and 1
sfxr.getPhaserOffsetSweep()
- Get the phaser offset sweep of the sfxr object
sfxr.setPhaserOffsetSweep(v)
- Set the phaser offset sweep of the sfxr object
Value must be between -1 and 1
sfxr.getRepeatSpeed()
- Get the repeat speed of the sfxr object
sfxr.setRepeatSpeed(v)
- Set the repeat speed of the sfxr object
Value must be between 0 and 1
sfxr.getArpeggio()
- Get the arpeggio of the sfxr object
sfxr.setArpeggio(v)
- Set the arpeggio of the sfxr object
Value must be between 0 and 1
sfxr.getArpeggioSpeed()
- Get the arpeggio speed of the sfxr object
sfxr.setArpeggioSpeed(v)
- Set the arpeggio speed of the sfxr object
Value must be between -1 and 1
sfxr.clone()
- creates a copy of the sfxr object
*** 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.wordWrapString(string, width)
- splits a string into an array of lines as if it were wrapped using
font_object.drawTextBox().
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'
font_object.getCharacterImage(code)
- returns the image in the font_object of the character based on
the code, e.g. 65 is 'A'
font_object.setCharacterImage(code, image)
- sets the character image in the font_object based on the code
*** 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
windowstyle_object.getBorder(border)
- get the border size (height or width) in pixels for the windowstyle object.
You can use EDGE_LEFT, EDGE_TOP, EDGE_RIGHT and EDGE_BOTTOM as parameters.
Note that the corner sizes are ignored.
*** particle engine ***
*** particle system parent ***
CreateParticleSystemParent()
- returns a new particle system parent object
*** particle system parent properties ***
ps_parent_object.type
- the constant PS_PARENT
ps_parent_object.id
- unsigned integer, read-only unique identifier
ps_parent_object.group
- integer, arbitrary user-defined group identifier
ps_parent_object.halted
- boolean, if true, system won't accept update requests
ps_parent_object.hidden
- boolean, if true, system won't accept render requests
ps_parent_object.cursed
- boolean, if true, system won't revive dead descendants
ps_parent_object.body
- a particle body object
ps_parent_object.initializer
- a particle initializer object
ps_parent_object.updater
- a particle updater object
ps_parent_object.renderer
- a particle renderer object
ps_parent_object.callback
- a particle callback object
*** particle system parent methods ***
ps_parent_object.update()
- ask particle system to update
ps_parent_object.render()
- ask particle system to render
ps_parent_object.adopt(particle_system)
- adopt the particle_system
ps_parent_object.host(particle_system)
- host the particle_system, hosted systems' bodies are neither initialized nor updated
ps_parent_object.isDead()
- return true, if the system is dead
ps_parent_object.kill()
- kills the system, this will trigger the on_death callback, if set
ps_parent_object.revive()
- revives the system, this will trigger the on_birth callback, if set
*** particle system parent descendants ***
ps_parent_object.descendants.size()
- returns the current size of the descendants list
ps_parent_object.descendants.unique()
- removes all duplicates from the descendants list
ps_parent_object.descendants.apply(function() {...})
- applies function to all systems in the descendants list by executing it
in the context of each system
ps_parent_object.descendants.sort(function(system_a, system_b) {...})
- sorts the descendants list using a custom implementation of merge sort
and function as the compare function
- the compare function should return true if the left argument goes first,
otherwise it should return false
ps_parent_object.descendants.contains(id)
- returns true if a system with the id is found in the descendants list, else false
ps_parent_object.descendants.containsGroup(group)
- returns true if any system related to the group is found in the descendants list,
else false
ps_parent_object.descendants.get(id)
- returns the system with the id in the descendants list
ps_parent_object.descendants.getGroup(group)
- returns an array of all systems related to the group in the descendants list
ps_parent_object.descendants.extract(id)
- extracts and returns the system with the id from the descendants list
ps_parent_object.descendants.extractGroup(group)
- extracts and returns an array of all systems related to the group from the
descendants list
ps_parent_object.descendants.remove(id)
- removes all occurrences of a system with the id from the descendants list
ps_parent_object.descendants.removeGroup(group)
- removes all occurrences of a systems related to the group from the descendants list
ps_parent_object.descendants.clear()
- clears the descendants list
*** particle system child ***
CreateParticleSystemChild(capacity)
- returns a new particle system child object with the initial capacity
*** particle system child properties ***
ps_child_object.type
- the constant PS_CHILD
ps_child_object.id
- unsigned integer, read-only unique identifier
ps_child_object.group
- integer, arbitrary user-defined group identifier
ps_child_object.halted
- boolean, if true, system won't accept update requests
ps_child_object.hidden
- boolean, if true, system won't accept render requests
ps_child_object.cursed
- boolean, if true, system won't revive dead descendants
ps_child_object.body
- a particle body object
ps_child_object.initializer
- a particle initializer object
ps_child_object.updater
- a particle updater object
ps_child_object.renderer
- a particle renderer object
ps_child_object.callback
- a particle callback object
*** particle system child methods ***
ps_child_object.update()
- ask particle system to update
ps_child_object.render()
- ask particle system to render
ps_child_object.clone()
- returns a new particle system child object which is the exact copy of ps_child_object
ps_child_object.isDead()
- return true, if the system is dead
ps_child_object.kill()
- kills the system, this will trigger the on_death callback, if set
ps_child_object.revive()
- revives the system, this will trigger the on_birth callback, if set
*** particle system child swarm ***
ps_child_object.swarm.renderer
- a particle renderer object
ps_child_object.swarm.size()
- returns the current size of the particle swarm
ps_child_object.swarm.capacity()
- returns the current swarm size limit
ps_child_object.swarm.grow()
- increases the swarm size by 1, if possible
ps_child_object.swarm.shrink()
- decreases size by 1, if possible
ps_child_object.swarm.resize(n)
- resizes the swarm by the integer n, can't resize to negative size or size bigger
than capacity
ps_child_object.swarm.reserve(n)
- makes sure that the swarm can hold at least n particles by allocating more space
if needed
ps_child_object.swarm.clear()
- sets swarm to a zero size
*** particle body ***
particle_system.body.x
particle_system.body.y
- floating point position coordinates
particle_system.body.vel_x
particle_system.body.vel_y
- floating point velocity components
particle_system.body.aging
- floating point aging factor which is subtracted from life each update
particle_system.body.life
- floating point life amount
*** particle initializer ***
particle_system.initializer.getAgingParams()
- returns an wrapper object filled with aging initialization parameters
- following signature is possible:
{min: -, max: -}
particle_system.initializer.setAgingParams({params})
- accepts a wrapper object filled with aging initialization parameters to set
- the same parameters are accepted as returned by getAgingParams()
- parameters which should not be set, can be omitted
particle_system.initializer.getPosParams([shape])
- returns a wrapper object filled with position initialization parameters
- if 'shape' is not specified, the parameters for the current shape are returned,
or if 'shape' is specified, the parameters belonging to the 'shape' are returned
- following signatures are possible:
{shape: PS_SHAPE_NULL}
{shape: PS_SHAPE_RECTANGLE,
x: {min: -, max: -},
y: {min: -, max: -}}
{shape: PS_SHAPE_ELLIPSE,
angle: {min: -, max: -},
a: {min: -, max: -},
b: {min: -, max: -}}
particle_system.initializer.setPosParams({params})
- accepts a wrapper object filled with position initialization parameters to set
- the same parameters are accepted as returned by getPosParams()
- parameters which should not be set, can be omitted
- if 'shape' is omitted, the parameters are assumed to belong to the current shape
particle_system.initializer.getVelParams()
- returns a wrapper object filled with velocity initialization parameters
- following signature is possible:
{mode: -,
angle: {min: -, max: -},
a: {min: -, max: -},
b: {min: -, max: -}}
mode can be either PS_ORIENTATION_EXPLICIT or PS_ORIENTATION_IMPLICIT
particle_system.initializer.setVelParams({params})
- accepts a wrapper object filled with position initialization parameters to set
- the same parameters are accepted as returned by getVelParams()
- parameters which should not be set, can be omitted
*** particle updater ***
particle_system.updater.force_x
particle_system.updater.force_y
- floating point force components (note: particles are assumed to have a mass of 1)
particle_system.updater.damping
- floating point damping constant
*** particle renderer ***
particle_system.renderer.texture
- holds the image to be rendered, always returns or sets copies
particle_system.renderer.blend_mode
- the blend mode to be used as the blendmode argument for rendering
particle_system.renderer.offset_x
particle_system.renderer.offset_y
- integers to be added to the position coordinates x and y
use them to adjust textures or to convert coordinates
particle_system.renderer.disabled
- boolean flag, if set to true, the standard renderer is disabled
*** particle callback ***
the following properties will accept ordinary JavaScript functions which
will be called on events in the context of the particle system object.
in order to disable a callback, set it to null.
particle_system.callback.on_update
- called on update, no arguments
particle_system.callback.on_render
- called on render, no arguments
particle_system.callback.on_birth
- called on birth, the first argument is either the parent particle system or null
particle_system.callback.on_death
- called on death, the first argument is either the parent particle system or null
*** images ***
Blend modes which can be used for image blitting:
- BLEND (default)
- ADD
- SUBTRACT
- MULTIPLY
Blend modes which can be used for image masking:
- ADD
- SUBTRACT
- MULTIPLY (default)
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 [, blendmode])
- draws the image onto the video buffer at x,y
image_object.blitMask(x, y, mask [, blendmode [, mask_blendmode]])
- draws the image into the video buffer, except that the color passed
as 'mask' tints the image
image_object.rotateBlit(x, y, radians [, blendmode])
- 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, [blendmode [, mask_blendmode]])
- rotateBlit + mask
image_object.zoomBlit(x, y, factor [, blendmode])
- 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 [, blendmode [, mask_blendmode]])
- zoomBlit + mask
image_object.transformBlit(x1, y1, x2, y2, x3, y3, x4, y4 [, blendmode])
- 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 [, blendmode [, mask_blendmode]])
- 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.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_object.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_object.rotateBlitMaskSurface(surface, x, y, angle, mask [, mask_blend_mode])
- rotateBlitSurface + blitMaskSurface
surface_object.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_object.zoomBlitMaskSurface(surface, x, y, factor, mask [, mask_blend_mode])
- zoomBlitSurface + blitMaskSurface
surface_object.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_object.transformBlitMaskSurface(surface, x1, y1, x2, y2, x3, y3, x4, y4, mask [, mask_blend_mode])
- transformBlitSurface + blitMaskSurface
surface_object.createImage()
- returns an image object from the surface object
Blend modes which can be used for drawing on surfaces:
- BLEND (default for drawing)
- REPLACE
- RGB_ONLY
- ALPHA_ONLY
- ADD
- SUBTRACT
- MULTIPLY (default for masking)
- AVERAGE
- INVERT
surface_object.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_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.findColor(aColor)
- Boolean: Tells us if the color aColor is in the surface
surface_object.floodFill(x, y, color)
- Flood Fills the area with a color
surface_object.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_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.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_object.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_object.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_object.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_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.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_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.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_object.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_object.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_object.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_object.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_object.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_object.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
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. Returns the original object.
surface_object.resize(w, h)
- resizes the surface images. This does not stretch or shrink the image
inside the surface. Returns the original object.
surface_object.rescale(w, h)
- stretches or shrinks the surface to the new width w and height h
Returns the original object.
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, .mng and .jng
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.getTicks()
- returns the amount of ticks
animation_object.getDelay()
- returns the delay between frames, in milliseconds
animation_object.getPlaytime()
- returns the total playtime, if defo
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
*** directories ***
Rename(old, new)
- renames or moves a file or directory and returns a boolean
CreateDirectory(directory)
- creates a new directory and returns a boolean
RemoveDirectory(directory)
- removes the directory 'directory' and returns a boolean
GetDirectoryList(directory)
- directory = directory in which to enumerate directories,
the current game's directory if not specified
- returns an array of strings, which contains the directory names that
resides in the 'directory' directory of the game.
*** 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.
RemoveFile(filename)
- remove the specified file
Rename(old_path, new_path)
- rename or move a file or directory
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
file_object.close()
- closes the file object, after this, the file_object cannot be used anymore.
*** 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