- Click a red link.
- Place the following code in the empty edit box:
{{subst:functemp}}for a new function, or{{subst:objecttemp}}for a new object. - Check the minor edit flag and save.
- Click 'edit' at the top of the page to add content.
- Try to be objective when writing, and save when you're done.
- Remove description from this page, add page link to list at the top of the matching section.
Difference between revisions of "Legacy:Functions"
From Spherical
(→Sphere objects: reorder, description) |
(→System interfaces: section out primitives, input) |
||
| Line 82: | Line 82: | ||
=== Graphics primitives === | === Graphics primitives === | ||
| − | + | {{API:Functions/Primitives}} | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
=== Screen size === | === Screen size === | ||
| Line 150: | Line 89: | ||
* [[GetScreenHeight]](): Get the height of the screen. | * [[GetScreenHeight]](): Get the height of the screen. | ||
| − | + | {{API:Functions/Input}} | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
== Time == | == Time == | ||
Revision as of 23:03, 30 May 2013
This is a definitive reference of the Sphere API: in other words, the functions that Sphere uses in its JavaScript engine. The page currently mimics the layout of docs/development/api.txt, but is undergoing reorganisation.
Alternatively, the whole Sphere API, sorted by category, with brief descriptions of the functions is available in the API text file mirror itself.
For assistance with using JavaScript itself, consult these links:
- https://developer.mozilla.org/en/Core_JavaScript_1.5_Guide - Mozilla JavaScript Guide
- https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference - Mozilla JavaScript Reference
Making new function/object pages
Simple steps:
Contents
General functions
- CreateStringFromCode(ascii_code): Translate a number to the matching character.
- GetVersion(): Get the version of Sphere as a number.
Script functions
- GarbageCollect(): Run JavaScript's garbage collector to free memory.
File inclusion
- EvaluateScript(filename): Include a script file unconditionally.
- EvaluateSystemScript(filename): Include a system script file unconditionally.
- RequireScript(filename): Include a script file once.
- RequireSystemScript(filename): Include a system script file once.
Engine functions
- GetVersionString(): Get the full Sphere version.
Game control
- Abort(): Exit with a message.
- Exit(): Exit unconditionally.
- RestartGame(): Restarts the game.
Acessing installed games
- Sphere Game object: Holds info about an installed Sphere game.
- GetGameList(): Get a list of installed Sphere games.
- ExecuteGame(directory): Execute Sphere game installed in directory.
System interfaces
Video
- ApplyColorMask(color): Fills the whole screen with color.
- FlipScreen(): Show the results of drawing to the screen.
Clipping
- Sphere Rectangle object: Holds dimensions for clipping rectangle functions.
- GetClippingRectangle(): Get the rectangle in which drawing is being clipped on screen.
- SetClippingRectangle(x, y, width, height): Set a rectangle to clip screen drawing.
Frame rate control
- GetFrameRate(): Get the frame rate that limits FlipScreen() call rate.
- SetFrameRate(frames_per_second): Limit the rate of FlipScreen() calls.
Graphics primitives
Screen size
- GetScreenWidth(): Get the width of the screen.
- GetScreenHeight(): Get the height of the screen.
Time
- GetTime(): Get the number of milliseconds since an arbitrary point in time.
Map object
- Sphere Map object: Holds map data.
- GetMapEngine(): Obtain the current Map object.
- Map.save(filename): Save a Map object to filename.
- Map.layerAppend(layer_width, layer_height, tile_index): Adds a new layer to the Map object.
ByteArray object
- Sphere ByteArray object: Holds an array of bytes.
- CreateByteArray(length): Create a new ByteArray.
- bytearray.concat(byte_array_object, byte_array_to_append): Returns bytearray with byte_array_to_append attached to the end of it
- bytearray.slice(start_slice [, end_slice]): Returns a slice of the bytearray starting at start, and ending at end or the end of the bytearray if end is omitted. If end is a negative number, the end point is started from the end of the bytearray.
Conversion to and from strings
- CreateByteArrayFromString(string): Create a ByteArray from string.
- CreateStringFromByteArray(byte_array): Convert a ByteArray into a string.
Data hashing
- HashByteArray(byte_array): Calculate MD5 'fingerprint' of data in byte_array.
Networking
- GetLocalAddress(): Get the local IP address.
- GetLocalName(): Get the local computer name.
- ListenOnPort(port): Wait for a connection and return a socket for it.
- OpenAddress(address, port): Connect to address on port.
Socket object
- Sphere Socket object: Has the ability to send/receive data over a network.
- Socket.close(): Close the socket.
- Socket.getPendingReadSize(): Get size of next incoming data block in bytes.
- Socket.isConnected(): Find if the socket is connected or not.
- Socket.read(size): Read size number of bytes into a ByteArray from socket.
- Socket.write(data): Send a ByteArray into the socket.
Map Engine
- MapEngine(map_filename, fps): Start the map engine at map_filename at speed fps.
- IsMapEngineRunning(): Check if the map engine is running or not.
- ExitMapEngine(): Flag the map engine to exit on the next update.
Engine control
- GetMapEngineFrameRate(): Get the frames per second the map engine is running at.
- SetMapEngineFrameRate(fps): Change map engine frame rate.
- RenderMap(): Draw all map layers and persons.
- UpdateMapEngine(): Update state of map entities, animations and events in map engine.
Map control
- GetCurrentMap(): Get the filename of the loaded map.
- ChangeMap(map_filename): Change the current map of the map engine.
Map scripts
- SetRenderScript(script): Set script to run after each time the map is drawn.
- SetUpdateScript(script): Set script to run after each map engine update.
- CallMapScript(map_event): Call map script associated with the current map.
- CallDefaultMapScript(map_event): Call map script set by SetDefaultMapScript().
- SetDefaultMapScript(map_event, script): Set map engine to run script when map_event occurs for any map.
- Map event constants:
- 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
- SetDelayScript(frames, script): Run script after frames delay.
Within the map engine
- SetColorMask(color, frames): Draws color over the map engine for frames duration.
Maps
Zones
- AreZonesAt(x, y, layer): Check if there are any zones at (x, y) on layer.
- ExecuteZones(x, y, layer): Run all scripts for zones that (x, y) on layer is in.
- GetNumZones(): Get the number of zones on the current map.
For each zone
- GetCurrentZone(): Get the current zone index in a zone script.
- ExecuteZoneScript(zone): Execute the script of zone.
Zone position
- GetZoneX(zone): Get the X coordinate of zone on the map.
- GetZoneY(zone): Get the Y coordinate of zone on the map.
- GetZoneWidth(zone): Get the pixel width of zone.
- GetZoneHeight(zone): Get the pixel height of zone.
- GetZoneLayer(zone): Get the map layer index of zone.
- SetZoneLayer(zone, layer): Sets the map layer of zone to layer.
Triggers
- IsTriggerAt(x, y, layer): Check if there is a trigger at pixel coords (x, y) on layer.
For each trigger
- ExecuteTrigger(x, y, layer): Activate the trigger at (x, y) on layer if one exists.
Layers
- GetNumLayers(): Get number of layers in the current map.
For each layer
- GetLayerName(layer): Get the name of layer.
- GetLayerWidth(layer): Get width of layer in tiles.
- GetLayerHeight(layer): Get height of layer in tiles.
- SetLayerWidth(layer, width): Set width of layer in tiles.
- SetLayerHeight(layer, height): Set height of layer in tiles.
- SetTile(tile_x, tile_y, layer, tile): Plot a tile at the given map location.
- GetLayerAngle(layer): Get layer angle in radians.
- SetLayerAngle(layer, angle): Set layer rotation to angle radians.
- GetLayerMask(layer): Get Color mask of layer.
- SetLayerMask(layer, color_mask): Mask the layer with color_mask.
- IsLayerReflective(layer): Find if layer shows person entity reflections.
- SetLayerReflective(layer, reflect): Set reflectivity of layer.
- IsLayerVisible(layer): Find if layer is visible.
- SetLayerVisible(layer, visible): Set visibility of layer.
- SetLayerScaleFactorX(layer, factor): Set width scaling of layer to factor.
- SetLayerScaleFactorY(layer, factor): Set height scaling of layer to factor.
- SetLayerRenderer(layer, script): Run script after layer has been rendered.
Tiles
- GetNumTiles(): Get the number of tiles in the current map tileset.
- GetTile(tile_x, tile_y, layer): Get the tileset index of the tile at the given map position.
- GetTileWidth(): Get the image width of tiles in the current map tileset.
- GetTileHeight(): Get the image height of tiles in the current map tileset.
- ReplaceTilesOnLayer(layer, old_tile, new_tile): Substitute all old_tile with new_tile on layer.
For each tile
- GetTileName(tile): Get the name of tile.
- GetTileImage(tile): Get the Image of tile in the current map tileset.
- SetTileImage(tile, image): Change the Image of tile.
- SetTileSurface(tile, surface): Change the Surface of tile.
Tile animations
- GetNextAnimatedTile(tile): Get next tile index of animation from tile.
- SetNextAnimatedTile(tile, next): Set next tile in a tile animation sequence.
- GetTileDelay(tile): Get frame delay of animated tile.
- SetTileDelay(tile, delay): Set a frame delay for this tile animation frame.
Input
Player input
- AttachInput(person): Give input control of person to the player.
- DetachInput(): Remove input control given by AttachInput() or AttachPlayerInput().
- AttachPlayerInput(person, player): Give input control of person to player.
- DetachPlayerInput(person): Remove input control from person given to a player.
- IsInputAttached(): Check if input is attached to a person or not.
- GetInputPerson(): Get the name of the person who holds player input.
Binding scripts to keys
- BindKey(key, on_key_down, on_key_up): Bind scripts to key events.
- UnbindKey(key): Remove script binding from the given key.
Binding scripts to joystick buttons
- BindJoystickButton(joystick, button, on_button_down, on_button_up): Bind scripts to joystick button events.
- UnbindJoystickButton(joystick, button): Unbind joystick buttons from scripts.
Camera
Following persons
- AttachCamera(person): Make the camera follow person.
- DetachCamera(): Stop the camera from following any person.
- IsCameraAttached(): Check if the camera is attached to a person.
- GetCameraPerson(): Get the name of the person the camera is attached to.
Camera position
- GetCameraX(): Get the map X coordinate the camera is focusing on.
- SetCameraX(x_pos): Set the X coordinate of the camera.
- GetCameraY(): Get the map Y coordinate the camera is focusing on.
- SetCameraY(y_pos): Set the Y coordinate of the camera.
Coordinate conversion
- MapToScreenX(layer, x): Convert a map X coordinate to screen X.
- MapToScreenY(layer, y): Convert a map Y coordinate to screen Y.
- ScreenToMapX(layer, x): Convert a screen X coordinate to map layer X.
- ScreenToMapY(layer, y): Convert a screen Y coordinate to map layer Y.
Persons
- GetPersonList(): Get an array of all named persons on the current map.
- CreatePerson(name, spriteset, destroy_with_map): Create a new person called name with spriteset (filename).
- DestroyPerson(name): Destroy the person called name.
Person position
- GetPersonX(name): Get the map X coordinate of name.
- GetPersonY(name): Get the map Y coordinate of name.
- GetPersonLayer(name): Get the map layer index of name.
- SetPersonX(name, x): Set the map X of name to x.
- SetPersonY(name, y): Set the map Y of name to y.
- SetPersonLayer(name, layer): Set the map layer of name to layer.
- GetPersonXFloat(name): Get the map X of name to floating point accuracy.
- GetPersonYFloat(name): Get the map Y of name to floating point accuracy.
- SetPersonXYFloat(name, x, y): Set the position of name with floating point accuracy.
Directions and animations
- GetPersonDirection(name): Get the animation direction of person name.
- SetPersonDirection(name, direction): Set animation direction of person name to direction.
- GetPersonFrame(name): gets the frame and direction that are currently being displayed.
- SetPersonFrame(name, frame): sets which frame from which direction to display.
- SetPersonFrameRevert(name, delay): sets the delay between when the person last moved and returning to first frame.
- GetPersonFrameRevert(name): gets the delay between when the person last moved and returning to first frame.
Movement speed
- SetPersonSpeed(name, speed): sets the person's speed.
- SetPersonSpeedXY(name, speed_x, speed_y): sets the person's x and y speed individually.
- GetPersonSpeedX(name): gets a person's x speed.
- GetPersonSpeedY(name): gets a person's y speed.
Appearance
GetPersonOffsetX(name) - gets the horizontal offset used for blitting frames
SetPersonOffsetX(name, x) - sets the horizontal offset to use for blitting frames e.g. setting it to 10 would result in the person frame blitted always 10 pixels to the right, while the person's x-position would remain unchanged.
GetPersonOffsetY(name) - gets the vertical offset used for blitting frames
SetPersonOffsetY(name, y) - sets the vertical offset to use for blitting frames e.g. setting it to 10 would result in the person frame blitted always 10 pixels to the bottom, while the person's y-position would remain unchanged.
- GetPersonAngle(name): Get the rotation angle of the person name.
- SetPersonAngle(name, angle): Set the rotation angle of person name to angle radians.
- GetPersonMask(name): Get the masking color of the person name.
- SetPersonMask(name, color): Set the color-channel multiplying mask color of the person name.
- SetPersonScaleFactor(name, scale_w, scale_h): Rescales the sprite of person name by relative factors scale_w and scale_h.
- SetPersonScaleAbsolute(name, width, height): Rescales the sprite of person name to width * height pixels.
- GetPersonSpriteset(name): Get the spriteset of person name.
- SetPersonSpriteset(name, spriteset): Set the spriteset of person name to spriteset (Sphere Spriteset object).
- IsPersonVisible(name): Check if the person with name is visible or not.
true: visible,false: not visible. - SetPersonVisible(name, visible): Make person name visible or invisible.
true: visible,false: not visible.
Obstruction
- GetPersonBase(name): Get a person's spriteset obstruction base.
- IsPersonObstructed(name, x, y): Check if person "name" would be obstructed at (x, y).
- IgnoreTileObstructions(person, ignore): Sets whether person "person" ignores tile obstructions.
- IsIgnoringTileObstructions(person): Checks whether "person" is ignoring tile obstructions.
GetObstructingTile(name, x, y) - returns -1 if name isn't obstructed by a tile at x, y, - returns the tile index of the tile if name is obstructed at x, y
GetObstructingPerson(name, x, y) - returns "" if name isn't obstructed by person at x, y, - returns the name of the person if name is obstructed at x, y
IgnorePersonObstructions(person, ignore) - Sets whether 'person' should ignore other spriteset bases IsIgnoringPersonObstructions(person) - Returns true if 'person' is ignoring person obstructions, else false
GetPersonIgnoreList(person) - Returns a list of people that 'name' is ignoring SetPersonIgnoreList(person, ignore_list) - Tells 'person' to ignore everyone in ignore_list e.g. SetPersonIgnoreList("White-Bomberman", ["bomb", "powerup"]); Tells White-Bomberman to not be obstructed by bombs or powerups
Talk interaction
SetTalkActivationKey(key) GetTalkActivationKey() - set key used to activate talk scripts
SetTalkDistance(pixels) GetTalkDistance() - set distance to check for talk script activation
Following other persons
- FollowPerson(name, leader, pixels): Makes a sprite follow behind another sprite.
Person data
GetPersonData(name) - gets a data object assiocated with the person 'name' There are certain default properties/values filled in by the engine, they are: num_frames - the number of frames for the person's current direction num_directions - the number of directions for the person width - the width of the spriteset's current frame height - the height of the spriteset's current frame leader - the person that this person is following, or "" if no-one... Any other properties are free for you to fill with values, e.g. var data = GetPersonData("Jimmy"); var num_frames = data["num_frames"]; SetPersonData(name, data) - sets the 'data' object assiocated with the person 'name' e.g. var data = GetPersonData("Jimmy"); data["talked_to_jimmy"] = true; SetPersonData("Jimmy", data);
SetPersonValue(name, key, value) - SetPersonValue("Jimmy", "talked_to_jimmy", true); // same as code above GetPersonValue(name, key) - GetPersonValue("Jimmy", "num_frames"); // same as previous code above
Person control
- SetPersonScript(name, which, script)
- Person scripts:
- SCRIPT_ON_CREATE
- SCRIPT_ON_DESTROY
- SCRIPT_ON_ACTIVATE_TOUCH
- SCRIPT_ON_ACTIVATE_TALK
- SCRIPT_COMMAND_GENERATOR
- CallPersonScript(name, which)
- QueuePersonCommand(name, command, immediate): add a command to the person's command queue.
- Person commands:
- COMMAND_WAIT
- COMMAND_ANIMATE
- COMMAND_FACE_NORTH
- COMMAND_FACE_NORTHEAST
- COMMAND_FACE_EAST
- COMMAND_FACE_SOUTHEAST
- COMMAND_FACE_SOUTH
- COMMAND_FACE_SOUTHWEST
- COMMAND_FACE_WEST
- COMMAND_FACE_NORTHWEST
- COMMAND_MOVE_NORTH
- COMMAND_MOVE_EAST
- COMMAND_MOVE_SOUTH
- COMMAND_MOVE_WEST
- QueuePersonScript(name, script, immediate): Queue a script command on the command queue of name.
- IsCommandQueueEmpty(name): Check if the command queue of the person is empty.
- ClearPersonCommands(name): Clears the command queue of the named person.
Sphere objects
Besides the above, Sphere has a set of built-in objects for more generalized use within projects. Most are loaded from external resource files, but a few (Color, ColorMatrix) are defined solely in script and remain only in-memory during the running of the project.
