StendhalScripting/Lua: Difference between revisions

<span style="color: red; font-style: italic;">this page is a work-in progress</span>

Stendhal supports [https://www.lua.org/ Lua scripting] via the [https://sourceforge.net/projects/luaj/ LuaJ library].

Lua scripts end in the <code>.lua</code> extension & are stored in the <code>data/script</code> directory.

== Objects and Functions ==

The following objects & functions are exposed to the Lua engine:

=== game ===

The main object that handles setting zone & adding entities to game.

Methods:

* <code>game:add(object)</code> - Adds an object to the current zone.

* <code>game:setZone(name)</code> - Sets the current zone.

* <code>game:createSign(visible)</code> - Creates a new {{StendhalFile|master|src/games/stendhal/server/entity/mapstuff/sign/Sign.java|Sign}} instance.

* <code>game:createShopSign(name, title, caption, seller)</code> - Creates a new {{StendhalFile|master|src/games/stendhal/server/entity/mapstuff/sign/ShopSign.java|ShopSign}} instance.

=== npcHelper ===

This object helps to create instances of {{StendhalFile|master|src/games/stendhal/server/entity/npc/SpeakerNPC.java|SpeakerNPC}} & {{StendhalFile|master|src/games/stendhal/server/entity/npc/SilentNPC.java|SilentNPC}} classes.

Methods:

* <code>npcHelper:createSpeakerNPC(name)</code> - Creates a new SpeakerNPC.

* <code>npcHelper:createSilentNPC()</code> - Creates a new SilentNPC.

* <code>npcHelper:setPath(npc, path, loop)</code> - Sets the path for the specified NPC.

* <code>npcHelper:setPathAndPosition(npc, path, loop)</code> - Sets the path & starting position of the specified NPC.

* <code>npcHelper:addMerchant(merchantType, npc, items, offer)</code> - Adds merchant behavior to <code>npc</code> of either a buyer or seller defined by <code>merchantType</code>.

* <code>npcHelper:addSeller(npc, items, offer)</code> - Adds seller merchant behavior to <code>npc</code>.

* <code>npcHelper:addBuyer(npc, items, offer)</code> - Adds buyer merchant behavior to <code>npc</code>.

== Setting Zone ==

To set the zone to work with, use the <code>game</code> object:

<pre>

game:setZone("0_semos_city")

</pre>

The logger is exposed to Lua via the <code>logger</code> object:

<pre>

local zone = "0_semos_city"

if game:setZone(zone) then

-- do something

else

logger:error("Could not set zone: " .. zone)

end

</pre>

== Adding Entities ==

=== Signs ===

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

<pre>

local zone = "0_semos_city"

if game:setZone(zone) then

-- create the sign instance

local sign = game: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

</pre>

=== NPCs ===

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

<pre>

local zone = "0_semos_city"

if game:setZone(zone) then

-- Use helper object to create a new NPC

local npc = npcHelper: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},

}

-- Use helper object to create NPC path

npcHelper:setPath(npc, 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

</pre>