summaryrefslogtreecommitdiff
path: root/Lua API.html
diff options
context:
space:
mode:
authorAlexander Gavrilov2012-04-23 21:30:53 +0400
committerAlexander Gavrilov2012-04-23 21:30:53 +0400
commit763a301b4f928bf20c78fb67f864e1623409c710 (patch)
treeb46ec827b20f49787aa77ba75d293b2951801544 /Lua API.html
parent125cd6622a1d2ce7a8dfa7caf40a85049baf4977 (diff)
downloaddfhack-763a301b4f928bf20c78fb67f864e1623409c710.tar.gz
dfhack-763a301b4f928bf20c78fb67f864e1623409c710.tar.bz2
dfhack-763a301b4f928bf20c78fb67f864e1623409c710.tar.xz
Add a few more lua api functions, documentation, and unit sort orders.
Units::getProfessionName appears to work correctly for everything except nobles.
Diffstat (limited to 'Lua API.html')
-rw-r--r--Lua API.html89
1 files changed, 81 insertions, 8 deletions
diff --git a/Lua API.html b/Lua API.html
index cbf35f0e..916c6eef 100644
--- a/Lua API.html
+++ b/Lua API.html
@@ -350,6 +350,11 @@ ul.auto-toc {
</li>
</ul>
</li>
+<li><a class="reference internal" href="#plugins" id="id21">Plugins</a><ul>
+<li><a class="reference internal" href="#burrows" id="id22">burrows</a></li>
+<li><a class="reference internal" href="#sort" id="id23">sort</a></li>
+</ul>
+</li>
</ul>
</div>
<div class="section" id="df-structure-wrapper">
@@ -842,37 +847,40 @@ Accept dfhack_material_category auto-assign table.</p>
</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.</p>
+<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.TranslateName(name,in_english,only_last_name)</tt></p>
+<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">dfhack.gui.getSelectedWorkshopJob(silent)</tt></p>
+<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">dfhack.gui.getSelectedJob(silent)</tt></p>
+<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">dfhack.gui.getSelectedUnit(silent)</tt></p>
+<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">dfhack.gui.getSelectedItem(silent)</tt></p>
+<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> -&gt;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">dfhack.gui.showAnnouncement(text,color,is_bright)</tt></p>
+<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">dfhack.gui.showPopupAnnouncement(text,color,is_bright)</tt></p>
+<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>
@@ -923,6 +931,9 @@ a lua list containing them.</p>
<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>
@@ -944,6 +955,16 @@ a lua list containing them.</p>
<li><p class="first"><tt class="docutils literal">dfhack.units.setInBurrow(unit,burrow,enable)</tt></p>
<p>Adds or removes the unit from the burrow.</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"><span class="pre">dfhack.units.getProfessionName(unit[,plural])</span></tt></p>
+<p>Retrieves the profession name using custom profession or raws.</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">
@@ -1061,6 +1082,58 @@ order using <tt class="docutils literal">dfhack.safecall</tt>.</p>
</div>
</div>
</div>
+<div class="section" id="plugins">
+<h1><a class="toc-backref" href="#id21">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="#id22">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 or wraps some of the
+functions implemented by the dfhack core for convenience.</p>
+</div>
+<div class="section" id="sort">
+<h2><a class="toc-backref" href="#id23">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>