Difference between revisions of "Legacy:Functions/Map/Entities"

Revision as of 00:28, 2 June 2013

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.

• API:GetPersonSpriteset(name): Get the spriteset of person name.
• API: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.