Legacy:Functions/Map

Map and map engine control

MapEngine(map_filename, fps): Start the map engine at map_filename at speed fps.
GetCurrentMap(): Get the filename of the loaded map.
ChangeMap(map_filename): Change the current map of the map engine.
IsMapEngineRunning(): Check if the map engine is running or not.
UpdateMapEngine(): Update state of map entities, animations and events in map engine.
ExitMapEngine(): Flag the map engine to exit on the next update.

RenderMap(): Draw all map layers and persons to the back buffer.
GetMapEngineFrameRate(): Get the frames per second the map engine is running at.
SetMapEngineFrameRate(fps): Change map engine frame rate.
SetColorMask(color, frames): Draws color over the map engine for frames duration.

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.

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.

Map Elements

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

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.
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.
GetTileWidth(): Get the image width of tiles in the current map tileset.
GetTileHeight(): Get the image height 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.
SetTile(tile_x, tile_y, layer, tile): Plot a tile at the given map location.
ReplaceTilesOnLayer(layer, old_tile, new_tile): Substitute all old_tile with new_tile on layer.

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

GetInputPerson(): Get the name of the person who holds player input.
IsInputAttached(): Check if input is attached to a person or not.
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.

Binding scripts to input devices

Note: Binding a key or joystick button overrides whatever input has already been associated with it via AttachInput or AttachPlayerInput!

BindKey(key, on_key_down, on_key_up): Bind scripts to key events.
UnbindKey(key): Remove script binding from the given key.

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 entities

GetCameraPerson(): Get the name of the person the camera is attached to.
IsCameraAttached(): Check if the camera is attached to a person.
AttachCamera(person): Make the camera follow person.
DetachCamera(): Stop the camera from following any person.

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

Coordinate conversion translates the current map position to screen coordinates based on the current camera position, and vice versa. Some functions (like checking obstructions) require map coordinates, while others (like image blitting) require screen coordinates. Both map and screen coordinates consider the top-left corner to be (0,0) and extend right-ward and down-ward for X and Y position, respectively.

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

NOTE: Entities are known in script as "persons" for legacy reasons.

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.
FollowPerson(name, leader, pixels): Makes a sprite follow behind another sprite.

Entity 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

GetPersonSpeedX(name): gets a person's x speed.
GetPersonSpeedY(name): gets a person's y speed.

SetPersonSpeed(name, speed): sets the person's speed.
SetPersonSpeedXY(name, speed_x, speed_y): sets the person's x and y speed independently.

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 the tile index of the tile if name is obstructed at x, y
returns -1 if name isn't obstructed by a tile at x, y,
GetObstructingPerson(name, x, y): returns the name of the person if name is obstructed at x, y
returns "" if name isn't obstructed by any person 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): set key used to activate talk scripts
GetTalkActivationKey(): return the key code used to activate talk scripts
SetTalkDistance(pixels): set maximum distance to check for talk script activation
GetTalkDistance(): return the maximum distance to check for talk script activation

Entity data

GetPersonData(name): gets a data object associated 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 associated 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

Controlling entities in script

GetCurrentPerson()
SetPersonScript(name, which, script)
- Available 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.
- Available 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.