Introduction
this page is a work-in progress
Stendhal supports Lua scripting via the LuaJ library.
Lua scripts end in the .lua
extension & are stored in the data/script
directory.
Lua Basics
For more detailed information, see the Lua reference manual.
Comments
Lua uses double dashes (--
) for single line comments & double dashes followed by double square brackets ([[
) & closed with double square brackets (]]
) for multi-line comments:
-- a single line comment
--[[
a multi-line comment
]]
Variables
By default, Lua variables are set in global scope (meaning it is exposed to the entire Lua engine). To create a variable in local scope, the local
keyword must be used:
-- a global variable
var1 = "Hello world!"
-- a local variable
local var2 = "Hello world!"
Data Types
Some common data types in Lua are string, integer, boolean, & table. Type names do not need to be declared when setting variables.
Examples:
-- string variable
local var1 = "Hello world!"
-- integer variable
local var2 = 11
-- boolean variable
local var3 = true
-- table variable
local var4 = {}
Strings
String Concatenation
String concatenation is simple, much like Java uses a plus operator (+
) to join strings, Lua uses two periods (..
).
Example:
-- create a string variable
local var = "Hello"
-- append another string
var = var .. " world!"
print(var) -- prints "Hello world!"
Tables
A Lua table is a data type similar to a Java list or map. Tables can be indexed or use key=value pairs.
(IMPORTANT NOTE: Lua table indexes begin at 1, not 0)
Creating Tables
An empty table is initialized with a pair of curly braces ({}
):
local mytable = {}
You can add values to indexed tables at initialization or with the table.insert
method:
-- create a table with values
local mytable = {"foo"}
-- add value
table.insert(mytable, "bar")
To create a key=value table, any of the following methods can be used to add values:
-- all of these do the same thing, that is, assigning "bar" to mytable.foo
local mytable {
foo = "bar",
["foo"] = "bar",
}
mytable.foo = "bar"
mytable["foo"] = "bar"
Accessing Table Values
Square brackets ([]
) enclosing an index number are used to access values in indexed tables (remember that Lua table indexes start at "1" not "0"):
local mytable = {"foo", "bar"}
print(mytable[1]) -- prints "foo"
print(mytable[2]) -- prints "bar"
In a key=value table, values can be accessed by either enclosing the key string in square brackets or concatenating the key member using a .
:
local mytable = {foo="bar"}
-- using square brackets
print(mytable["foo"]) -- prints "bar"
-- using concatenated member
print(mytable.foo) -- prints "bar"
Iterating Tables
Tables can be iterated in a for
loop using the pairs
or ipairs
iterators. Loops are terminated with the end
keyword:
local mytable = {"foo", "bar"}
print("indexes:")
for idx in pairs(mytable) do
print(idx)
end
print("\nvalues:")
for idx, value in pairs(mytable) do
print(value)
end
Output:
indexes:
1
2
values:
foo
bar
Using a key=value table:
local mytable = {
["foo"] = "hello",
["bar"] = " world!",
}
print("keys:")
for key in pairs(mytable) do
print(key)
end
print("\nvalues:")
for key, value in pairs(mytable) do
print(value)
end
Output:
keys:
foo
bar
values:
hello
world!
See also: Lua Tables Tutorial
Functions
Like normal variables, functions can be declared as global or local & must be terminated with the end
keyword.
There are two ways to define functions with the function
keyword:
local function myFunction()
print("Hello world!")
end
or
local myFunction = function()
print("Hello world!")
end
Functions can also be members of a table:
local myTable = {}
function myTable.myFunction()
print("Hello world!")
end
or
local myTable = {}
myTable.myFunction = function()
print("Hello world!")
end
or
local myTable = {
myFunction = function()
print("Hello world!")
end,
}
-- execute with
myTable.myFunction()
Comparison Operators
Logical Operators
Operator | Description | Java Equivalent |
---|---|---|
and | logical and | && |
or | logical or | || |
not | logical inverse | ! |
Relational Operators
Operator | Description | Java Equivalent |
---|---|---|
< | less than | < |
> | greater than | > |
<= | less than or equal to | <= |
>= | greater than or equal to | >= |
== | equal to | == |
~= | not equal to | != |
Stendhal Application
Zones
Setting Zone
To set the zone to work with, use the game
object:
game:setZone("0_semos_city")
Create New Zone
It is recommended to create new zones in the XML configurations in data/conf/zones.
Currently creating new zones via Lua is not supported.
Add Zone Music
Music can be added to zones with the game:setMusic
function. It supports the following arguments:
* filename: Basename of the OGG audio file to use stored in data/music.
* args: A table of key=value integers.
* Valid keys:
* volume: Volume level (default: 100).
* x: The horizontal point for the source of the music (default: 1).
* y: The vertical point for the source of the music (default: 1).
* radius: The radial range at which the music can be heard (default: 10000).
Example:
if game:setZone("0_semos_plains_n") then
game:setMusic("pleasant_creek_loop", {volume=85, radius=100})
end
Adding Entities
Signs
Signs can be created with entities:createSign
and entities:createShopSign
:
local zone = "0_semos_city"
if game:setZone(zone) then
-- create the sign instance
local sign = entities:createSign()
sign:setEntityClass("signpost")
sign:setPosition(12, 55)
sign:setText("Meet Lua!")
-- Add it to the world
game:add(sign)
else
logger:error("Could not set zone: " .. zone)
end
NPCs
Use the entities:createSpeakerNPC
method to create an interactive NPC:
local zone = "0_semos_city"
if game:setZone(zone) then
-- Use helper object to create a new NPC
local npc = entities:createSpeakerNPC("Lua")
npc:setEntityClass("littlegirlnpc")
npc:setPosition(10, 55)
npc:setBaseSpeed(0.1)
npc:setCollisionAction(CollisionAction.STOP)
local nodes = {
{10, 55},
{11, 55},
{11, 56},
{10, 56},
}
npc:setPath(nodes)
-- Dialogue
npc:addJob("Actually, I am jobless.")
npc:addGoodbye();
-- Add to the world
game:add(npc)
else
logger:error("Could not set zone: " .. zone)
end
Adding Transitions
A simple example of adding a chat transition can be done without any special functionality:
local frank = entities:createSpeakerNPC("Frank")
frank:add(ConversationStates.IDLE,
ConversationPhrases.GREETING_MESSAGES,
nil,
ConversationStates.ATTENDING,
"Hello.",
nil)
This simply adds a response to saying "hello" & sets the NPC to attend to the player (equivalent of frank:addGreeting("Hello")
).
For more complicated behavior, we need to use some helper methods. If we want to check a condition we use the conditions:create
method. The first parameter is the string name of the ChatCondition we want to instantiate. The second parameter is a table that contains the values that should be passed to the ChatCondition constructor.
Example:
frank:add(ConversationStates.IDLE,
ConversationPhrases.GREETING_MESSAGES,
conditions:create("PlayerHasItemWithHimCondition", {"money"}),
ConversationStates.ATTENDING,
"Hello.",
nil)
In this scenario, the NPC will only respond if the player is carrying money.
A NotCondition instance can be created with the actions:notCondition
method:
Example usage:
local condition = conditions.notCondition(conditions:create("PlayerHasItemWithHimCondition", {"money"})
To add a ChatAction, we use the actions:create
method. Its usage is identical to conditions:create
.
Example:
frank:add(ConversationStates.IDLE,
ConversationPhrases.GREETING_MESSAGES,
conditions:create("PlayerHasItemWithHimCondition", {"money"}),
ConversationStates.ATTENDING,
"Hello.",
actions:create("NPCEmoteAction", {"looks greedily at your pouch of money.", false}))
Lua tables can be used to add multiple conditions or actions:
frank:add(ConversationStates.IDLE,
ConversationPhrases.GREETING_MESSAGES,
{
conditions:create("PlayerHasItemWithHimCondition", {"money"}),
conditions:notCondition(conditions:create("NakedCondition")),
},
ConversationStates.ATTENDING,
nil,
{
actions:create("SayTextAction", {"Hello."}),
actions:create("NPCEmoteAction", {"looks greedily at your pouch of money.", false}),
})
In this scenario, the NPC will respond if the player has money & is not naked.
Nested tables are supported as well:
local conditions = {
conditions:create("PlayerHasItemWithHimCondition", {"money"}),
{
conditions:notCondition(conditions:create("NakedCondition")),
},
}
frank:add(ConversationStates.IDLE,
ConversationPhrases.GREETING_MESSAGES,
conditions,
ConversationStates.ATTENDING,
nil,
{
actions:create("SayTextAction", {"Hello."}),
actions:create("NPCEmoteAction", {"looks greedily at your pouch of money.", false}),
})
Adding Merchant Behavior
The merchants
object is used for adding merchant behavior (buying/selling) to an NPC.
Example of adding seller behavior to an NPC:
if game:setZone("0_semos_city") then
local frank = entities.createSpeakerNPC("Frank")
merchants:addSeller(frank, merchants.shops:get("shopname"), true)
game:add(frank)
end
To create a custom shop list, you can use a Lua table (there are multiple ways to add elements to a Lua table):
Method 1:
local priceList = {
meat = 50,
["ham"] = 70,
}
Method 2:
local priceList = {}
priceList.meat = 50
priceList["ham"] = 70
The helper methods have special handling for underscore characters as well (the following are all the same):
local priceList = {
smoked_ham = 100,
["smoked ham"] = 100,
}
priceList.smoked_ham = 100
priceList["smoked ham"] = 100
Then add the seller behavior using the custom list:
merchants:addSeller(frank, priceList, true)
System Properties
Java's system properties are exposed to Lua with the properties
object.
Examples:
-- property state
if properties:enabled("stendhal.testserver") then
print("Test server enabled")
if properties:equals("stendhal.testserver", "junk") then
print("Junk enabled")
else
print("Junk disabled")
end
else
print("Test server disabled")
end
-- property value
local prop = properties:getValue("stendhal.testserver")
if prop ~= nil then
print("Test server enabled")
if prop == "junk" then
print("Junk enabled")
else
print("Junk disabled")
end
else
print("Test server disabled")
end
Misc
Typecasting
Lua does not support typecasting (as far as I know), but if the class you want to cast to has a copy constructor, achieving the same functionality is quite simple.
-- "entities:getItem" returns an instance of Item
local bestiary = entities:getItem("bestiary")
-- in order to use the bestiary's "setOwner" method, we must convert it to an "OwnedItem" instance by calling its copy constructor
bestiary = luajava.newInstance("games.stendhal.server.entity.item.OwnedItem", bestiary)
bestiary:setOwner("Ted")