|
|
| Line 94: |
Line 94: |
| | = Map Engine = | | = Map Engine = |
| | | | |
| − | * [[MapEngine]](''map_filename'', ''fps''): Start the map engine at ''map_filename'' at speed ''fps''.
| + | {{API:Functions/Map}} |
| − | * [[IsMapEngineRunning]](): Check if the map engine is running or not.
| |
| − | * [[ExitMapEngine]](): Flag the map engine to exit on the next update.
| |
| − | | |
| − | == Map object ==
| |
| − | | |
| − | * Sphere [[Object-Map|Map]] object: Holds map data.
| |
| − | | |
| − | * [[GetMapEngine]](): Obtain the current [[Object-Map|Map]] object.
| |
| − | * [[Map.save]](''filename''): Save a [[Object-Map|Map]] object to ''filename''.
| |
| − | * [[Map.layerAppend]](''layer_width'', ''layer_height'', ''tile_index''): Adds a new layer to the [[Object-Map|Map]] object.
| |
| − | | |
| − | == Engine control ==
| |
| − | | |
| − | * [[GetMapEngineFrameRate]](): Get the frames per second the map engine is running at.
| |
| − | * [[SetMapEngineFrameRate]](''fps''): Change map engine frame rate.
| |
| − | * [[RenderMap]](): Draw all map layers and persons.
| |
| − | * [[UpdateMapEngine]](): Update state of map entities, animations and events in map engine.
| |
| − | | |
| − | == Map control ==
| |
| − | | |
| − | * [[GetCurrentMap]](): Get the filename of the loaded map.
| |
| − | * [[ChangeMap]](''map_filename''): Change the current map of the map engine.
| |
| − | | |
| − | == Map scripts ==
| |
| − | | |
| − | * [[SetRenderScript]](''script''): Set ''script'' to run after each time the map is drawn.
| |
| − | * [[SetUpdateScript]](''script''): Set ''script'' to run after each map engine update.
| |
| − | | |
| − | * [[CallMapScript]](''map_event''): Call map script associated with the current map.
| |
| − | | |
| − | * [[CallDefaultMapScript]](''map_event''): Call map script set by [[SetDefaultMapScript]]().
| |
| − | * [[SetDefaultMapScript]](''map_event'', ''script''): Set map engine to run ''script'' when ''map_event'' occurs for any map.
| |
| − | | |
| − | * Map event constants:
| |
| − | ** <var>SCRIPT_ON_ENTER_MAP</var>
| |
| − | ** <var>SCRIPT_ON_LEAVE_MAP</var>
| |
| − | ** <var>SCRIPT_ON_LEAVE_MAP_NORTH</var>
| |
| − | ** <var>SCRIPT_ON_LEAVE_MAP_EAST</var>
| |
| − | ** <var>SCRIPT_ON_LEAVE_MAP_SOUTH</var>
| |
| − | ** <var>SCRIPT_ON_LEAVE_MAP_WEST</var>
| |
| − | | |
| − | * [[SetDelayScript]](''frames'', ''script''): Run ''script'' after ''frames'' delay.
| |
| − | | |
| − | == Within the map engine ==
| |
| − | | |
| − | * [[SetColorMask]](''color'', ''frames''): Draws ''color'' over the map engine for ''frames'' duration.
| |
| − | | |
| − | === Maps ===
| |
| − | | |
| − | ==== Zones ====
| |
| − | | |
| − | * [[AreZonesAt]](''x'', ''y'', ''layer''): Check if there are any zones at (''x'', ''y'') on ''layer''.
| |
| − | * [[ExecuteZones]](''x'', ''y'', ''layer''): Run all scripts for zones that (''x'', ''y'') on ''layer'' is in.
| |
| − | * [[GetNumZones]](): Get the number of zones on the current map.
| |
| − | | |
| − | ===== For each zone =====
| |
| − | | |
| − | * [[GetCurrentZone]](): Get the current zone index in a zone script.
| |
| − | * [[ExecuteZoneScript]](''zone''): Execute the script of ''zone''.
| |
| − | | |
| − | ===== Zone position =====
| |
| − | | |
| − | * [[GetZoneX]](''zone''): Get the X coordinate of ''zone'' on the map.
| |
| − | * [[GetZoneY]](''zone''): Get the Y coordinate of ''zone'' on the map.
| |
| − | * [[GetZoneWidth]](''zone''): Get the pixel width of ''zone''.
| |
| − | * [[GetZoneHeight]](''zone''): Get the pixel height of ''zone''.
| |
| − | | |
| − | * [[GetZoneLayer]](''zone''): Get the map layer index of ''zone''.
| |
| − | * [[SetZoneLayer]](''zone'', ''layer''): Sets the map layer of ''zone'' to ''layer''.
| |
| − | | |
| − | ==== Triggers ====
| |
| − | | |
| − | * [[IsTriggerAt]](''x'', ''y'', ''layer''): Check if there is a trigger at pixel coords (''x'', ''y'') on ''layer''.
| |
| − | | |
| − | ===== For each trigger =====
| |
| − | | |
| − | * [[ExecuteTrigger]](''x'', ''y'', ''layer''): Activate the trigger at (''x'', ''y'') on ''layer'' if one exists.
| |
| − | | |
| − | ==== Layers ====
| |
| − | | |
| − | * [[GetNumLayers]](): Get number of layers in the current map.
| |
| − | | |
| − | ===== For each layer =====
| |
| − | | |
| − | * [[GetLayerName]](''layer''): Get the name of ''layer''.
| |
| − | * [[GetLayerWidth]](''layer''): Get width of ''layer'' in tiles.
| |
| − | * [[GetLayerHeight]](''layer''): Get height of ''layer'' in tiles.
| |
| − | * [[SetLayerWidth]](''layer'', ''width''): Set width of ''layer'' in tiles.
| |
| − | * [[SetLayerHeight]](''layer'', ''height''): Set height of ''layer'' in tiles.
| |
| − | | |
| − | * [[SetTile]](''tile_x'', ''tile_y'', ''layer'', ''tile''): Plot a tile at the given map location.
| |
| − | | |
| − | * [[GetLayerAngle]](''layer''): Get ''layer'' angle in radians.
| |
| − | * [[SetLayerAngle]](''layer'', ''angle''): Set ''layer'' rotation to ''angle'' radians.
| |
| − | | |
| − | * [[GetLayerMask]](''layer''): Get [[Object-Color|Color]] mask of ''layer''.
| |
| − | * [[SetLayerMask]](''layer'', ''color_mask''): Mask the layer with ''color_mask''.
| |
| − | | |
| − | * [[IsLayerReflective]](''layer''): Find if ''layer'' shows person entity reflections.
| |
| − | * [[SetLayerReflective]](''layer'', ''reflect''): Set reflectivity of ''layer''.
| |
| − | | |
| − | * [[IsLayerVisible]](''layer''): Find if ''layer'' is visible.
| |
| − | * [[SetLayerVisible]](''layer'', ''visible''): Set visibility of ''layer''.
| |
| − | | |
| − | * [[SetLayerScaleFactorX]](''layer'', ''factor''): Set width scaling of ''layer'' to ''factor''.
| |
| − | * [[SetLayerScaleFactorY]](''layer'', ''factor''): Set height scaling of ''layer'' to ''factor''.
| |
| − | | |
| − | * [[SetLayerRenderer]](''layer'', ''script''): Run ''script'' after ''layer'' has been rendered.
| |
| − | | |
| − | ==== Tiles ====
| |
| − | | |
| − | * [[GetNumTiles]](): Get the number of tiles in the current map tileset.
| |
| − | * [[GetTile]](''tile_x'', ''tile_y'', ''layer''): Get the tileset index of the tile at the given map position.
| |
| − | * [[GetTileWidth]](): Get the image width of tiles in the current map tileset.
| |
| − | * [[GetTileHeight]](): Get the image height of tiles in the current map tileset.
| |
| − | * [[ReplaceTilesOnLayer]](''layer'', ''old_tile'', ''new_tile''): Substitute all ''old_tile'' with ''new_tile'' on ''layer''.
| |
| − | | |
| − | ===== For each tile =====
| |
| − | | |
| − | * [[GetTileName]](''tile''): Get the name of ''tile''.
| |
| − | | |
| − | * [[GetTileImage]](''tile''): Get the [[Object-Image|Image]] of ''tile'' in the current map tileset.
| |
| − | * [[SetTileImage]](''tile'', ''image''): Change the [[Object-Image|Image]] of ''tile''.
| |
| − | | |
| − | * [[SetTileSurface]](''tile'', ''surface''): Change the [[Object-Surface|Surface]] of ''tile''.
| |
| − | | |
| − | ===== Tile animations =====
| |
| − | | |
| − | * [[GetNextAnimatedTile]](''tile''): Get next tile index of animation from ''tile''.
| |
| − | * [[SetNextAnimatedTile]](''tile'', ''next''): Set next tile in a tile animation sequence.
| |
| − | | |
| − | * [[GetTileDelay]](''tile''): Get frame delay of animated tile.
| |
| − | * [[SetTileDelay]](''tile'', ''delay''): Set a frame delay for this ''tile'' animation frame.
| |
| − | | |
| − | === Input ===
| |
| − | | |
| − | ==== Player input ====
| |
| − | | |
| − | * [[AttachInput]](''person''): Give input control of ''person'' to the player.
| |
| − | * [[DetachInput]](): Remove input control given by [[AttachInput]]() or [[AttachPlayerInput]]().
| |
| − | | |
| − | * [[AttachPlayerInput]](''person'', ''player''): Give input control of ''person'' to ''player''.
| |
| − | * [[DetachPlayerInput]](''person''): Remove input control from ''person'' given to a player.
| |
| − | | |
| − | * [[IsInputAttached]](): Check if input is attached to a person or not.
| |
| − | * [[GetInputPerson]](): Get the name of the person who holds player input.
| |
| − | | |
| − | ==== Binding scripts to keys ====
| |
| − | | |
| − | * [[BindKey]](''key'', ''on_key_down'', ''on_key_up''): Bind scripts to key events.
| |
| − | * [[UnbindKey]](''key''): Remove script binding from the given ''key''.
| |
| − | | |
| − | ==== Binding scripts to joystick buttons ====
| |
| − | | |
| − | * [[BindJoystickButton]](''joystick'', ''button'', ''on_button_down'', ''on_button_up''): Bind scripts to joystick button events.
| |
| − | * [[UnbindJoystickButton]](joystick, button): Unbind joystick buttons from scripts.
| |
| − | | |
| − | === Camera ===
| |
| − | | |
| − | ==== Following persons ====
| |
| − | | |
| − | * [[AttachCamera]](''person''): Make the camera follow ''person''.
| |
| − | * [[DetachCamera]](): Stop the camera from following any person.
| |
| − | | |
| − | * [[IsCameraAttached]](): Check if the camera is attached to a person.
| |
| − | * [[GetCameraPerson]](): Get the name of the person the camera is attached to.
| |
| − | | |
| − | ==== Camera position ====
| |
| − | | |
| − | * [[GetCameraX]](): Get the map X coordinate the camera is focusing on.
| |
| − | * [[SetCameraX]](''x_pos''): Set the X coordinate of the camera.
| |
| − | | |
| − | * [[GetCameraY]](): Get the map Y coordinate the camera is focusing on.
| |
| − | * [[SetCameraY]](''y_pos''): Set the Y coordinate of the camera.
| |
| − | | |
| − | ==== Coordinate conversion ====
| |
| − | | |
| − | * [[MapToScreenX]](''layer'', ''x''): Convert a map X coordinate to screen X.
| |
| − | * [[MapToScreenY]](''layer'', ''y''): Convert a map Y coordinate to screen Y.
| |
| − | * [[ScreenToMapX]](''layer'', ''x''): Convert a screen X coordinate to map ''layer'' X.
| |
| − | * [[ScreenToMapY]](''layer'', ''y''): Convert a screen Y coordinate to map ''layer'' Y.
| |
| − | | |
| − | === Persons ===
| |
| − | | |
| − | * [[GetPersonList]](): Get an array of all named persons on the current map.
| |
| − | | |
| − | * [[CreatePerson]](''name'', ''spriteset'', ''destroy_with_map''): Create a new person called ''name'' with ''spriteset'' (filename).
| |
| − | * [[DestroyPerson]](''name''): Destroy the person called ''name''.
| |
| − | | |
| − | ==== Person position ====
| |
| − | | |
| − | * [[GetPersonX]](''name''): Get the map X coordinate of ''name''.
| |
| − | * [[GetPersonY]](''name''): Get the map Y coordinate of ''name''.
| |
| − | * [[GetPersonLayer]](''name''): Get the map layer index of ''name''.
| |
| − | | |
| − | * [[SetPersonX]](''name'', ''x''): Set the map X of ''name'' to ''x''.
| |
| − | * [[SetPersonY]](''name'', ''y''): Set the map Y of ''name'' to ''y''.
| |
| − | * [[SetPersonLayer]](''name'', ''layer''): Set the map layer of ''name'' to ''layer''.
| |
| − | | |
| − | * [[GetPersonXFloat]](''name''): Get the map X of ''name'' to floating point accuracy.
| |
| − | * [[GetPersonYFloat]](''name''): Get the map Y of ''name'' to floating point accuracy.
| |
| − | * [[SetPersonXYFloat]](''name'', ''x'', ''y''): Set the position of ''name'' with floating point accuracy.
| |
| − | | |
| − | ==== Directions and animations ====
| |
| − | | |
| − | * [[GetPersonDirection]](''name''): Get the animation direction of person ''name''.
| |
| − | * [[SetPersonDirection]](''name'', ''direction''): Set animation direction of person ''name'' to ''direction''.
| |
| − | | |
| − | * [[GetPersonFrame]](''name''): gets the frame and direction that are currently being displayed.
| |
| − | * [[SetPersonFrame]](''name'', ''frame''): sets which frame from which direction to display.
| |
| − | | |
| − | * [[SetPersonFrameRevert]](''name'', ''delay''): sets the delay between when the person last moved and returning to first frame.
| |
| − | * [[GetPersonFrameRevert]](''name''): gets the delay between when the person last moved and returning to first frame.
| |
| − | | |
| − | ==== Movement speed ====
| |
| − | | |
| − | * [[SetPersonSpeed]](''name'', ''speed''): sets the person's speed.
| |
| − | * [[SetPersonSpeedXY]](''name'', ''speed_x'', ''speed_y''): sets the person's x and y speed individually.
| |
| − | | |
| − | * [[GetPersonSpeedX]](''name''): gets a person's x speed.
| |
| − | * [[GetPersonSpeedY]](''name''): gets a person's y speed.
| |
| − | | |
| − | ==== Appearance ====
| |
| − | | |
| − | [[GetPersonOffsetX]](name)
| |
| − | - gets the horizontal offset used for blitting frames
| |
| − | | |
| − | [[SetPersonOffsetX]](name, x)
| |
| − | - sets the horizontal offset to use for blitting frames
| |
| − | e.g. setting it to 10 would result in the person frame blitted always 10 pixels
| |
| − | to the right, while the person's x-position would remain unchanged.
| |
| − | | |
| − | [[GetPersonOffsetY]](name)
| |
| − | - gets the vertical offset used for blitting frames
| |
| − | | |
| − | [[SetPersonOffsetY]](name, y)
| |
| − | - sets the vertical offset to use for blitting frames
| |
| − | e.g. setting it to 10 would result in the person frame blitted always 10 pixels
| |
| − | to the bottom, while the person's y-position would remain unchanged.
| |
| − | | |
| − | * [[GetPersonAngle]](''name''): Get the rotation angle of the person ''name''.
| |
| − | * [[SetPersonAngle]](''name'', ''angle''): Set the rotation angle of person ''name'' to ''angle'' radians.
| |
| − | | |
| − | * [[GetPersonMask]](''name''): Get the masking [[Object-Color|color]] of the person ''name''.
| |
| − | * [[SetPersonMask]](''name'', ''color''): Set the color-channel multiplying mask ''[[Object-Color|color]]'' of the person ''name''.
| |
| − | | |
| − | * [[SetPersonScaleFactor]](''name'', ''scale_w'', ''scale_h''): Rescales the sprite of person ''name'' by relative factors ''scale_w'' and ''scale_h''.
| |
| − | * [[SetPersonScaleAbsolute]](''name'', ''width'', ''height''): Rescales the sprite of person ''name'' to ''width'' * ''height'' pixels.
| |
| − | | |
| − | * [[GetPersonSpriteset]](''name''): Get the spriteset of person ''name''.
| |
| − | * [[SetPersonSpriteset]](''name'', ''spriteset''): Set the spriteset of person ''name'' to ''spriteset'' (Sphere [[Object-Spriteset|Spriteset]] object).
| |
| − | | |
| − | * [[IsPersonVisible]](''name''): Check if the person with ''name'' is visible or not. <code>true</code>: visible, <code>false</code>: not visible.
| |
| − | * [[SetPersonVisible]](''name'', ''visible''): Make person ''name'' visible or invisible. <code>true</code>: visible, <code>false</code>: not visible.
| |
| − | | |
| − | ==== Obstruction ====
| |
| − | | |
| − | * [[GetPersonBase]](''name''): Get a person's spriteset obstruction base.
| |
| − | | |
| − | * [[IsPersonObstructed]](''name'', ''x'', ''y''): Check if person "''name''" would be obstructed at (''x'', ''y'').
| |
| − | | |
| − | * [[IgnoreTileObstructions]](''person'', ''ignore''): Sets whether person "''person''" ignores tile obstructions.
| |
| − | | |
| − | * [[IsIgnoringTileObstructions]](''person''): Checks whether "''person''" is ignoring tile obstructions.
| |
| − | | |
| − | [[GetObstructingTile]](name, x, y)
| |
| − | - returns -1 if name isn't obstructed by a tile at x, y,
| |
| − | - returns the tile index of the tile if name is obstructed at x, y
| |
| − | | |
| − | [[GetObstructingPerson]](name, x, y)
| |
| − | - returns "" if name isn't obstructed by person at x, y,
| |
| − | - returns the name of the person if name is obstructed at x, y
| |
| − | | |
| − | [[IgnorePersonObstructions]](person, ignore)
| |
| − | - Sets whether 'person' should ignore other spriteset bases
| |
| − |
| |
| − | [[IsIgnoringPersonObstructions]](person)
| |
| − | - Returns true if 'person' is ignoring person obstructions, else false
| |
| − | | |
| − | [[GetPersonIgnoreList]](person)
| |
| − | - Returns a list of people that 'name' is ignoring
| |
| − |
| |
| − | [[SetPersonIgnoreList]](person, ignore_list)
| |
| − | - Tells 'person' to ignore everyone in ignore_list
| |
| − | e.g. SetPersonIgnoreList("White-Bomberman", ["bomb", "powerup"]);
| |
| − | Tells White-Bomberman to not be obstructed by bombs or powerups
| |
| − | | |
| − | ==== Talk interaction ====
| |
| − | | |
| − | [[SetTalkActivationKey]](key)
| |
| − | [[GetTalkActivationKey]]()
| |
| − | - set key used to activate talk scripts
| |
| − | | |
| − | [[SetTalkDistance]](pixels)
| |
| − | [[GetTalkDistance]]()
| |
| − | - set distance to check for talk script activation
| |
| − | | |
| − | ==== Following other persons ====
| |
| − | | |
| − | * [[FollowPerson]](''name'', ''leader'', ''pixels''): Makes a sprite follow behind another sprite.
| |
| − | | |
| − | ==== Person data ====
| |
| − | | |
| − | [[GetPersonData]](name)
| |
| − | - gets a data object assiocated with the person 'name'
| |
| − | There are certain default properties/values filled in by the engine, they are:
| |
| − | num_frames - the number of frames for the person's current direction
| |
| − | num_directions - the number of directions for the person
| |
| − | width - the width of the spriteset's current frame
| |
| − | height - the height of the spriteset's current frame
| |
| − | leader - the person that this person is following, or "" if no-one...
| |
| − | Any other properties are free for you to fill with values,
| |
| − | e.g.
| |
| − | var data = GetPersonData("Jimmy");
| |
| − | var num_frames = data["num_frames"];
| |
| − |
| |
| − | [[SetPersonData]](name, data)
| |
| − | - sets the 'data' object assiocated with the person 'name'
| |
| − | e.g.
| |
| − | var data = GetPersonData("Jimmy");
| |
| − | data["talked_to_jimmy"] = true;
| |
| − | SetPersonData("Jimmy", data);
| |
| − | | |
| − | [[SetPersonValue]](name, key, value)
| |
| − | - SetPersonValue("Jimmy", "talked_to_jimmy", true); // same as code above
| |
| − |
| |
| − | [[GetPersonValue]](name, key)
| |
| − | - GetPersonValue("Jimmy", "num_frames"); // same as previous code above
| |
| − | | |
| − | ==== Person control ====
| |
| − | | |
| − | * [[SetPersonScript]](name, which, script)
| |
| − | * Person scripts:
| |
| − | ** SCRIPT_ON_CREATE
| |
| − | ** SCRIPT_ON_DESTROY
| |
| − | ** SCRIPT_ON_ACTIVATE_TOUCH
| |
| − | ** SCRIPT_ON_ACTIVATE_TALK
| |
| − | ** SCRIPT_COMMAND_GENERATOR
| |
| − | * [[CallPersonScript]](name, which)
| |
| − | | |
| − | * [[GetCurrentPerson]]()
| |
| − | | |
| − | * [[QueuePersonCommand]](''name'', ''command'', ''immediate''): add a command to the person's command queue.
| |
| − | * Person commands:
| |
| − | ** <var>COMMAND_WAIT</var>
| |
| − | ** <var>COMMAND_ANIMATE</var>
| |
| − | ** <var>COMMAND_FACE_NORTH</var>
| |
| − | ** <var>COMMAND_FACE_NORTHEAST</var>
| |
| − | ** <var>COMMAND_FACE_EAST</var>
| |
| − | ** <var>COMMAND_FACE_SOUTHEAST</var>
| |
| − | ** <var>COMMAND_FACE_SOUTH</var>
| |
| − | ** <var>COMMAND_FACE_SOUTHWEST</var>
| |
| − | ** <var>COMMAND_FACE_WEST</var>
| |
| − | ** <var>COMMAND_FACE_NORTHWEST</var>
| |
| − | ** <var>COMMAND_MOVE_NORTH</var>
| |
| − | ** <var>COMMAND_MOVE_EAST</var>
| |
| − | ** <var>COMMAND_MOVE_SOUTH</var>
| |
| − | ** <var>COMMAND_MOVE_WEST</var>
| |
| − | * [[QueuePersonScript]](''name'', ''script'', ''immediate''): Queue a script command on the command queue of ''name''.
| |
| − | * [[IsCommandQueueEmpty]](''name''): Check if the command queue of the person is empty.
| |
| − | * [[ClearPersonCommands]](name): Clears the command queue of the named person.
| |
| | | | |
| | = Sphere objects = | | = Sphere objects = |
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.
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.
