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:createQuest(slotName, name)
• quests:load(quest)
• quests:unload(questName)
• quests:cache(quest)
• quests:register(quest) Alias for quests:cache(quest).
• quests:isLoaded(quest)
• quests:listAll(player)
• quests:list(player, questName)
• quests:listStates(player)
• quests:getQuest()
• quests:getQuestFromSlot(questSlot)
• quests:getOpen(player)
• quests:getCompleted(player)
• quests:getIncomplete(player, region)
• quests:getRepeatable(player)
• quests:getDescription(player, questName)
• quests:getLevelWarning(player, questeName)
• quests:getProgressDetails(player, questeName)
• quests:getNPCNamesForUnstartedInRegionForLevel(player, region)
• quests:getDescriptionForUnstartedInRegionFromNPCName(player, region, name)

quests.simple

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

Methods:

• quests.simple:create(slotName, properName, npcName)
  • slotName: (string)
  • properName: (string)
  • npcName: (string)
  • 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, Int> 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, Int> 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, Int> 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