summaryrefslogtreecommitdiff
path: root/Lua API.html
diff options
context:
space:
mode:
Diffstat (limited to 'Lua API.html')
-rw-r--r--Lua API.html430
1 files changed, 376 insertions, 54 deletions
diff --git a/Lua API.html b/Lua API.html
index 2c9a6a8d..36be1ba4 100644
--- a/Lua API.html
+++ b/Lua API.html
@@ -3,7 +3,7 @@
<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: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.8.1: http://docutils.sourceforge.net/" />
<title>DFHack Lua API</title>
<style type="text/css">
@@ -337,41 +337,44 @@ ul.auto-toc {
<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 &amp; Output</a></li>
<li><a class="reference internal" href="#exception-handling" id="id13">Exception handling</a></li>
-<li><a class="reference internal" href="#locking-and-finalization" id="id14">Locking and finalization</a></li>
-<li><a class="reference internal" href="#persistent-configuration-storage" id="id15">Persistent configuration storage</a></li>
-<li><a class="reference internal" href="#material-info-lookup" id="id16">Material info lookup</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="id17">C++ function wrappers</a><ul>
-<li><a class="reference internal" href="#gui-module" id="id18">Gui module</a></li>
-<li><a class="reference internal" href="#job-module" id="id19">Job module</a></li>
-<li><a class="reference internal" href="#units-module" id="id20">Units module</a></li>
-<li><a class="reference internal" href="#items-module" id="id21">Items module</a></li>
-<li><a class="reference internal" href="#maps-module" id="id22">Maps module</a></li>
-<li><a class="reference internal" href="#burrows-module" id="id23">Burrows module</a></li>
-<li><a class="reference internal" href="#buildings-module" id="id24">Buildings module</a></li>
-<li><a class="reference internal" href="#constructions-module" id="id25">Constructions module</a></li>
-<li><a class="reference internal" href="#internal-api" id="id26">Internal API</a></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="id27">Core interpreter context</a><ul>
-<li><a class="reference internal" href="#event-type" id="id28">Event type</a></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="id29">Lua Modules</a><ul>
-<li><a class="reference internal" href="#global-environment" id="id30">Global environment</a></li>
-<li><a class="reference internal" href="#utils" id="id31">utils</a></li>
-<li><a class="reference internal" href="#dumper" id="id32">dumper</a></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="id33">Plugins</a><ul>
-<li><a class="reference internal" href="#burrows" id="id34">burrows</a></li>
-<li><a class="reference internal" href="#sort" id="id35">sort</a></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="id36">Scripts</a></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
@@ -778,7 +781,7 @@ 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>
+<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>
@@ -841,8 +844,21 @@ following properties:</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="#id14">Locking and finalization</a></h3>
+<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.
@@ -875,7 +891,7 @@ Implemented using <tt class="docutils literal"><span class="pre">call_with_final
</ul>
</div>
<div class="section" id="persistent-configuration-storage">
-<h3><a class="toc-backref" href="#id15">Persistent configuration storage</a></h3>
+<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
@@ -910,7 +926,7 @@ 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="#id16">Material info lookup</a></h3>
+<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>
@@ -955,7 +971,7 @@ Accept dfhack_material_category auto-assign table.</p>
</div>
</div>
<div class="section" id="c-function-wrappers">
-<h2><a class="toc-backref" href="#id17">C++ function wrappers</a></h2>
+<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
@@ -973,6 +989,9 @@ can be omitted.</p>
<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">&quot;.../df/hack/&quot;</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>
@@ -984,15 +1003,19 @@ can be omitted.</p>
</li>
</ul>
<div class="section" id="gui-module">
-<h3><a class="toc-backref" href="#id18">Gui module</a></h3>
+<h3><a class="toc-backref" href="#id19">Gui module</a></h3>
<ul>
-<li><p class="first"><tt class="docutils literal">dfhack.gui.getCurViewscreen()</tt></p>
-<p>Returns the viewscreen that is current in the core.</p>
+<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 &quot;screen/foo/bar/baz...&quot; 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>
@@ -1010,17 +1033,27 @@ 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="#id19">Job module</a></h3>
+<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>
@@ -1057,7 +1090,7 @@ a lua list containing them.</p>
</ul>
</div>
<div class="section" id="units-module">
-<h3><a class="toc-backref" href="#id20">Units module</a></h3>
+<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>
@@ -1077,6 +1110,26 @@ a lua list containing them.</p>
<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>
@@ -1097,6 +1150,12 @@ same checks the game uses to decide game-over by extinction.</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.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>
@@ -1108,10 +1167,17 @@ or raws. The <tt class="docutils literal">ignore_noble</tt> boolean disables the
<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="#id21">Items module</a></h3>
+<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>
@@ -1151,10 +1217,16 @@ Returns <em>false</em> in case of error.</p>
<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="#id22">Maps module</a></h3>
+<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>
@@ -1165,15 +1237,25 @@ Returns <em>false</em> in case of error.</p>
<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>
@@ -1195,7 +1277,7 @@ burrows, or the presence of invaders.</p>
</ul>
</div>
<div class="section" id="burrows-module">
-<h3><a class="toc-backref" href="#id23">Burrows module</a></h3>
+<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>
@@ -1230,8 +1312,12 @@ burrows, or the presence of invaders.</p>
</ul>
</div>
<div class="section" id="buildings-module">
-<h3><a class="toc-backref" href="#id24">Buildings module</a></h3>
+<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>
@@ -1370,7 +1456,7 @@ can be determined this way, <tt class="docutils literal">constructBuilding</tt>
</ul>
</div>
<div class="section" id="constructions-module">
-<h3><a class="toc-backref" href="#id25">Constructions module</a></h3>
+<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
@@ -1385,8 +1471,161 @@ Returns <em>true, was_only_planned</em> if removed; or <em>false</em> if none fo
</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 &amp; 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 &quot;DFHack&quot; 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 &quot;STRING_A???&quot; 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="#id26">Internal API</a></h3>
+<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>
@@ -1409,6 +1648,11 @@ global environment, persistent between calls to the script.</p>
<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>
@@ -1429,7 +1673,7 @@ Returns: <em>found_index</em>, or <em>nil</em> if end reached.</p>
</div>
</div>
<div class="section" id="core-interpreter-context">
-<h2><a class="toc-backref" href="#id27">Core interpreter context</a></h2>
+<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>
@@ -1460,9 +1704,9 @@ Using <tt class="docutils literal">timeout_active(id,nil)</tt> cancels the timer
</li>
</ul>
<div class="section" id="event-type">
-<h3><a class="toc-backref" href="#id28">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
+<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
@@ -1473,9 +1717,15 @@ core context has the actual events defined by C++ code.</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>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, and has some special semantics.</p>
+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
@@ -1486,7 +1736,7 @@ order using <tt class="docutils literal">dfhack.safecall</tt>.</p>
</div>
</div>
<div class="section" id="lua-modules">
-<h1><a class="toc-backref" href="#id29">Lua Modules</a></h1>
+<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
@@ -1515,7 +1765,7 @@ in this document.</p>
</li>
</ul>
<div class="section" id="global-environment">
-<h2><a class="toc-backref" href="#id30">Global environment</a></h2>
+<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>
@@ -1556,7 +1806,7 @@ Returns <em>nil</em> if any of obj or indices is <em>nil</em>, or a numeric inde
</ul>
</div>
<div class="section" id="utils">
-<h2><a class="toc-backref" href="#id31">utils</a></h2>
+<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&lt;b, <em>1</em> if a&gt;b, <em>0</em> otherwise.</p>
@@ -1669,7 +1919,7 @@ throws an error.</p>
</ul>
</div>
<div class="section" id="dumper">
-<h2><a class="toc-backref" href="#id32">dumper</a></h2>
+<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>
@@ -1681,16 +1931,88 @@ 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="#id33">Plugins</a></h1>
+<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.&lt;name&gt;')</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="#id34">burrows</a></h2>
+<h2><a class="toc-backref" href="#id37">burrows</a></h2>
<p>Implements extended burrow manipulations.</p>
<p>Events:</p>
<ul>
@@ -1728,13 +2050,13 @@ set is the same as used by the command line.</p>
<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="#id35">sort</a></h2>
+<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="#id36">Scripts</a></h1>
+<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