Legacy:Functions/Map

• 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.

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.

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)

• GetCurrentPerson()

• 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.