StendhalScripting/LuaAPI: Difference between revisions

{{Navigation for Stendhal Top|Playing}}

Methods:

; ''<span style="color:green;">properties:getValue</span>(p)''

: Retrieves the value of a property.

: '''''p:''''' (string) Property name.

: '''''returns:''''' (string) Property value or `nil`.

; ''<span style="color:green;">properties:enabled</span>(p)''

: Checks if a property is enabed.

: '''''p:''''' (string) Property name.

: '''''returns:''''' (boolean) `true` if enabled.

; ''<span style="color:green;">properties:equals</span>(p, v)''

: Checks if a property is set to a specified value.

: '''''p:''''' (string) Property name.

: '''''v:''''' (string) Value to compare with.

: '''''returns:''''' (boolean) `true` if the value of the property is the same as `v`.

Examples usage:

<pre>

-- example of only executing script contents on test server

if not properties:enabed("stendhal.testserver") then

do return end

end

</pre>

See also: [[StendhalAPI#Entities]] for public methods that can be performed on <code>Entity</code> objects.

; ''<span style="color:green">entities:getPlayer</span>(name)''

: Retrieves a logged in Player.

: '''''name:''''' (<code>String</code>) Name of player.

: ''returns:'' Logged in {{StendhalFile|master|src/games/stendhal/server/entity/player/Player.java|Player}} or <code>null</code>.

; ''<span style="color:green">entities:getNPC</span>(name)''

: Retrieves an existing SpeakerNPC.

: '''''name:''''' (<code>String</code>) Name of NPC.

: ''returns:'' [[StendhalScripting/LuaAPI#LuaSpeakerNPC|SpeakerNPC]] instance or <code>null</code>.

; ''<span style="color:green">entities:getItem</span>(name)''

: Retrieves a registered Item.

: '''''name:''''' (<code>String</code>) Name of the item.

: ''returns:'' {{StendhalFile|master|src/games/stendhal/server/entity/item/Item.java|Item}} instance or <code>null</code> if not a registered item.

; ''<span style="color:green">entities:getStackableItem</span>(name)''

: Retrieves a registered StackableItem.

: '''''name:''''' (<code>String</code>) Name of the item.

: ''returns:'' {{StendhalFile|master|src/games/stendhal/server/entity/item/StackableItem.java|StackableItem}} instance or <code>null</code> if not a registered stackable item.

; ''<span style="color:green">entities:createSpeakerNPC</span>(name)''

: Creates an interactive NPC.

: '''''name:''''' (<code>String</code>) Name of new NPC.

: ''returns:'' New [[StendhalScripting/LuaAPI#LuaSpeakerNPC|SpeakerNPC]] instance.

; ''<span style="color:green">entities:createSilentNPC</span>()''

: Creates a non-interactive NPC.

: ''returns:'' New [[StendhalScripting/LuaAPI#LuaSilentNPC|SilentNPC]] instance.

; ''<span style="color:green">entities:setPath</span>(entity, table, loop)''

: '''''DEPRECATED:''' path can now be set by directly calling the NPC's <code>setPath</code> method''

: Helper method for setting an NPC's path.

: '''''entity:''''' (<code>RPEntity</code>) Then entity whose path is being set.

: '''''table:''''' (<code>LuaTable</code>) Table with list of coordinates representing nodes.

: '''''loop:''''' (<code>boolean</code>) If <code>true</code>, the entity's path should loop.

; ''<span style="color:green">entities:setPathAndPosition</span>(entity, table, loop)'' <nowiki>

: '''''DEPRECATED:''' path can now be set by directly calling the NPC's <code>setPath</code> method''

: Helper function for setting an NPC's path & starting position.

: '''''entity:''''' (<code>RPEntity</code>) Then entity whose path is being set.

: '''''table:''''' (<code>LuaTable</code>) Table with list of coordinates representing nodes.

: '''''loop:''''' (<code>boolean</code>) If <code>true</code>, the entity's path should loop.

; ''<span style="color:green">entities:createSign</span>(visible)''

: Creates a new {{StendhalFile|master|src/games/stendhal/server/entity/sign/Sign.java|Sign}} entity.

: '''''visible:''''' (<code>boolean</code>) (optional) If <code>false</code>, the sign will not have a visual representation.

: ''returns:'' New <code>Sign</code> instance.

; ''<span style="color:green">entities:createShopSign</span>(name, title, caption, seller)''

: Creates a new {{StendhalFile|master|src/games/stendhal/server/entity/sign/ShopSign.java|ShopSign}} entity.

: '''''name:''''' (<code>String</code>) The shop name.

: '''''title:''''' (<code>String</code>) The sign title.

: '''''caption:''''' (<code>String</code>) The caption above the table.

: '''''seller:''''' (<code>boolean</code>) <code>true</code>, if this sign is for items sold by an NPC (defaults to <code>true</code> if <code>null</code>).

: ''returns:'' New <code>ShopSign</code> instance.

; ''<span style="color:green;">entities:summonCreature</span>(table)''

: Summons a creature into the area.

: '''''table:''''' Key-value table containing parameters for summoning creature.

:; ''keys:''

:: ''<span style="color:blue;">name:</span>'' (<code>string</code>) Name of creature to be summoned.

:: ''<span style="color:blue;">zone:</span>'' (<code>string</code>) Name of zone where creature should be summoned.

:: ''<span style="color:blue;">x:</span>'' (<code>int</code>) Horizontal position of summon location.

:: ''<span style="color:blue;">y:</span>'' (<code>int</code>) Vertical position of summon location.

:: ''<span style="color:blue;">summoner:</span>'' (<code>string</code>) (optional) Name of entity doing the summoning (used for logging game events).

:: ''<span style="color:blue;">raid:</span>'' (<code>bool</code>) (optional) Whether or not the creature should be a <code>RaidCreature</code> instance (default: true).

=== Lua Entity Classes ===

==== LuaSpeakerNPC ====

* Inherits: [[StendhalAPI#SpeakerNPC|SpeakerNPC]]

Public methods:

{{PublicMethod | add | params=states, triggers, conditions, nextState, reply, actions | desc=Additional method to support passing Lua data types as parameters. | paramlist=

{{MethodParam | states | desc=The conversation state(s) the entity should be in to trigger response. Can be [[StendhalAPI#ConversationStates|ConversationStates enum]] value or <code>LuaTable</code> of ConversationStates. }}

{{MethodParam | triggers | desc=<code>String</code> or <code>LuaTable</code> of strings to trigger response. }}

{{MethodParam | conditions | desc=Conditions to check for this response. Can be [[StendhalAPI#ChatCondition|ChatCondition instance]], a <code>LuaTable</code> of ChatCondition instances, or a function. }}

{{MethodParam | nextState | type=ConversationState | desc=Conversation state to set entity to after response. }}

{{MethodParam | reply | type=String | desc=The NPC's response or <code>null</code>. }}

{{MethodParam | actions | desc=Actions to execute. Can be [[StendhalAPI#ChatAction|ChatAction instance]], a <code>LuaTable</code> of ChatAction instances, or a function. }} }}

{{PublicMethod | setPath | params=table, loop | desc=Set a path for this entity to follow. | paramlist=

{{MethodParam | table | type=table | desc=Table of coordinates to set as path. Example: <code>{{35, 79}, {35, 89}, {40, 89}}</code> }}

{{MethodParam | loop | type=boolean | desc=(optional) If <code>true</code>, entity should loop around to restart path when reaching the end. }} }}

{{PublicMethod | setPathAndPosition | params=table, loop | desc=Set path & starting position for entity. The starting position is the first node in the path. | paramlist=

{{MethodParam | table | type=table | desc=Table of coordinates to set as path. Example: <code>{{35, 79}, {35, 89}, {40, 89}}</code> }}

{{MethodParam | loop | type=boolean | desc=(optional) If <code>true</code>, entity should loop around to restart path when reaching the end. }} }}

==== LuaSilentNPC ====

* Inherits: [[StendhalAPI#SilentNPC|SilentNPC]]

Public methods:

{{PublicMethod | setPath | params=table, loop | desc=Set a path for this entity to follow. | paramlist=

{{MethodParam | table | type=table | desc=Table of coordinates to set as path. Example: <code>{{35, 79}, {35, 89}, {40, 89}}</code> }}

{{MethodParam | loop | type=boolean | desc=(optional) If <code>true</code>, entity should loop around to restart path when reaching the end. }} }}

{{PublicMethod | setPathAndPosition | params=table, loop | desc=Set path & starting position for entity. The starting position is the first node in the path. | paramlist=

{{MethodParam | table | type=table | desc=Table of coordinates to set as path. Example: <code>{{35, 79}, {35, 89}, {40, 89}}</code> }}

{{MethodParam | loop | type=boolean | desc=(optional) If <code>true</code>, entity should loop around to restart path when reaching the end. }} }}

=== entities.manager ===

This is simply the {{StendhalFile|master|src/games/stendhal/server/core/rule/defaultruleset/DefaultEntityManager.java|entity manager}} instance.

Public methods:

'''''TODO'''''

; ''<span style="color:green">quests:create</span>(slotName, name)''

: Creates a new quest.

: '''''slotName:''''' (optional) The string identifier for the quest.

: '''''name:''''' (optional) The human-readable name that can be shown in travel log.

: ''returns:'' New {{StendhalFile|master|src/games/stendhal/server/core/scripting/lua/QuestHelper.java|games.stendhal.server.core.scripting.lua.QuestHelper.LuaQuest}} instance.

; ''<span style="color:green">quests:load</span>(quest)''

: Adds a quest to the world.

: '''''quest:''''' The {{StendhalFile|master|src/games/stendhal/server/maps/quests/IQuest.java|IQuest}} instance to be loaded.

; ''<span style="color:green">quests:unload</span>(questName)''

: Removes a quest from the world.

: '''''questName:''''' String name of the quest to be removed.

; ''<span style="color:green">quests:cache</span>(quest)''

: Caches a quest for loading at server startup.

: '''''quest:''''' {{StendhalFile|master|src/games/stendhal/server/maps/quests/IQuest.java|IQuest}} instance to be loaded.

:; ''aliases:''

:: ''<span style="color:green">quests:register</span>''

; ''<span style="color:green">quests:isLoaded</span>(quest)''

: Checks if a quest has been loaded.

: '''''quest:''''' {{StendhalFile|master|src/games/stendhal/server/maps/quests/IQuest.java|IQuest}} instance to check.

: ''returns:'' <code>true</code> if the instance matches stored quests.

; ''<span style="color:green">quests:listAll</span>(player)''

: List all quests the player knows about.

: '''''player:''''' Player to create the report for.

: ''returns:'' String report.

; ''<span style="color:green">quests:list</span>(player, questName)''

: Creates a report on a specified quest for a player.

: '''''player:''''' Player to create the report for.

: '''''questName:''''' Name of quest to be reported.

: ''returns:'' String report.

; ''<span style="color:green">quests:listStates</span>(player)''

: Dumps the internal quest states for the specified player. This is used for the {{StendhalFile|master|src/games/stendhal/server/action/admin/InspectAction.java|InspectAction}}.

: '''''player:''''' Player to create the report for.

: ''returns:'' String report.

; ''<span style="color:green">quests:getQuest</span>(questName)''

: Retrieves the {{StendhalFile|master|src/games/stendhal/server/maps/quests/IQuest.java|IQuest}} object for a named quest.

: '''''questName:''''' Name of quest.

: ''returns:'' <code>IQuest</code> or <code>null</code> if doesn't exist.

; ''<span style="color:green">quests:getQuestFromSlot</span>(questSlot)''

: Retrieves the {{StendhalFile|master|src/games/stendhal/server/maps/quests/IQuest.java|IQuest}} object for a quest.

: '''''questSlot:''''' Quest identifier string.

: ''returns:'' <code>IQuest</code> or <code>null</code> if doesn't exist.

; ''<span style="color:green">quests:getOpen</span>(player)''

: Retrieves a list of open quests from a player.

: '''''player:''''' {{StendhalFile|master|src/games/stendhal/server/entity/player/Player.java|Player}} instance to be checked.

: ''returns:'' List of string identifiers for open quests.

; ''<span style="color:green">quests:getCompleted</span>(player)''

: Retrieves a list of completed quests from a player.

: '''''player:''''' {{StendhalFile|master|src/games/stendhal/server/entity/player/Player.java|Player}} instance to be checked.

: ''returns:'' List of string identifiers for completed quests.

; ''<span style="color:green">quests:getIncomplete</span>(player, region)''

: Retrieves a list of incomplete quests in a specified region.

: '''''player:''''' {{StendhalFile|master|src/games/stendhal/server/entity/player/Player.java|Player}} instance to be checked.

: '''''region:''''' Region name/identifier.

: ''returns:'' List of string identifiers of incomplete quests in region.

; ''<span style="color:green">quests:getRepeatable</span>(player)''

: Retrieves a list of quests a player has completed, and can now do again.

: '''''player:''''' {{StendhalFile|master|src/games/stendhal/server/entity/player/Player.java|Player}} instance to be checked.

: ''returns:''

; ''<span style="color:green">quests:getDescription</span>(player, questName)''

: Retrieves the description of a quest.

: '''''player:''''' {{StendhalFile|master|src/games/stendhal/server/entity/player/Player.java|Player}} instance to be checked.

: '''''questName:''''' Name of the quest.

: ''returns:'' <code>String</code> description.

; ''<span style="color:green">quests:getLevelWarning</span>(player, questName)''

: If the quest is too dangerous, add a warning unless the player has already completed it.

: '''''player:''''' {{StendhalFile|master|src/games/stendhal/server/entity/player/Player.java|Player}} instance to be checked.

: '''''questName:''''' Name of the quest.

: ''returns:'' <code>String</code>

; ''<span style="color:green">quests:getProgressDetails</span>(player, questeName)''

: Retrieves details on the progress of the quest.

: '''''player:''''' {{StendhalFile|master|src/games/stendhal/server/entity/player/Player.java|Player}} instance to be checked.

: '''''questName:''''' Name of the quest.

: ''returns:'' <code>List<String></code>

; ''<span style="color:green">quests:getNPCNamesForUnstartedInRegionForLevel</span>(player, region)''

: Retrieves a list of the unique npc names for unstarted quests in a specified region.

: '''''player:''''' {{StendhalFile|master|src/games/stendhal/server/entity/player/Player.java|Player}} instance to be checked.

: '''''region:''''' Region to check in.

: ''returns:'' <code>List<String></code>

; ''<span style="color:green">quests:getDescriptionForUnstartedInRegionFromNPCName</span>(player, region, name)''

: Retrieves quest descriptions for unstarted quests in a specified region matching a specific NPC name.

: '''''player:''''' {{StendhalFile|master|src/games/stendhal/server/entity/player/Player.java|Player}} instance to be checked.

: '''''region:''''' Region to check in.

: '''''name:''''' Name of NPC.

: ''returns:'' <code>List<String></code>

; ''<span style="color:green">quests.simple:create</span></span>(slotName, properName, npcName)''

: '''''slotName:''''' <code>String</code> identifier to be used for quest.

: '''''properName:''''' Human-readable name to be displayed in travel log.

: '''''npcName:''''' The NPC associated with the quest.

: ''returns:'' {{StendhalFile|master|src/games/stendhal/server/maps/quests/SimpleQuestCreator.java|SimpleQuest}} instance.

{{StendhalFile|master|src/games/stendhal/server/maps/quests/SimpleQuestCreator.java|games.stendhal.server.maps.quests.SimpleQuestCreator.SimpleQuest}}

Methods:

; ''<span style="color:green">setDescription</span>(descr)''

:

: '''''descr:''''' (<code>String</code>)

; ''<span style="color:green">setRepeatable</span>(delay)''

:

: '''''delay:''''' (<code>Integer</code>)

; ''<span style="color:green">setItemToCollect</span>(itemName, quantity)''

:

: '''''itemName:''''' (<code>String</code>)

: '''''quantity:''''' (<code>int</code>)

; ''<span style="color:green">setXPReward</span>(xp)''

:

: '''''xp:''''' (<code>int</code>)

; ''<span style="color:green">setKarmaReward</span>(karma)''

:

: '''''karma:''''' (<code>double</code>)

; ''<span style="color:green">setKarmaAcceptReward</span>(karma)''

:

: '''''karma:''''' (<code>double</code>)

; ''<span style="color:green">setKarmaRejectReward</span>(karma)''

:

: '''''karma:''''' (<code>double</code>)

; ''<span style="color:green">addItemReward</span>(itemName, quantity)''

:

: '''''itemName:''''' (<code>String</code>)

: '''''quantity:''''' (<code>int</code>) (optional)

; ''<span style="color:green">addStatReward</span>(id, amount)''

:

: '''''id:''''' (<code>String</code>) See IDs below.

: '''''amount:''''' (<code>int</code>)

:; ''IDs:''

:: '''''xp:'''''

:: '''''def:'''''

:: '''''atk:'''''

:: '''''ratk:'''''

; ''<span style="color:green">setVerboseReward</span>(verbose)''

:

: '''''verbose:''''' (<code>boolean</code>)

; ''<span style="color:green">setReply</span>(id, reply)''

:

: '''''id:''''' (<code>String</code>) See IDs below.

: '''''reply:''''' (<code>String</code>)

:; ''IDs:''

:: '''''request:'''''

:: '''''accept:'''''

:: '''''reject:'''''

:: '''''reward:'''''

:: '''''verbose_reward_prefix:'''''

:: '''''already_active:'''''

:: '''''missing:'''''

:: '''''no_repeat:'''''

:: '''''cooldown_prefix:'''''

; ''<span style="color:green">setRegion</span>(regionName)''

:

: '''''regionName:''''' (<code>String</code>)

Also inherits methods from {{StendhalFile|master|src/games/stendhal/server/maps/quests/AbstractQuest.java|AbstractQuest}}:

: '''''condition:''''' Can be a <code>ChatCondition</code>, <code>LuaValue</code> containing a <code>ChatCondition</code> instance, a Lua table of <code>ChatCondition</code> instances, or a function.

Members:

; ''<span style="color:brown;">merchants.shops</span>''

: This is the {{StendhalFile|master|src/games/stendhal/server/entity/npc/ShopList.java|games.stendhal.server.entity.npc.ShopList}} instance.

: ''public methods: TODO''

: '''''prices:''''' List of items & their prices (can be instance of either Map<String, Integer> or a Lua table).

: '''''prices:''''' List of items & their prices (can be instance of either Map<String, Integer> or a Lua table).

: '''''prices:''''' List of items & their prices (can be instance of either Map<String, Integer> or a Lua table).

; ''<span style="color:green;">arrays:toTable</span>(list)''

: '''''list:''''' Java array or [https://docs.oracle.com/javase/8/docs/api/java/util/List.html list].

: ''returns:'' New Lua table with contents of <code>list</code> added.

Example usage:

<pre>

local npc = entities:createSpeakerNPC("foo")

npc:setCurrentState(ConversationStates.IDLE)

</pre>

Example usage:

<pre>

local npc = entities:createSpeakerNPC("foo")

npc:add(ConversationStates.IDLE,

ConversationPhrases.GREETING_MESSAGES,

nil,

ConversationStates.ATTENDING,

"Hello! How can I help you.",

nil)

</pre>

Example usage:

<pre>

local npc = entities:createSilentNPC()

npc:setCollisionAction(CollisionAction.STOP)

</pre>

Example usage:

<pre>

local npc = entities:createSpeakerNPC("foo")

npc:setOutfit("body=0,head=0,hair=3,dress=5")

npc:setOutfitColor("skin", SkinColor.DARK)

</pre>

Example usage:

<pre>

local npc = entities:createSpeakerNPC("foo")

npc:setDirection(Direction.DOWN)

</pre>

Example usage:

<pre>

local npc = entities:createSpeakerNPC("foo")

npc:setOutfit("body=0,head=0,hair=3,dress=5")

npc:setOutfitColor("dress", Color.BLUE)

</pre>

; ''<span style="color:green;">table.concat</span>(tbl1, tbl2)''

: Merges the contents of one table into another.

: '''''tbl1:''''' The table receiving the new content.

: '''''tbl2:''''' The table containing the content to be copied.

{{PublicMethod | table.contains | params=table, o | desc=Checks if a table contains a value. | paramlist=

{{MethodParam | table | type=table | desc=Table to be checked.}}

{{MethodParam | o | desc=The object to check for.}}

| ret=<code>true</code> if <code>o</code> is in <code>table</code>. | rettype=boolean }}

{{PublicMethod | table.join | params=table, delim | desc=Joins a table of strings into a string. | paramlist=

{{MethodParam | table | type=table | desc=Table to be joined.}}

{{MethodParam | delim | type=string | desc=Character(s) to be used as separator.}}

| ret=The resulting string. | rettype=string }}

[[Category:Stendhal]]

[[Category:Documentation]]

[[Category:API]]

[[Category:Scripting]]

[[Category:Lua]]