1277 lines
60 KiB
HTML
1277 lines
60 KiB
HTML
<?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.8.1: http://docutils.sourceforge.net/" />
|
|
<title>DFHack Lua API</title>
|
|
<style type="text/css">
|
|
|
|
/*
|
|
:Author: David Goodger (goodger@python.org)
|
|
:Id: $Id: html4css1.css 7056 2011-06-17 10:50:48Z 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 {
|
|
margin-left: 2em ;
|
|
margin-right: 2em }
|
|
|
|
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-structure-wrapper" id="id1">DF 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-utilities" id="id10">DFHack utilities</a><ul>
|
|
<li><a class="reference internal" href="#persistent-configuration-storage" id="id11">Persistent configuration storage</a></li>
|
|
<li><a class="reference internal" href="#material-info-lookup" id="id12">Material info lookup</a></li>
|
|
<li><a class="reference internal" href="#c-function-wrappers" id="id13">C++ function wrappers</a><ul>
|
|
<li><a class="reference internal" href="#gui-module" id="id14">Gui module</a></li>
|
|
<li><a class="reference internal" href="#job-module" id="id15">Job module</a></li>
|
|
<li><a class="reference internal" href="#units-module" id="id16">Units module</a></li>
|
|
<li><a class="reference internal" href="#items-module" id="id17">Items module</a></li>
|
|
<li><a class="reference internal" href="#maps-module" id="id18">Maps module</a></li>
|
|
<li><a class="reference internal" href="#burrows-module" id="id19">Burrows module</a></li>
|
|
<li><a class="reference internal" href="#buildings-module" id="id20">Buildings module</a></li>
|
|
<li><a class="reference internal" href="#constructions-module" id="id21">Constructions module</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference internal" href="#core-interpreter-context" id="id22">Core interpreter context</a><ul>
|
|
<li><a class="reference internal" href="#event-type" id="id23">Event type</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference internal" href="#plugins" id="id24">Plugins</a><ul>
|
|
<li><a class="reference internal" href="#burrows" id="id25">burrows</a></li>
|
|
<li><a class="reference internal" href="#sort" id="id26">sort</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="section" id="df-structure-wrapper">
|
|
<h1><a class="toc-backref" href="#id1">DF 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>
|
|
</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.
|
|
The <tt class="docutils literal">_enum</tt> property points to the bitfield type.</p>
|
|
<p>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>
|
|
</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>
|
|
</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-utilities">
|
|
<h1><a class="toc-backref" href="#id10">DFHack utilities</a></h1>
|
|
<p>DFHack utility functions are placed in the <tt class="docutils literal">dfhack</tt> global tree.</p>
|
|
<p>Currently it defines the following features:</p>
|
|
<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.</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[,env[,history_filename]]])</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>
|
|
<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>
|
|
<p>The returned error is a table with separate <tt class="docutils literal">message</tt> and
|
|
<tt class="docutils literal">stacktrace</tt> string fields; it implements <tt class="docutils literal">__tostring</tt>.</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"><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 class="section" id="persistent-configuration-storage">
|
|
<h2><a class="toc-backref" href="#id11">Persistent configuration storage</a></h2>
|
|
<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">
|
|
<h2><a class="toc-backref" href="#id12">Material info lookup</a></h2>
|
|
<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 class="section" id="c-function-wrappers">
|
|
<h2><a class="toc-backref" href="#id13">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.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="#id14">Gui module</a></h3>
|
|
<ul>
|
|
<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.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.showPopupAnnouncement(text,color[,is_bright])</span></tt></p>
|
|
<p>Pops up a titan-style modal announcement window.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="section" id="job-module">
|
|
<h3><a class="toc-backref" href="#id15">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.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="#id16">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; 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.isDead(unit)</tt></p>
|
|
<p>The unit is completely dead and passive.</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 or zombie.</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.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>
|
|
</ul>
|
|
</div>
|
|
<div class="section" id="items-module">
|
|
<h3><a class="toc-backref" href="#id17">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; may be not equal to item.pos if in inventory.</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>
|
|
</ul>
|
|
</div>
|
|
<div class="section" id="maps-module">
|
|
<h3><a class="toc-backref" href="#id18">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.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.getRegionBiome(region_coord2d)</tt></p>
|
|
<p>Returns the biome info struct for the given global map region.</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.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="#id19">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="#id20">Buildings module</a></h3>
|
|
<ul>
|
|
<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>
|
|
</div>
|
|
<div class="section" id="constructions-module">
|
|
<h3><a class="toc-backref" href="#id21">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>
|
|
<div class="section" id="core-interpreter-context">
|
|
<h2><a class="toc-backref" href="#id22">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">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="#id23">Event type</a></h3>
|
|
<p>An event is just a lua table with a predefined metatable that
|
|
contains 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.</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, and has some special semantics.</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="plugins">
|
|
<h1><a class="toc-backref" href="#id24">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="#id25">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)</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="#id26">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>
|
|
</body>
|
|
</html>
|