Legacy:Functions/Map: Difference between revisions

From Spherical
Jump to navigation Jump to search
Newer edit →
created, needs reformatting
 
Reformat for new convention
Line 1: Line 1:
* [[MapEngine]](''map_filename'', ''fps''): Start the map engine at ''map_filename'' at speed ''fps''.
== Map and map engine control ==
* [[IsMapEngineRunning]](): Check if the map engine is running or not.
* [[ExitMapEngine]](): Flag the map engine to exit on the next update.


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


* Sphere [[Object-Map|Map]] object: Holds map data.
* [[API:RenderMap|RenderMap]](): Draw all map layers and persons to the back buffer.
* [[API:GetMapEngineFrameRate|GetMapEngineFrameRate]](): Get the frames per second the map engine is running at.
* [[API:SetMapEngineFrameRate|SetMapEngineFrameRate]](''fps''): Change map engine frame rate.


* [[GetMapEngine]](): Obtain the current [[Object-Map|Map]] object.
== 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 ==
* Sphere [[API:Map|Map]] object: Holds map data.


* [[GetCurrentMap]](): Get the filename of the loaded map.
* [[API:GetMapEngine|GetMapEngine]](): Obtain the current [[API:Map|Map]] object.
* [[ChangeMap]](''map_filename''): Change the current map of the map engine.
* [[API:Map/save|Map.save]](''filename''): Save a [[API:Map|Map]] object to ''filename''.
* [[API:Map/layerAppend|Map.layerAppend]](''layer_width'', ''layer_height'', ''tile_index''): Adds a new layer to the [[API:Map|Map]] object.


== Map scripts ==
== Map scripts ==


* [[SetRenderScript]](''script''): Set ''script'' to run after each time the map is drawn.
* [[API:SetRenderScript]](''script''): Set ''script'' to run after each time the map is drawn.
* [[SetUpdateScript]](''script''): Set ''script'' to run after each map engine update.
* [[API: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:
* [[API:CallMapScript]](''map_event''): Call map script associated with the current map.
** <var>SCRIPT_ON_ENTER_MAP</var>
* [[API:CallDefaultMapScript]](''map_event''): Call map script set by [[SetDefaultMapScript]]().
** <var>SCRIPT_ON_LEAVE_MAP</var>
* [[API:SetDefaultMapScript]](''map_event'', ''script''): Set map engine to run ''script'' when ''map_event'' occurs for any map.
** <var>SCRIPT_ON_LEAVE_MAP_NORTH</var>
** Map event constants:
** <var>SCRIPT_ON_LEAVE_MAP_EAST</var>
**: <var>SCRIPT_ON_ENTER_MAP</var>
** <var>SCRIPT_ON_LEAVE_MAP_SOUTH</var>
**: <var>SCRIPT_ON_LEAVE_MAP</var>
** <var>SCRIPT_ON_LEAVE_MAP_WEST</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.
* [[API:SetDelayScript]](''frames'', ''script''): Run ''script'' after ''frames'' delay.


== Within the map engine ==
== Within the map engine ==


* [[SetColorMask]](''color'', ''frames''): Draws ''color'' over the map engine for ''frames'' duration.
* [[API:SetColorMask]](''color'', ''frames''): Draws ''color'' over the map engine for ''frames'' duration.


=== Maps ===
=== Maps ===


==== Zones ====
{{API:Functions/Map/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''.
{{API:Functions/Map/Triggers}}
* [[SetLayerMask]](''layer'', ''color_mask''): Mask the layer with ''color_mask''.


* [[IsLayerReflective]](''layer''): Find if ''layer'' shows person entity reflections.
{{API:Functions/Map/Layers}}
* [[SetLayerReflective]](''layer'', ''reflect''): Set reflectivity of ''layer''.


* [[IsLayerVisible]](''layer''): Find if ''layer'' is visible.
{{API:Functions/Map/Tiles}}
* [[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 ===
=== Input ===
 
{{API:Functions/Map/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 ===
=== Camera ===
 
{{API:Functions/Map/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 ===
=== Persons ===
 
{{API:Functions/Map/Entities}}
* [[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.

Revision as of 23:49, 1 June 2013

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.

Map object

  • Sphere Map object: Holds map data.

Map scripts

  • API:CallMapScript(map_event): Call map script associated with the current map.
  • API:CallDefaultMapScript(map_event): Call map script set by SetDefaultMapScript().
  • API: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

Within the map engine

  • API:SetColorMask(color, frames): Draws color over the map engine for frames duration.

Maps

API:Functions/Map/Zones

API:Functions/Map/Triggers

API:Functions/Map/Layers

API:Functions/Map/Tiles

Input

API:Functions/Map/Input

Camera

API:Functions/Map/Camera

Persons

API:Functions/Map/Entities

Retrieved from "http://wiki.spheredev.org/index.php?title=Legacy:Functions/Map&oldid=604"