Update texts.

develop
expwnent 2015-01-31 23:15:40 -05:00
parent b407044b94
commit d7bbde0aa0
4 changed files with 560 additions and 130 deletions

@ -365,12 +365,6 @@ ul.auto-toc {
<li><a class="reference internal" href="#using-the-library-as-a-developer" id="id16">Using the library as a developer</a><ul> <li><a class="reference internal" href="#using-the-library-as-a-developer" id="id16">Using the library as a developer</a><ul>
<li><a class="reference internal" href="#df-data-structure-definitions" id="id17">DF data structure definitions</a></li> <li><a class="reference internal" href="#df-data-structure-definitions" id="id17">DF data structure definitions</a></li>
<li><a class="reference internal" href="#remote-access-interface" id="id18">Remote access interface</a></li> <li><a class="reference internal" href="#remote-access-interface" id="id18">Remote access interface</a></li>
<li><a class="reference internal" href="#contributing-to-dfhack" id="id19">Contributing to DFHack</a><ul>
<li><a class="reference internal" href="#coding-style" id="id20">Coding style</a></li>
<li><a class="reference internal" href="#how-to-get-new-code-into-dfhack" id="id21">How to get new code into DFHack</a></li>
<li><a class="reference internal" href="#memory-research" id="id22">Memory research</a></li>
</ul>
</li>
</ul> </ul>
</li> </li>
</ul> </ul>
@ -469,10 +463,10 @@ This will take some time—maybe hours, depending on your machine.</li>
<blockquote> <blockquote>
<ul class="simple"> <ul class="simple">
<li><a class="reference external" href="http://brew.sh/">Install Homebrew</a> and run:</li> <li><a class="reference external" href="http://brew.sh/">Install Homebrew</a> and run:</li>
<li><tt class="docutils literal">brew tap lethosor/gcc</tt></li> <li><tt class="docutils literal">brew tap homebrew/versions</tt></li>
<li><tt class="docutils literal">brew install git</tt></li> <li><tt class="docutils literal">brew install git</tt></li>
<li><tt class="docutils literal">brew install cmake</tt></li> <li><tt class="docutils literal">brew install cmake</tt></li>
<li><tt class="docutils literal">brew install lethosor/gcc/gcc45 <span class="pre">--enable-multilib</span></tt></li> <li><tt class="docutils literal">brew install gcc45 <span class="pre">--enable-multilib</span></tt></li>
</ul> </ul>
</blockquote> </blockquote>
</blockquote> </blockquote>
@ -648,46 +642,6 @@ the dfhack repository is welcome and the right thing to do :)</p>
<p>Currently the supported set of requests is limited, because the developers don't know what exactly is most useful.</p> <p>Currently the supported set of requests is limited, because the developers don't know what exactly is most useful.</p>
<p>Protocol client implementations exist for Java and C#.</p> <p>Protocol client implementations exist for Java and C#.</p>
</div> </div>
<div class="section" id="contributing-to-dfhack">
<h2><a class="toc-backref" href="#id19">Contributing to DFHack</a></h2>
<p>Several things should be kept in mind when contributing to DFHack.</p>
<div class="section" id="coding-style">
<h3><a class="toc-backref" href="#id20">Coding style</a></h3>
<p>DFhack uses ANSI formatting and four spaces as indentation. Line
endings are UNIX. The files use UTF-8 encoding. Code not following this
won't make me happy, because I'll have to fix it. There's a good chance
I'll make <em>you</em> fix it ;)</p>
</div>
<div class="section" id="how-to-get-new-code-into-dfhack">
<h3><a class="toc-backref" href="#id21">How to get new code into DFHack</a></h3>
<p>You can send patches or make a clone of the github repo and ask me on
the IRC channel to pull your code in. I'll review it and see if there
are any problems. I'll fix them if they are minor.</p>
<p>Fixes are higher in priority. If you want to work on something, but
don't know what, check out <a class="reference external" href="http://github.com/DFHack/dfhack/issues">http://github.com/DFHack/dfhack/issues</a> --
this is also a good place to dump new ideas and/or bugs that need
fixing.</p>
</div>
<div class="section" id="memory-research">
<h3><a class="toc-backref" href="#id22">Memory research</a></h3>
<p>If you want to do memory research, you'll need some tools and some knowledge.
In general, you'll need a good memory viewer and optionally something
to look at machine code without getting crazy :)</p>
<p>Good windows tools include:</p>
<ul class="simple">
<li>Cheat Engine</li>
<li>IDA Pro 5.0 (freely available for non-commercial use)</li>
</ul>
<p>Good linux tools:</p>
<ul class="simple">
<li>angavrilov's df-structures gui (visit us on IRC for details).</li>
<li>edb (Evan's Debugger)</li>
<li>IDA Pro 5.0 running under Wine</li>
<li>Some of the tools residing in the <tt class="docutils literal">legacy</tt> dfhack branch.</li>
</ul>
<p>Using publicly known information and analyzing the game's data is preferred.</p>
</div>
</div>
</div> </div>
</div> </div>
</body> </body>

@ -0,0 +1,410 @@
<?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.12: http://docutils.sourceforge.net/" />
<title>Contributing to DFHACK</title>
<style type="text/css">
/*
:Author: David Goodger (goodger@python.org)
:Id: $Id: html4css1.css 7614 2013-02-21 15:55:51Z 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, .code .error {
color: red ;
font-weight: bold ;
font-family: sans-serif }
/* Uncomment (and remove this text!) to get reduced vertical space in
compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
margin-bottom: 0.5em }
div.compound .compound-last, div.compound .compound-middle {
margin-top: 0.5em }
*/
div.dedication {
margin: 2em 5em ;
text-align: center ;
font-style: italic }
div.dedication p.topic-title {
font-weight: bold ;
font-style: normal }
div.figure {
margin-left: 2em ;
margin-right: 2em }
div.footer, div.header {
clear: both;
font-size: smaller }
div.line-block {
display: block ;
margin-top: 1em ;
margin-bottom: 1em }
div.line-block div.line-block {
margin-top: 0 ;
margin-bottom: 0 ;
margin-left: 1.5em }
div.sidebar {
margin: 0 0 0.5em 1em ;
border: medium outset ;
padding: 1em ;
background-color: #ffffee ;
width: 40% ;
float: right ;
clear: right }
div.sidebar p.rubric {
font-family: sans-serif ;
font-size: medium }
div.system-messages {
margin: 5em }
div.system-messages h1 {
color: red }
div.system-message {
border: medium outset ;
padding: 1em }
div.system-message p.system-message-title {
color: red ;
font-weight: bold }
div.topic {
margin: 2em }
h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
margin-top: 0.4em }
h1.title {
text-align: center }
h2.subtitle {
text-align: center }
hr.docutils {
width: 75% }
img.align-left, .figure.align-left, object.align-left {
clear: left ;
float: left ;
margin-right: 1em }
img.align-right, .figure.align-right, object.align-right {
clear: right ;
float: right ;
margin-left: 1em }
img.align-center, .figure.align-center, object.align-center {
display: block;
margin-left: auto;
margin-right: auto;
}
.align-left {
text-align: left }
.align-center {
clear: both ;
text-align: center }
.align-right {
text-align: right }
/* reset inner alignment in figures */
div.align-right {
text-align: inherit }
/* div.align-center * { */
/* text-align: left } */
ol.simple, ul.simple {
margin-bottom: 1em }
ol.arabic {
list-style: decimal }
ol.loweralpha {
list-style: lower-alpha }
ol.upperalpha {
list-style: upper-alpha }
ol.lowerroman {
list-style: lower-roman }
ol.upperroman {
list-style: upper-roman }
p.attribution {
text-align: right ;
margin-left: 50% }
p.caption {
font-style: italic }
p.credits {
font-style: italic ;
font-size: smaller }
p.label {
white-space: nowrap }
p.rubric {
font-weight: bold ;
font-size: larger ;
color: maroon ;
text-align: center }
p.sidebar-title {
font-family: sans-serif ;
font-weight: bold ;
font-size: larger }
p.sidebar-subtitle {
font-family: sans-serif ;
font-weight: bold }
p.topic-title {
font-weight: bold }
pre.address {
margin-bottom: 0 ;
margin-top: 0 ;
font: inherit }
pre.literal-block, pre.doctest-block, pre.math, pre.code {
margin-left: 2em ;
margin-right: 2em }
pre.code .ln { color: grey; } /* line numbers */
pre.code, code { background-color: #eeeeee }
pre.code .comment, code .comment { color: #5C6576 }
pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold }
pre.code .literal.string, code .literal.string { color: #0C5404 }
pre.code .name.builtin, code .name.builtin { color: #352B84 }
pre.code .deleted, code .deleted { background-color: #DEB0A1}
pre.code .inserted, code .inserted { background-color: #A3D289}
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 }
/* "booktabs" style (no vertical lines) */
table.docutils.booktabs {
border: 0px;
border-top: 2px solid;
border-bottom: 2px solid;
border-collapse: collapse;
}
table.docutils.booktabs * {
border: 0px;
}
table.docutils.booktabs th {
border-bottom: thin solid;
text-align: left;
}
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="contributing-to-dfhack">
<h1 class="title">Contributing to DFHACK</h1>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#id1" id="id2">Contributing to DFHack</a><ul>
<li><a class="reference internal" href="#code-format" id="id3">Code Format</a></li>
<li><a class="reference internal" href="#how-to-get-new-code-into-dfhack" id="id4">How to get new code into DFHack</a></li>
<li><a class="reference internal" href="#memory-research" id="id5">Memory research</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="id1">
<h1><a class="toc-backref" href="#id2">Contributing to DFHack</a></h1>
<p>Several things should be kept in mind when contributing to DFHack.</p>
<div class="section" id="code-format">
<h2><a class="toc-backref" href="#id3">Code Format</a></h2>
<ul class="simple">
<li>Four space indents for C++. Never use tabs for indentation in any language.</li>
<li>LF (Unix style) line terminators</li>
<li>Avoid trailing whitespace</li>
<li>UTF-8 encoding</li>
<li>For C++:<ul>
<li>Opening and closing braces on their own lines or opening brace at the end of the previous line</li>
<li>Braces placed at original indent level if on their own lines</li>
<li>#includes should be sorted. C++ libraries first, then dfhack modules, then df structures, then local includes. Within each category they should be sorted alphabetically. This policy is currently broken by most C++ files but try to follow it if you can.</li>
</ul>
</li>
</ul>
</div>
<div class="section" id="how-to-get-new-code-into-dfhack">
<h2><a class="toc-backref" href="#id4">How to get new code into DFHack</a></h2>
<ul class="simple">
<li>Submit pull requests to the develop branch, not the master branch. The master branch always points at the most recent release.</li>
<li>Use new branches for each feature/fix so that your changes can be merged independently.</li>
<li>If possible, compile on multiple platforms</li>
<li>Do update NEWS/Contributors.rst</li>
<li>Do <strong>NOT</strong> run fix-texts.sh or update .html files (except to locally test changes to .rst files)</li>
<li>Create a Github Pull Request once finished</li>
<li>Work done against <a class="reference external" href="http://github.com/DFHack/dfhack/issues">issues</a> that are tagged &quot;bug report&quot; gets priority<ul>
<li>Submit ideas and bug reports as issues on github. Posts in the forum thread are also acceptable but can get missed or forgotten more easily.</li>
</ul>
</li>
</ul>
</div>
<div class="section" id="memory-research">
<h2><a class="toc-backref" href="#id5">Memory research</a></h2>
<p>If you want to do memory research, you'll need some tools and some knowledge.
In general, you'll need a good memory viewer and optionally something
to look at machine code without getting crazy :)</p>
<p>Good windows tools include:</p>
<ul class="simple">
<li>Cheat Engine</li>
<li>IDA Pro 5.0 (freely available for non-commercial use)</li>
</ul>
<p>Good linux tools:</p>
<ul class="simple">
<li>angavrilov's df-structures gui (visit us on IRC for details).</li>
<li>edb (Evan's Debugger)</li>
<li>IDA Pro 5.0 running under Wine</li>
<li>Some of the tools residing in the <tt class="docutils literal">legacy</tt> dfhack branch.</li>
</ul>
<p>Using publicly known information and analyzing the game's data is preferred.</p>
</div>
</div>
</div>
</body>
</html>

@ -378,63 +378,64 @@ ul.auto-toc {
<li><a class="reference internal" href="#buildings-module" id="id28">Buildings module</a></li> <li><a class="reference internal" href="#buildings-module" id="id28">Buildings module</a></li>
<li><a class="reference internal" href="#constructions-module" id="id29">Constructions module</a></li> <li><a class="reference internal" href="#constructions-module" id="id29">Constructions module</a></li>
<li><a class="reference internal" href="#screen-api" id="id30">Screen API</a></li> <li><a class="reference internal" href="#screen-api" id="id30">Screen API</a></li>
<li><a class="reference internal" href="#internal-api" id="id31">Internal API</a></li> <li><a class="reference internal" href="#filesystem-module" id="id31">Filesystem module</a></li>
<li><a class="reference internal" href="#internal-api" id="id32">Internal API</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference internal" href="#core-interpreter-context" id="id32">Core interpreter context</a><ul> <li><a class="reference internal" href="#core-interpreter-context" id="id33">Core interpreter context</a><ul>
<li><a class="reference internal" href="#event-type" id="id33">Event type</a></li> <li><a class="reference internal" href="#event-type" id="id34">Event type</a></li>
</ul> </ul>
</li> </li>
</ul> </ul>
</li> </li>
<li><a class="reference internal" href="#lua-modules" id="id34">Lua Modules</a><ul> <li><a class="reference internal" href="#lua-modules" id="id35">Lua Modules</a><ul>
<li><a class="reference internal" href="#global-environment" id="id35">Global environment</a></li> <li><a class="reference internal" href="#global-environment" id="id36">Global environment</a></li>
<li><a class="reference internal" href="#utils" id="id36">utils</a></li> <li><a class="reference internal" href="#utils" id="id37">utils</a></li>
<li><a class="reference internal" href="#dumper" id="id37">dumper</a></li> <li><a class="reference internal" href="#dumper" id="id38">dumper</a></li>
<li><a class="reference internal" href="#class" id="id38">class</a></li> <li><a class="reference internal" href="#class" id="id39">class</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference internal" href="#in-game-ui-library" id="id39">In-game UI Library</a><ul> <li><a class="reference internal" href="#in-game-ui-library" id="id40">In-game UI Library</a><ul>
<li><a class="reference internal" href="#gui" id="id40">gui</a><ul> <li><a class="reference internal" href="#gui" id="id41">gui</a><ul>
<li><a class="reference internal" href="#misc" id="id41">Misc</a></li> <li><a class="reference internal" href="#misc" id="id42">Misc</a></li>
<li><a class="reference internal" href="#viewrect-class" id="id42">ViewRect class</a></li> <li><a class="reference internal" href="#viewrect-class" id="id43">ViewRect class</a></li>
<li><a class="reference internal" href="#painter-class" id="id43">Painter class</a></li> <li><a class="reference internal" href="#painter-class" id="id44">Painter class</a></li>
<li><a class="reference internal" href="#view-class" id="id44">View class</a></li> <li><a class="reference internal" href="#view-class" id="id45">View class</a></li>
<li><a class="reference internal" href="#screen-class" id="id45">Screen class</a></li> <li><a class="reference internal" href="#screen-class" id="id46">Screen class</a></li>
<li><a class="reference internal" href="#framedscreen-class" id="id46">FramedScreen class</a></li> <li><a class="reference internal" href="#framedscreen-class" id="id47">FramedScreen class</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference internal" href="#gui-widgets" id="id47">gui.widgets</a><ul> <li><a class="reference internal" href="#gui-widgets" id="id48">gui.widgets</a><ul>
<li><a class="reference internal" href="#widget-class" id="id48">Widget class</a></li> <li><a class="reference internal" href="#widget-class" id="id49">Widget class</a></li>
<li><a class="reference internal" href="#panel-class" id="id49">Panel class</a></li> <li><a class="reference internal" href="#panel-class" id="id50">Panel class</a></li>
<li><a class="reference internal" href="#pages-class" id="id50">Pages class</a></li> <li><a class="reference internal" href="#pages-class" id="id51">Pages class</a></li>
<li><a class="reference internal" href="#editfield-class" id="id51">EditField class</a></li> <li><a class="reference internal" href="#editfield-class" id="id52">EditField class</a></li>
<li><a class="reference internal" href="#label-class" id="id52">Label class</a></li> <li><a class="reference internal" href="#label-class" id="id53">Label class</a></li>
<li><a class="reference internal" href="#list-class" id="id53">List class</a></li> <li><a class="reference internal" href="#list-class" id="id54">List class</a></li>
<li><a class="reference internal" href="#filteredlist-class" id="id54">FilteredList class</a></li> <li><a class="reference internal" href="#filteredlist-class" id="id55">FilteredList class</a></li>
</ul> </ul>
</li> </li>
</ul> </ul>
</li> </li>
<li><a class="reference internal" href="#plugins" id="id55">Plugins</a><ul> <li><a class="reference internal" href="#plugins" id="id56">Plugins</a><ul>
<li><a class="reference internal" href="#burrows" id="id56">burrows</a></li> <li><a class="reference internal" href="#burrows" id="id57">burrows</a></li>
<li><a class="reference internal" href="#sort" id="id57">sort</a></li> <li><a class="reference internal" href="#sort" id="id58">sort</a></li>
<li><a class="reference internal" href="#eventful" id="id58">Eventful</a><ul> <li><a class="reference internal" href="#eventful" id="id59">Eventful</a><ul>
<li><a class="reference internal" href="#list-of-events" id="id59">List of events</a></li> <li><a class="reference internal" href="#list-of-events" id="id60">List of events</a></li>
<li><a class="reference internal" href="#events-from-eventmanager" id="id60">Events from EventManager</a></li> <li><a class="reference internal" href="#events-from-eventmanager" id="id61">Events from EventManager</a></li>
<li><a class="reference internal" href="#functions" id="id61">Functions</a></li> <li><a class="reference internal" href="#functions" id="id62">Functions</a></li>
<li><a class="reference internal" href="#examples" id="id62">Examples</a></li> <li><a class="reference internal" href="#examples" id="id63">Examples</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference internal" href="#building-hacks" id="id63">Building-hacks</a><ul> <li><a class="reference internal" href="#building-hacks" id="id64">Building-hacks</a><ul>
<li><a class="reference internal" href="#id1" id="id64">Functions</a></li> <li><a class="reference internal" href="#id1" id="id65">Functions</a></li>
<li><a class="reference internal" href="#id2" id="id65">Examples</a></li> <li><a class="reference internal" href="#id2" id="id66">Examples</a></li>
</ul> </ul>
</li> </li>
</ul> </ul>
</li> </li>
<li><a class="reference internal" href="#scripts" id="id66">Scripts</a><ul> <li><a class="reference internal" href="#scripts" id="id67">Scripts</a><ul>
<li><a class="reference internal" href="#save-init-script" id="id67">Save init script</a></li> <li><a class="reference internal" href="#save-init-script" id="id68">Save init script</a></li>
</ul> </ul>
</li> </li>
</ul> </ul>
@ -1913,8 +1914,59 @@ options; if multiple interpretations exist, the table will contain multiple keys
</li> </li>
</ul> </ul>
</div> </div>
<div class="section" id="filesystem-module">
<h3><a class="toc-backref" href="#id31">Filesystem module</a></h3>
<p>Most of these functions return <tt class="docutils literal">true</tt> on success and <tt class="docutils literal">false</tt> on failure,
unless otherwise noted.</p>
<ul>
<li><p class="first"><tt class="docutils literal">dfhack.filesystem.exists(path)</tt></p>
<p>Returns <tt class="docutils literal">true</tt> if <tt class="docutils literal">path</tt> exists.</p>
</li>
<li><p class="first"><tt class="docutils literal">dfhack.filesystem.isfile(path)</tt></p>
<p>Returns <tt class="docutils literal">true</tt> if <tt class="docutils literal">path</tt> exists and is a file.</p>
</li>
<li><p class="first"><tt class="docutils literal">dfhack.filesystem.isdir(path)</tt></p>
<p>Returns <tt class="docutils literal">true</tt> if <tt class="docutils literal">path</tt> exists and is a directory.</p>
</li>
<li><p class="first"><tt class="docutils literal">dfhack.filesystem.getcwd()</tt></p>
<p>Returns the current working directory. To retrieve the DF path, use <tt class="docutils literal">dfhack.getDFPath()</tt> instead.</p>
</li>
<li><p class="first"><tt class="docutils literal">dfhack.filesystem.chdir(path)</tt></p>
<p>Changes the current directory to <tt class="docutils literal">path</tt>. Use with caution.</p>
</li>
<li><p class="first"><tt class="docutils literal">dfhack.filesystem.mkdir(path)</tt></p>
<p>Creates a new directory. Returns <tt class="docutils literal">false</tt> if unsuccessful, including if <tt class="docutils literal">path</tt> already exists.</p>
</li>
<li><p class="first"><tt class="docutils literal">dfhack.filesystem.rmdir(path)</tt></p>
<p>Removes a directory. Only works if the directory is already empty.</p>
</li>
<li><p class="first"><tt class="docutils literal">dfhack.filesystem.mtime(path)</tt></p>
<p>Returns the modification time (in seconds) of the file or directory specified by <tt class="docutils literal">path</tt>,
or -1 if <tt class="docutils literal">path</tt> does not exist. This depends on the system clock and should only be used locally.</p>
</li>
<li><p class="first"><tt class="docutils literal">dfhack.filesystem.atime(path)</tt></p>
</li>
<li><p class="first"><tt class="docutils literal">dfhack.filesystem.ctime(path)</tt></p>
<p>Return values vary across operating systems - return the <tt class="docutils literal">st_atime</tt> and <tt class="docutils literal">st_ctime</tt>
fields of a C++ stat struct, respectively.</p>
</li>
<li><p class="first"><tt class="docutils literal">dfhack.filesystem.listdir(path)</tt></p>
<p>Lists files/directories in a directory. Returns <tt class="docutils literal">{}</tt> if <tt class="docutils literal">path</tt> does not exist.</p>
</li>
<li><p class="first"><tt class="docutils literal">dfhack.filesystem.listdir_recursive(path [, depth = 10])</tt></p>
<p>Lists all files/directories in a directory and its subdirectories. All directories
are listed before their contents. Returns a table with subtables of the format:</p>
<pre class="literal-block">
{path: 'path to file', isdir: true|false}
</pre>
<p>Note that <tt class="docutils literal">listdir()</tt> returns only the base name of each directory entry, while
<tt class="docutils literal">listdir_recursive()</tt> returns the initial path and all components following it
for each entry.</p>
</li>
</ul>
</div>
<div class="section" id="internal-api"> <div class="section" id="internal-api">
<h3><a class="toc-backref" href="#id31">Internal API</a></h3> <h3><a class="toc-backref" href="#id32">Internal API</a></h3>
<p>These functions are intended for the use by dfhack developers, <p>These functions are intended for the use by dfhack developers,
and are only documented here for completeness:</p> and are only documented here for completeness:</p>
<ul> <ul>
@ -1976,14 +2028,14 @@ The oldval, newval or delta arguments may be used to specify additional constrai
Returns: <em>found_index</em>, or <em>nil</em> if end reached.</p> Returns: <em>found_index</em>, or <em>nil</em> if end reached.</p>
</li> </li>
<li><p class="first"><tt class="docutils literal">dfhack.internal.getDir(path)</tt></p> <li><p class="first"><tt class="docutils literal">dfhack.internal.getDir(path)</tt></p>
<p>List files in a directory. <p>Lists files/directories in a directory.
Returns: <em>file_names</em> or empty table if not found.</p> Returns: <em>file_names</em> or empty table if not found. Identical to <tt class="docutils literal">dfhack.filesystem.listdir(path)</tt>.</p>
</li> </li>
</ul> </ul>
</div> </div>
</div> </div>
<div class="section" id="core-interpreter-context"> <div class="section" id="core-interpreter-context">
<h2><a class="toc-backref" href="#id32">Core interpreter context</a></h2> <h2><a class="toc-backref" href="#id33">Core interpreter context</a></h2>
<p>While plugins can create any number of interpreter instances, <p>While plugins can create any number of interpreter instances,
there is one special context managed by dfhack core. It is the there is one special context managed by dfhack core. It is the
only context that can receive events from DF and plugins.</p> only context that can receive events from DF and plugins.</p>
@ -2014,7 +2066,7 @@ Using <tt class="docutils literal">timeout_active(id,nil)</tt> cancels the timer
</li> </li>
</ul> </ul>
<div class="section" id="event-type"> <div class="section" id="event-type">
<h3><a class="toc-backref" href="#id33">Event type</a></h3> <h3><a class="toc-backref" href="#id34">Event type</a></h3>
<p>An event is a native object transparently wrapping a lua table, <p>An event is a native object transparently wrapping a lua table,
and implementing a __call metamethod. When it is invoked, it loops and implementing a __call metamethod. When it is invoked, it loops
through the table with next and calls all contained values. through the table with next and calls all contained values.
@ -2046,7 +2098,7 @@ order using <tt class="docutils literal">dfhack.safecall</tt>.</p>
</div> </div>
</div> </div>
<div class="section" id="lua-modules"> <div class="section" id="lua-modules">
<h1><a class="toc-backref" href="#id34">Lua Modules</a></h1> <h1><a class="toc-backref" href="#id35">Lua Modules</a></h1>
<p>DFHack sets up the lua interpreter so that the built-in <tt class="docutils literal">require</tt> <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/. 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 The <tt class="docutils literal">dfhack</tt> namespace reference itself may be obtained via
@ -2075,7 +2127,7 @@ in this document.</p>
</li> </li>
</ul> </ul>
<div class="section" id="global-environment"> <div class="section" id="global-environment">
<h2><a class="toc-backref" href="#id35">Global environment</a></h2> <h2><a class="toc-backref" href="#id36">Global environment</a></h2>
<p>A number of variables and functions are provided in the base global <p>A number of variables and functions are provided in the base global
environment by the mandatory init file dfhack.lua:</p> environment by the mandatory init file dfhack.lua:</p>
<ul> <ul>
@ -2138,7 +2190,7 @@ Returns <em>nil</em> if any of obj or indices is <em>nil</em>, or a numeric inde
</ul> </ul>
</div> </div>
<div class="section" id="utils"> <div class="section" id="utils">
<h2><a class="toc-backref" href="#id36">utils</a></h2> <h2><a class="toc-backref" href="#id37">utils</a></h2>
<ul> <ul>
<li><p class="first"><tt class="docutils literal">utils.compare(a,b)</tt></p> <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> <p>Comparator function; returns <em>-1</em> if a&lt;b, <em>1</em> if a&gt;b, <em>0</em> otherwise.</p>
@ -2287,7 +2339,7 @@ throws an error.</p>
</ul> </ul>
</div> </div>
<div class="section" id="dumper"> <div class="section" id="dumper">
<h2><a class="toc-backref" href="#id37">dumper</a></h2> <h2><a class="toc-backref" href="#id38">dumper</a></h2>
<p>A third-party lua table dumper module from <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 <a class="reference external" href="http://lua-users.org/wiki/DataDumper">http://lua-users.org/wiki/DataDumper</a>. Defines one
function:</p> function:</p>
@ -2300,7 +2352,7 @@ the other arguments see the original documentation link above.</p>
</ul> </ul>
</div> </div>
<div class="section" id="class"> <div class="section" id="class">
<h2><a class="toc-backref" href="#id38">class</a></h2> <h2><a class="toc-backref" href="#id39">class</a></h2>
<p>Implements a trivial single-inheritance class system.</p> <p>Implements a trivial single-inheritance class system.</p>
<ul> <ul>
<li><p class="first"><tt class="docutils literal">Foo = defclass(Foo[, ParentClass])</tt></p> <li><p class="first"><tt class="docutils literal">Foo = defclass(Foo[, ParentClass])</tt></p>
@ -2391,7 +2443,7 @@ library itself uses them for constructors.</p>
</div> </div>
</div> </div>
<div class="section" id="in-game-ui-library"> <div class="section" id="in-game-ui-library">
<h1><a class="toc-backref" href="#id39">In-game UI Library</a></h1> <h1><a class="toc-backref" href="#id40">In-game UI Library</a></h1>
<p>A number of lua modules with names starting with <tt class="docutils literal">gui</tt> are dedicated <p>A number of lua modules with names starting with <tt class="docutils literal">gui</tt> are dedicated
to wrapping the natives of the <tt class="docutils literal">dfhack.screen</tt> module in a way that to wrapping the natives of the <tt class="docutils literal">dfhack.screen</tt> module in a way that
is easy to use. This allows relatively easily and naturally creating is easy to use. This allows relatively easily and naturally creating
@ -2400,12 +2452,12 @@ dialogs that integrate in the main game UI window.</p>
things ranging from the basic <tt class="docutils literal">Painter</tt>, <tt class="docutils literal">View</tt> and <tt class="docutils literal">Screen</tt> things ranging from the basic <tt class="docutils literal">Painter</tt>, <tt class="docutils literal">View</tt> and <tt class="docutils literal">Screen</tt>
classes, to fully functional predefined dialogs.</p> classes, to fully functional predefined dialogs.</p>
<div class="section" id="gui"> <div class="section" id="gui">
<h2><a class="toc-backref" href="#id40">gui</a></h2> <h2><a class="toc-backref" href="#id41">gui</a></h2>
<p>This module defines the most important classes and functions for <p>This module defines the most important classes and functions for
implementing interfaces. This documents those of them that are implementing interfaces. This documents those of them that are
considered stable.</p> considered stable.</p>
<div class="section" id="misc"> <div class="section" id="misc">
<h3><a class="toc-backref" href="#id41">Misc</a></h3> <h3><a class="toc-backref" href="#id42">Misc</a></h3>
<ul> <ul>
<li><p class="first"><tt class="docutils literal">USE_GRAPHICS</tt></p> <li><p class="first"><tt class="docutils literal">USE_GRAPHICS</tt></p>
<p>Contains the value of <tt class="docutils literal">dfhack.screen.inGraphicsMode()</tt>, which cannot be <p>Contains the value of <tt class="docutils literal">dfhack.screen.inGraphicsMode()</tt>, which cannot be
@ -2444,7 +2496,7 @@ msec. This is intended for rendering blinking interface objects.</p>
</ul> </ul>
</div> </div>
<div class="section" id="viewrect-class"> <div class="section" id="viewrect-class">
<h3><a class="toc-backref" href="#id42">ViewRect class</a></h3> <h3><a class="toc-backref" href="#id43">ViewRect class</a></h3>
<p>This class represents an on-screen rectangle with an associated independent <p>This class represents an on-screen rectangle with an associated independent
clip area rectangle. It is the base of the <tt class="docutils literal">Painter</tt> class, and is used by clip area rectangle. It is the base of the <tt class="docutils literal">Painter</tt> class, and is used by
<tt class="docutils literal">Views</tt> to track their client area.</p> <tt class="docutils literal">Views</tt> to track their client area.</p>
@ -2492,7 +2544,7 @@ it with the clip area of the original object.</p>
</ul> </ul>
</div> </div>
<div class="section" id="painter-class"> <div class="section" id="painter-class">
<h3><a class="toc-backref" href="#id43">Painter class</a></h3> <h3><a class="toc-backref" href="#id44">Painter class</a></h3>
<p>The painting natives in <tt class="docutils literal">dfhack.screen</tt> apply to the whole screen, are <p>The painting natives in <tt class="docutils literal">dfhack.screen</tt> apply to the whole screen, are
completely stateless and don't implement clipping.</p> completely stateless and don't implement clipping.</p>
<p>The Painter class inherits from ViewRect to provide clipping and local <p>The Painter class inherits from ViewRect to provide clipping and local
@ -2563,7 +2615,7 @@ painter:pen(foo):seek(x,y):char(1):advance(1):string('bar')...
</pre> </pre>
</div> </div>
<div class="section" id="view-class"> <div class="section" id="view-class">
<h3><a class="toc-backref" href="#id44">View class</a></h3> <h3><a class="toc-backref" href="#id45">View class</a></h3>
<p>This class is the common abstract base of both the stand-alone screens <p>This class is the common abstract base of both the stand-alone screens
and common widgets to be used inside them. It defines the basic layout, and common widgets to be used inside them. It defines the basic layout,
rendering and event handling framework.</p> rendering and event handling framework.</p>
@ -2687,7 +2739,7 @@ Returns <em>true</em> if any of the subviews handled the event.</p>
</ul> </ul>
</div> </div>
<div class="section" id="screen-class"> <div class="section" id="screen-class">
<h3><a class="toc-backref" href="#id45">Screen class</a></h3> <h3><a class="toc-backref" href="#id46">Screen class</a></h3>
<p>This is a View subclass intended for use as a stand-alone dialog or screen. <p>This is a View subclass intended for use as a stand-alone dialog or screen.
It adds the following methods:</p> It adds the following methods:</p>
<ul> <ul>
@ -2741,7 +2793,7 @@ the screen is removed by any means here.</p>
</ul> </ul>
</div> </div>
<div class="section" id="framedscreen-class"> <div class="section" id="framedscreen-class">
<h3><a class="toc-backref" href="#id46">FramedScreen class</a></h3> <h3><a class="toc-backref" href="#id47">FramedScreen class</a></h3>
<p>A Screen subclass that paints a visible frame around its body. <p>A Screen subclass that paints a visible frame around its body.
Most dialogs should inherit from this class.</p> Most dialogs should inherit from this class.</p>
<p>A framed screen has the following attributes:</p> <p>A framed screen has the following attributes:</p>
@ -2779,10 +2831,10 @@ Most dialogs should inherit from this class.</p>
</div> </div>
</div> </div>
<div class="section" id="gui-widgets"> <div class="section" id="gui-widgets">
<h2><a class="toc-backref" href="#id47">gui.widgets</a></h2> <h2><a class="toc-backref" href="#id48">gui.widgets</a></h2>
<p>This module implements some basic widgets based on the View infrastructure.</p> <p>This module implements some basic widgets based on the View infrastructure.</p>
<div class="section" id="widget-class"> <div class="section" id="widget-class">
<h3><a class="toc-backref" href="#id48">Widget class</a></h3> <h3><a class="toc-backref" href="#id49">Widget class</a></h3>
<p>Base of all the widgets. Inherits from View and has the following attributes:</p> <p>Base of all the widgets. Inherits from View and has the following attributes:</p>
<ul> <ul>
<li><p class="first"><tt class="docutils literal">frame = <span class="pre">{...}</span></tt></p> <li><p class="first"><tt class="docutils literal">frame = <span class="pre">{...}</span></tt></p>
@ -2848,7 +2900,7 @@ inset, or a table with the following fields:</p>
</ul> </ul>
</div> </div>
<div class="section" id="panel-class"> <div class="section" id="panel-class">
<h3><a class="toc-backref" href="#id49">Panel class</a></h3> <h3><a class="toc-backref" href="#id50">Panel class</a></h3>
<p>Inherits from Widget, and intended for grouping a number of subviews.</p> <p>Inherits from Widget, and intended for grouping a number of subviews.</p>
<p>Has attributes:</p> <p>Has attributes:</p>
<ul> <ul>
@ -2861,7 +2913,7 @@ inset, or a table with the following fields:</p>
</ul> </ul>
</div> </div>
<div class="section" id="pages-class"> <div class="section" id="pages-class">
<h3><a class="toc-backref" href="#id50">Pages class</a></h3> <h3><a class="toc-backref" href="#id51">Pages class</a></h3>
<p>Subclass of Panel; keeps exactly one child visible.</p> <p>Subclass of Panel; keeps exactly one child visible.</p>
<ul> <ul>
<li><p class="first"><tt class="docutils literal">Pages{ <span class="pre">...,</span> selected = ... }</tt></p> <li><p class="first"><tt class="docutils literal">Pages{ <span class="pre">...,</span> selected = ... }</tt></p>
@ -2877,7 +2929,7 @@ It is permitted to use the subview object, or its <tt class="docutils literal">v
</ul> </ul>
</div> </div>
<div class="section" id="editfield-class"> <div class="section" id="editfield-class">
<h3><a class="toc-backref" href="#id51">EditField class</a></h3> <h3><a class="toc-backref" href="#id52">EditField class</a></h3>
<p>Subclass of Widget; implements a simple edit field.</p> <p>Subclass of Widget; implements a simple edit field.</p>
<p>Attributes:</p> <p>Attributes:</p>
<table class="docutils field-list" frame="void" rules="none"> <table class="docutils field-list" frame="void" rules="none">
@ -2899,7 +2951,7 @@ If it returns false, the character is ignored.</td>
</table> </table>
</div> </div>
<div class="section" id="label-class"> <div class="section" id="label-class">
<h3><a class="toc-backref" href="#id52">Label class</a></h3> <h3><a class="toc-backref" href="#id53">Label class</a></h3>
<p>This Widget subclass implements flowing semi-static text.</p> <p>This Widget subclass implements flowing semi-static text.</p>
<p>It has the following attributes:</p> <p>It has the following attributes:</p>
<table class="docutils field-list" frame="void" rules="none"> <table class="docutils field-list" frame="void" rules="none">
@ -2995,7 +3047,7 @@ this may be extended with mouse click support.</p>
</ul> </ul>
</div> </div>
<div class="section" id="list-class"> <div class="section" id="list-class">
<h3><a class="toc-backref" href="#id53">List class</a></h3> <h3><a class="toc-backref" href="#id54">List class</a></h3>
<p>The List widget implements a simple list with paging.</p> <p>The List widget implements a simple list with paging.</p>
<p>It has the following attributes:</p> <p>It has the following attributes:</p>
<table class="docutils field-list" frame="void" rules="none"> <table class="docutils field-list" frame="void" rules="none">
@ -3081,7 +3133,7 @@ with the following fields:</p>
</ul> </ul>
</div> </div>
<div class="section" id="filteredlist-class"> <div class="section" id="filteredlist-class">
<h3><a class="toc-backref" href="#id54">FilteredList class</a></h3> <h3><a class="toc-backref" href="#id55">FilteredList class</a></h3>
<p>This widget combines List, EditField and Label into a combo-box like <p>This widget combines List, EditField and Label into a combo-box like
construction that allows filtering the list by subwords of its items.</p> construction that allows filtering the list by subwords of its items.</p>
<p>In addition to passing through all attributes supported by List, it <p>In addition to passing through all attributes supported by List, it
@ -3134,14 +3186,14 @@ index <tt class="docutils literal">pos</tt> in the <em>unfiltered</em> list if p
</div> </div>
</div> </div>
<div class="section" id="plugins"> <div class="section" id="plugins">
<h1><a class="toc-backref" href="#id55">Plugins</a></h1> <h1><a class="toc-backref" href="#id56">Plugins</a></h1>
<p>DFHack plugins may export native functions and events <p>DFHack plugins may export native functions and events
to lua contexts. They are automatically imported by 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 <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> module file is still necessary for <tt class="docutils literal">require</tt> to read.</p>
<p>The following plugins have lua support.</p> <p>The following plugins have lua support.</p>
<div class="section" id="burrows"> <div class="section" id="burrows">
<h2><a class="toc-backref" href="#id56">burrows</a></h2> <h2><a class="toc-backref" href="#id57">burrows</a></h2>
<p>Implements extended burrow manipulations.</p> <p>Implements extended burrow manipulations.</p>
<p>Events:</p> <p>Events:</p>
<ul> <ul>
@ -3179,16 +3231,16 @@ 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> <p>The lua module file also re-exports functions from <tt class="docutils literal">dfhack.burrows</tt>.</p>
</div> </div>
<div class="section" id="sort"> <div class="section" id="sort">
<h2><a class="toc-backref" href="#id57">sort</a></h2> <h2><a class="toc-backref" href="#id58">sort</a></h2>
<p>Does not export any native functions as of now. Instead, it <p>Does not export any native functions as of now. Instead, it
calls lua code to perform the actual ordering of list items.</p> calls lua code to perform the actual ordering of list items.</p>
</div> </div>
<div class="section" id="eventful"> <div class="section" id="eventful">
<h2><a class="toc-backref" href="#id58">Eventful</a></h2> <h2><a class="toc-backref" href="#id59">Eventful</a></h2>
<p>This plugin exports some events to lua thus allowing to run lua functions <p>This plugin exports some events to lua thus allowing to run lua functions
on DF world events.</p> on DF world events.</p>
<div class="section" id="list-of-events"> <div class="section" id="list-of-events">
<h3><a class="toc-backref" href="#id59">List of events</a></h3> <h3><a class="toc-backref" href="#id60">List of events</a></h3>
<ol class="arabic"> <ol class="arabic">
<li><p class="first"><tt class="docutils literal">onReactionComplete(reaction,unit,input_items,input_reagents,output_items,call_native)</tt></p> <li><p class="first"><tt class="docutils literal">onReactionComplete(reaction,unit,input_items,input_reagents,output_items,call_native)</tt></p>
<p>Auto activates if detects reactions starting with <tt class="docutils literal">LUA_HOOK_</tt>. Is called when reaction finishes.</p> <p>Auto activates if detects reactions starting with <tt class="docutils literal">LUA_HOOK_</tt>. Is called when reaction finishes.</p>
@ -3218,7 +3270,7 @@ tweaking (e.g. adding custom reactions)</p>
</ol> </ol>
</div> </div>
<div class="section" id="events-from-eventmanager"> <div class="section" id="events-from-eventmanager">
<h3><a class="toc-backref" href="#id60">Events from EventManager</a></h3> <h3><a class="toc-backref" href="#id61">Events from EventManager</a></h3>
<p>These events are straight from EventManager module. Each of them first needs to be enabled. See functions for more info. If you register a listener before the game is loaded, be aware that no events will be triggered immediately after loading, so you might need to add another event listener for when the game first loads in some cases.</p> <p>These events are straight from EventManager module. Each of them first needs to be enabled. See functions for more info. If you register a listener before the game is loaded, be aware that no events will be triggered immediately after loading, so you might need to add another event listener for when the game first loads in some cases.</p>
<ol class="arabic"> <ol class="arabic">
<li><p class="first"><tt class="docutils literal">onBuildingCreatedDestroyed(building_id)</tt></p> <li><p class="first"><tt class="docutils literal">onBuildingCreatedDestroyed(building_id)</tt></p>
@ -3263,7 +3315,7 @@ tweaking (e.g. adding custom reactions)</p>
</ol> </ol>
</div> </div>
<div class="section" id="functions"> <div class="section" id="functions">
<h3><a class="toc-backref" href="#id61">Functions</a></h3> <h3><a class="toc-backref" href="#id62">Functions</a></h3>
<ol class="arabic"> <ol class="arabic">
<li><p class="first"><tt class="docutils literal">registerReaction(reaction_name,callback)</tt></p> <li><p class="first"><tt class="docutils literal">registerReaction(reaction_name,callback)</tt></p>
<p>Simplified way of using onReactionComplete; the callback is function (same params as event).</p> <p>Simplified way of using onReactionComplete; the callback is function (same params as event).</p>
@ -3284,7 +3336,7 @@ as callback. Best used with <tt class="docutils literal">gui.dwarfmode</tt> clas
</ol> </ol>
</div> </div>
<div class="section" id="examples"> <div class="section" id="examples">
<h3><a class="toc-backref" href="#id62">Examples</a></h3> <h3><a class="toc-backref" href="#id63">Examples</a></h3>
<p>Spawn dragon breath on each item attempt to contaminate wound:</p> <p>Spawn dragon breath on each item attempt to contaminate wound:</p>
<pre class="literal-block"> <pre class="literal-block">
b=require &quot;plugins.eventful&quot; b=require &quot;plugins.eventful&quot;
@ -3320,11 +3372,11 @@ b.addReactionToShop(&quot;TAN_A_HIDE&quot;,&quot;LEATHERWORKS&quot;)
</div> </div>
</div> </div>
<div class="section" id="building-hacks"> <div class="section" id="building-hacks">
<h2><a class="toc-backref" href="#id63">Building-hacks</a></h2> <h2><a class="toc-backref" href="#id64">Building-hacks</a></h2>
<p>This plugin overwrites some methods in workshop df class so that mechanical workshops are possible. Although <p>This plugin overwrites some methods in workshop df class so that mechanical workshops are possible. Although
plugin export a function it's recommended to use lua decorated function.</p> plugin export a function it's recommended to use lua decorated function.</p>
<div class="section" id="id1"> <div class="section" id="id1">
<h3><a class="toc-backref" href="#id64">Functions</a></h3> <h3><a class="toc-backref" href="#id65">Functions</a></h3>
<dl class="docutils"> <dl class="docutils">
<dt><tt class="docutils literal">registerBuilding(table)</tt> where table must contain name, as a workshop raw name, the rest are optional:</dt> <dt><tt class="docutils literal">registerBuilding(table)</tt> where table must contain name, as a workshop raw name, the rest are optional:</dt>
<dd><ol class="first last arabic simple"> <dd><ol class="first last arabic simple">
@ -3352,7 +3404,7 @@ plugin export a function it's recommended to use lua decorated function.</p>
</dl> </dl>
</div> </div>
<div class="section" id="id2"> <div class="section" id="id2">
<h3><a class="toc-backref" href="#id65">Examples</a></h3> <h3><a class="toc-backref" href="#id66">Examples</a></h3>
<p>Simple mechanical workshop:</p> <p>Simple mechanical workshop:</p>
<pre class="literal-block"> <pre class="literal-block">
require('plugins.building-hacks').registerBuilding{name=&quot;BONE_GRINDER&quot;, require('plugins.building-hacks').registerBuilding{name=&quot;BONE_GRINDER&quot;,
@ -3370,11 +3422,11 @@ require('plugins.building-hacks').registerBuilding{name=&quot;BONE_GRINDER&quot;
</div> </div>
</div> </div>
<div class="section" id="scripts"> <div class="section" id="scripts">
<h1><a class="toc-backref" href="#id66">Scripts</a></h1> <h1><a class="toc-backref" href="#id67">Scripts</a></h1>
<p>Any files with the .lua extension placed into hack/scripts/* <p>Any files with the .lua extension placed into hack/scripts/*
are automatically used by the DFHack core as commands. The are automatically used by the DFHack core as commands. The
matching command name consists of the name of the file sans matching command name consists of the name of the file without
the extension.</p> the extension. First DFHack searches for the script in the save folder/raw/scripts folder. If it is not found there, it searches in the DF/raw/scripts folder. If it is not there, it searches in DF/hack/scripts. If it is not there, it gives up.</p>
<p>If the first line of the script is a one-line comment, it is <p>If the first line of the script is a one-line comment, it is
used by the built-in <tt class="docutils literal">ls</tt> and <tt class="docutils literal">help</tt> commands.</p> used by the built-in <tt class="docutils literal">ls</tt> and <tt class="docutils literal">help</tt> commands.</p>
<p><strong>NOTE:</strong> Scripts placed in subdirectories still can be accessed, but <p><strong>NOTE:</strong> Scripts placed in subdirectories still can be accessed, but
@ -3400,8 +3452,22 @@ The <tt class="docutils literal">name</tt> argument should be the name stem, as
</li> </li>
</ul> </ul>
<p>Note that this function lets errors propagate to the caller.</p> <p>Note that this function lets errors propagate to the caller.</p>
<ul>
<li><p class="first"><tt class="docutils literal">dfhack.script_environment(name)</tt></p>
<p>Run an Lua script and return its environment.
This command allows you to use scripts like modules for increased portability.
It is highly recommended that if you are a modder you put your custom modules in <tt class="docutils literal">raw/scripts</tt> and use <tt class="docutils literal">script_environment</tt> instead of <tt class="docutils literal">require</tt> so that saves with your mod installed will be self-contained and can be transferred to people who do have DFHack but do not have your mod installed.
You can say <tt class="docutils literal"><span class="pre">dfhack.script_environment('add-thought').addEmotionToUnit([arguments</span> go here])</tt> and it will have the desired effect.
It will call the script in question with the global <tt class="docutils literal">moduleMode</tt> set to <tt class="docutils literal">true</tt> so that the script can return early.
This is useful because if the script is called from the console it should deal with its console arguments and if it is called by <tt class="docutils literal">script_environment</tt> it should only create its global functions and return.
You can also access global variables with, for example <tt class="docutils literal"><span class="pre">print(dfhack.script_environment('add-thought').validArgs)</span></tt>
The function <tt class="docutils literal">script_environment</tt> is fast enough that it is recommended that you not store its result in a nonlocal variable, because your script might need to load a different version of that script if the save is unloaded and a save with a different mod that overrides the same script with a slightly different functionality is loaded.
This will not be an issue in most cases.
This function also permits circular dependencies of scripts.</p>
</li>
</ul>
<div class="section" id="save-init-script"> <div class="section" id="save-init-script">
<h2><a class="toc-backref" href="#id67">Save init script</a></h2> <h2><a class="toc-backref" href="#id68">Save init script</a></h2>
<p>If a save directory contains a file called <tt class="docutils literal">raw/init.lua</tt>, it is <p>If a save directory contains a file called <tt class="docutils literal">raw/init.lua</tt>, it is
automatically loaded and executed every time the save is loaded. automatically loaded and executed every time the save is loaded.
The same applies to any files called <tt class="docutils literal"><span class="pre">raw/init.d/*.lua</span></tt>. Every The same applies to any files called <tt class="docutils literal"><span class="pre">raw/init.d/*.lua</span></tt>. Every

@ -789,6 +789,8 @@ by whitespace. To include whitespace in an argument, quote it in double quotes.
To include a double quote character, use <tt class="docutils literal">\&quot;</tt> inside double quotes.</p> To include a double quote character, use <tt class="docutils literal">\&quot;</tt> inside double quotes.</p>
<p>If the first non-whitespace character of a line is <tt class="docutils literal">#</tt>, the line is treated <p>If the first non-whitespace character of a line is <tt class="docutils literal">#</tt>, the line is treated
as a comment, i.e. a silent no-op command.</p> as a comment, i.e. a silent no-op command.</p>
<p>When reading commands from dfhack.init or with the <tt class="docutils literal">script</tt> command, if the final character on a line is a backslash then the next uncommented line is considered a continuation of that line, with the backslash deleted.
Commented lines are skipped, so it is possible to comment out parts of a command with the <tt class="docutils literal">#</tt> character.</p>
<p>If the first non-whitespace character is <tt class="docutils literal">:</tt>, the command is parsed in a special <p>If the first non-whitespace character is <tt class="docutils literal">:</tt>, the command is parsed in a special
alternative mode: first, non-whitespace characters immediately following the <tt class="docutils literal">:</tt> alternative mode: first, non-whitespace characters immediately following the <tt class="docutils literal">:</tt>
are used as the command name; the remaining part of the line, starting with the first are used as the command name; the remaining part of the line, starting with the first
@ -2666,6 +2668,8 @@ units or with 'zone nick' to mass-rename units in pastures and cages).</p>
<p>Creatures trained for war or hunting will be ignored as well.</p> <p>Creatures trained for war or hunting will be ignored as well.</p>
<p>Creatures assigned to cages will be ignored if the cage is defined as a room <p>Creatures assigned to cages will be ignored if the cage is defined as a room
(to avoid butchering unnamed zoo animals).</p> (to avoid butchering unnamed zoo animals).</p>
<p>Creatures who will not reproduce (because they're not interested in the opposite
sex or have been gelded) have first priority for butchering.</p>
<p>Once you have too much adults, the oldest will be butchered first. <p>Once you have too much adults, the oldest will be butchered first.
Once you have too much kids, the youngest will be butchered first. Once you have too much kids, the youngest will be butchered first.
If you don't set any target count the following default will be used: If you don't set any target count the following default will be used:
@ -3051,10 +3055,6 @@ directory.</p>
<li><p class="first">gui/stockpiles</p> <li><p class="first">gui/stockpiles</p>
<p>Load and save stockpile settings from the 'q' menu. <p>Load and save stockpile settings from the 'q' menu.
Usage:</p> Usage:</p>
<div class="system-message">
<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">Readme.rst</tt>, line 2225)</p>
<p>Unexpected indentation.</p>
</div>
<blockquote> <blockquote>
<p>gui/stockpiles -save to save the current stockpile <p>gui/stockpiles -save to save the current stockpile
gui/stockpiles -load to load settings into the current stockpile gui/stockpiles -load to load settings into the current stockpile