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(npc)
• game:add(object) - Adds an object to the current zone.
• game:add(creature, x, y)
• game:remove(npc)
• game:remove(object)
• game:addGameEvent(source, event, params)
• game:setZone(name) - Sets the current zone.
• game:setZone(zone)
• game:getZone(rpobject)
• game:playerIsInZone(player, zoneName)
• game:getCreatures()
• game:getCreature(clazz)
• game:getItems()
• game:getItem(name)
• game:modify(entity)
• game:privateText(player, text)
• game:getMessage()
• game:setMessage(message)

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)
• conditions.not(condition)
• conditions.not(value)
• conditions.and(conditionList)

actions

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

Methods:

• actions.create(function)
  • function: A Lua function to be executed when ChatAction.fire is called.
• actions.multiple(actionList)
  • actionList: A Lua table containing ChatAction instances.

merchants

Exposes merchant handling classes & functions to Lua.

Methods:

• merchants.add(merchantType, npc, prices, addOffer)
• merchants.addSeller(npc, prices, addOffer)
• merchants.addBuyer(npc, prices, addOffer)

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.

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.