Introduction

Daimonin uses the embedded scripting language Lua 5.0∞ to extend the functionality of the core engine. This is mostly used for NPC interaction and other complex map functions, but can in theory do much more.

General Lua Documentation

O'Reilly has a short overview∞ of the most important parts of Lua.

The Lua Reference Manual∞ is a short but excellent reference manual for programmers.

Programming in Lua∞ is a complete manual with plenty of examples and tips. A paper version of this book is also available∞.

Using Lua in Daimonin

We will assume that you already have set up a local server and can use the editor. If not, please go back and read Your Own Server? before continuing.

For the impatient: Scripting Quickstart Tutorial -- this tutorial takes you through the steps necessary for building your first script. It also picks an example script apart and explains every part of it.

Event Objects

Event objects are used to attach scripts to objects and events. The easiest way to create one is by using the scripts tab in the bottom panel of the map editor. First select the object you want to connect the script to (usually a NPC), then click "Create New". You will get a dialog with the following fields:

• Event type: This selects what kind of event will trigger the script. Most common is Say for NPCs that should react to speech.
• Plugin: Which script plugin to use. Choose Lua.
• Script File: Path for the script file. The default will not work!. Always enter a full path, for example /stoneglow/Jahrel.lua.
• Script Options: Whatever you write here will be sent to the script in the event.options variable.

Cancel will abort, and Ok will apply the settings. If you have chosen a non-existant file the built-in script editor will be launched and you can start coding your scripts.

The other buttons on the Scripts tab does the following:

• Edit Data: brings up the above mentioned dialog for the selected script
• Edit Script: brings up the Script Pad for the selected script
• Remove Script: removes the selected script from the current object

Since event obejcts are also normal objects in the inventory of objects, you can also use the standard tools in the editor to manipulate them or edit their attributes.

Event Types (Triggers)

There are bunch of different event types:

• Apply: Triggers when the object is applied
• Attack: Triggers when the object is attacked (or attacks??)
• Death: Triggers when the object dies (how about non-living objects??)
• Drop: Triggers when the object drops
• Pickup: Triggers when the obejct is picked up
• Say: Triggers when something is said nearby
• Talk: Triggers when a monster/NPC is /talk:ed to
• Stop: Triggers when a missile stops
• Time: For active objects (objects with speed) triggers every time the object gets to move. (don't use this. Check out coroutines instead)
• Throw: Triggers when the object is thrown
• Trigger: Triggers when the object or its connection is triggered. Mostly for buttons, levers and the like but can also be used on traps and missiles(!?).
• Close: Triggers when the object (a container) is closed. (To trigger on open, use Apply)
• Examine: Triggers when an object is examined.

The exact details of the different event types can be found under Event Types And Triggers

Scripts

By now you should know some about Lua and some about Daimonin script events, so it is time to connect the two.

Whenever an event object is triggered, it starts its connected script. The server suspends while the script is being executed and doesn't resume normal operations until the script has finished. So it is very important that the script finishes quickly.

Except for the standard Lua global functions and variables, there are a couple of Daimonin-specific:

• game represents the actual game, and contains a couple of Daimonin-specific functions and constants.
• event is an object with the data for the current event. For example for a Say event, event.message will contain the said text and event.activator will be the speaker. event.me is always the object to which the event is attached. More details can be found in Event Types and Triggers.

Core Classes

We have five core Daimonin classes:

• Game - the global game object. Always accessible through the global game.
• Event - the event class. Has no functions, but several fields related to the currently triggered event
• GameObject - an in-game object, item or thing. For example event.me is always the object for which the current script was triggered.
• Map - represents a daimonin map. For example event.me.map is the map that the scripted object is on (unless it has been taken out of the map or is inside another object).
• AI - represents the "mind" of monsters and NPCs. For experienced scripters only. Ignore this until you have mastered Daimonin scripting =).

The Core Class Reference ∞ is autogenerated from the latest plugin source code. (Currently this doc is for the unreleased SVN HEAD version, but in the future there will be two versions, one for the latest release and one for the current SVN).

The Core Class Reference is updated now and then to reflect changes in the SVN server, so remember to check it out after any updates.

Extra Classes

Those classes are defined in /maps/lua/*.lua and can be used by other scripts through the require function:

• Using the TopicList for NPC chat scripts is recommended, but not mandatory.
• InterfaceBuilder is a convenient way to access the new (beta 4) NPC GUI.
• QuestManager is the easy way to access the beta 4 quest system
• The DataStore class can be used to store global data shared between scripts, objects and/or maps. This class is always loaded and should not be included with the require function.
• Behaviourlist is a support class for manipulating mob AI configurations

Detached Scripts / Coroutines

(For advanced scripters only)

By using the lua function coroutine.yield(yield_time) you can now run a script over time, instead of having to fully end it at the instant it was triggered by an event.
The yield_time parameter is the number of seconds the script should be put into the background.
Read up on lua coroutines, and see the example kickball script∞
Please use this feature sparingly, as it can possibly take a lot of CPU time (e.g. if you have very low yield_time). It is however much more efficient (and easier) to have a script doing something repeatedly using coroutines than by using events that trigger at similar intervals.
There are some possible gotchas, though:

• your script stays in memory during the yield(), so for very long intervals this costs memory. If you have very long intervals (minutes or more), consider using recurring triggers instead.
• Maps, objects and other game objects may have been freed during the time the script was yield()ing. The game.isValid(anything) function can test whether any object is still valid.

Using lua scipts to prototype AI behaviours

(For advanced scripters only)

With the AI class it is possible to write monster behaviours in lua. Read up on how to configure monster behaviours?, and how to use plugin behaviours? before you try this. There are some examples and experiments in the AI testmap, and in the maps/lua/ai∞ directory.

Please note that for performance reasons 99.9% of all monster behaviours must be implemented in C in the AI engine when running on a major server. But using lua is a great way to quickly prototype new behaviours and test out ideas, and the AI developers are happy to port good new behaviours to C.

to be documented!!

Tips & Tricks, Problems and Gotchas

• The file maps/lua/plugin_init.lua∞ contains a few useful function definitions, for example obj_inventory() and map_objects() which are iterator functions for walking through the contents of an object or a map square in a loop like this:

• Useful Lua functions?
• Best Practices
• Make sure you can read the error messages from your scripts. Those are normally printed in the server output window. Any DM who triggers a script will also see any Lua error messages in the client.
• Don't be afraid to ask questions in #daimonin∞