From bd37cc09c525d4db9400e224e4ca3cadcf0eed4c Mon Sep 17 00:00:00 2001 From: Alexander Gavrilov Date: Fri, 22 Jun 2012 20:17:55 +0400 Subject: Update the Lua API document with info about scripts. --- Lua API.html | 172 +++++++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 121 insertions(+), 51 deletions(-) (limited to 'Lua API.html') diff --git a/Lua API.html b/Lua API.html index 47cf08ab..04e89936 100644 --- a/Lua API.html +++ b/Lua API.html @@ -320,7 +320,7 @@ ul.auto-toc {

Contents

-
-

DF structure wrapper

+

The current version of DFHack has extensive support for +the Lua scripting language, providing access to:

+
    +
  1. Raw data structures used by the game.
  2. +
  3. Many C++ functions for high-level access to these +structures, and interaction with dfhack itself.
  4. +
  5. Some functions exported by C++ plugins.
  6. +
+

Lua code can be used both for writing scripts, which +are treated by DFHack command line prompt almost as +native C++ commands, and invoked by plugins written in c++.

+

This document describes native API available to Lua in detail. +For the most part it does not describe utility functions +implemented by Lua files located in hack/lua/...

+
+

DF data structure wrapper

DF structures described by the xml files in library/xml are exported to lua code as a tree of objects and functions under the df global, which broadly maps to the df namespace in C++.

@@ -764,28 +780,8 @@ string, global environment and command-line history file.

-
-

Miscellaneous

- -
-

Exception handling

+

Exception handling

+
+

Locking and finalization

+ +

Persistent configuration storage

This api is intended for storing configuration options in the world itself. @@ -1470,15 +1480,45 @@ order using dfhack.safecall.

+
+

Modules

+

DFHack sets up the lua interpreter so that the built-in require +function can be used to load shared lua code from hack/lua/. +The dfhack namespace reference itself may be obtained via +require('dfhack'), although it is initially created as a +global by C++ bootstrap code.

+

The following functions are provided:

+ +
-

Plugins

+

Plugins

DFHack plugins may export native functions and events to lua contexts. They are automatically imported by mkmodule('plugins.<name>'); this means that a lua module file is still necessary for require to read.

The following plugins have lua support.

-

burrows

+

burrows

Implements extended burrow manipulations.

Events:

-

sort

+

sort

Does not export any native functions as of now. Instead, it calls lua code to perform the actual ordering of list items.

+
+

Scripts

+

Any files with the .lua extension placed into hack/scripts/* +are automatically used by the DFHack core as commands. The +matching command name consists of the name of the file sans +the extension.

+

NOTE: Scripts placed in subdirectories still can be accessed, but +do not clutter the ls command list; thus it is preferred +for obscure developer-oriented scripts and scripts used by tools. +When calling such scripts, always use '/' as the separator for +directories, e.g. devel/lua-example.

+

Scripts are re-read from disk every time they are used +(this may be changed later to check the file change time); however +the global variable values persist in memory between calls. +Every script gets its own separate environment for global +variables.

+

Arguments are passed in to the scripts via the ... built-in +quasi-variable; when the script is called by the DFHack core, +they are all guaranteed to be non-nil strings.

+

DFHack core invokes the scripts in the core context (see above); +however it is possible to call them from any lua code (including +from other scripts) in any context, via the same function the core uses:

+ +

Note that this function lets errors propagate to the caller.

+
-- cgit v1.2.1