diff options
| author | Petr Mrázek | 2012-09-30 06:44:00 +0200 |
|---|---|---|
| committer | Petr Mrázek | 2012-09-30 06:44:00 +0200 |
| commit | e2d810ddc2bbedc1dcdc154b299f0dee7452f8aa (patch) | |
| tree | ac563f4d87647ff513d7b82a573534c28265a644 /LUA Api.html | |
| parent | dd9be6cc7c81a3d577f6283a798c78b522013d9e (diff) | |
| download | dfhack-e2d810ddc2bbedc1dcdc154b299f0dee7452f8aa.tar.gz dfhack-e2d810ddc2bbedc1dcdc154b299f0dee7452f8aa.tar.bz2 dfhack-e2d810ddc2bbedc1dcdc154b299f0dee7452f8aa.tar.xz | |
Put HTML back.
Diffstat (limited to 'LUA Api.html')
| -rw-r--r-- | LUA Api.html | 2104 |
1 files changed, 2104 insertions, 0 deletions
diff --git a/LUA Api.html b/LUA Api.html new file mode 100644 index 00000000..047ef978 --- /dev/null +++ b/LUA Api.html @@ -0,0 +1,2104 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<meta name="generator" content="Docutils 0.9.1: http://docutils.sourceforge.net/" /> +<title>DFHack Lua API</title> +<style type="text/css"> + +/* +:Author: David Goodger (goodger@python.org) +:Id: $Id: html4css1.css 7434 2012-05-11 21:06:27Z milde $ +:Copyright: This stylesheet has been placed in the public domain. + +Default cascading style sheet for the HTML output of Docutils. + +See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to +customize this style sheet. +*/ + +/* used to remove borders from tables and images */ +.borderless, table.borderless td, table.borderless th { + border: 0 } + +table.borderless td, table.borderless th { + /* Override padding for "table.docutils td" with "! important". + The right padding separates the table cells. */ + padding: 0 0.5em 0 0 ! important } + +.first { + /* Override more specific margin styles with "! important". */ + margin-top: 0 ! important } + +.last, .with-subtitle { + margin-bottom: 0 ! important } + +.hidden { + display: none } + +a.toc-backref { + text-decoration: none ; + color: black } + +blockquote.epigraph { + margin: 2em 5em ; } + +dl.docutils dd { + margin-bottom: 0.5em } + +object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] { + overflow: hidden; +} + +/* Uncomment (and remove this text!) to get bold-faced definition list terms +dl.docutils dt { + font-weight: bold } +*/ + +div.abstract { + margin: 2em 5em } + +div.abstract p.topic-title { + font-weight: bold ; + text-align: center } + +div.admonition, div.attention, div.caution, div.danger, div.error, +div.hint, div.important, div.note, div.tip, div.warning { + margin: 2em ; + border: medium outset ; + padding: 1em } + +div.admonition p.admonition-title, div.hint p.admonition-title, +div.important p.admonition-title, div.note p.admonition-title, +div.tip p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + +div.attention p.admonition-title, div.caution p.admonition-title, +div.danger p.admonition-title, div.error p.admonition-title, +div.warning p.admonition-title { + color: red ; + font-weight: bold ; + font-family: sans-serif } + +/* Uncomment (and remove this text!) to get reduced vertical space in + compound paragraphs. +div.compound .compound-first, div.compound .compound-middle { + margin-bottom: 0.5em } + +div.compound .compound-last, div.compound .compound-middle { + margin-top: 0.5em } +*/ + +div.dedication { + margin: 2em 5em ; + text-align: center ; + font-style: italic } + +div.dedication p.topic-title { + font-weight: bold ; + font-style: normal } + +div.figure { + margin-left: 2em ; + margin-right: 2em } + +div.footer, div.header { + clear: both; + font-size: smaller } + +div.line-block { + display: block ; + margin-top: 1em ; + margin-bottom: 1em } + +div.line-block div.line-block { + margin-top: 0 ; + margin-bottom: 0 ; + margin-left: 1.5em } + +div.sidebar { + margin: 0 0 0.5em 1em ; + border: medium outset ; + padding: 1em ; + background-color: #ffffee ; + width: 40% ; + float: right ; + clear: right } + +div.sidebar p.rubric { + font-family: sans-serif ; + font-size: medium } + +div.system-messages { + margin: 5em } + +div.system-messages h1 { + color: red } + +div.system-message { + border: medium outset ; + padding: 1em } + +div.system-message p.system-message-title { + color: red ; + font-weight: bold } + +div.topic { + margin: 2em } + +h1.section-subtitle, h2.section-subtitle, h3.section-subtitle, +h4.section-subtitle, h5.section-subtitle, h6.section-subtitle { + margin-top: 0.4em } + +h1.title { + text-align: center } + +h2.subtitle { + text-align: center } + +hr.docutils { + width: 75% } + +img.align-left, .figure.align-left, object.align-left { + clear: left ; + float: left ; + margin-right: 1em } + +img.align-right, .figure.align-right, object.align-right { + clear: right ; + float: right ; + margin-left: 1em } + +img.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left } + +.align-center { + clear: both ; + text-align: center } + +.align-right { + text-align: right } + +/* reset inner alignment in figures */ +div.align-right { + text-align: inherit } + +/* div.align-center * { */ +/* text-align: left } */ + +ol.simple, ul.simple { + margin-bottom: 1em } + +ol.arabic { + list-style: decimal } + +ol.loweralpha { + list-style: lower-alpha } + +ol.upperalpha { + list-style: upper-alpha } + +ol.lowerroman { + list-style: lower-roman } + +ol.upperroman { + list-style: upper-roman } + +p.attribution { + text-align: right ; + margin-left: 50% } + +p.caption { + font-style: italic } + +p.credits { + font-style: italic ; + font-size: smaller } + +p.label { + white-space: nowrap } + +p.rubric { + font-weight: bold ; + font-size: larger ; + color: maroon ; + text-align: center } + +p.sidebar-title { + font-family: sans-serif ; + font-weight: bold ; + font-size: larger } + +p.sidebar-subtitle { + font-family: sans-serif ; + font-weight: bold } + +p.topic-title { + font-weight: bold } + +pre.address { + margin-bottom: 0 ; + margin-top: 0 ; + font: inherit } + +pre.literal-block, pre.doctest-block, pre.math, pre.code { + margin-left: 2em ; + margin-right: 2em } + +pre.code .ln { /* line numbers */ + color: grey; +} + +.code { + background-color: #eeeeee +} + +span.classifier { + font-family: sans-serif ; + font-style: oblique } + +span.classifier-delimiter { + font-family: sans-serif ; + font-weight: bold } + +span.interpreted { + font-family: sans-serif } + +span.option { + white-space: nowrap } + +span.pre { + white-space: pre } + +span.problematic { + color: red } + +span.section-subtitle { + /* font-size relative to parent (h1..h6 element) */ + font-size: 80% } + +table.citation { + border-left: solid 1px gray; + margin-left: 1px } + +table.docinfo { + margin: 2em 4em } + +table.docutils { + margin-top: 0.5em ; + margin-bottom: 0.5em } + +table.footnote { + border-left: solid 1px black; + margin-left: 1px } + +table.docutils td, table.docutils th, +table.docinfo td, table.docinfo th { + padding-left: 0.5em ; + padding-right: 0.5em ; + vertical-align: top } + +table.docutils th.field-name, table.docinfo th.docinfo-name { + font-weight: bold ; + text-align: left ; + white-space: nowrap ; + padding-left: 0 } + +h1 tt.docutils, h2 tt.docutils, h3 tt.docutils, +h4 tt.docutils, h5 tt.docutils, h6 tt.docutils { + font-size: 100% } + +ul.auto-toc { + list-style-type: none } + +</style> +</head> +<body> +<div class="document" id="dfhack-lua-api"> +<h1 class="title">DFHack Lua API</h1> + +<div class="contents topic" id="contents"> +<p class="topic-title first">Contents</p> +<ul class="simple"> +<li><a class="reference internal" href="#df-data-structure-wrapper" id="id1">DF data structure wrapper</a><ul> +<li><a class="reference internal" href="#typed-object-references" id="id2">Typed object references</a><ul> +<li><a class="reference internal" href="#primitive-references" id="id3">Primitive references</a></li> +<li><a class="reference internal" href="#struct-references" id="id4">Struct references</a></li> +<li><a class="reference internal" href="#container-references" id="id5">Container references</a></li> +<li><a class="reference internal" href="#bitfield-references" id="id6">Bitfield references</a></li> +</ul> +</li> +<li><a class="reference internal" href="#named-types" id="id7">Named types</a></li> +<li><a class="reference internal" href="#global-functions" id="id8">Global functions</a></li> +<li><a class="reference internal" href="#recursive-table-assignment" id="id9">Recursive table assignment</a></li> +</ul> +</li> +<li><a class="reference internal" href="#dfhack-api" id="id10">DFHack API</a><ul> +<li><a class="reference internal" href="#native-utilities" id="id11">Native utilities</a><ul> +<li><a class="reference internal" href="#input-output" id="id12">Input & Output</a></li> +<li><a class="reference internal" href="#exception-handling" id="id13">Exception handling</a></li> +<li><a class="reference internal" href="#miscellaneous" id="id14">Miscellaneous</a></li> +<li><a class="reference internal" href="#locking-and-finalization" id="id15">Locking and finalization</a></li> +<li><a class="reference internal" href="#persistent-configuration-storage" id="id16">Persistent configuration storage</a></li> +<li><a class="reference internal" href="#material-info-lookup" id="id17">Material info lookup</a></li> +</ul> +</li> +<li><a class="reference internal" href="#c-function-wrappers" id="id18">C++ function wrappers</a><ul> +<li><a class="reference internal" href="#gui-module" id="id19">Gui module</a></li> +<li><a class="reference internal" href="#job-module" id="id20">Job module</a></li> +<li><a class="reference internal" href="#units-module" id="id21">Units module</a></li> +<li><a class="reference internal" href="#items-module" id="id22">Items module</a></li> +<li><a class="reference internal" href="#maps-module" id="id23">Maps module</a></li> +<li><a class="reference internal" href="#burrows-module" id="id24">Burrows module</a></li> +<li><a class="reference internal" href="#buildings-module" id="id25">Buildings module</a></li> +<li><a class="reference internal" href="#constructions-module" id="id26">Constructions module</a></li> +<li><a class="reference internal" href="#screen-api" id="id27">Screen API</a></li> +<li><a class="reference internal" href="#internal-api" id="id28">Internal API</a></li> +</ul> +</li> +<li><a class="reference internal" href="#core-interpreter-context" id="id29">Core interpreter context</a><ul> +<li><a class="reference internal" href="#event-type" id="id30">Event type</a></li> +</ul> +</li> +</ul> +</li> +<li><a class="reference internal" href="#lua-modules" id="id31">Lua Modules</a><ul> +<li><a class="reference internal" href="#global-environment" id="id32">Global environment</a></li> +<li><a class="reference internal" href="#utils" id="id33">utils</a></li> +<li><a class="reference internal" href="#dumper" id="id34">dumper</a></li> +<li><a class="reference internal" href="#class" id="id35">class</a></li> +</ul> +</li> +<li><a class="reference internal" href="#plugins" id="id36">Plugins</a><ul> +<li><a class="reference internal" href="#burrows" id="id37">burrows</a></li> +<li><a class="reference internal" href="#sort" id="id38">sort</a></li> +</ul> +</li> +<li><a class="reference internal" href="#scripts" id="id39">Scripts</a></li> +</ul> +</div> +<p>The current version of DFHack has extensive support for +the Lua scripting language, providing access to:</p> +<ol class="arabic simple"> +<li>Raw data structures used by the game.</li> +<li>Many C++ functions for high-level access to these +structures, and interaction with dfhack itself.</li> +<li>Some functions exported by C++ plugins.</li> +</ol> +<p>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++.</p> +<p>This document describes native API available to Lua in detail. +It does not describe all of the utility functions +implemented by Lua files located in hack/lua/...</p> +<div class="section" id="df-data-structure-wrapper"> +<h1><a class="toc-backref" href="#id1">DF data structure wrapper</a></h1> +<p>DF structures described by the xml files in library/xml are exported +to lua code as a tree of objects and functions under the <tt class="docutils literal">df</tt> global, +which broadly maps to the <tt class="docutils literal">df</tt> namespace in C++.</p> +<p><strong>WARNING</strong>: The wrapper provides almost raw access to the memory +of the game, so mistakes in manipulating objects are as likely to +crash the game as equivalent plain C++ code would be. E.g. NULL +pointer access is safely detected, but dangling pointers aren't.</p> +<p>Objects managed by the wrapper can be broadly classified into the following groups:</p> +<ol class="arabic"> +<li><p class="first">Typed object pointers (references).</p> +<p>References represent objects in DF memory with a known type.</p> +<p>In addition to fields and methods defined by the wrapped type, +every reference has some built-in properties and methods.</p> +</li> +<li><p class="first">Untyped pointers</p> +<p>Represented as lightuserdata.</p> +<p>In assignment to a pointer NULL can be represented either as +<tt class="docutils literal">nil</tt>, or a NULL lightuserdata; reading a NULL pointer field +returns <tt class="docutils literal">nil</tt>.</p> +</li> +<li><p class="first">Named types</p> +<p>Objects in the <tt class="docutils literal">df</tt> tree that represent identity of struct, class, +enum and bitfield types. They host nested named types, static +methods, builtin properties & methods, and, for enums and bitfields, +the bi-directional mapping between key names and values.</p> +</li> +<li><p class="first">The <tt class="docutils literal">global</tt> object</p> +<p><tt class="docutils literal">df.global</tt> corresponds to the <tt class="docutils literal"><span class="pre">df::global</span></tt> namespace, and +behaves as a mix between a named type and a reference, containing +both nested types and fields corresponding to global symbols.</p> +</li> +</ol> +<p>In addition to the <tt class="docutils literal">global</tt> object and top-level types the <tt class="docutils literal">df</tt> +global also contains a few global builtin utility functions.</p> +<div class="section" id="typed-object-references"> +<h2><a class="toc-backref" href="#id2">Typed object references</a></h2> +<p>The underlying primitive lua object is userdata with a metatable. +Every structured field access produces a new userdata instance.</p> +<p>All typed objects have the following built-in features:</p> +<ul> +<li><p class="first"><tt class="docutils literal">ref1 == ref2</tt>, <tt class="docutils literal">tostring(ref)</tt></p> +<p>References implement equality by type & pointer value, and string conversion.</p> +</li> +<li><p class="first"><tt class="docutils literal">pairs(ref)</tt></p> +<p>Returns an iterator for the sequence of actual C++ field names +and values. Fields are enumerated in memory order. Methods and +lua wrapper properties are not included in the iteration.</p> +<p><strong>WARNING</strong>: a few of the data structures (like ui_look_list) +contain unions with pointers to different types with vtables. +Using pairs on such structs is an almost sure way to crash with +an access violation.</p> +</li> +<li><p class="first"><tt class="docutils literal">ref._kind</tt></p> +<p>Returns one of: <tt class="docutils literal">primitive</tt>, <tt class="docutils literal">struct</tt>, <tt class="docutils literal">container</tt>, +or <tt class="docutils literal">bitfield</tt>, as appropriate for the referenced object.</p> +</li> +<li><p class="first"><tt class="docutils literal">ref._type</tt></p> +<p>Returns the named type object or a string that represents +the referenced object type.</p> +</li> +<li><p class="first"><tt class="docutils literal">ref:sizeof()</tt></p> +<p>Returns <em>size, address</em></p> +</li> +<li><p class="first"><tt class="docutils literal">ref:new()</tt></p> +<p>Allocates a new instance of the same type, and copies data +from the current object.</p> +</li> +<li><p class="first"><tt class="docutils literal">ref:delete()</tt></p> +<p>Destroys the object with the C++ <tt class="docutils literal">delete</tt> operator. +If destructor is not available, returns <em>false</em>.</p> +<p><strong>WARNING</strong>: the lua reference object remains as a dangling +pointer, like a raw C++ pointer would.</p> +</li> +<li><p class="first"><tt class="docutils literal">ref:assign(object)</tt></p> +<p>Assigns data from object to ref. Object must either be another +ref of a compatible type, or a lua table; in the latter case +special recursive assignment rules are applied.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">ref:_displace(index[,step])</span></tt></p> +<p>Returns a new reference with the pointer adjusted by index*step. +Step defaults to the natural object size.</p> +</li> +</ul> +<div class="section" id="primitive-references"> +<h3><a class="toc-backref" href="#id3">Primitive references</a></h3> +<p>References of the <em>_kind</em> <tt class="docutils literal">'primitive'</tt> are used for objects +that don't fit any of the other reference types. Such +references can only appear as a value of a pointer field, +or as a result of calling the <tt class="docutils literal">_field()</tt> method.</p> +<p>They behave as structs with one field <tt class="docutils literal">value</tt> of the right type.</p> +<p>To make working with numeric buffers easier, they also allow +numeric indices. Note that other than excluding negative values +no bound checking is performed, since buffer length is not available. +Index 0 is equivalent to the <tt class="docutils literal">value</tt> field.</p> +</div> +<div class="section" id="struct-references"> +<h3><a class="toc-backref" href="#id4">Struct references</a></h3> +<p>Struct references are used for class and struct objects.</p> +<p>They implement the following features:</p> +<ul> +<li><p class="first"><tt class="docutils literal">ref.field</tt>, <tt class="docutils literal">ref.field = value</tt></p> +<p>Valid fields of the structure may be accessed by subscript.</p> +<p>Primitive typed fields, i.e. numbers & strings, are converted +to/from matching lua values. The value of a pointer is a reference +to the target, or nil/NULL. Complex types are represented by +a reference to the field within the structure; unless recursive +lua table assignment is used, such fields can only be read.</p> +<p><strong>NOTE:</strong> In case of inheritance, <em>superclass</em> fields have precedence +over the subclass, but fields shadowed in this way can still +be accessed as <tt class="docutils literal"><span class="pre">ref['subclasstype.field']</span></tt>. +This shadowing order is necessary because vtable-based classes +are automatically exposed in their exact type, and the reverse +rule would make access to superclass fields unreliable.</p> +</li> +<li><p class="first"><tt class="docutils literal">ref._field(field)</tt></p> +<p>Returns a reference to a valid field. That is, unlike regular +subscript, it returns a reference to the field within the structure +even for primitive typed fields and pointers.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">ref:vmethod(args...)</span></tt></p> +<p>Named virtual methods are also exposed, subject to the same +shadowing rules.</p> +</li> +<li><p class="first"><tt class="docutils literal">pairs(ref)</tt></p> +<p>Enumerates all real fields (but not methods) in memory +(= declaration) order.</p> +</li> +</ul> +</div> +<div class="section" id="container-references"> +<h3><a class="toc-backref" href="#id5">Container references</a></h3> +<p>Containers represent vectors and arrays, possibly resizable.</p> +<p>A container field can associate an enum to the container +reference, which allows accessing elements using string keys +instead of numerical indices.</p> +<p>Implemented features:</p> +<ul> +<li><p class="first"><tt class="docutils literal">ref._enum</tt></p> +<p>If the container has an associated enum, returns the matching +named type object.</p> +</li> +<li><p class="first"><tt class="docutils literal">#ref</tt></p> +<p>Returns the <em>length</em> of the container.</p> +</li> +<li><p class="first"><tt class="docutils literal">ref[index]</tt></p> +<p>Accesses the container element, using either a <em>0-based</em> numerical +index, or, if an enum is associated, a valid enum key string.</p> +<p>Accessing an invalid index is an error, but some container types +may return a default value, or auto-resize instead for convenience. +Currently this relaxed mode is implemented by df-flagarray aka BitArray.</p> +</li> +<li><p class="first"><tt class="docutils literal">ref._field(index)</tt></p> +<p>Like with structs, returns a pointer to the array element, if possible. +Flag and bit arrays cannot return such pointer, so it fails with an error.</p> +</li> +<li><p class="first"><tt class="docutils literal">pairs(ref)</tt>, <tt class="docutils literal">ipairs(ref)</tt></p> +<p>If the container has no associated enum, both behave identically, +iterating over numerical indices in order. Otherwise, ipairs still +uses numbers, while pairs tries to substitute enum keys whenever +possible.</p> +</li> +<li><p class="first"><tt class="docutils literal">ref:resize(new_size)</tt></p> +<p>Resizes the container if supported, or fails with an error.</p> +</li> +<li><p class="first"><tt class="docutils literal">ref:insert(index,item)</tt></p> +<p>Inserts a new item at the specified index. To add at the end, +use <tt class="docutils literal">#ref</tt>, or just <tt class="docutils literal">'#'</tt> as index.</p> +</li> +<li><p class="first"><tt class="docutils literal">ref:erase(index)</tt></p> +<p>Removes the element at the given valid index.</p> +</li> +</ul> +</div> +<div class="section" id="bitfield-references"> +<h3><a class="toc-backref" href="#id6">Bitfield references</a></h3> +<p>Bitfields behave like special fixed-size containers. +Consider them to be something in between structs and +fixed-size vectors.</p> +<p>The <tt class="docutils literal">_enum</tt> property points to the bitfield type. +Numerical indices correspond to the shift value, +and if a subfield occupies multiple bits, the +<tt class="docutils literal">ipairs</tt> order would have a gap.</p> +<p>Since currently there is no API to allocate a bitfield +object fully in GC-managed lua heap, consider using the +lua table assignment feature outlined below in order to +pass bitfield values to dfhack API functions that need +them, e.g. <tt class="docutils literal">matinfo:matches{metal=true}</tt>.</p> +</div> +</div> +<div class="section" id="named-types"> +<h2><a class="toc-backref" href="#id7">Named types</a></h2> +<p>Named types are exposed in the <tt class="docutils literal">df</tt> tree with names identical +to the C++ version, except for the <tt class="docutils literal">::</tt> vs <tt class="docutils literal">.</tt> difference.</p> +<p>All types and the global object have the following features:</p> +<ul> +<li><p class="first"><tt class="docutils literal">type._kind</tt></p> +<p>Evaluates to one of <tt class="docutils literal"><span class="pre">struct-type</span></tt>, <tt class="docutils literal"><span class="pre">class-type</span></tt>, <tt class="docutils literal"><span class="pre">enum-type</span></tt>, +<tt class="docutils literal"><span class="pre">bitfield-type</span></tt> or <tt class="docutils literal">global</tt>.</p> +</li> +<li><p class="first"><tt class="docutils literal">type._identity</tt></p> +<p>Contains a lightuserdata pointing to the underlying +DFHack::type_instance object.</p> +</li> +</ul> +<p>Types excluding the global object also support:</p> +<ul> +<li><p class="first"><tt class="docutils literal">type:sizeof()</tt></p> +<p>Returns the size of an object of the type.</p> +</li> +<li><p class="first"><tt class="docutils literal">type:new()</tt></p> +<p>Creates a new instance of an object of the type.</p> +</li> +<li><p class="first"><tt class="docutils literal">type:is_instance(object)</tt></p> +<p>Returns true if object is same or subclass type, or a reference +to an object of same or subclass type. It is permissible to pass +nil, NULL or non-wrapper value as object; in this case the +method returns nil.</p> +</li> +</ul> +<p>In addition to this, enum and bitfield types contain a +bi-directional mapping between key strings and values, and +also map <tt class="docutils literal">_first_item</tt> and <tt class="docutils literal">_last_item</tt> to the min and +max values.</p> +<p>Struct and class types with instance-vector attribute in the +xml have a <tt class="docutils literal">type.find(key)</tt> function that wraps the find +method provided in C++.</p> +</div> +<div class="section" id="global-functions"> +<h2><a class="toc-backref" href="#id8">Global functions</a></h2> +<p>The <tt class="docutils literal">df</tt> table itself contains the following functions and values:</p> +<ul> +<li><p class="first"><tt class="docutils literal">NULL</tt>, <tt class="docutils literal">df.NULL</tt></p> +<p>Contains the NULL lightuserdata.</p> +</li> +<li><p class="first"><tt class="docutils literal">df.isnull(obj)</tt></p> +<p>Evaluates to true if obj is nil or NULL; false otherwise.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">df.isvalid(obj[,allow_null])</span></tt></p> +<p>For supported objects returns one of <tt class="docutils literal">type</tt>, <tt class="docutils literal">voidptr</tt>, <tt class="docutils literal">ref</tt>.</p> +<p>If <em>allow_null</em> is true, and obj is nil or NULL, returns <tt class="docutils literal">null</tt>.</p> +<p>Otherwise returns <em>nil</em>.</p> +</li> +<li><p class="first"><tt class="docutils literal">df.sizeof(obj)</tt></p> +<p>For types and refs identical to <tt class="docutils literal">obj:sizeof()</tt>. +For lightuserdata returns <em>nil, address</em></p> +</li> +<li><p class="first"><tt class="docutils literal">df.new(obj)</tt>, <tt class="docutils literal">df.delete(obj)</tt>, <tt class="docutils literal">df.assign(obj, obj2)</tt></p> +<p>Equivalent to using the matching methods of obj.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">df._displace(obj,index[,step])</span></tt></p> +<p>For refs equivalent to the method, but also works with +lightuserdata (step is mandatory then).</p> +</li> +<li><p class="first"><tt class="docutils literal">df.is_instance(type,obj)</tt></p> +<p>Equivalent to the method, but also allows a reference as proxy for its type.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">df.new(ptype[,count])</span></tt></p> +<p>Allocate a new instance, or an array of built-in types. +The <tt class="docutils literal">ptype</tt> argument is a string from the following list: +<tt class="docutils literal">string</tt>, <tt class="docutils literal">int8_t</tt>, <tt class="docutils literal">uint8_t</tt>, <tt class="docutils literal">int16_t</tt>, <tt class="docutils literal">uint16_t</tt>, +<tt class="docutils literal">int32_t</tt>, <tt class="docutils literal">uint32_t</tt>, <tt class="docutils literal">int64_t</tt>, <tt class="docutils literal">uint64_t</tt>, <tt class="docutils literal">bool</tt>, +<tt class="docutils literal">float</tt>, <tt class="docutils literal">double</tt>. All of these except <tt class="docutils literal">string</tt> can be +used with the count argument to allocate an array.</p> +</li> +<li><p class="first"><tt class="docutils literal">df.reinterpret_cast(type,ptr)</tt></p> +<p>Converts ptr to a ref of specified type. The type may be anything +acceptable to <tt class="docutils literal">df.is_instance</tt>. Ptr may be <em>nil</em>, a ref, +a lightuserdata, or a number.</p> +<p>Returns <em>nil</em> if NULL, or a ref.</p> +</li> +</ul> +</div> +<div class="section" id="recursive-table-assignment"> +<h2><a class="toc-backref" href="#id9">Recursive table assignment</a></h2> +<p>Recursive assignment is invoked when a lua table is assigned +to a C++ object or field, i.e. one of:</p> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">ref:assign{...}</span></tt></li> +<li><tt class="docutils literal">ref.field = <span class="pre">{...}</span></tt></li> +</ul> +<p>The general mode of operation is that all fields of the table +are assigned to the fields of the target structure, roughly +emulating the following code:</p> +<pre class="literal-block"> +function rec_assign(ref,table) + for key,value in pairs(table) do + ref[key] = value + end +end +</pre> +<p>Since assigning a table to a field using = invokes the same +process, it is recursive.</p> +<p>There are however some variations to this process depending +on the type of the field being assigned to:</p> +<ol class="arabic"> +<li><p class="first">If the table contains an <tt class="docutils literal">assign</tt> field, it is +applied first, using the <tt class="docutils literal">ref:assign(value)</tt> method. +It is never assigned as a usual field.</p> +</li> +<li><p class="first">When a table is assigned to a non-NULL pointer field +using the <tt class="docutils literal">ref.field = <span class="pre">{...}</span></tt> syntax, it is applied +to the target of the pointer instead.</p> +<p>If the pointer is NULL, the table is checked for a <tt class="docutils literal">new</tt> field:</p> +<ol class="loweralpha simple"> +<li>If it is <em>nil</em> or <em>false</em>, assignment fails with an error.</li> +<li>If it is <em>true</em>, the pointer is initialized with a newly +allocated object of the declared target type of the pointer.</li> +<li>Otherwise, <tt class="docutils literal">table.new</tt> must be a named type, or an +object of a type compatible with the pointer. The pointer +is initialized with the result of calling <tt class="docutils literal">table.new:new()</tt>.</li> +</ol> +<p>After this auto-vivification process, assignment proceeds +as if the pointer wasn't NULL.</p> +<p>Obviously, the <tt class="docutils literal">new</tt> field inside the table is always skipped +during the actual per-field assignment processing.</p> +</li> +<li><p class="first">If the target of the assignment is a container, a separate +rule set is used:</p> +<ol class="loweralpha"> +<li><p class="first">If the table contains neither <tt class="docutils literal">assign</tt> nor <tt class="docutils literal">resize</tt> +fields, it is interpreted as an ordinary <em>1-based</em> lua +array. The container is resized to the #-size of the +table, and elements are assigned in numeric order:</p> +<pre class="literal-block"> +ref:resize(#table); +for i=1,#table do ref[i-1] = table[i] end +</pre> +</li> +<li><p class="first">Otherwise, <tt class="docutils literal">resize</tt> must be <em>true</em>, <em>false</em>, or +an explicit number. If it is not false, the container +is resized. After that the usual struct-like 'pairs' +assignment is performed.</p> +<p>In case <tt class="docutils literal">resize</tt> is <em>true</em>, the size is computed +by scanning the table for the largest numeric key.</p> +</li> +</ol> +<p>This means that in order to reassign only one element of +a container using this system, it is necessary to use:</p> +<pre class="literal-block"> +{ resize=false, [idx]=value } +</pre> +</li> +</ol> +<p>Since nil inside a table is indistinguishable from missing key, +it is necessary to use <tt class="docutils literal">df.NULL</tt> as a null pointer value.</p> +<p>This system is intended as a way to define a nested object +tree using pure lua data structures, and then materialize it in +C++ memory in one go. Note that if pointer auto-vivification +is used, an error in the middle of the recursive walk would +not destroy any objects allocated in this way, so the user +should be prepared to catch the error and do the necessary +cleanup.</p> +</div> +</div> +<div class="section" id="dfhack-api"> +<h1><a class="toc-backref" href="#id10">DFHack API</a></h1> +<p>DFHack utility functions are placed in the <tt class="docutils literal">dfhack</tt> global tree.</p> +<div class="section" id="native-utilities"> +<h2><a class="toc-backref" href="#id11">Native utilities</a></h2> +<div class="section" id="input-output"> +<h3><a class="toc-backref" href="#id12">Input & Output</a></h3> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.print(args...)</span></tt></p> +<p>Output tab-separated args as standard lua print would do, +but without a newline.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">print(args...)</span></tt>, <tt class="docutils literal"><span class="pre">dfhack.println(args...)</span></tt></p> +<p>A replacement of the standard library print function that +works with DFHack output infrastructure.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.printerr(args...)</span></tt></p> +<p>Same as println; intended for errors. Uses red color and logs to stderr.log.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.color([color])</span></tt></p> +<p>Sets the current output color. If color is <em>nil</em> or <em>-1</em>, resets to default. +Returns the previous color value.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.is_interactive()</tt></p> +<p>Checks if the thread can access the interactive console and returns <em>true</em> or <em>false</em>.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.lineedit([prompt[,history_filename]])</span></tt></p> +<p>If the thread owns the interactive console, shows a prompt +and returns the entered string. Otherwise returns <em>nil, error</em>.</p> +<p>Depending on the context, this function may actually yield the +running coroutine and let the C++ code release the core suspend +lock. Using an explicit <tt class="docutils literal">dfhack.with_suspend</tt> will prevent +this, forcing the function to block on input with lock held.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.interpreter([prompt[,history_filename[,env]]])</span></tt></p> +<p>Starts an interactive lua interpreter, using the specified prompt +string, global environment and command-line history file.</p> +<p>If the interactive console is not accessible, returns <em>nil, error</em>.</p> +</li> +</ul> +</div> +<div class="section" id="exception-handling"> +<h3><a class="toc-backref" href="#id13">Exception handling</a></h3> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.error(msg[,level[,verbose]])</span></tt></p> +<p>Throws a dfhack exception object with location and stack trace. +The verbose parameter controls whether the trace is printed by default.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">qerror(msg[,level])</span></tt></p> +<p>Calls <tt class="docutils literal">dfhack.error()</tt> with <tt class="docutils literal">verbose</tt> being <em>false</em>. Intended to +be used for user-caused errors in scripts, where stack traces are not +desirable.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.pcall(f[,args...])</span></tt></p> +<p>Invokes f via xpcall, using an error function that attaches +a stack trace to the error. The same function is used by SafeCall +in C++, and dfhack.safecall.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">safecall(f[,args...])</span></tt>, <tt class="docutils literal"><span class="pre">dfhack.safecall(f[,args...])</span></tt></p> +<p>Just like pcall, but also prints the error using printerr before +returning. Intended as a convenience function.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.saferesume(coroutine[,args...])</span></tt></p> +<p>Compares to coroutine.resume like dfhack.safecall vs pcall.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.exception</tt></p> +<p>Metatable of error objects used by dfhack. The objects have the +following properties:</p> +<dl class="docutils"> +<dt><tt class="docutils literal">err.where</tt></dt> +<dd><p class="first last">The location prefix string, or <em>nil</em>.</p> +</dd> +<dt><tt class="docutils literal">err.message</tt></dt> +<dd><p class="first last">The base message string.</p> +</dd> +<dt><tt class="docutils literal">err.stacktrace</tt></dt> +<dd><p class="first last">The stack trace string, or <em>nil</em>.</p> +</dd> +<dt><tt class="docutils literal">err.cause</tt></dt> +<dd><p class="first last">A different exception object, or <em>nil</em>.</p> +</dd> +<dt><tt class="docutils literal">err.thread</tt></dt> +<dd><p class="first last">The coroutine that has thrown the exception.</p> +</dd> +<dt><tt class="docutils literal">err.verbose</tt></dt> +<dd><p class="first last">Boolean, or <em>nil</em>; specifies if where and stacktrace should be printed.</p> +</dd> +<dt><tt class="docutils literal">tostring(err)</tt>, or <tt class="docutils literal"><span class="pre">err:tostring([verbose])</span></tt></dt> +<dd><p class="first last">Converts the exception to string.</p> +</dd> +</dl> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.exception.verbose</tt></p> +<p>The default value of the <tt class="docutils literal">verbose</tt> argument of <tt class="docutils literal">err:tostring()</tt>.</p> +</li> +</ul> +</div> +<div class="section" id="miscellaneous"> +<h3><a class="toc-backref" href="#id14">Miscellaneous</a></h3> +<ul> +<li><p class="first"><tt class="docutils literal">dfhack.VERSION</tt></p> +<p>DFHack version string constant.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.curry(func,args...)</span></tt>, or <tt class="docutils literal"><span class="pre">curry(func,args...)</span></tt></p> +<p>Returns a closure that invokes the function with args combined +both from the curry call and the closure call itself. I.e. +<tt class="docutils literal"><span class="pre">curry(func,a,b)(c,d)</span></tt> equals <tt class="docutils literal">func(a,b,c,d)</tt>.</p> +</li> +</ul> +</div> +<div class="section" id="locking-and-finalization"> +<h3><a class="toc-backref" href="#id15">Locking and finalization</a></h3> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.with_suspend(f[,args...])</span></tt></p> +<p>Calls <tt class="docutils literal">f</tt> with arguments after grabbing the DF core suspend lock. +Suspending is necessary for accessing a consistent state of DF memory.</p> +<p>Returned values and errors are propagated through after releasing +the lock. It is safe to nest suspends.</p> +<p>Every thread is allowed only one suspend per DF frame, so it is best +to group operations together in one big critical section. A plugin +can choose to run all lua code inside a C++-side suspend lock.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.call_with_finalizer(num_cleanup_args,always,cleanup_fn[,cleanup_args...],fn[,args...])</span></tt></p> +<p>Invokes <tt class="docutils literal">fn</tt> with <tt class="docutils literal">args</tt>, and after it returns or throws an +error calls <tt class="docutils literal">cleanup_fn</tt> with <tt class="docutils literal">cleanup_args</tt>. Any return values from +<tt class="docutils literal">fn</tt> are propagated, and errors are re-thrown.</p> +<p>The <tt class="docutils literal">num_cleanup_args</tt> integer specifies the number of <tt class="docutils literal">cleanup_args</tt>, +and the <tt class="docutils literal">always</tt> boolean specifies if cleanup should be called in any case, +or only in case of an error.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.with_finalize(cleanup_fn,fn[,args...])</span></tt></p> +<p>Calls <tt class="docutils literal">fn</tt> with arguments, then finalizes with <tt class="docutils literal">cleanup_fn</tt>. +Implemented using <tt class="docutils literal"><span class="pre">call_with_finalizer(0,true,...)</span></tt>.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.with_onerror(cleanup_fn,fn[,args...])</span></tt></p> +<p>Calls <tt class="docutils literal">fn</tt> with arguments, then finalizes with <tt class="docutils literal">cleanup_fn</tt> on any thrown error. +Implemented using <tt class="docutils literal"><span class="pre">call_with_finalizer(0,false,...)</span></tt>.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.with_temp_object(obj,fn[,args...])</span></tt></p> +<p>Calls <tt class="docutils literal"><span class="pre">fn(obj,args...)</span></tt>, then finalizes with <tt class="docutils literal">obj:delete()</tt>.</p> +</li> +</ul> +</div> +<div class="section" id="persistent-configuration-storage"> +<h3><a class="toc-backref" href="#id16">Persistent configuration storage</a></h3> +<p>This api is intended for storing configuration options in the world itself. +It probably should be restricted to data that is world-dependent.</p> +<p>Entries are identified by a string <tt class="docutils literal">key</tt>, but it is also possible to manage +multiple entries with the same key; their identity is determined by <tt class="docutils literal">entry_id</tt>. +Every entry has a mutable string <tt class="docutils literal">value</tt>, and an array of 7 mutable <tt class="docutils literal">ints</tt>.</p> +<ul> +<li><p class="first"><tt class="docutils literal">dfhack.persistent.get(key)</tt>, <tt class="docutils literal">entry:get()</tt></p> +<p>Retrieves a persistent config record with the given string key, +or refreshes an already retrieved entry. If there are multiple +entries with the same key, it is undefined which one is retrieved +by the first version of the call.</p> +<p>Returns entry, or <em>nil</em> if not found.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.persistent.delete(key)</tt>, <tt class="docutils literal">entry:delete()</tt></p> +<p>Removes an existing entry. Returns <em>true</em> if succeeded.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.persistent.get_all(key[,match_prefix])</span></tt></p> +<p>Retrieves all entries with the same key, or starting with key..'/'. +Calling <tt class="docutils literal"><span class="pre">get_all('',true)</span></tt> will match all entries.</p> +<p>If none found, returns nil; otherwise returns an array of entries.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.persistent.save({key=str1,</span> <span class="pre">...}[,new])</span></tt>, <tt class="docutils literal"><span class="pre">entry:save([new])</span></tt></p> +<p>Saves changes in an entry, or creates a new one. Passing true as +new forces creation of a new entry even if one already exists; +otherwise the existing one is simply updated. +Returns <em>entry, did_create_new</em></p> +</li> +</ul> +<p>Since the data is hidden in data structures owned by the DF world, +and automatically stored in the save game, these save and retrieval +functions can just copy values in memory without doing any actual I/O. +However, currently every entry has a 180+-byte dead-weight overhead.</p> +</div> +<div class="section" id="material-info-lookup"> +<h3><a class="toc-backref" href="#id17">Material info lookup</a></h3> +<p>A material info record has fields:</p> +<ul> +<li><p class="first"><tt class="docutils literal">type</tt>, <tt class="docutils literal">index</tt>, <tt class="docutils literal">material</tt></p> +<p>DF material code pair, and a reference to the material object.</p> +</li> +<li><p class="first"><tt class="docutils literal">mode</tt></p> +<p>One of <tt class="docutils literal">'builtin'</tt>, <tt class="docutils literal">'inorganic'</tt>, <tt class="docutils literal">'plant'</tt>, <tt class="docutils literal">'creature'</tt>.</p> +</li> +<li><p class="first"><tt class="docutils literal">inorganic</tt>, <tt class="docutils literal">plant</tt>, <tt class="docutils literal">creature</tt></p> +<p>If the material is of the matching type, contains a reference to the raw object.</p> +</li> +<li><p class="first"><tt class="docutils literal">figure</tt></p> +<p>For a specific creature material contains a ref to the historical figure.</p> +</li> +</ul> +<p>Functions:</p> +<ul> +<li><p class="first"><tt class="docutils literal">dfhack.matinfo.decode(type,index)</tt></p> +<p>Looks up material info for the given number pair; if not found, returs <em>nil</em>.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">....decode(matinfo)</span></tt>, <tt class="docutils literal"><span class="pre">....decode(item)</span></tt>, <tt class="docutils literal"><span class="pre">....decode(obj)</span></tt></p> +<p>Uses <tt class="docutils literal">matinfo.type</tt>/<tt class="docutils literal">matinfo.index</tt>, item getter vmethods, +or <tt class="docutils literal">obj.mat_type</tt>/<tt class="docutils literal">obj.mat_index</tt> to get the code pair.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.matinfo.find(token[,token...])</span></tt></p> +<p>Looks up material by a token string, or a pre-split string token sequence.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.matinfo.getToken(...)</span></tt>, <tt class="docutils literal">info:getToken()</tt></p> +<p>Applies <tt class="docutils literal">decode</tt> and constructs a string token.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">info:toString([temperature[,named]])</span></tt></p> +<p>Returns the human-readable name at the given temperature.</p> +</li> +<li><p class="first"><tt class="docutils literal">info:getCraftClass()</tt></p> +<p>Returns the classification used for craft skills.</p> +</li> +<li><p class="first"><tt class="docutils literal">info:matches(obj)</tt></p> +<p>Checks if the material matches job_material_category or job_item. +Accept dfhack_material_category auto-assign table.</p> +</li> +</ul> +</div> +</div> +<div class="section" id="c-function-wrappers"> +<h2><a class="toc-backref" href="#id18">C++ function wrappers</a></h2> +<p>Thin wrappers around C++ functions, similar to the ones for virtual methods. +One notable difference is that these explicit wrappers allow argument count +adjustment according to the usual lua rules, so trailing false/nil arguments +can be omitted.</p> +<ul> +<li><p class="first"><tt class="docutils literal">dfhack.getOSType()</tt></p> +<p>Returns the OS type string from <tt class="docutils literal">symbols.xml</tt>.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.getDFVersion()</tt></p> +<p>Returns the DF version string from <tt class="docutils literal">symbols.xml</tt>.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.getDFPath()</tt></p> +<p>Returns the DF directory path.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.getHackPath()</tt></p> +<p>Returns the dfhack directory path, i.e. <tt class="docutils literal"><span class="pre">".../df/hack/"</span></tt>.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.getTickCount()</tt></p> +<p>Returns the tick count in ms, exactly as DF ui uses.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.isWorldLoaded()</tt></p> +<p>Checks if the world is loaded.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.isMapLoaded()</tt></p> +<p>Checks if the world and map are loaded.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.TranslateName(name[,in_english,only_last_name])</span></tt></p> +<p>Convert a language_name or only the last name part to string.</p> +</li> +</ul> +<div class="section" id="gui-module"> +<h3><a class="toc-backref" href="#id19">Gui module</a></h3> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.gui.getCurViewscreen([skip_dismissed])</span></tt></p> +<p>Returns the topmost viewscreen. If <tt class="docutils literal">skip_dismissed</tt> is <em>true</em>, +ignores screens already marked to be removed.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.gui.getFocusString(viewscreen)</tt></p> +<p>Returns a string representation of the current focus position +in the ui. The string has a "screen/foo/bar/baz..." format.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.gui.getCurFocus([skip_dismissed])</span></tt></p> +<p>Returns the focus string of the current viewscreen.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.gui.getSelectedWorkshopJob([silent])</span></tt></p> +<p>When a job is selected in <em>'q'</em> mode, returns the job, else +prints error unless silent and returns <em>nil</em>.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.gui.getSelectedJob([silent])</span></tt></p> +<p>Returns the job selected in a workshop or unit/jobs screen.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.gui.getSelectedUnit([silent])</span></tt></p> +<p>Returns the unit selected via <em>'v'</em>, <em>'k'</em>, unit/jobs, or +a full-screen item view of a cage or suchlike.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.gui.getSelectedItem([silent])</span></tt></p> +<p>Returns the item selected via <em>'v'</em> ->inventory, <em>'k'</em>, <em>'t'</em>, or +a full-screen item view of a container. Note that in the +last case, the highlighted <em>contained item</em> is returned, not +the container itself.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.gui.getSelectedBuilding([silent])</span></tt></p> +<p>Returns the building selected via <em>'q'</em>, <em>'t'</em>, <em>'k'</em> or <em>'i'</em>.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.gui.showAnnouncement(text,color[,is_bright])</span></tt></p> +<p>Adds a regular announcement with given text, color, and brightness. +The is_bright boolean actually seems to invert the brightness.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.gui.showZoomAnnouncement(type,pos,text,color[,is_bright])</span></tt></p> +<p>Like above, but also specifies a position you can zoom to from the announcement menu.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.gui.showPopupAnnouncement(text,color[,is_bright])</span></tt></p> +<p>Pops up a titan-style modal announcement window.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.gui.showAutoAnnouncement(type,pos,text,color[,is_bright])</span></tt></p> +<p>Uses the type to look up options from announcements.txt, and calls the +above operations accordingly. If enabled, pauses and zooms to position.</p> +</li> +</ul> +</div> +<div class="section" id="job-module"> +<h3><a class="toc-backref" href="#id20">Job module</a></h3> +<ul> +<li><p class="first"><tt class="docutils literal">dfhack.job.cloneJobStruct(job)</tt></p> +<p>Creates a deep copy of the given job.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.job.printJobDetails(job)</tt></p> +<p>Prints info about the job.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.job.printItemDetails(jobitem,idx)</tt></p> +<p>Prints info about the job item.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.job.getHolder(job)</tt></p> +<p>Returns the building holding the job.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.job.getWorker(job)</tt></p> +<p>Returns the unit performing the job.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.job.checkBuildingsNow()</tt></p> +<p>Instructs the game to check buildings for jobs next frame and assign workers.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.job.checkDesignationsNow()</tt></p> +<p>Instructs the game to check designations for jobs next frame and assign workers.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.job.is_equal(job1,job2)</tt></p> +<p>Compares important fields in the job and nested item structures.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.job.is_item_equal(job_item1,job_item2)</tt></p> +<p>Compares important fields in the job item structures.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.job.listNewlyCreated(first_id)</tt></p> +<p>Returns the current value of <tt class="docutils literal">df.global.job_next_id</tt>, and +if there are any jobs with <tt class="docutils literal">first_id <= id < job_next_id</tt>, +a lua list containing them.</p> +</li> +</ul> +</div> +<div class="section" id="units-module"> +<h3><a class="toc-backref" href="#id21">Units module</a></h3> +<ul> +<li><p class="first"><tt class="docutils literal">dfhack.units.getPosition(unit)</tt></p> +<p>Returns true <em>x,y,z</em> of the unit, or <em>nil</em> if invalid; may be not equal to unit.pos if caged.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.units.getContainer(unit)</tt></p> +<p>Returns the container (cage) item or <em>nil</em>.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.units.setNickname(unit,nick)</tt></p> +<p>Sets the unit's nickname properly.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.units.getVisibleName(unit)</tt></p> +<p>Returns the language_name object visible in game, accounting for false identities.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.units.getIdentity(unit)</tt></p> +<p>Returns the false identity of the unit if it has one, or <em>nil</em>.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.units.getNemesis(unit)</tt></p> +<p>Returns the nemesis record of the unit if it has one, or <em>nil</em>.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.units.isHidingCurse(unit)</tt></p> +<p>Checks if the unit hides improved attributes from its curse.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.units.getPhysicalAttrValue(unit, attr_type)</tt></p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.units.getMentalAttrValue(unit, attr_type)</tt></p> +<p>Computes the effective attribute value, including curse effect.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.units.isCrazed(unit)</tt></p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.units.isOpposedToLife(unit)</tt></p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.units.hasExtravision(unit)</tt></p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.units.isBloodsucker(unit)</tt></p> +<p>Simple checks of caste attributes that can be modified by curses.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.units.getMiscTrait(unit, type[, create])</tt></p> +<p>Finds (or creates if requested) a misc trait object with the given id.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.units.isDead(unit)</tt></p> +<p>The unit is completely dead and passive, or a ghost.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.units.isAlive(unit)</tt></p> +<p>The unit isn't dead or undead.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.units.isSane(unit)</tt></p> +<p>The unit is capable of rational action, i.e. not dead, insane, zombie, or active werewolf.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.units.isDwarf(unit)</tt></p> +<p>The unit is of the correct race of the fortress.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.units.isCitizen(unit)</tt></p> +<p>The unit is an alive sane citizen of the fortress; wraps the +same checks the game uses to decide game-over by extinction.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.units.getAge(unit[,true_age])</span></tt></p> +<p>Returns the age of the unit in years as a floating-point value. +If <tt class="docutils literal">true_age</tt> is true, ignores false identities.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.units.getNominalSkill(unit, skill[, use_rust])</tt></p> +<p>Retrieves the nominal skill level for the given unit. If <tt class="docutils literal">use_rust</tt> +is <em>true</em>, subtracts the rust penalty.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.units.getEffectiveSkill(unit, skill)</tt></p> +<p>Computes the effective rating for the given skill, taking into account exhaustion, pain etc.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.units.computeMovementSpeed(unit)</tt></p> +<p>Computes number of frames * 100 it takes the unit to move in its current state of mind and body.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.units.getNoblePositions(unit)</tt></p> +<p>Returns a list of tables describing noble position assignments, or <em>nil</em>. +Every table has fields <tt class="docutils literal">entity</tt>, <tt class="docutils literal">assignment</tt> and <tt class="docutils literal">position</tt>.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.units.getProfessionName(unit[,ignore_noble,plural])</span></tt></p> +<p>Retrieves the profession name using custom profession, noble assignments +or raws. The <tt class="docutils literal">ignore_noble</tt> boolean disables the use of noble positions.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.units.getCasteProfessionName(race,caste,prof_id[,plural])</span></tt></p> +<p>Retrieves the profession name for the given race/caste using raws.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.units.getProfessionColor(unit[,ignore_noble])</span></tt></p> +<p>Retrieves the color associated with the profession, using noble assignments +or raws. The <tt class="docutils literal">ignore_noble</tt> boolean disables the use of noble positions.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.units.getCasteProfessionColor(race,caste,prof_id)</tt></p> +<p>Retrieves the profession color for the given race/caste using raws.</p> +</li> +</ul> +</div> +<div class="section" id="items-module"> +<h3><a class="toc-backref" href="#id22">Items module</a></h3> +<ul> +<li><p class="first"><tt class="docutils literal">dfhack.items.getPosition(item)</tt></p> +<p>Returns true <em>x,y,z</em> of the item, or <em>nil</em> if invalid; may be not equal to item.pos if in inventory.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.items.getDescription(item, type[, decorate])</tt></p> +<p>Returns the string description of the item, as produced by the getItemDescription +method. If decorate is true, also adds markings for quality and improvements.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.items.getGeneralRef(item, type)</tt></p> +<p>Searches for a general_ref with the given type.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.items.getSpecificRef(item, type)</tt></p> +<p>Searches for a specific_ref with the given type.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.items.getOwner(item)</tt></p> +<p>Returns the owner unit or <em>nil</em>.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.items.setOwner(item,unit)</tt></p> +<p>Replaces the owner of the item. If unit is <em>nil</em>, removes ownership. +Returns <em>false</em> in case of error.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.items.getContainer(item)</tt></p> +<p>Returns the container item or <em>nil</em>.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.items.getContainedItems(item)</tt></p> +<p>Returns a list of items contained in this one.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.items.moveToGround(item,pos)</tt></p> +<p>Move the item to the ground at position. Returns <em>false</em> if impossible.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.items.moveToContainer(item,container)</tt></p> +<p>Move the item to the container. Returns <em>false</em> if impossible.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.items.moveToBuilding(item,building,use_mode)</tt></p> +<p>Move the item to the building. Returns <em>false</em> if impossible.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.items.moveToInventory(item,unit,use_mode,body_part)</tt></p> +<p>Move the item to the unit inventory. Returns <em>false</em> if impossible.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.items.remove(item[, no_uncat])</tt></p> +<p>Removes the item, and marks it for garbage collection unless <tt class="docutils literal">no_uncat</tt> is true.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.items.makeProjectile(item)</tt></p> +<p>Turns the item into a projectile, and returns the new object, or <em>nil</em> if impossible.</p> +</li> +</ul> +</div> +<div class="section" id="maps-module"> +<h3><a class="toc-backref" href="#id23">Maps module</a></h3> +<ul> +<li><p class="first"><tt class="docutils literal">dfhack.maps.getSize()</tt></p> +<p>Returns map size in blocks: <em>x, y, z</em></p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.maps.getTileSize()</tt></p> +<p>Returns map size in tiles: <em>x, y, z</em></p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.maps.getBlock(x,y,z)</tt></p> +<p>Returns a map block object for given x,y,z in local block coordinates.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.maps.isValidTilePos(coords)</tt>, or isValidTilePos(x,y,z)``</p> +<p>Checks if the given df::coord or x,y,z in local tile coordinates are valid.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.maps.getTileBlock(coords)</tt>, or <tt class="docutils literal">getTileBlock(x,y,z)</tt></p> +<p>Returns a map block object for given df::coord or x,y,z in local tile coordinates.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.maps.ensureTileBlock(coords)</tt>, or <tt class="docutils literal">ensureTileBlock(x,y,z)</tt></p> +<p>Like <tt class="docutils literal">getTileBlock</tt>, but if the block is not allocated, try creating it.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.maps.getRegionBiome(region_coord2d)</tt>, or <tt class="docutils literal">getRegionBiome(x,y)</tt></p> +<p>Returns the biome info struct for the given global map region.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.maps.enableBlockUpdates(block[,flow,temperature])</span></tt></p> +<p>Enables updates for liquid flow or temperature, unless already active.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.maps.spawnFlow(pos,type,mat_type,mat_index,dimension)</tt></p> +<p>Spawns a new flow (i.e. steam/mist/dust/etc) at the given pos, and with +the given parameters. Returns it, or <em>nil</em> if unsuccessful.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.maps.getGlobalInitFeature(index)</tt></p> +<p>Returns the global feature object with the given index.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.maps.getLocalInitFeature(region_coord2d,index)</tt></p> +<p>Returns the local feature object with the given region coords and index.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.maps.getTileBiomeRgn(coords)</tt>, or <tt class="docutils literal">getTileBiomeRgn(x,y,z)</tt></p> +<p>Returns <em>x, y</em> for use with <tt class="docutils literal">getRegionBiome</tt>.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.maps.canWalkBetween(pos1, pos2)</tt></p> +<p>Checks if a dwarf may be able to walk between the two tiles, +using a pathfinding cache maintained by the game. Note that +this cache is only updated when the game is unpaused, and thus +can get out of date if doors are forbidden or unforbidden, or +tools like liquids or tiletypes are used. It also cannot possibly +take into account anything that depends on the actual units, like +burrows, or the presence of invaders.</p> +</li> +</ul> +</div> +<div class="section" id="burrows-module"> +<h3><a class="toc-backref" href="#id24">Burrows module</a></h3> +<ul> +<li><p class="first"><tt class="docutils literal">dfhack.burrows.findByName(name)</tt></p> +<p>Returns the burrow pointer or <em>nil</em>.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.burrows.clearUnits(burrow)</tt></p> +<p>Removes all units from the burrow.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.burrows.isAssignedUnit(burrow,unit)</tt></p> +<p>Checks if the unit is in the burrow.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.burrows.setAssignedUnit(burrow,unit,enable)</tt></p> +<p>Adds or removes the unit from the burrow.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.burrows.clearTiles(burrow)</tt></p> +<p>Removes all tiles from the burrow.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.burrows.listBlocks(burrow)</tt></p> +<p>Returns a table of map block pointers.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.burrows.isAssignedTile(burrow,tile_coord)</tt></p> +<p>Checks if the tile is in burrow.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.burrows.setAssignedTile(burrow,tile_coord,enable)</tt></p> +<p>Adds or removes the tile from the burrow. Returns <em>false</em> if invalid coords.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.burrows.isAssignedBlockTile(burrow,block,x,y)</tt></p> +<p>Checks if the tile within the block is in burrow.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.burrows.setAssignedBlockTile(burrow,block,x,y,enable)</tt></p> +<p>Adds or removes the tile from the burrow. Returns <em>false</em> if invalid coords.</p> +</li> +</ul> +</div> +<div class="section" id="buildings-module"> +<h3><a class="toc-backref" href="#id25">Buildings module</a></h3> +<ul> +<li><p class="first"><tt class="docutils literal">dfhack.buildings.setOwner(item,unit)</tt></p> +<p>Replaces the owner of the building. If unit is <em>nil</em>, removes ownership. +Returns <em>false</em> in case of error.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.buildings.getSize(building)</tt></p> +<p>Returns <em>width, height, centerx, centery</em>.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.buildings.findAtTile(pos)</tt>, or <tt class="docutils literal">findAtTile(x,y,z)</tt></p> +<p>Scans the buildings for the one located at the given tile. +Does not work on civzones. Warning: linear scan if the map +tile indicates there are buildings at it.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.buildings.findCivzonesAt(pos)</tt>, or <tt class="docutils literal">findCivzonesAt(x,y,z)</tt></p> +<p>Scans civzones, and returns a lua sequence of those that touch +the given tile, or <em>nil</em> if none.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.buildings.getCorrectSize(width, height, type, subtype, custom, direction)</tt></p> +<p>Computes correct dimensions for the specified building type and orientation, +using width and height for flexible dimensions. +Returns <em>is_flexible, width, height, center_x, center_y</em>.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.buildings.checkFreeTiles(pos,size[,extents,change_extents,allow_occupied])</span></tt></p> +<p>Checks if the rectangle defined by <tt class="docutils literal">pos</tt> and <tt class="docutils literal">size</tt>, and possibly extents, +can be used for placing a building. If <tt class="docutils literal">change_extents</tt> is true, bad tiles +are removed from extents. If <tt class="docutils literal">allow_occupied</tt>, the occupancy test is skipped.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.buildings.countExtentTiles(extents,defval)</tt></p> +<p>Returns the number of tiles included by extents, or defval.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.buildings.containsTile(building, x, y[, room])</tt></p> +<p>Checks if the building contains the specified tile, either directly, or as room.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.buildings.hasSupport(pos,size)</tt></p> +<p>Checks if a bridge constructed at specified position would have +support from terrain, and thus won't collapse if retracted.</p> +</li> +</ul> +<p>Low-level building creation functions;</p> +<ul> +<li><p class="first"><tt class="docutils literal">dfhack.buildings.allocInstance(pos, type, subtype, custom)</tt></p> +<p>Creates a new building instance of given type, subtype and custom type, +at specified position. Returns the object, or <em>nil</em> in case of an error.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.buildings.setSize(building, width, height, direction)</tt></p> +<p>Configures an object returned by <tt class="docutils literal">allocInstance</tt>, using specified +parameters wherever appropriate. If the building has fixed size along +any dimension, the corresponding input parameter will be ignored. +Returns <em>false</em> if the building cannot be placed, or <em>true, width, +height, rect_area, true_area</em>. Returned width and height are the +final values used by the building; true_area is less than rect_area +if any tiles were removed from designation.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.buildings.constructAbstract(building)</tt></p> +<p>Links a fully configured object created by <tt class="docutils literal">allocInstance</tt> into the +world. The object must be an abstract building, i.e. a stockpile or civzone. +Returns <em>true</em>, or <em>false</em> if impossible.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.buildings.constructWithItems(building, items)</tt></p> +<p>Links a fully configured object created by <tt class="docutils literal">allocInstance</tt> into the +world for construction, using a list of specific items as material. +Returns <em>true</em>, or <em>false</em> if impossible.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.buildings.constructWithFilters(building, job_items)</tt></p> +<p>Links a fully configured object created by <tt class="docutils literal">allocInstance</tt> into the +world for construction, using a list of job_item filters as inputs. +Returns <em>true</em>, or <em>false</em> if impossible. Filter objects are claimed +and possibly destroyed in any case. +Use a negative <tt class="docutils literal">quantity</tt> field value to auto-compute the amount +from the size of the building.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.buildings.deconstruct(building)</tt></p> +<p>Destroys the building, or queues a deconstruction job. +Returns <em>true</em> if the building was destroyed and deallocated immediately.</p> +</li> +</ul> +<p>More high-level functions are implemented in lua and can be loaded by +<tt class="docutils literal"><span class="pre">require('dfhack.buildings')</span></tt>. See <tt class="docutils literal">hack/lua/dfhack/buildings.lua</tt>.</p> +<p>Among them are:</p> +<ul> +<li><p class="first"><tt class="docutils literal">dfhack.buildings.getFiltersByType(argtable,type,subtype,custom)</tt></p> +<p>Returns a sequence of lua structures, describing input item filters +suitable for the specified building type, or <em>nil</em> if unknown or invalid. +The returned sequence is suitable for use as the <tt class="docutils literal">job_items</tt> argument +of <tt class="docutils literal">constructWithFilters</tt>. +Uses tables defined in <tt class="docutils literal">buildings.lua</tt>.</p> +<p>Argtable members <tt class="docutils literal">material</tt> (the default name), <tt class="docutils literal">bucket</tt>, <tt class="docutils literal">barrel</tt>, +<tt class="docutils literal">chain</tt>, <tt class="docutils literal">mechanism</tt>, <tt class="docutils literal">screw</tt>, <tt class="docutils literal">pipe</tt>, <tt class="docutils literal">anvil</tt>, <tt class="docutils literal">weapon</tt> are used to +augment the basic attributes with more detailed information if the +building has input items with the matching name (see the tables for naming details). +Note that it is impossible to <em>override</em> any properties this way, only supply those that +are not mentioned otherwise; one exception is that flags2.non_economic +is automatically cleared if an explicit material is specified.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.buildings.constructBuilding{...}</span></tt></p> +<p>Creates a building in one call, using options contained +in the argument table. Returns the building, or <em>nil, error</em>.</p> +<p><strong>NOTE:</strong> Despite the name, unless the building is abstract, +the function creates it in an 'unconstructed' stage, with +a queued in-game job that will actually construct it. I.e. +the function replicates programmatically what can be done +through the construct building menu in the game ui, except +that it does less environment constraint checking.</p> +<p>The following options can be used:</p> +<ul> +<li><p class="first"><tt class="docutils literal">pos = coordinates</tt>, or <tt class="docutils literal">x = <span class="pre">...,</span> y = <span class="pre">...,</span> z = ...</tt></p> +<p>Mandatory. Specifies the left upper corner of the building.</p> +</li> +<li><p class="first"><tt class="docutils literal">type = df.building_type.FOO, subtype = <span class="pre">...,</span> custom = ...</tt></p> +<p>Mandatory. Specifies the type of the building. Obviously, subtype +and custom are only expected if the type requires them.</p> +</li> +<li><p class="first"><tt class="docutils literal">fields = { ... }</tt></p> +<p>Initializes fields of the building object after creation with <tt class="docutils literal">df.assign</tt>.</p> +</li> +<li><p class="first"><tt class="docutils literal">width = <span class="pre">...,</span> height = <span class="pre">...,</span> direction = ...</tt></p> +<p>Sets size and orientation of the building. If it is +fixed-size, specified dimensions are ignored.</p> +</li> +<li><p class="first"><tt class="docutils literal">full_rectangle = true</tt></p> +<p>For buildings like stockpiles or farm plots that can normally +accomodate individual tile exclusion, forces an error if any +tiles within the specified width*height are obstructed.</p> +</li> +<li><p class="first"><tt class="docutils literal">items = { item, item ... }</tt>, or <tt class="docutils literal">filters = { <span class="pre">{...},</span> <span class="pre">{...}...</span> }</tt></p> +<p>Specifies explicit items or item filters to use in construction. +It is the job of the user to ensure they are correct for the building type.</p> +</li> +<li><p class="first"><tt class="docutils literal">abstract = true</tt></p> +<p>Specifies that the building is abstract and does not require construction. +Required for stockpiles and civzones; an error otherwise.</p> +</li> +<li><p class="first"><tt class="docutils literal">material = <span class="pre">{...},</span> mechanism = <span class="pre">{...},</span> ...</tt></p> +<p>If none of <tt class="docutils literal">items</tt>, <tt class="docutils literal">filter</tt>, or <tt class="docutils literal">abstract</tt> is used, +the function uses <tt class="docutils literal">getFiltersByType</tt> to compute the input +item filters, and passes the argument table through. If no filters +can be determined this way, <tt class="docutils literal">constructBuilding</tt> throws an error.</p> +</li> +</ul> +</li> +</ul> +</div> +<div class="section" id="constructions-module"> +<h3><a class="toc-backref" href="#id26">Constructions module</a></h3> +<ul> +<li><p class="first"><tt class="docutils literal">dfhack.constructions.designateNew(pos,type,item_type,mat_index)</tt></p> +<p>Designates a new construction at given position. If there already is +a planned but not completed construction there, changes its type. +Returns <em>true</em>, or <em>false</em> if obstructed. +Note that designated constructions are technically buildings.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.constructions.designateRemove(pos)</tt>, or <tt class="docutils literal">designateRemove(x,y,z)</tt></p> +<p>If there is a construction or a planned construction at the specified +coordinates, designates it for removal, or instantly cancels the planned one. +Returns <em>true, was_only_planned</em> if removed; or <em>false</em> if none found.</p> +</li> +</ul> +</div> +<div class="section" id="screen-api"> +<h3><a class="toc-backref" href="#id27">Screen API</a></h3> +<p>The screen module implements support for drawing to the tiled screen of the game. +Note that drawing only has any effect when done from callbacks, so it can only +be feasibly used in the core context.</p> +<p>Basic painting functions:</p> +<ul> +<li><p class="first"><tt class="docutils literal">dfhack.screen.getWindowSize()</tt></p> +<p>Returns <em>width, height</em> of the screen.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.screen.getMousePos()</tt></p> +<p>Returns <em>x,y</em> of the tile the mouse is over.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.screen.inGraphicsMode()</tt></p> +<p>Checks if [GRAPHICS:YES] was specified in init.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.screen.paintTile(pen,x,y[,char,tile])</span></tt></p> +<p>Paints a tile using given parameters. Pen is a table with following possible fields:</p> +<dl class="docutils"> +<dt><tt class="docutils literal">ch</tt></dt> +<dd><p class="first last">Provides the ordinary tile character, as either a 1-character string or a number. +Can be overridden with the <tt class="docutils literal">char</tt> function parameter.</p> +</dd> +<dt><tt class="docutils literal">fg</tt></dt> +<dd><p class="first last">Foreground color for the ordinary tile. Defaults to COLOR_GREY (7).</p> +</dd> +<dt><tt class="docutils literal">bg</tt></dt> +<dd><p class="first last">Background color for the ordinary tile. Defaults to COLOR_BLACK (0).</p> +</dd> +<dt><tt class="docutils literal">bold</tt></dt> +<dd><p class="first last">Bright/bold text flag. If <em>nil</em>, computed based on (fg & 8); fg is masked to 3 bits. +Otherwise should be <em>true/false</em>.</p> +</dd> +<dt><tt class="docutils literal">tile</tt></dt> +<dd><p class="first last">Graphical tile id. Ignored unless [GRAPHICS:YES] was in init.txt.</p> +</dd> +<dt><tt class="docutils literal">tile_color = true</tt></dt> +<dd><p class="first last">Specifies that the tile should be shaded with <em>fg/bg</em>.</p> +</dd> +<dt><tt class="docutils literal">tile_fg, tile_bg</tt></dt> +<dd><p class="first last">If specified, overrides <em>tile_color</em> and supplies shading colors directly.</p> +</dd> +</dl> +<p>Returns <em>false</em> if coordinates out of bounds, or other error.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.screen.readTile(x,y)</tt></p> +<p>Retrieves the contents of the specified tile from the screen buffers. +Returns a pen, or <em>nil</em> if invalid or TrueType.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.screen.paintString(pen,x,y,text)</tt></p> +<p>Paints the string starting at <em>x,y</em>. Uses the string characters +in sequence to override the <tt class="docutils literal">ch</tt> field of pen.</p> +<p>Returns <em>true</em> if painting at least one character succeeded.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.screen.fillRect(pen,x1,y1,x2,y2)</tt></p> +<p>Fills the rectangle specified by the coordinates with the given pen. +Returns <em>true</em> if painting at least one character succeeded.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.screen.findGraphicsTile(pagename,x,y)</tt></p> +<p>Finds a tile from a graphics set (i.e. the raws used for creatures), +if in graphics mode and loaded.</p> +<p>Returns: <em>tile, tile_grayscale</em>, or <em>nil</em> if not found. +The values can then be used for the <em>tile</em> field of <em>pen</em> structures.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.screen.clear()</tt></p> +<p>Fills the screen with blank background.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.screen.invalidate()</tt></p> +<p>Requests repaint of the screen by setting a flag. Unlike other +functions in this section, this may be used at any time.</p> +</li> +</ul> +<p>In order to actually be able to paint to the screen, it is necessary +to create and register a viewscreen (basically a modal dialog) with +the game.</p> +<p><strong>NOTE</strong>: As a matter of policy, in order to avoid user confusion, all +interface screens added by dfhack should bear the "DFHack" signature.</p> +<p>Screens are managed with the following functions:</p> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.screen.show(screen[,below])</span></tt></p> +<p>Displays the given screen, possibly placing it below a different one. +The screen must not be already shown. Returns <em>true</em> if success.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.screen.dismiss(screen[,to_first])</span></tt></p> +<p>Marks the screen to be removed when the game enters its event loop. +If <tt class="docutils literal">to_first</tt> is <em>true</em>, all screens up to the first one will be deleted.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.screen.isDismissed(screen)</tt></p> +<p>Checks if the screen is already marked for removal.</p> +</li> +</ul> +<p>Apart from a native viewscreen object, these functions accept a table +as a screen. In this case, <tt class="docutils literal">show</tt> creates a new native viewscreen +that delegates all processing to methods stored in that table.</p> +<p><strong>NOTE</strong>: Lua-implemented screens are only supported in the core context.</p> +<p>Supported callbacks and fields are:</p> +<ul> +<li><p class="first"><tt class="docutils literal">screen._native</tt></p> +<p>Initialized by <tt class="docutils literal">show</tt> with a reference to the backing viewscreen +object, and removed again when the object is deleted.</p> +</li> +<li><p class="first"><tt class="docutils literal">function screen:onShow()</tt></p> +<p>Called by <tt class="docutils literal">dfhack.screen.show</tt> if successful.</p> +</li> +<li><p class="first"><tt class="docutils literal">function screen:onDismiss()</tt></p> +<p>Called by <tt class="docutils literal">dfhack.screen.dismiss</tt> if successful.</p> +</li> +<li><p class="first"><tt class="docutils literal">function screen:onDestroy()</tt></p> +<p>Called from the destructor when the viewscreen is deleted.</p> +</li> +<li><p class="first"><tt class="docutils literal">function screen:onResize(w, h)</tt></p> +<p>Called before <tt class="docutils literal">onRender</tt> or <tt class="docutils literal">onIdle</tt> when the window size has changed.</p> +</li> +<li><p class="first"><tt class="docutils literal">function screen:onRender()</tt></p> +<p>Called when the viewscreen should paint itself. This is the only context +where the above painting functions work correctly.</p> +<p>If omitted, the screen is cleared; otherwise it should do that itself. +In order to make a see-through dialog, call <tt class="docutils literal">self._native.parent:render()</tt>.</p> +</li> +<li><p class="first"><tt class="docutils literal">function screen:onIdle()</tt></p> +<p>Called every frame when the screen is on top of the stack.</p> +</li> +<li><p class="first"><tt class="docutils literal">function screen:onHelp()</tt></p> +<p>Called when the help keybinding is activated (usually '?').</p> +</li> +<li><p class="first"><tt class="docutils literal">function screen:onInput(keys)</tt></p> +<p>Called when keyboard or mouse events are available. +If any keys are pressed, the keys argument is a table mapping them to <em>true</em>. +Note that this refers to logical keybingings computed from real keys via +options; if multiple interpretations exist, the table will contain multiple keys.</p> +<p>The table also may contain special keys:</p> +<dl class="docutils"> +<dt><tt class="docutils literal">_STRING</tt></dt> +<dd><p class="first last">Maps to an integer in range 0-255. Duplicates a separate "STRING_A???" code for convenience.</p> +</dd> +<dt><tt class="docutils literal">_MOUSE_L, _MOUSE_R</tt></dt> +<dd><p class="first last">If the left or right mouse button is pressed.</p> +</dd> +</dl> +<p>If this method is omitted, the screen is dismissed on receival of the <tt class="docutils literal">LEAVESCREEN</tt> key.</p> +</li> +<li><p class="first"><tt class="docutils literal">function screen:onGetSelectedUnit()</tt></p> +</li> +<li><p class="first"><tt class="docutils literal">function screen:onGetSelectedItem()</tt></p> +</li> +<li><p class="first"><tt class="docutils literal">function screen:onGetSelectedJob()</tt></p> +</li> +<li><p class="first"><tt class="docutils literal">function screen:onGetSelectedBuilding()</tt></p> +<p>Implement these to provide a return value for the matching +<tt class="docutils literal"><span class="pre">dfhack.gui.getSelected...</span></tt> function.</p> +</li> +</ul> +</div> +<div class="section" id="internal-api"> +<h3><a class="toc-backref" href="#id28">Internal API</a></h3> +<p>These functions are intended for the use by dfhack developers, +and are only documented here for completeness:</p> +<ul> +<li><p class="first"><tt class="docutils literal">dfhack.internal.scripts</tt></p> +<p>The table used by <tt class="docutils literal">dfhack.run_script()</tt> to give every script its own +global environment, persistent between calls to the script.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.internal.getAddress(name)</tt></p> +<p>Returns the global address <tt class="docutils literal">name</tt>, or <em>nil</em>.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.internal.setAddress(name, value)</tt></p> +<p>Sets the global address <tt class="docutils literal">name</tt>. Returns the value of <tt class="docutils literal">getAddress</tt> before the change.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.internal.getVTable(name)</tt></p> +<p>Returns the pre-extracted vtable address <tt class="docutils literal">name</tt>, or <em>nil</em>.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.internal.getRebaseDelta()</tt></p> +<p>Returns the ASLR rebase offset of the DF executable.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.internal.getMemRanges()</tt></p> +<p>Returns a sequence of tables describing virtual memory ranges of the process.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.internal.patchMemory(dest,src,count)</tt></p> +<p>Like memmove below, but works even if dest is read-only memory, e.g. code. +If destination overlaps a completely invalid memory region, or another error +occurs, returns false.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.internal.memmove(dest,src,count)</tt></p> +<p>Wraps the standard memmove function. Accepts both numbers and refs as pointers.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.internal.memcmp(ptr1,ptr2,count)</tt></p> +<p>Wraps the standard memcmp function.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.internal.memscan(haystack,count,step,needle,nsize)</tt></p> +<p>Searches for <tt class="docutils literal">needle</tt> of <tt class="docutils literal">nsize</tt> bytes in <tt class="docutils literal">haystack</tt>, +using <tt class="docutils literal">count</tt> steps of <tt class="docutils literal">step</tt> bytes. +Returns: <em>step_idx, sum_idx, found_ptr</em>, or <em>nil</em> if not found.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.internal.diffscan(old_data, new_data, start_idx, end_idx, eltsize[, oldval, newval, delta])</tt></p> +<p>Searches for differences between buffers at ptr1 and ptr2, as integers of size eltsize. +The oldval, newval or delta arguments may be used to specify additional constraints. +Returns: <em>found_index</em>, or <em>nil</em> if end reached.</p> +</li> +</ul> +</div> +</div> +<div class="section" id="core-interpreter-context"> +<h2><a class="toc-backref" href="#id29">Core interpreter context</a></h2> +<p>While plugins can create any number of interpreter instances, +there is one special context managed by dfhack core. It is the +only context that can receive events from DF and plugins.</p> +<p>Core context specific functions:</p> +<ul> +<li><p class="first"><tt class="docutils literal">dfhack.is_core_context</tt></p> +<p>Boolean value; <em>true</em> in the core context.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.timeout(time,mode,callback)</tt></p> +<p>Arranges for the callback to be called once the specified +period of time passes. The <tt class="docutils literal">mode</tt> argument specifies the +unit of time used, and may be one of <tt class="docutils literal">'frames'</tt> (raw FPS), +<tt class="docutils literal">'ticks'</tt> (unpaused FPS), <tt class="docutils literal">'days'</tt>, <tt class="docutils literal">'months'</tt>, +<tt class="docutils literal">'years'</tt> (in-game time). All timers other than +<tt class="docutils literal">'frames'</tt> are cancelled when the world is unloaded, +and cannot be queued until it is loaded again. +Returns the timer id, or <em>nil</em> if unsuccessful due to +world being unloaded.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.timeout_active(id[,new_callback])</span></tt></p> +<p>Returns the active callback with the given id, or <em>nil</em> +if inactive or nil id. If called with 2 arguments, replaces +the current callback with the given value, if still active. +Using <tt class="docutils literal">timeout_active(id,nil)</tt> cancels the timer.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.onStateChange.foo = function(code)</tt></p> +<p>Event. Receives the same codes as plugin_onstatechange in C++.</p> +</li> +</ul> +<div class="section" id="event-type"> +<h3><a class="toc-backref" href="#id30">Event type</a></h3> +<p>An event is a native object transparently wrapping a lua table, +and implementing a __call metamethod. When it is invoked, it loops +through the table with next and calls all contained values. +This is intended as an extensible way to add listeners.</p> +<p>This type itself is available in any context, but only the +core context has the actual events defined by C++ code.</p> +<p>Features:</p> +<ul> +<li><p class="first"><tt class="docutils literal">dfhack.event.new()</tt></p> +<p>Creates a new instance of an event.</p> +</li> +<li><p class="first"><tt class="docutils literal">event[key] = function</tt></p> +<p>Sets the function as one of the listeners. Assign <em>nil</em> to remove it.</p> +<p><strong>NOTE</strong>: The <tt class="docutils literal">df.NULL</tt> key is reserved for the use by +the C++ owner of the event; it is an error to try setting it.</p> +</li> +<li><p class="first"><tt class="docutils literal">#event</tt></p> +<p>Returns the number of non-nil listeners.</p> +</li> +<li><p class="first"><tt class="docutils literal">pairs(event)</tt></p> +<p>Iterates over all listeners in the table.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">event(args...)</span></tt></p> +<p>Invokes all listeners contained in the event in an arbitrary +order using <tt class="docutils literal">dfhack.safecall</tt>.</p> +</li> +</ul> +</div> +</div> +</div> +<div class="section" id="lua-modules"> +<h1><a class="toc-backref" href="#id31">Lua Modules</a></h1> +<p>DFHack sets up the lua interpreter so that the built-in <tt class="docutils literal">require</tt> +function can be used to load shared lua code from hack/lua/. +The <tt class="docutils literal">dfhack</tt> namespace reference itself may be obtained via +<tt class="docutils literal"><span class="pre">require('dfhack')</span></tt>, although it is initially created as a +global by C++ bootstrap code.</p> +<p>The following module management functions are provided:</p> +<ul> +<li><p class="first"><tt class="docutils literal">mkmodule(name)</tt></p> +<p>Creates an environment table for the module. Intended to be used as:</p> +<pre class="literal-block"> +local _ENV = mkmodule('foo') +... +return _ENV +</pre> +<p>If called the second time, returns the same table; thus providing reload support.</p> +</li> +<li><p class="first"><tt class="docutils literal">reload(name)</tt></p> +<p>Reloads a previously <tt class="docutils literal">require</tt>-d module <em>"name"</em> from the file. +Intended as a help for module development.</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.BASE_G</tt></p> +<p>This variable contains the root global environment table, which is +used as a base for all module and script environments. Its contents +should be kept limited to the standard Lua library and API described +in this document.</p> +</li> +</ul> +<div class="section" id="global-environment"> +<h2><a class="toc-backref" href="#id32">Global environment</a></h2> +<p>A number of variables and functions are provided in the base global +environment by the mandatory init file dfhack.lua:</p> +<ul> +<li><p class="first">Color constants</p> +<p>These are applicable both for <tt class="docutils literal">dfhack.color()</tt> and color fields +in DF functions or structures:</p> +<p>COLOR_RESET, COLOR_BLACK, COLOR_BLUE, COLOR_GREEN, COLOR_CYAN, +COLOR_RED, COLOR_MAGENTA, COLOR_BROWN, COLOR_GREY, COLOR_DARKGREY, +COLOR_LIGHTBLUE, COLOR_LIGHTGREEN, COLOR_LIGHTCYAN, COLOR_LIGHTRED, +COLOR_LIGHTMAGENTA, COLOR_YELLOW, COLOR_WHITE</p> +</li> +<li><p class="first"><tt class="docutils literal">dfhack.onStateChange</tt> event codes</p> +<p>Available only in the core context, as is the event itself:</p> +<p>SC_WORLD_LOADED, SC_WORLD_UNLOADED, SC_MAP_LOADED, +SC_MAP_UNLOADED, SC_VIEWSCREEN_CHANGED, SC_CORE_INITIALIZED</p> +</li> +<li><p class="first">Functions already described above</p> +<p>safecall, qerror, mkmodule, reload</p> +</li> +<li><p class="first"><tt class="docutils literal">printall(obj)</tt></p> +<p>If the argument is a lua table or DF object reference, prints all fields.</p> +</li> +<li><p class="first"><tt class="docutils literal">copyall(obj)</tt></p> +<p>Returns a shallow copy of the table or reference as a lua table.</p> +</li> +<li><p class="first"><tt class="docutils literal">pos2xyz(obj)</tt></p> +<p>The object must have fields x, y and z. Returns them as 3 values. +If obj is <em>nil</em>, or x is -30000 (the usual marker for undefined +coordinates), returns <em>nil</em>.</p> +</li> +<li><p class="first"><tt class="docutils literal">xyz2pos(x,y,z)</tt></p> +<p>Returns a table with x, y and z as fields.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">safe_index(obj,index...)</span></tt></p> +<p>Walks a sequence of dereferences, which may be represented by numbers or strings. +Returns <em>nil</em> if any of obj or indices is <em>nil</em>, or a numeric index is out of array bounds.</p> +</li> +</ul> +</div> +<div class="section" id="utils"> +<h2><a class="toc-backref" href="#id33">utils</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal">utils.compare(a,b)</tt></p> +<p>Comparator function; returns <em>-1</em> if a<b, <em>1</em> if a>b, <em>0</em> otherwise.</p> +</li> +<li><p class="first"><tt class="docutils literal">utils.compare_name(a,b)</tt></p> +<p>Comparator for names; compares empty string last.</p> +</li> +<li><p class="first"><tt class="docutils literal">utils.is_container(obj)</tt></p> +<p>Checks if obj is a container ref.</p> +</li> +<li><p class="first"><tt class="docutils literal">utils.make_index_sequence(start,end)</tt></p> +<p>Returns a lua sequence of numbers in start..end.</p> +</li> +<li><p class="first"><tt class="docutils literal">utils.make_sort_order(data, ordering)</tt></p> +<p>Computes a sorted permutation of objects in data, as a table of integer +indices into the data sequence. Uses <tt class="docutils literal">data.n</tt> as input length +if present.</p> +<p>The ordering argument is a sequence of ordering specs, represented +as lua tables with following possible fields:</p> +<dl class="docutils"> +<dt>ord.key = <em>function(value)</em></dt> +<dd><p class="first last">Computes comparison key from input data value. Not called on nil. +If omitted, the comparison key is the value itself.</p> +</dd> +<dt>ord.key_table = <em>function(data)</em></dt> +<dd><p class="first last">Computes a key table from the data table in one go.</p> +</dd> +<dt>ord.compare = <em>function(a,b)</em></dt> +<dd><p class="first last">Comparison function. Defaults to <tt class="docutils literal">utils.compare</tt> above. +Called on non-nil keys; nil sorts last.</p> +</dd> +<dt>ord.nil_first = <em>true/false</em></dt> +<dd><p class="first last">If true, nil keys are sorted first instead of last.</p> +</dd> +<dt>ord.reverse = <em>true/false</em></dt> +<dd><p class="first last">If true, sort non-nil keys in descending order.</p> +</dd> +</dl> +<p>For every comparison during sorting the specs are applied in +order until an unambiguous decision is reached. Sorting is stable.</p> +<p>Example of sorting a sequence by field foo:</p> +<pre class="literal-block"> +local spec = { key = function(v) return v.foo end } +local order = utils.make_sort_order(data, { spec }) +local output = {} +for i = 1,#order do output[i] = data[order[i]] end +</pre> +<p>Separating the actual reordering of the sequence in this +way enables applying the same permutation to multiple arrays. +This function is used by the sort plugin.</p> +</li> +<li><p class="first"><tt class="docutils literal">utils.assign(tgt, src)</tt></p> +<p>Does a recursive assignment of src into tgt. +Uses <tt class="docutils literal">df.assign</tt> if tgt is a native object ref; otherwise +recurses into lua tables.</p> +</li> +<li><p class="first"><tt class="docutils literal">utils.clone(obj, deep)</tt></p> +<p>Performs a shallow, or semi-deep copy of the object as a lua table tree. +The deep mode recurses into lua tables and subobjects, except pointers +to other heap objects. +Null pointers are represented as df.NULL. Zero-based native containers +are converted to 1-based lua sequences.</p> +</li> +<li><p class="first"><tt class="docutils literal">utils.clone_with_default(obj, default, force)</tt></p> +<p>Copies the object, using the <tt class="docutils literal">default</tt> lua table tree +as a guide to which values should be skipped as uninteresting. +The <tt class="docutils literal">force</tt> argument makes it always return a non-<em>nil</em> value.</p> +</li> +<li><p class="first"><tt class="docutils literal">utils.sort_vector(vector,field,cmpfun)</tt></p> +<p>Sorts a native vector or lua sequence using the comparator function. +If <tt class="docutils literal">field</tt> is not <em>nil</em>, applies the comparator to the field instead +of the whole object.</p> +</li> +<li><p class="first"><tt class="docutils literal">utils.binsearch(vector,key,field,cmpfun,min,max)</tt></p> +<p>Does a binary search in a native vector or lua sequence for +<tt class="docutils literal">key</tt>, using <tt class="docutils literal">cmpfun</tt> and <tt class="docutils literal">field</tt> like sort_vector. +If <tt class="docutils literal">min</tt> and <tt class="docutils literal">max</tt> are specified, they are used as the +search subrange bounds.</p> +<p>If found, returns <em>item, true, idx</em>. Otherwise returns +<em>nil, false, insert_idx</em>, where <em>insert_idx</em> is the correct +insertion point.</p> +</li> +<li><p class="first"><tt class="docutils literal">utils.insert_sorted(vector,item,field,cmpfun)</tt></p> +<p>Does a binary search, and inserts item if not found. +Returns <em>did_insert, vector[idx], idx</em>.</p> +</li> +<li><p class="first"><tt class="docutils literal">utils.insert_or_update(vector,item,field,cmpfun)</tt></p> +<p>Like <tt class="docutils literal">insert_sorted</tt>, but also assigns the item into +the vector cell if insertion didn't happen.</p> +<p>As an example, you can use this to set skill values:</p> +<pre class="literal-block"> +utils.insert_or_update(soul.skills, {new=true, id=..., rating=...}, 'id') +</pre> +<p>(For an explanation of <tt class="docutils literal">new=true</tt>, see table assignment in the wrapper section)</p> +</li> +<li><p class="first"><tt class="docutils literal">utils.prompt_yes_no(prompt, default)</tt></p> +<p>Presents a yes/no prompt to the user. If <tt class="docutils literal">default</tt> is not <em>nil</em>, +allows just pressing Enter to submit the default choice. +If the user enters <tt class="docutils literal">'abort'</tt>, throws an error.</p> +</li> +<li><p class="first"><tt class="docutils literal">utils.prompt_input(prompt, checkfun, quit_str)</tt></p> +<p>Presents a prompt to input data, until a valid string is entered. +Once <tt class="docutils literal">checkfun(input)</tt> returns <em>true, ...</em>, passes the values +through. If the user enters the quit_str (defaults to <tt class="docutils literal"><span class="pre">'~~~'</span></tt>), +throws an error.</p> +</li> +<li><p class="first"><tt class="docutils literal">utils.check_number(text)</tt></p> +<p>A <tt class="docutils literal">prompt_input</tt> <tt class="docutils literal">checkfun</tt> that verifies a number input.</p> +</li> +</ul> +</div> +<div class="section" id="dumper"> +<h2><a class="toc-backref" href="#id34">dumper</a></h2> +<p>A third-party lua table dumper module from +<a class="reference external" href="http://lua-users.org/wiki/DataDumper">http://lua-users.org/wiki/DataDumper</a>. Defines one +function:</p> +<ul> +<li><p class="first"><tt class="docutils literal">dumper.DataDumper(value, varname, fastmode, ident, indent_step)</tt></p> +<p>Returns <tt class="docutils literal">value</tt> converted to a string. The <tt class="docutils literal">indent_step</tt> +argument specifies the indentation step size in spaces. For +the other arguments see the original documentation link above.</p> +</li> +</ul> +</div> +<div class="section" id="class"> +<h2><a class="toc-backref" href="#id35">class</a></h2> +<p>Implements a trivial single-inheritance class system.</p> +<ul> +<li><p class="first"><tt class="docutils literal">Foo = defclass(Foo[, ParentClass])</tt></p> +<p>Defines or updates class Foo. The <tt class="docutils literal">Foo = defclass(Foo)</tt> syntax +is needed so that when the module or script is reloaded, the +class identity will be preserved through the preservation of +global variable values.</p> +<p>The <tt class="docutils literal">defclass</tt> function is defined as a stub in the global +namespace, and using it will auto-load the class module.</p> +</li> +<li><p class="first"><tt class="docutils literal">Class.super</tt></p> +<p>This class field is set by defclass to the parent class, and +allows a readable <tt class="docutils literal">Class.super.method(self, <span class="pre">...)</span></tt> syntax for +calling superclass methods.</p> +</li> +<li><p class="first"><tt class="docutils literal">Class.ATTRS { foo = xxx, bar = yyy }</tt></p> +<p>Declares certain instance fields to be attributes, i.e. auto-initialized +from fields in the table used as the constructor argument. If omitted, +they are initialized with the default values specified in this declaration.</p> +<p>If the default value should be <em>nil</em>, use <tt class="docutils literal">ATTRS { foo = DEFAULT_NIL }</tt>.</p> +</li> +<li><p class="first"><tt class="docutils literal">new_obj = Class{ foo = arg, bar = arg, ... }</tt></p> +<p>Calling the class as a function creates and initializes a new instance. +Initialization happens in this order:</p> +<ol class="arabic simple"> +<li>An empty instance table is created, and its metatable set.</li> +<li>The <tt class="docutils literal">preinit</tt> method is called via <tt class="docutils literal">invoke_before</tt> (see below) +with the table used as argument to the class. This method is intended +for validating and tweaking that argument table.</li> +<li>Declared ATTRS are initialized from the argument table or their default values.</li> +<li>The <tt class="docutils literal">init</tt> method is called via <tt class="docutils literal">invoke_after</tt> with the argument table. +This is the main constructor method.</li> +<li>The <tt class="docutils literal">postinit</tt> method is called via <tt class="docutils literal">invoke_after</tt> with the argument table. +Place code that should be called after the object is fully constructed here.</li> +</ol> +</li> +</ul> +<p>Predefined instance methods:</p> +<ul> +<li><p class="first"><tt class="docutils literal">instance:assign{ foo = xxx }</tt></p> +<p>Assigns all values in the input table to the matching instance fields.</p> +</li> +<li><p class="first"><tt class="docutils literal">instance:callback(method_name, <span class="pre">[args...])</span></tt></p> +<p>Returns a closure that invokes the specified method of the class, +properly passing in self, and optionally a number of initial arguments too. +The arguments given to the closure are appended to these.</p> +</li> +<li><p class="first"><tt class="docutils literal">instance:invoke_before(method_name, <span class="pre">args...)</span></tt></p> +<p>Navigates the inheritance chain of the instance starting from the most specific +class, and invokes the specified method with the arguments if it is defined in +that specific class. Equivalent to the following definition in every class:</p> +<pre class="literal-block"> +function Class:invoke_before(method, ...) + if rawget(Class, method) then + rawget(Class, method)(self, ...) + end + Class.super.invoke_before(method, ...) +end +</pre> +</li> +<li><p class="first"><tt class="docutils literal">instance:invoke_after(method_name, <span class="pre">args...)</span></tt></p> +<p>Like invoke_before, only the method is called after the recursive call to super, +i.e. invocations happen in the parent to child order.</p> +<p>These two methods are inspired by the Common Lisp before and after methods, and +are intended for implementing similar protocols for certain things. The class +library itself uses them for constructors.</p> +</li> +</ul> +<p>To avoid confusion, these methods cannot be redefined.</p> +</div> +</div> +<div class="section" id="plugins"> +<h1><a class="toc-backref" href="#id36">Plugins</a></h1> +<p>DFHack plugins may export native functions and events +to lua contexts. They are automatically imported by +<tt class="docutils literal"><span class="pre">mkmodule('plugins.<name>')</span></tt>; this means that a lua +module file is still necessary for <tt class="docutils literal">require</tt> to read.</p> +<p>The following plugins have lua support.</p> +<div class="section" id="burrows"> +<h2><a class="toc-backref" href="#id37">burrows</a></h2> +<p>Implements extended burrow manipulations.</p> +<p>Events:</p> +<ul> +<li><p class="first"><tt class="docutils literal">onBurrowRename.foo = function(burrow)</tt></p> +<p>Emitted when a burrow might have been renamed either through +the game UI, or <tt class="docutils literal">renameBurrow()</tt>.</p> +</li> +<li><p class="first"><tt class="docutils literal">onDigComplete.foo = function(job_type,pos,old_tiletype,new_tiletype,worker)</tt></p> +<p>Emitted when a tile might have been dug out. Only tracked if the +auto-growing burrows feature is enabled.</p> +</li> +</ul> +<p>Native functions:</p> +<ul> +<li><p class="first"><tt class="docutils literal">renameBurrow(burrow,name)</tt></p> +<p>Renames the burrow, emitting <tt class="docutils literal">onBurrowRename</tt> and updating auto-grow state properly.</p> +</li> +<li><p class="first"><tt class="docutils literal">findByName(burrow,name)</tt></p> +<p>Finds a burrow by name, using the same rules as the plugin command line interface. +Namely, trailing <tt class="docutils literal">'+'</tt> characters marking auto-grow burrows are ignored.</p> +</li> +<li><p class="first"><tt class="docutils literal">copyUnits(target,source,enable)</tt></p> +<p>Applies units from <tt class="docutils literal">source</tt> burrow to <tt class="docutils literal">target</tt>. The <tt class="docutils literal">enable</tt> +parameter specifies if they are to be added or removed.</p> +</li> +<li><p class="first"><tt class="docutils literal">copyTiles(target,source,enable)</tt></p> +<p>Applies tiles from <tt class="docutils literal">source</tt> burrow to <tt class="docutils literal">target</tt>. The <tt class="docutils literal">enable</tt> +parameter specifies if they are to be added or removed.</p> +</li> +<li><p class="first"><tt class="docutils literal">setTilesByKeyword(target,keyword,enable)</tt></p> +<p>Adds or removes tiles matching a predefined keyword. The keyword +set is the same as used by the command line.</p> +</li> +</ul> +<p>The lua module file also re-exports functions from <tt class="docutils literal">dfhack.burrows</tt>.</p> +</div> +<div class="section" id="sort"> +<h2><a class="toc-backref" href="#id38">sort</a></h2> +<p>Does not export any native functions as of now. Instead, it +calls lua code to perform the actual ordering of list items.</p> +</div> +</div> +<div class="section" id="scripts"> +<h1><a class="toc-backref" href="#id39">Scripts</a></h1> +<p>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.</p> +<p>If the first line of the script is a one-line comment, it is +used by the built-in <tt class="docutils literal">ls</tt> and <tt class="docutils literal">help</tt> commands.</p> +<p><strong>NOTE:</strong> Scripts placed in subdirectories still can be accessed, but +do not clutter the <tt class="docutils literal">ls</tt> 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. <tt class="docutils literal"><span class="pre">devel/lua-example</span></tt>.</p> +<p>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.</p> +<p>Arguments are passed in to the scripts via the <strong>...</strong> built-in +quasi-variable; when the script is called by the DFHack core, +they are all guaranteed to be non-nil strings.</p> +<p>DFHack core invokes the scripts in the <em>core context</em> (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:</p> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.run_script(name[,args...])</span></tt></p> +<p>Run a lua script in hack/scripts/, as if it was started from dfhack command-line. +The <tt class="docutils literal">name</tt> argument should be the name stem, as would be used on the command line.</p> +</li> +</ul> +<p>Note that this function lets errors propagate to the caller.</p> +</div> +</div> +</body> +</html> |
