---

Contents

---

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:addKnownChatOptions

• Helper function as SpeakerNPC.addKnownChatOptions cannot seem to handle array of LuaString.
• Parameters:
  • npc SpeakerNPC NPC to which options should be added.
  • keywords table Keyword(s) to be added.

---

entities:create

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

---

entities:createItemSpawner

• 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

• 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

• 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

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

---

entities:createSpeakerNPC

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

---

entities:fixedPath

• Creates a path for a guided entity.
• Parameters:
  • nodes table List of path coordinates.
  • loop boolean Whether the path should loop.
• Returns: FixedPath Entity path.
• new in Stendhal 1.44
• Usage example:

  local npc = entities:createSilentNPC()
  local nodes = entities:fixedPath({{13, 15}, {13, 18}}, true)
  npc:setPathAndPosition(nodes)
  

---

entities:getItem

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

---

entities:getNPC

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

---

entities:getPlayer

• Retrieves a logged in player.
• Parameters:
  • name string Name of player.
• Returns: Player Logged in player or nil.
• Usage example:

  local player = entities:getPlayer("foo")
  

---

entities:getStackableItem

• 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

• 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

• 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

• 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

• 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

• 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

• 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

TODO: layers & colors data types should be the same

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

• 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

• 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

• 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

• 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

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