StendhalScripting/LuaAPI

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.

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

Methods:

• entities:getPlayer(name)
• entities:getNPC(name)
• entities:getItem(name)
• entities:getStackableItem(name)
• entities:createSpeakerNPC(name)
• entities:createSilentNPC()
• entities:setPath(entity, table, loop)
• entities:setPathAndPosition(entity, table, loop)
• entities:createSign(visible)
• entities:createShopSign(name, title, caption, seller)

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: games.stendhal.server.maps.quests.SimpleQuestCreator.SimpleQuest instance.

SimpleQuest Object

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 at ChatCondition instance, or a Lua table of ChatCondition instances.

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.

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.

ConversationPhrases

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

CollisionAction

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

SkinColor

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

Direction

The games.stendhal.common.Direction enum.

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.

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.clean(tbl)

Removes nil values from a table.

tbl: The table to be cleaned.

returns: Copy of tbl with nil values removed.

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.

See Also

• Lua: Basics
• Lua: Stendhal Application