stendhal/doc/mkdocs/lua/objects/entities.md

---

Contents

[TOC]

---

Introduction

Object instance: entities

---

Description

Helper for managing in-game entities.

---

See Also

For public methods that can be performed on Entity objects.

• RPEntity
• SilentNPC
• SpeakerNPC
• Item
• StackableItem
• Sign
• ShopSign
• Reader

---

Methods

---

entities:create

entities:create (def)

• Creates a new entity.
• Parameters:
  • def: (table) Entity definition table (see Entity Definition Tables).
• Returns: (Entity) New entity instance.

---

entities:createItemSpawner

entities:createItemSpawner (name, meanTurns)

entities:createItemSpawner (name, meanTurns, initOnAdded)

• Creates an item spawner.
• Parameters:
  • name: (string) Name of item to be spawned.
  • meanTurns: (int) Average number of turns for item to respawn.
  • initOnAdded: (boolean) If true initializes spawner when added to zone.
• Returns: (PassiveEntityRespawnPoint) New spawn point instance.

---

entities:createShopSign

entities:createShopSign (name, title, caption, seller)

• DEPRECATED: Use entities:create.
• Creates a new ShopSign entity.
• Parameters:
  • name: (string) The shop name.
  • title: (string) The sign title.
  • caption: (string) The caption above the table.
  • seller: (boolean) true, if this sign is for items sold by an NPC (default: true).
• Returns: (ShopSign) New shop sign instance.

---

entities:createSign

entities:createSign ()

entities:createSign (visible)

• DEPRECATED: Use entities:create.
• Creates a new sign.
• Parameters:
  • visible: (boolean) If false, the sign will not have a visual representation (default: true).
• Returns: (Sign|Reader) New sign or reader (visible=false).

---

entities:createSilentNPC

entities:createSilentNPC ()

• DEPRECATED: Use entities:create.
• Creates a non-interactive NPC.
• Returns: (LuaSilentNPC) New silent NPC instance.

---

entities:createSpeakerNPC

entities:createSpeakerNPC (name)

• DEPRECATED: Use entities:create.
• Creates an interactive NPC.
• Parameters:
  • name: (string) Name of new NPC.
• Returns: (LuaSpeakerNPC) New speaker NPC instance.

---

entities:getItem

entities:getItem (name)

• Retrieves a registered Item.
• Parameters:
  • name: (string) Name of the item.
• Returns: (Item) Item instance or nil if name not registered.

---

entities:getNPC

entities:getNPC (name)

• Retrieves an existing NPC.
• Parameters:
  • name: (string) Name of NPC.
• Returns: (SpeakerNPC) NPC instance or nil.

---

entities:getPlayer

entities:getPlayer (name)

• Retrieves a logged in player.

• Parameters:

  • name: (string) Name of player.

• Returns: (Player) Logged in player or nil.

• Usage:

    local player = entities:getPlayer("foo")
  

---

entities:getStackableItem

entities:getStackableItem (name)

• Retrieves a registered stackable item.
• Parameters:
  • name: (string) Name of the item.
• Returns: (StackableItem) Stackable item instance or nil if name not registered.

---

entities:setEntityPath

entities:setEntityPath (entity, table, loop)

• DEPRECATED: Path can now be set by directly calling the NPC's setPath method.
• Sets a guided entity's path using a table.
• Parameters:
  • entity (LuaGuidedEntity) The entity whose path is being set.
  • table (table) Table with list of coordinates representing nodes.
  • loop (boolean) If true entity will restart path upon completion.

---

entities:setPath

entities:setPath (entity, table, loop)

• DEPRECATED: Path can now be set by directly calling the NPC's setPath method.
• Helper method for setting an NPC's path.
• Parameters:
  • entity: (RPEntity) Then entity whose path is being set.
  • table: (table) Table with list of coordinates representing nodes.
  • loop: (boolean) If true entity will restart path upon completion.

---

entities:setPathAndPosition

entities:setPathAndPosition (entity, table, loop)

• DEPRECATED: Path can now be set by directly by calling the NPC's setPath method.
• Helper function for setting an NPC's path & starting position.
• Parameters:
  • entity: (RPEntity) The entity whose path is being set.
  • table: (table) Table with list of coordinates representing nodes.
  • loop: (boolean) If true, the entity's path should loop.

---

entities:setEntityTraits

entities:setEntityTraits (entity, traits)

• DEPRECATED: Use entities:create.
• Adds attributes defined in Entity.
• Parameters:
  • entity: (Entity) The entity to whom attributes will be added.
  • traits: (table) List of attributes.

---

entities:setNPCTraits

entities:setNPCTraits (npc, traits)

• DEPRECATED: Use entities:create.
• Adds attributes defined in PassiveNPC.
• Parameters:
  • npc: (PassiveNPC) The entity to whom attributes will be added.
  • traits: (table) table of attributes.

---

entities:summonCreature

entities:summonCreature (name, zone, x, y, summoner, raid)

entities:summonCreature (def)

• Summons a creature into the area.
• Parameters:
  • name: (string) Name of creature to be summoned.
  • zone: (string) Name of zone where creature should be summoned.
  • x: (int) Horizontal position of summon location.
  • y: (int) Vertical position of summon location.
  • summoner: (string) Name of entity doing the summoning.
  • raid: (bool) Whether or not the creature should be a RaidCreature instance.
  • def: (table) Key-value table containing parameters for summoning creature (see Summon Creature Table).
• Returns: (int)
  • 0 = success
  • 1 = creature not found
  • 2 = zone not found

---

Entity Definition Tables

General Definition Table

Key	Type	Required	Description
type	string	yes	"SpeakerNPC", "SilentNPC", "Sign", "ShopSign", or "Reader".
pos	table	no	Entity position relative to zone ({x, y}).
description	string	no	Information for "look" command.
class	string	no	Entity class (for signs, image to be used).
subclass	string	no	Entity sub-class (usually image to be used).
resistance	int	no	Amount of resistance when colliding with another entity (0-100) (default: 100).
size	table	no	{w, h}
cursor	string	no	Cursor to display over entity.
visibility	int	no	Level of visibility (0-100) (default: 100).
menu	string	no	Alternate text for menu.

SpeakerNPC & SilentNPC Definition Table

Includes: general definition

Key	Type	Required	Description
dir	Direction	no	Entity's initial facing direction.
ignoresCollision	boolean	no	If false, movement won't be halted on collision.
path	table	no	See Path Table
speed	double	no	Entity movement speed.
basehp	int	no	Entity base HP.
hp	int	no	Entity actual HP.
outfit	table	no	See Outfit Table
idea	string	no	Icon shown representing entity's state.
sounds	table<string>	no	Randomly played sounds emitted from entity.
teleports	boolean	no

SpeakerNPC Definition Table

Includes: SpeakerNPC & SilentNPC definition

Key	Type	Required	Description
name	string	yes	Name of the NPC.
idleDir	Direction	no	Facing direction when NPC is idle.
chatTimeout	long	no	Amount of idle time before NPC ends conversation (default: ???).
perceptionRange	int	no	Distance at which NPC will hear players (default: ???).
currentState	ConversationStates	no	Converstion state NPC is initialized with (default: ConversationStates.IDLE).
greeting	table	no	Responses to keywords (see Greeting Table).
replies	table	no	Responses to keywords (see Replies Table).
altImage	string	no	Image that will be displayed on NPCs webpage.

Sign Definition Table

Includes: general definition

Key	Type	Required	Description
text	string	no	Text shown when sign is read.
visible	boolean	no	Whether or not a sprite should be drawn for this sign (default: true).

ShopSign Definition Table

Includes: Sign definition

Key	Type	Required	Description
name	string	yes	Shop name/identfier associated with this sign.
title	string	yes	Title displayed at top of window.
caption	string	yes	Caption displayed at top of window.
seller	boolean	yes	Whether sign represents a seller shop or not.

Parameter Tables

Greeting Table

Key	Type	Required	Description
text	string	yes	NPC response when player starts conversation.
action	ChatAction	no	NPC action when player start conversation.

Replies Table

Key	Type	Required	Description
quest	string	no	Reply to "quest"/"task".
job	string	no	Reply to "job".
help	string	no	Reply to "help".
offer	string	no	Reply to "offer".
bye	string	no	Reply to "bye"/"goodbye".

Outfit Table

Key	Type	Required	Description
layers	string	yes	Entity's outfit.
colors	table<string, int>	no	Entity's outfit colors.

Path Table

Key	Type	Required	Description
nodes	table	yes	List of positions the entity will traverse.
loop	boolean	no	If true, entity will restart path unpon completion.
retrace	boolean	no	If true, entity will retrace path backwards upon completion.
collisionAction	CollisionAction	no	Action when entity collides (default: CollisionAction.REVERSE).

Summon Creature Table

Key	Type	Required	Description
name	string	yes	Name of creature to be summoned.
zone	string	yes	Name of zone where creature should be summoned.
x	int	yes	Horizontal position of summon location.
y	int	yes	Vertical position of summon location.
summoner	string	no	Name of entity doing the summoning (used for logging game events).
raid	bool	no	Whether or not the creature should be a RaidCreature instance (default: true).

Members

entities.manager

This is simply the entity manager instance.

---

LuaSpeakerNPC

• Inherits: SpeakerNPC

Public Methods

---

LuaSpeakerNPC:add

LuaSpeakerNPC:add (states, triggers, conditions, nextState, reply, actions)

• Additional method to support passing Lua data types as parameters.
• Parameters:
  • states: The conversation state(s) the entity should be in to trigger response. Can be ConversationStates enum value or table of ConversationStates.
  • triggers: string or table of strings to trigger response.
  • conditions: Conditions to check for this response. Can be ChatCondition instance, a table of ChatCondition instances, or a function.
  • nextState: (ConversationStates) Conversation state to set entity to after response.
  • reply: (string) The NPC's response or nil.
  • actions: Actions to execute. Can be ChatAction instance, a table of ChatAction instances, or a function.

---

LuaSpeakerNPC:setPath

entities:setPath (table, loop)

• Set a path for this entity to follow.
• Parameters:
  • table: (table) Table of coordinates to set as path. Example: {{35, 79}, {35, 89}, {40, 89}}
  • loop: (bool) (optional) If true, entity should loop around to restart path when reaching the end.

---

LuaSpeakerNPC:setPathAndPosition

entities:setPathAndPosition (table, loop)

• Set path & starting position for entity. The starting position is the first node in the path.
• Parameters:
  • table: (table) Table of coordinates to set as path. Example: {{35, 79}, {35, 89}, {40, 89}}
  • loop: (bool) (optional) If true, entity should loop around to restart path when reaching the end.

---

LuaSilentNPC

• Inherits: SilentNPC

Public Methods

---

LuaSilentNPC:setPath

entities:setPath (table, loop)

• Set a path for this entity to follow.
• Parameters:
  • table: (table) Table of coordinates to set as path. Example: {{35, 79}, {35, 89}, {40, 89}}
  • loop: (bool) (optional) If true, entity should loop around to restart path when reaching the end.

---

LuaSilentNPC:setPathAndPosition

entities:setPathAndPosition (table, loop)

• Set path & starting position for entity. The starting position is the first node in the path.
• Parameters:
  • table: (table) Table of coordinates to set as path. Example: {{35, 79}, {35, 89}, {40, 89}}
  • loop: (bool) (optional) If true, entity should loop around to restart path when reaching the end.