StendhalScripting/Lua: Difference between revisions

By default, Lua variables are set in [https://en.wikipedia.org/wiki/Global_variable '''global''' scope] (meaning it is exposed to the entire Lua engine). To create a variable in [https://en.wikipedia.org/wiki/Local_variable '''local''' scope], the <code>local</code> keyword must be used:

</pre>

== 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:

<pre>

-- string variable

local var1 = "Hello world!"

-- integer variable

local var2 = 11

-- boolean variable

local var3 = true

-- table variable

local var4 = {}

</pre>

=== Strings ===

==== String Concatenation ====

String concatenation is simple, much like Java uses a plus operator (<code>+</code>) to join strings, Lua uses two periods (<code>..</code>).

Example:

<pre>

-- create a string variable

local var = "Hello"

-- append another string

var = var .. " world!"

print(var) -- prints "Hello world!"

A Lua table is a data type similar to a Java list or map. Tables can be indexed or use key=value pairs.

==== Creating Tables ====

local mytable = {"foo"}

-- all of these do the same thing, that is, assigning "bar" to mytable.foo

</pre>

==== Accessing Table Values ====

Square brackets (<code>[]</code>) enclosing an index number are used to access values in indexed tables (''remember that Lua table indexes start at "1" not "0"''):

<pre>

local mytable = {"foo", "bar"}

print(mytable[1]) -- prints "foo"

print(mytable[2]) -- prints "bar"

</pre>

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 <code>.</code>:

<pre>

local mytable = {foo="bar"}

-- using square brackets

print(mytable["foo"]) -- prints "bar"

-- using concatenated member

print(mytable.foo) -- prints "bar"

Tables can be iterated in a <code>for</code> loop using the <code>pairs</code> or <code>ipairs</code> iterators. Loops are terminated with the <code>end</code> keyword:

local mytable = {"foo", "bar"}

There are two ways to define functions with the <code>function</code> keyword:

Functions can also be members of a table:

== Comparison Operators ==

{| class="wikitable"

|+ Logical Operators

! Operator !! Description !! Java Equivalent

|-

| and || logical ''and'' || &&

|-

| or || logical ''or'' || <nowiki>||</nowiki>

|-

| not || logical ''opposite'' || !

|}

{| class="wikitable"

|+ 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 <code>game</code> object:

game:setZone("0_semos_city")

=== Create New Zone ===

It is recommended to create new zones in the XML configurations in {{StendhalFile|master|data/conf/zones|data/conf/zones}}.

Currently creating new zones via Lua is not supported.

=== Add Zone Music ===

Music can be added to zones with the <code>game:setMusic</code> function. It supports the following arguments:

* <span style="color:darkgreen; font-style:italic;>filename:</span> Basename of the OGG audio file to use stored in {{StendhalFile|master|data/music|data/music}}.

* <span style="color:darkgreen; font-style:italic;>args:</span> A table of key=value integers.

* Valid keys:

** <span style="color:darkblue; font-style:italic;">volume:</span> Volume level (default: 100).

** <span style="color:darkblue; font-style:italic;">x:</span> The horizontal point for the source of the music (default: 1).

** <span style="color:darkblue; font-style:italic;">y:</span> The vertical point for the source of the music (default: 1).

** <span style="color:darkblue; font-style:italic;">radius:</span> 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})

Signs can be created with <code>entities:createSign</code> and <code>entities:createShopSign</code>:

local sign = entities:createSign()

Use the <code>entities:createSpeakerNPC</code> method to create an interactive NPC:

local npc = entities:createSpeakerNPC("Lua")

npc:setPath(nodes)

</pre>

==== Adding Transitions ====

A simple example of adding a chat transition can be done without any special functionality:

<pre>

local frank = entities:createSpeakerNPC("Frank")

frank:add(ConversationStates.IDLE,

ConversationPhrases.GREETING_MESSAGES,

nil,

ConversationStates.ATTENDING,

"Hello.",

nil)

</pre>

This simply adds a response to saying "hello" & sets the NPC to attend to the player (equivalent of <code>frank:addGreeting("Hello")</code>).

For more complicated behavior, we need to use some helper methods. If we want to check a condition we use the <code>conditions:create</code> 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:

<pre>

frank:add(ConversationStates.IDLE,

ConversationPhrases.GREETING_MESSAGES,

conditions:create("PlayerHasItemWithHimCondition", {"money"}),

ConversationStates.ATTENDING,

"Hello.",

nil)

</pre>

In this scenario, the NPC will only respond if the player is carrying <item>money</item>.

A NotCondition instance can be created with the <code>actions:notCondition</code> method:

Example usage:

<pre>

local condition = conditions.notCondition(conditions:create("PlayerHasItemWithHimCondition", {"money"})

</pre>

To add a ChatAction, we use the <code>actions:create</code> method. Its usage is identical to <code>conditions:create</code>.

Example:

<pre>

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}))

</pre>

Lua tables can be used to add multiple conditions or actions:

<pre>

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}),

})

</pre>

In this scenario, the NPC will respond if the player has money & is not naked.

Nested tables are supported as well:

<pre>

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}),

})

The <code>merchants</code> object is used for adding merchant behavior (buying/selling) to an NPC.

local frank = entities.createSpeakerNPC("Frank")

merchants:addSeller(frank, merchants.shops:get("shopname"), true)

merchants:addSeller(frank, priceList, true)

== System Properties ==

Java's system properties are exposed to Lua with the <code>properties</code> object.

Examples:

<pre>

-- 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

</pre>

== 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.

<pre>

-- "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")

</pre>

= See Also =

* [[StendhalScripting/LuaAPI|Lua API]]

[[Category:Stendhal]]

[[Category:Documentation]]

[[Category:API]]

[[Category:Scripting]]

[[Category:Lua]]