---
# Contents
[TOC]
---
# Introduction
Object instance: `entities`
---
## Description
Helper for managing in-game entities.
---
## See Also
For public methods that can be performed on [`Entity`][Entity] objects.
- [RPEntity]
- [SilentNPC]
- [SpeakerNPC]
- [Item]
- [StackableItem]
- [Sign]
- [ShopSign]
- [Reader]
---
# Methods
---
## entities:create
entities:create (def)
- Creates a new entity.
- Parameters:
- def: _([table][LuaTable])_ Entity definition table (see
[Entity Definition Tables](#entity-definition-tables)).
- Returns: _([Entity][Entity])_ New entity instance.
---
## entities:createItemSpawner
entities:createItemSpawner (name, meanTurns)
entities:createItemSpawner (name, meanTurns, initOnAdded)
- Creates an item spawner.
- Parameters:
- name: _([string][LuaString])_ Name of item to be spawned.
- meanTurns: _([int][LuaInteger])_ Average number of turns for item
to respawn.
- initOnAdded: _([boolean][LuaBoolean])_ 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](#entitiescreate)._
- Creates a new [ShopSign] entity.
- Parameters:
- name: _([string][LuaString])_ The shop name.
- title: _([string][LuaString])_ The sign title.
- caption: _([string][LuaString])_ The caption above the table.
- seller: _([boolean][LuaBoolean])_ `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](#entitiescreate)._
- Creates a new sign.
- Parameters:
- visible: _([boolean][LuaBoolean])_ 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](#entitiescreate)._
- Creates a non-interactive NPC.
- Returns: _([LuaSilentNPC](#luasilentnpc))_ New silent NPC instance.
---
## entities:createSpeakerNPC
entities:createSpeakerNPC (name)
- ___DEPRECATED:__ Use [entities:create](#entitiescreate)._
- Creates an interactive NPC.
- Parameters:
- name: _([string][LuaString])_ Name of new NPC.
- Returns: _([LuaSpeakerNPC](#luaspeakernpc))_ New speaker NPC instance.
---
## entities:getItem
entities:getItem (name)
- Retrieves a registered Item.
- Parameters:
- name: _([string][LuaString])_ Name of the item.
- Returns: _([Item])_ Item instance or [`nil`][LuaNil] if ___name___ not registered.
---
## entities:getNPC
entities:getNPC (name)
- Retrieves an existing NPC.
- Parameters:
- name: _([string][LuaString])_ Name of NPC.
- Returns: _([SpeakerNPC])_ NPC instance or [`nil`][LuaNil].
---
## entities:getPlayer
entities:getPlayer (name)
- Retrieves a logged in player.
- Parameters:
- name: _([string][LuaString])_ Name of player.
- Returns: _([Player])_ Logged in player or [`nil`][LuaNil].
- Usage:
local player = entities:getPlayer("foo")
---
## entities:getStackableItem
entities:getStackableItem (name)
- Retrieves a registered stackable item.
- Parameters:
- name: _([string][LuaString])_ Name of the item.
- Returns: _([StackableItem])_ Stackable item instance or [`nil`][LuaNil] 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](#luaguidedentity))_ The entity whose path is being set.
- ___table__ ([table][LuaTable])_ Table with list of coordinates representing nodes.
- ___loop__ ([boolean][LuaBoolean])_ 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][LuaTable])_ Table with list of coordinates
representing nodes.
- loop: _([boolean][LuaBoolean])_ 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][LuaTable])_ Table with list of coordinates
representing nodes.
- loop: _([boolean][LuaBoolean])_ If `true`, the entity's path should
loop.
---
## entities:setEntityTraits
entities:setEntityTraits (entity, traits)
- ___DEPRECATED:__ Use [entities:create](#entitiescreate)._
- Adds attributes defined in [Entity].
- Parameters:
- entity: _([Entity])_ The entity to whom attributes will be added.
- traits: _([table][LuaTable])_ List of attributes.
---
## entities:setNPCTraits
entities:setNPCTraits (npc, traits)
- ___DEPRECATED:__ Use [entities:create](#entitiescreate)._
- Adds attributes defined in [PassiveNPC].
- Parameters:
- npc: _([PassiveNPC])_ The entity to whom attributes will be added.
- traits: _([table][LuaTable])_ 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][LuaString])_ Name of creature to be summoned.
- zone: _([string][LuaString])_ Name of zone where creature should be
summoned.
- x: _([int][LuaInteger])_ Horizontal position of summon location.
- y: _([int][LuaInteger])_ Vertical position of summon location.
- summoner: _([string][LuaString])_ Name of entity doing the
summoning.
- raid: _([bool][LuaBoolean])_ Whether or not the creature should be
a [RaidCreature] instance.
- def: _([table][LuaTable])_ Key-value table containing parameters
for summoning creature (see [Summon Creature Table](#summon-creature-table)).
- Returns: _([int][LuaInteger])_
- 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`][SpeakerNPC] & [`SilentNPC`][SilentNPC] Definition Table
Includes: [general definition](#general-definition-table)
| 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](#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](#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`][SpeakerNPC] Definition Table
Includes: [SpeakerNPC & SilentNPC definition](#speakernpc-silentnpc-definition-table)
| 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](#greeting-table)). |
| replies | table | no | Responses to keywords (see [Replies Table](#replies-table)). |
| altImage | string | no | Image that will be displayed on NPCs webpage. |
## [`Sign`][Sign] Definition Table
Includes: [general definition](#general-definition-table)
| 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`][ShopSign] Definition Table
Includes: [Sign definition](#sign-definition-table)
| 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][DefaultEntityManager] 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][LuaTable] of
`ConversationStates`.
- triggers: [string][LuaString] 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][LuaFunction].
- nextState: _([ConversationStates])_ Conversation state to set
entity to after response.
- reply: _([string][LuaString])_ The NPC's response or [nil][LuaNil].
- 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][LuaTable])_ Table of coordinates to set as path.
Example: `{{35, 79}, {35, 89}, {40, 89}}`
- loop: _([bool][LuaBoolean]) (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][LuaTable])_ Table of coordinates to set as path.
Example: `{{35, 79}, {35, 89}, {40, 89}}`
- loop: _([bool][LuaBoolean]) (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][LuaTable])_ Table of coordinates to set as path.
Example: `{{35, 79}, {35, 89}, {40, 89}}`
- loop: _([bool][LuaBoolean]) (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][LuaTable])_ Table of coordinates to set as path.
Example: `{{35, 79}, {35, 89}, {40, 89}}`
- loop: _([bool][LuaBoolean]) (optional)_ If `true`, entity should
loop around to restart path when reaching the end.
[ChatAction]: /reference/java/games/stendhal/server/entity/npc/ChatAction.html
[ChatCondition]: /reference/java/games/stendhal/server/entity/npc/ChatCondition.html
[ConversationStates]: /reference/java/games/stendhal/server/entity/npc/ConversationStates.html
[DefaultEntityManager]: /reference/java/games/stendhal/server/core/rule/defaultruleset/DefaultEntityManager.html
[Entity]: /reference/java/games/stendhal/server/entity/Entity.html
[Item]: /reference/java/games/stendhal/server/entity/item/Item.html
[LuaEntityHelper]: /reference/java/games/stendhal/server/core/scripting/lua/LuaEntityHelper.html
[PassiveEntityRespawnPoint]: /reference/java/games/stendhal/server/entity/mapstuff/spawner/PassiveEntityRespawnPoint.html
[PassiveNPC]: /reference/java/games/stendhal/server/entity/npc/PassiveNPC.html
[Player]: /reference/java/games/stendhal/server/entity/player/Player.html
[RaidCreature]: /reference/java/games/stendhal/server/entity/creature/RaidCreature.html
[Reader]: /reference/java/games/stendhal/server/entity/mapstuff/sign/Reader.html
[RPEntity]: /reference/java/games/stendhal/server/entity/RPEntity.html
[ShopSign]: /reference/java/games/stendhal/server/entity/mapstuff/sign/ShopSign.html
[Sign]: /reference/java/games/stendhal/server/entity/mapstuff/sign/Sign.html
[SilentNPC]: /reference/java/games/stendhal/server/entity/npc/SilentNPC.html
[SpeakerNPC]: /reference/java/games/stendhal/server/entity/npc/SpeakerNPC.html
[StackableItem]: /reference/java/games/stendhal/server/entity/item/StackableItem.html
[LuaBoolean]: http://luaj.org/luaj/3.0/api/org/luaj/vm2/LuaBoolean.html
[LuaFunction]: http://luaj.org/luaj/3.0/api/org/luaj/vm2/LuaFunction.html
[LuaInteger]: http://luaj.org/luaj/3.0/api/org/luaj/vm2/LuaInteger.html
[LuaNil]: http://luaj.org/luaj/3.0/api/org/luaj/vm2/LuaNil.html
[LuaString]: http://luaj.org/luaj/3.0/api/org/luaj/vm2/LuaString.html
[LuaTable]: http://luaj.org/luaj/3.0/api/org/luaj/vm2/LuaTable.html