StendhalScripting/LuaAPI

From Arianne
Jump to navigation Jump to search


The following objects & functions are exposed to the Lua engine:

Objects

luajava

This is an object of the LuajavaLib library. It can be used to coerce Java static objects to Lua or create new Java object instances.

Example of exposing a static object & enums to Lua: 

-- store a Java enum in a Lua global variable
ConversationStates = luajava.bindClass("games.stendhal.server.entity.npc.ConversationStates")

-- access the enum values like so
ConversationStates.IDLE

Example of creating an object instance: 

-- store instance in local variable
local dog = luajava.newInstance("games.stendhal.server.entity.npc.SilentNPC")
-- access object methods like so
dog:setEntityClass("animal/puppy")
dog:setPosition(2, 5)

-- class with constructor using parameters
local speaker = luajava.newInstance("games.stendhal.server.entity.npc.SpeakerNPC", "Frank")
speaker:setOutfit("body=0,head=0,eyes=0,hair=5,dress=5")
speaker:setPosition(2, 6)

To make scripting easier, Stendhal employs a master script & some helper objects & methods to handle the functionality mentioned above. An explanation of these objects & methods follows.

logger

Manages logging in Lua via the org.apache.log4j.Logger class.

Methods:

logger:info(message)
Prints an information level message to the console.
message: Text to be printed.
logger:warn(message)
Prints a warning level message to the console.
message: Text to be printed.
logger:error(message)
Prints an error level message to the console.
message: Text to be printed.

Example usage: 

local zone = "0_semos_city"
if game:setZone(zone) then
	-- do something
else
	logger:error("Could not set zone: " .. zone)
end

properties

Defines functions for accessing Java system properties.

Methods:

properties:getValue(p)
Retrieves the value of a property.
p: (string) Property name.
returns: (string) Property value or `nil`.
properties:enabled(p)
Checks if a property is enabed.
p: (string) Property name.
returns: (boolean) `true` if enabled.
properties:equals(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: 

-- example of only executing script contents on test server

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

game

The main object that handles setting zone & adding entities to game.

Methods:

game:add(object)
Adds an RPObject instance to the current zone.
object: Object to add.
game:add(npc)
Adds an NPC instance to the current zone.
npc: NPC to add.
game:add(creature, x, y)
Adds a Creature instance to the current zone.
creature: Creature to add.
x: Horizontal position of where to add creature.
y: Vertical position of where to add creature.
game:remove(object)
object:
game:remove(npc)
npc:
game:addGameEvent(source, event, params)
Adds a new GameEvent.
source:
event:
params:
game:setZone(name)
Sets the current zone.
name: String identifier for zone to be set as current zone.
returns: true if zone was successfully set.
game:setZone(zone)
Sets the current zone.
zone: StendhalRPZone instance to set as current zone.
returns: true if zone was successfully set.
game:getZone(object)
Retrieves the zone where object is located.
object: The RPObject from which the zone should be retrieved.
returns: StendhalRPZone or null if it doesn't exists
game:getZone(name)
Retrieves a zone by string ID.
zoneName: Name of zone to retrieve.
returns: StendhalRPZone or null if it doesn't exist.
game:setMusic(filename, args)
Sets the music for the currently selected zone.
filename:
File basename excluding .ogg extension.
args:
Lua table of key=value integer values.
Valid keys:
volume: Volume level (default: 100).
x: The X coordinate of the sound source (default: 1).
y: The Y coordinate of the sound source (default: 1).
radius: The radius from which the music can be heard (default: 10000).
game:playerIsInZone(player, zoneName)
player:
zoneName:
returns: boolean
game:getCreatures()
returns: An array of all available creatures.
game:getCreature(clazz)
Retrieves a Creature instance.
clazz: String name of the creature.
returns: Creature or null if doesn't exist.
game:getItems()
returns: Array list of available items.
game:getItem(name)
name:
returns: Item instance or null if doesn't exist.
game:modify(entity)
entity:
game:privateText(player, text)
Sends a private text to a player.
player: Player to receive the message.
text: Message text to send to player.
game:getMessage()
returns: String

entities

See also: StendhalAPI#Entities for public methods that can be performed on Entity objects.

Methods:

entities:getPlayer(name)
Retrieves a logged in Player.
name: (String) Name of player.
returns: Logged in Player or null.
entities:getNPC(name)
Retrieves an existing SpeakerNPC.
name: (String) Name of NPC.
returns: SpeakerNPC instance or null.
entities:getItem(name)
Retrieves a registered Item.
name: (String) Name of the item.
returns: Item instance or null if not a registered item.
entities:getStackableItem(name)
Retrieves a registered StackableItem.
name: (String) Name of the item.
returns: StackableItem instance or null if not a registered stackable item.
entities:createSpeakerNPC(name)
Creates an interactive NPC.
name: (String) Name of new NPC.
returns: New SpeakerNPC instance.
entities:createSilentNPC()
Creates a non-interactive NPC.
returns: New SilentNPC instance.
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.
entity: (RPEntity) Then entity whose path is being set.
table: (LuaTable) Table with list of coordinates representing nodes.
loop: (boolean) If true, the entity's path should loop.
entities:setPathAndPosition(entity, table, loop) <nowiki>
DEPRECATED: path can now be set by directly calling the NPC's setPath method
Helper function for setting an NPC's path & starting position.
entity: (RPEntity) Then entity whose path is being set.
table: (LuaTable) Table with list of coordinates representing nodes.
loop: (boolean) If true, the entity's path should loop.
entities:createSign(visible)
Creates a new Sign entity.
visible: (boolean) (optional) If false, the sign will not have a visual representation.
returns: New Sign instance.
entities:createShopSign(name, title, caption, seller)
Creates a new ShopSign entity.
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 (defaults to true if null).
returns: New ShopSign instance.
entities:summonCreature(table)
Summons a creature into the area.
table: Key-value table containing parameters for summoning creature.
keys:
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) (optional) Name of entity doing the summoning (used for logging game events).
raid: (bool) (optional) Whether or not the creature should be a RaidCreature instance (default: true).

Lua Entity Classes

LuaSpeakerNPC

Public methods:

add (states, triggers, conditions, nextState, reply, actions)
Additional method to support passing Lua data types as parameters.
states : The conversation state(s) the entity should be in to trigger response. Can be ConversationStates enum value or LuaTable of ConversationStates.
triggers : String or LuaTable of strings to trigger response.
conditions : Conditions to check for this response. Can be ChatCondition instance, a LuaTable of ChatCondition instances, or a function.
nextState : (ConversationState) Conversation state to set entity to after response.
reply : (String) The NPC's response or null.
actions : Actions to execute. Can be ChatAction instance, a LuaTable of ChatAction instances, or a function.
setPath (table, loop)
Set a path for this entity to follow.
table : (table) Table of coordinates to set as path. Example: {{35, 79}, {35, 89}, {40, 89}}
loop : (boolean) (optional) If true, entity should loop around to restart path when reaching the end.
setPathAndPosition (table, loop)
Set path & starting position for entity. The starting position is the first node in the path.
table : (table) Table of coordinates to set as path. Example: {{35, 79}, {35, 89}, {40, 89}}
loop : (boolean) (optional) If true, entity should loop around to restart path when reaching the end.

LuaSilentNPC

Public methods:

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

entities.manager

This is simply the entity manager instance.

Public methods:

TODO

quests

Adds helper functions for creating & manipulating quests & exposes select public methods of the games.stendhal.server.core.rp.StendhalQuestSystem class.

Methods:

quests:create(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 games.stendhal.server.core.scripting.lua.QuestHelper.LuaQuest instance.
quests:load(quest)
Adds a quest to the world.
quest: The IQuest instance to be loaded.
quests:unload(questName)
Removes a quest from the world.
questName: String name of the quest to be removed.
quests:cache(quest)
Caches a quest for loading at server startup.
quest: IQuest instance to be loaded.
aliases:
quests:register
quests:isLoaded(quest)
Checks if a quest has been loaded.
quest: IQuest instance to check.
returns: true if the instance matches stored quests.
quests:listAll(player)
List all quests the player knows about.
player: Player to create the report for.
returns: String report.
quests:list(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.
quests:listStates(player)
Dumps the internal quest states for the specified player. This is used for the InspectAction.
player: Player to create the report for.
returns: String report.
quests:getQuest(questName)
Retrieves the IQuest object for a named quest.
questName: Name of quest.
returns: IQuest or null if doesn't exist.
quests:getQuestFromSlot(questSlot)
Retrieves the IQuest object for a quest.
questSlot: Quest identifier string.
returns: IQuest or null if doesn't exist.
quests:getOpen(player)
Retrieves a list of open quests from a player.
player: Player instance to be checked.
returns: List of string identifiers for open quests.
quests:getCompleted(player)
Retrieves a list of completed quests from a player.
player: Player instance to be checked.
returns: List of string identifiers for completed quests.
quests:getIncomplete(player, region)
Retrieves a list of incomplete quests in a specified region.
player: Player instance to be checked.
region: Region name/identifier.
returns: List of string identifiers of incomplete quests in region.
quests:getRepeatable(player)
Retrieves a list of quests a player has completed, and can now do again.
player: Player instance to be checked.
returns:
quests:getDescription(player, questName)
Retrieves the description of a quest.
player: Player instance to be checked.
questName: Name of the quest.
returns: String description.
quests:getLevelWarning(player, questName)
If the quest is too dangerous, add a warning unless the player has already completed it.
player: Player instance to be checked.
questName: Name of the quest.
returns: String
quests:getProgressDetails(player, questeName)
Retrieves details on the progress of the quest.
player: Player instance to be checked.
questName: Name of the quest.
returns: List<String>
quests:getNPCNamesForUnstartedInRegionForLevel(player, region)
Retrieves a list of the unique npc names for unstarted quests in a specified region.
player: Player instance to be checked.
region: Region to check in.
returns: List<String>
quests:getDescriptionForUnstartedInRegionFromNPCName(player, region, name)
Retrieves quest descriptions for unstarted quests in a specified region matching a specific NPC name.
player: Player instance to be checked.
region: Region to check in.
name: Name of NPC.
returns: List<String>

quests.simple

A special class for creating a simple collect single item quest.

Methods:

quests.simple:create(slotName, properName, npcName)
slotName: String identifier to be used for quest.
properName: Human-readable name to be displayed in travel log.
npcName: The NPC associated with the quest.
returns: SimpleQuest instance.

SimpleQuest Object

games.stendhal.server.maps.quests.SimpleQuestCreator.SimpleQuest

Methods:

setDescription(descr)
descr: (String)
setRepeatable(delay)
delay: (Integer)
setItemToCollect(itemName, quantity)
itemName: (String)
quantity: (int)
setXPReward(xp)
xp: (int)
setKarmaReward(karma)
karma: (double)
setKarmaAcceptReward(karma)
karma: (double)
setKarmaRejectReward(karma)
karma: (double)
addItemReward(itemName, quantity)
itemName: (String)
quantity: (int) (optional)
addStatReward(id, amount)
id: (String) See IDs below.
amount: (int)
IDs:
xp:
def:
atk:
ratk:
setVerboseReward(verbose)
verbose: (boolean)
setReply(id, reply)
id: (String) See IDs below.
reply: (String)
IDs:
request:
accept:
reject:
reward:
verbose_reward_prefix:
already_active:
missing:
no_repeat:
cooldown_prefix:
setRegion(regionName)
regionName: (String)

Also inherits methods from AbstractQuest:

Example: 

-- create SimpleQuest instance
local quest = simpleQuest:create("wood_for_lua", "Wood for Lua", "Lua")

quest:setDescription("Lua needs help gathering wood.")
quest:setRequestReply("I need help gathering some wood. Will you help me?")
quest:setAcceptReply("Great!")
quest:setRewardReply("Thank a bunch!")
quest:setRejectReply("Fine! I don't need your help anyway.")
quest:setItemToCollect("wood", 5)
quest:setRepeatable(true)
quest:setRepeatDelay(10)
quest:setXPReward(50)
quest:setKarmaReward(5.0)
quest:addItemReward("rose", 3)
quest:addItemReward("money", 100)
quest:setRegion(Region.SEMOS_CITY)

quests:register(quest)

conditions

Object for creating games.stendhal.server.entity.npc.ChatCondition instances.

Methods:

conditions:create(function)
Creates a custom ChatCondition.
function: Lua function to be invoked when ChatCondition.fire is called.
returns: New ChatCondition instance.
conditions:notCondition(condition)
Creates a NotCondition.
condition: Can be a ChatCondition, LuaValue containing a ChatCondition instance, a Lua table of ChatCondition instances, or a function.
returns: New NotCondition instance.
conditions:andCondition(conditionList)
Creates an AndCondition.
conditionList: Lua table containing ChatCondition instances.
returns: New AndCondition instance.

actions

Object for creating games.stendhal.server.entity.npc.ChatAction instances.

Methods:

actions:create(function)
Creates a custom ChatAction.
function: A Lua function to be executed when ChatAction.fire is called.
returns: New ChatAction instance.
actions:multiple(actionList)
Helper method for creating a MultipleActions instance.
actionList: A Lua table containing ChatAction instances.
returns: New MultipleActions instance.

merchants

Exposes merchant handling classes & functions to Lua.

Members:

merchants.shops
This is the games.stendhal.server.entity.npc.ShopList instance.
public methods: TODO

Methods:

merchants:add(merchantType, npc, prices, addOffer)
Adds merchant behavior to a SpeakerNPC.
merchantType: If set to "buyer", will add buyer behavior, otherwise will be "seller".
npc: The SpeakerNPC to add the behavior to.
prices: List of items & their prices (can be instance of either Map<String, Integer> or a Lua table).
addOffer: If true, will add default replies for "offer" (default: true).
merchants:addSeller(npc, prices, addOffer)
Adds seller behavior to a SpeakerNPC.
npc: The SpeakerNPC to add the behavior to.
prices: List of items & their prices (can be instance of either Map<String, Integer> or a Lua table).
addOffer: If true, will add default replies for "offer" (default: true).
merchants:addBuyer(npc, prices, addOffer)
Adds buyer behavior to a SpeakerNPC.
npc: The SpeakerNPC to add the behavior to.
prices: List of items & their prices (can be instance of either Map<String, Integer> or a Lua table).
addOffer: If true, will add default replies for "offer" (default: true).

arrays

Handles some conversion of Java arrays & lists to Lua tables.

Methods:

arrays:toTable(list)
Converts a Java array or list to a Lua table.
list: Java array or list.
returns: New Lua table with contents of list added.

grammar

Exposes the games.stendhal.common.grammar.Grammar parser instance to Lua.

Static Classes & Enumerations

ConversationStates

The games.stendhal.server.entity.npc.ConversationStates enum.

Example usage: 

local npc = entities:createSpeakerNPC("foo")
npc:setCurrentState(ConversationStates.IDLE)

ConversationPhrases

The games.stendhal.server.entity.npc.ConversationPhrases class.

Example usage: 

local npc = entities:createSpeakerNPC("foo")
npc:add(ConversationStates.IDLE,
	ConversationPhrases.GREETING_MESSAGES,
	nil,
	ConversationStates.ATTENDING,
	"Hello! How can I help you.",
	nil)

CollisionAction

The games.stendhal.server.entity.CollisionAction enum.

Example usage: 

local npc = entities:createSilentNPC()
npc:setCollisionAction(CollisionAction.STOP)

SkinColor

The games.stendhal.common.constants.SkinColor enum.

Example usage: 

local npc = entities:createSpeakerNPC("foo")
npc:setOutfit("body=0,head=0,hair=3,dress=5")
npc:setOutfitColor("skin", SkinColor.DARK)

Direction

The games.stendhal.common.Direction enum.

Example usage: 

local npc = entities:createSpeakerNPC("foo")
npc:setDirection(Direction.DOWN)

DaylightPhase

The games.stendhal.server.core.rp.DaylightPhase enum.

Region

The games.stendhal.server.maps.Region class.

MathHelper

The games.stendhal.common.MathHelper class.

Color

The java.awt.Color class.

Example usage: 

local npc = entities:createSpeakerNPC("foo")
npc:setOutfit("body=0,head=0,hair=3,dress=5")
npc:setOutfitColor("dress", Color.BLUE)

Supplemental Methods

A few convenience methods are added to make scripting easier.

String Manipulation

The following methods have been added to the built-in Lua string library.

string.startsWith(st, prefix)
Checks if a string begins with a set of characters.
st: The string to be checked.
prefix: The prefix to be compared with.
returns: true if prefix matches the beginning characters of st.
aliases:
string.beginsWith
string.endsWith(st, suffix)
Checks if a string ends with a set of characters.
st: The string to be checked.
suffix: The suffix to be compared with.
returns: true if suffix matches then end characters of st.
string.isNumber(st)
Checks if a string contains numeric characters only.
st: The string to be checked.
returns: true if all characters are numeric, false otherwise.
aliases:
string.isNumeric
string.trim(st)
Removes leading & trailing whitespace from a string.
st: The string to be trimmed.
returns: Trimmed string.
string.ltrim(st)
Removes leading whitespace from a string.
st: The string to be trimmed.
returns: Trimmed string.
string.rtrim(st)
Removes trailing whitespace from a string.
st: The string to be trimmed.
returns: Trimmed string.
string.builder(st)
Creates a new instance of java.lang.StringBuilder.
st: (optional) String to append on instantiation.
returns: new StringBuilder instance.

Table Manipulation

The following methods have been added to the built-in Lua table library.

table.concat(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.
table.contains (table, o)
Checks if a table contains a value.
table : (table) Table to be checked.
o : The object to check for.
returns: (boolean) true if o is in table.
table.clean(tbl)
Removes nil values from a table.
tbl: The table to be cleaned.
returns: Copy of tbl with nil values removed.
table.join (table, delim)
Joins a table of strings into a string.
table : (table) Table to be joined.
delim : (string) Character(s) to be used as separator.
returns: (string) The resulting string.

See Also

Retrieved from "https://stendhalgame.org/w/index.php?title=StendhalScripting/LuaAPI&oldid=26554"