MetzNet
/
dfhack
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'warmist/dev-buildings' into develop

develop
Alexander Gavrilov 2014-05-04 19:52:01 +04:00
parent b76ededc1b 94904eb66b
commit 13584f08c5
8 changed files with 752 additions and 132 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

308
Lua API.html
Unescape Escape View File

@ -344,92 +344,97 @@ ul.auto-toc {
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#df-data-structure-wrapper" id="id1">DF data structure wrapper</a><ul>
<li><a class="reference internal" href="#typed-object-references" id="id2">Typed object references</a><ul>
<li><a class="reference internal" href="#primitive-references" id="id3">Primitive references</a></li>
<li><a class="reference internal" href="#struct-references" id="id4">Struct references</a></li>
<li><a class="reference internal" href="#container-references" id="id5">Container references</a></li>
<li><a class="reference internal" href="#bitfield-references" id="id6">Bitfield references</a></li>
<li><a class="reference internal" href="#df-data-structure-wrapper" id="id3">DF data structure wrapper</a><ul>
<li><a class="reference internal" href="#typed-object-references" id="id4">Typed object references</a><ul>
<li><a class="reference internal" href="#primitive-references" id="id5">Primitive references</a></li>
<li><a class="reference internal" href="#struct-references" id="id6">Struct references</a></li>
<li><a class="reference internal" href="#container-references" id="id7">Container references</a></li>
<li><a class="reference internal" href="#bitfield-references" id="id8">Bitfield references</a></li>
</ul>
</li>
<li><a class="reference internal" href="#named-types" id="id7">Named types</a></li>
<li><a class="reference internal" href="#global-functions" id="id8">Global functions</a></li>
<li><a class="reference internal" href="#recursive-table-assignment" id="id9">Recursive table assignment</a></li>
<li><a class="reference internal" href="#named-types" id="id9">Named types</a></li>
<li><a class="reference internal" href="#global-functions" id="id10">Global functions</a></li>
<li><a class="reference internal" href="#recursive-table-assignment" id="id11">Recursive table assignment</a></li>
</ul>
</li>
<li><a class="reference internal" href="#dfhack-api" id="id10">DFHack API</a><ul>
<li><a class="reference internal" href="#native-utilities" id="id11">Native utilities</a><ul>
<li><a class="reference internal" href="#input-output" id="id12">Input &amp; Output</a></li>
<li><a class="reference internal" href="#exception-handling" id="id13">Exception handling</a></li>
<li><a class="reference internal" href="#miscellaneous" id="id14">Miscellaneous</a></li>
<li><a class="reference internal" href="#locking-and-finalization" id="id15">Locking and finalization</a></li>
<li><a class="reference internal" href="#persistent-configuration-storage" id="id16">Persistent configuration storage</a></li>
<li><a class="reference internal" href="#material-info-lookup" id="id17">Material info lookup</a></li>
<li><a class="reference internal" href="#random-number-generation" id="id18">Random number generation</a></li>
<li><a class="reference internal" href="#dfhack-api" id="id12">DFHack API</a><ul>
<li><a class="reference internal" href="#native-utilities" id="id13">Native utilities</a><ul>
<li><a class="reference internal" href="#input-output" id="id14">Input &amp; Output</a></li>
<li><a class="reference internal" href="#exception-handling" id="id15">Exception handling</a></li>
<li><a class="reference internal" href="#miscellaneous" id="id16">Miscellaneous</a></li>
<li><a class="reference internal" href="#locking-and-finalization" id="id17">Locking and finalization</a></li>
<li><a class="reference internal" href="#persistent-configuration-storage" id="id18">Persistent configuration storage</a></li>
<li><a class="reference internal" href="#material-info-lookup" id="id19">Material info lookup</a></li>
<li><a class="reference internal" href="#random-number-generation" id="id20">Random number generation</a></li>
</ul>
</li>
<li><a class="reference internal" href="#c-function-wrappers" id="id19">C++ function wrappers</a><ul>
<li><a class="reference internal" href="#gui-module" id="id20">Gui module</a></li>
<li><a class="reference internal" href="#job-module" id="id21">Job module</a></li>
<li><a class="reference internal" href="#units-module" id="id22">Units module</a></li>
<li><a class="reference internal" href="#items-module" id="id23">Items module</a></li>
<li><a class="reference internal" href="#maps-module" id="id24">Maps module</a></li>
<li><a class="reference internal" href="#burrows-module" id="id25">Burrows module</a></li>
<li><a class="reference internal" href="#buildings-module" id="id26">Buildings module</a></li>
<li><a class="reference internal" href="#constructions-module" id="id27">Constructions module</a></li>
<li><a class="reference internal" href="#screen-api" id="id28">Screen API</a></li>
<li><a class="reference internal" href="#internal-api" id="id29">Internal API</a></li>
<li><a class="reference internal" href="#c-function-wrappers" id="id21">C++ function wrappers</a><ul>
<li><a class="reference internal" href="#gui-module" id="id22">Gui module</a></li>
<li><a class="reference internal" href="#job-module" id="id23">Job module</a></li>
<li><a class="reference internal" href="#units-module" id="id24">Units module</a></li>
<li><a class="reference internal" href="#items-module" id="id25">Items module</a></li>
<li><a class="reference internal" href="#maps-module" id="id26">Maps module</a></li>
<li><a class="reference internal" href="#burrows-module" id="id27">Burrows 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="#screen-api" id="id30">Screen API</a></li>
<li><a class="reference internal" href="#internal-api" id="id31">Internal API</a></li>
</ul>
</li>
<li><a class="reference internal" href="#core-interpreter-context" id="id30">Core interpreter context</a><ul>
<li><a class="reference internal" href="#event-type" id="id31">Event type</a></li>
<li><a class="reference internal" href="#core-interpreter-context" id="id32">Core interpreter context</a><ul>
<li><a class="reference internal" href="#event-type" id="id33">Event type</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#lua-modules" id="id32">Lua Modules</a><ul>
<li><a class="reference internal" href="#global-environment" id="id33">Global environment</a></li>
<li><a class="reference internal" href="#utils" id="id34">utils</a></li>
<li><a class="reference internal" href="#dumper" id="id35">dumper</a></li>
<li><a class="reference internal" href="#class" id="id36">class</a></li>
<li><a class="reference internal" href="#lua-modules" id="id34">Lua Modules</a><ul>
<li><a class="reference internal" href="#global-environment" id="id35">Global environment</a></li>
<li><a class="reference internal" href="#utils" id="id36">utils</a></li>
<li><a class="reference internal" href="#dumper" id="id37">dumper</a></li>
<li><a class="reference internal" href="#class" id="id38">class</a></li>
</ul>
</li>
<li><a class="reference internal" href="#in-game-ui-library" id="id37">In-game UI Library</a><ul>
<li><a class="reference internal" href="#gui" id="id38">gui</a><ul>
<li><a class="reference internal" href="#misc" id="id39">Misc</a></li>
<li><a class="reference internal" href="#viewrect-class" id="id40">ViewRect class</a></li>
<li><a class="reference internal" href="#painter-class" id="id41">Painter class</a></li>
<li><a class="reference internal" href="#view-class" id="id42">View class</a></li>
<li><a class="reference internal" href="#screen-class" id="id43">Screen class</a></li>
<li><a class="reference internal" href="#framedscreen-class" id="id44">FramedScreen class</a></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="#gui" id="id40">gui</a><ul>
<li><a class="reference internal" href="#misc" id="id41">Misc</a></li>
<li><a class="reference internal" href="#viewrect-class" id="id42">ViewRect class</a></li>
<li><a class="reference internal" href="#painter-class" id="id43">Painter class</a></li>
<li><a class="reference internal" href="#view-class" id="id44">View class</a></li>
<li><a class="reference internal" href="#screen-class" id="id45">Screen class</a></li>
<li><a class="reference internal" href="#framedscreen-class" id="id46">FramedScreen class</a></li>
</ul>
</li>
<li><a class="reference internal" href="#gui-widgets" id="id45">gui.widgets</a><ul>
<li><a class="reference internal" href="#widget-class" id="id46">Widget class</a></li>
<li><a class="reference internal" href="#panel-class" id="id47">Panel class</a></li>
<li><a class="reference internal" href="#pages-class" id="id48">Pages class</a></li>
<li><a class="reference internal" href="#editfield-class" id="id49">EditField class</a></li>
<li><a class="reference internal" href="#label-class" id="id50">Label class</a></li>
<li><a class="reference internal" href="#list-class" id="id51">List class</a></li>
<li><a class="reference internal" href="#filteredlist-class" id="id52">FilteredList class</a></li>
<li><a class="reference internal" href="#gui-widgets" id="id47">gui.widgets</a><ul>
<li><a class="reference internal" href="#widget-class" id="id48">Widget class</a></li>
<li><a class="reference internal" href="#panel-class" id="id49">Panel class</a></li>
<li><a class="reference internal" href="#pages-class" id="id50">Pages class</a></li>
<li><a class="reference internal" href="#editfield-class" id="id51">EditField class</a></li>
<li><a class="reference internal" href="#label-class" id="id52">Label class</a></li>
<li><a class="reference internal" href="#list-class" id="id53">List class</a></li>
<li><a class="reference internal" href="#filteredlist-class" id="id54">FilteredList class</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#plugins" id="id53">Plugins</a><ul>
<li><a class="reference internal" href="#burrows" id="id54">burrows</a></li>
<li><a class="reference internal" href="#sort" id="id55">sort</a></li>
<li><a class="reference internal" href="#eventful" id="id56">Eventful</a><ul>
<li><a class="reference internal" href="#list-of-events" id="id57">List of events</a></li>
<li><a class="reference internal" href="#events-from-eventmanager" id="id58">Events from EventManager</a></li>
<li><a class="reference internal" href="#functions" id="id59">Functions</a></li>
<li><a class="reference internal" href="#examples" id="id60">Examples</a></li>
<li><a class="reference internal" href="#plugins" id="id55">Plugins</a><ul>
<li><a class="reference internal" href="#burrows" id="id56">burrows</a></li>
<li><a class="reference internal" href="#sort" id="id57">sort</a></li>
<li><a class="reference internal" href="#eventful" id="id58">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="#events-from-eventmanager" id="id60">Events from EventManager</a></li>
<li><a class="reference internal" href="#functions" id="id61">Functions</a></li>
<li><a class="reference internal" href="#examples" id="id62">Examples</a></li>
</ul>
</li>
<li><a class="reference internal" href="#building-hacks" id="id63">Building-hacks</a><ul>
<li><a class="reference internal" href="#id1" id="id64">Functions</a></li>
<li><a class="reference internal" href="#id2" id="id65">Examples</a></li>
</ul>
</li>
<li><a class="reference internal" href="#scripts" id="id61">Scripts</a><ul>
<li><a class="reference internal" href="#save-init-script" id="id62">Save init script</a></li>
</ul>
</li>
<li><a class="reference internal" href="#scripts" id="id66">Scripts</a><ul>
<li><a class="reference internal" href="#save-init-script" id="id67">Save init script</a></li>
</ul>
</li>
</ul>
@ -449,7 +454,7 @@ native C++ commands, and invoked by plugins written in c++.</p>
It does not describe all of the utility functions
implemented by Lua files located in hack/lua/...</p>
<div class="section" id="df-data-structure-wrapper">
<h1><a class="toc-backref" href="#id1">DF data structure wrapper</a></h1>
<h1><a class="toc-backref" href="#id3">DF data structure wrapper</a></h1>
<p>DF structures described by the xml files in library/xml are exported
to lua code as a tree of objects and functions under the <tt class="docutils literal">df</tt> global,
which broadly maps to the <tt class="docutils literal">df</tt> namespace in C++.</p>
@ -485,7 +490,7 @@ both nested types and fields corresponding to global symbols.</p>
<p>In addition to the <tt class="docutils literal">global</tt> object and top-level types the <tt class="docutils literal">df</tt>
global also contains a few global builtin utility functions.</p>
<div class="section" id="typed-object-references">
<h2><a class="toc-backref" href="#id2">Typed object references</a></h2>
<h2><a class="toc-backref" href="#id4">Typed object references</a></h2>
<p>The underlying primitive lua object is userdata with a metatable.
Every structured field access produces a new userdata instance.</p>
<p>All typed objects have the following built-in features:</p>
@ -534,7 +539,7 @@ Step defaults to the natural object size.</p>
</li>
</ul>
<div class="section" id="primitive-references">
<h3><a class="toc-backref" href="#id3">Primitive references</a></h3>
<h3><a class="toc-backref" href="#id5">Primitive references</a></h3>
<p>References of the <em>_kind</em> <tt class="docutils literal">'primitive'</tt> are used for objects
that don't fit any of the other reference types. Such
references can only appear as a value of a pointer field,
@ -546,7 +551,7 @@ no bound checking is performed, since buffer length is not available.
Index 0 is equivalent to the <tt class="docutils literal">value</tt> field.</p>
</div>
<div class="section" id="struct-references">
<h3><a class="toc-backref" href="#id4">Struct references</a></h3>
<h3><a class="toc-backref" href="#id6">Struct references</a></h3>
<p>Struct references are used for class and struct objects.</p>
<p>They implement the following features:</p>
<ul>
@ -580,7 +585,7 @@ shadowing rules.</p>
</ul>
</div>
<div class="section" id="container-references">
<h3><a class="toc-backref" href="#id5">Container references</a></h3>
<h3><a class="toc-backref" href="#id7">Container references</a></h3>
<p>Containers represent vectors and arrays, possibly resizable.</p>
<p>A container field can associate an enum to the container
reference, which allows accessing elements using string keys
@ -624,7 +629,7 @@ use <tt class="docutils literal">#ref</tt>, or just <tt class="docutils literal"
</ul>
</div>
<div class="section" id="bitfield-references">
<h3><a class="toc-backref" href="#id6">Bitfield references</a></h3>
<h3><a class="toc-backref" href="#id8">Bitfield references</a></h3>
<p>Bitfields behave like special fixed-size containers.
Consider them to be something in between structs and
fixed-size vectors.</p>
@ -640,7 +645,7 @@ them, e.g. <tt class="docutils literal">matinfo:matches{metal=true}</tt>.</p>
</div>
</div>
<div class="section" id="named-types">
<h2><a class="toc-backref" href="#id7">Named types</a></h2>
<h2><a class="toc-backref" href="#id9">Named types</a></h2>
<p>Named types are exposed in the <tt class="docutils literal">df</tt> tree with names identical
to the C++ version, except for the <tt class="docutils literal">::</tt> vs <tt class="docutils literal">.</tt> difference.</p>
<p>All types and the global object have the following features:</p>
@ -678,7 +683,7 @@ xml have a <tt class="docutils literal">type.find(key)</tt> function that wraps
method provided in C++.</p>
</div>
<div class="section" id="global-functions">
<h2><a class="toc-backref" href="#id8">Global functions</a></h2>
<h2><a class="toc-backref" href="#id10">Global functions</a></h2>
<p>The <tt class="docutils literal">df</tt> table itself contains the following functions and values:</p>
<ul>
<li><p class="first"><tt class="docutils literal">NULL</tt>, <tt class="docutils literal">df.NULL</tt></p>
@ -723,7 +728,7 @@ a lightuserdata, or a number.</p>
</ul>
</div>
<div class="section" id="recursive-table-assignment">
<h2><a class="toc-backref" href="#id9">Recursive table assignment</a></h2>
<h2><a class="toc-backref" href="#id11">Recursive table assignment</a></h2>
<p>Recursive assignment is invoked when a lua table is assigned
to a C++ object or field, i.e. one of:</p>
<ul class="simple">
@ -805,12 +810,12 @@ cleanup.</p>
</div>
</div>
<div class="section" id="dfhack-api">
<h1><a class="toc-backref" href="#id10">DFHack API</a></h1>
<h1><a class="toc-backref" href="#id12">DFHack API</a></h1>
<p>DFHack utility functions are placed in the <tt class="docutils literal">dfhack</tt> global tree.</p>
<div class="section" id="native-utilities">
<h2><a class="toc-backref" href="#id11">Native utilities</a></h2>
<h2><a class="toc-backref" href="#id13">Native utilities</a></h2>
<div class="section" id="input-output">
<h3><a class="toc-backref" href="#id12">Input &amp; Output</a></h3>
<h3><a class="toc-backref" href="#id14">Input &amp; Output</a></h3>
<ul>
<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.print(args...)</span></tt></p>
<p>Output tab-separated args as standard lua print would do,
@ -846,7 +851,7 @@ string, global environment and command-line history file.</p>
</ul>
</div>
<div class="section" id="exception-handling">
<h3><a class="toc-backref" href="#id13">Exception handling</a></h3>
<h3><a class="toc-backref" href="#id15">Exception handling</a></h3>
<ul>
<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.error(msg[,level[,verbose]])</span></tt></p>
<p>Throws a dfhack exception object with location and stack trace.
@ -902,7 +907,7 @@ following properties:</p>
</ul>
</div>
<div class="section" id="miscellaneous">
<h3><a class="toc-backref" href="#id14">Miscellaneous</a></h3>
<h3><a class="toc-backref" href="#id16">Miscellaneous</a></h3>
<ul>
<li><p class="first"><tt class="docutils literal">dfhack.VERSION</tt></p>
<p>DFHack version string constant.</p>
@ -915,7 +920,7 @@ both from the curry call and the closure call itself. I.e.
</ul>
</div>
<div class="section" id="locking-and-finalization">
<h3><a class="toc-backref" href="#id15">Locking and finalization</a></h3>
<h3><a class="toc-backref" href="#id17">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.
@ -948,7 +953,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="#id16">Persistent configuration storage</a></h3>
<h3><a class="toc-backref" href="#id18">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
@ -998,7 +1003,7 @@ as an all-zero mask.</p>
the persistent entry will <strong>NOT</strong> delete the associated masks.</p>
</div>
<div class="section" id="material-info-lookup">
<h3><a class="toc-backref" href="#id17">Material info lookup</a></h3>
<h3><a class="toc-backref" href="#id19">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>
@ -1042,7 +1047,7 @@ Accept dfhack_material_category auto-assign table.</p>
</ul>
</div>
<div class="section" id="random-number-generation">
<h3><a class="toc-backref" href="#id18">Random number generation</a></h3>
<h3><a class="toc-backref" href="#id20">Random number generation</a></h3>
<ul>
<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.random.new([seed[,perturb_count]])</span></tt></p>
<p>Creates a new random number generator object. Without any
@ -1086,7 +1091,7 @@ Dimension may be 1, 2 or 3 (default).</p>
</div>
</div>
<div class="section" id="c-function-wrappers">
<h2><a class="toc-backref" href="#id19">C++ function wrappers</a></h2>
<h2><a class="toc-backref" href="#id21">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
@ -1127,7 +1132,7 @@ can be omitted.</p>
</li>
</ul>
<div class="section" id="gui-module">
<h3><a class="toc-backref" href="#id20">Gui module</a></h3>
<h3><a class="toc-backref" href="#id22">Gui module</a></h3>
<ul>
<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.gui.getCurViewscreen([skip_dismissed])</span></tt></p>
<p>Returns the topmost viewscreen. If <tt class="docutils literal">skip_dismissed</tt> is <em>true</em>,
@ -1197,7 +1202,7 @@ operations accordingly. The units are used to call <tt class="docutils literal">
</ul>
</div>
<div class="section" id="job-module">
<h3><a class="toc-backref" href="#id21">Job module</a></h3>
<h3><a class="toc-backref" href="#id23">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>
@ -1258,7 +1263,7 @@ the flags in the job item.</p>
</ul>
</div>
<div class="section" id="units-module">
<h3><a class="toc-backref" href="#id22">Units module</a></h3>
<h3><a class="toc-backref" href="#id24">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>
@ -1362,7 +1367,7 @@ or raws. The <tt class="docutils literal">ignore_noble</tt> boolean disables the
</ul>
</div>
<div class="section" id="items-module">
<h3><a class="toc-backref" href="#id23">Items module</a></h3>
<h3><a class="toc-backref" href="#id25">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>
@ -1432,7 +1437,7 @@ Returns <em>false</em> in case of error.</p>
</ul>
</div>
<div class="section" id="maps-module">
<h3><a class="toc-backref" href="#id24">Maps module</a></h3>
<h3><a class="toc-backref" href="#id26">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>
@ -1501,7 +1506,7 @@ burrows, or the presence of invaders.</p>
</ul>
</div>
<div class="section" id="burrows-module">
<h3><a class="toc-backref" href="#id25">Burrows module</a></h3>
<h3><a class="toc-backref" href="#id27">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>
@ -1536,7 +1541,7 @@ burrows, or the presence of invaders.</p>
</ul>
</div>
<div class="section" id="buildings-module">
<h3><a class="toc-backref" href="#id26">Buildings module</a></h3>
<h3><a class="toc-backref" href="#id28">Buildings module</a></h3>
<ul>
<li><p class="first"><tt class="docutils literal">dfhack.buildings.getGeneralRef(building, type)</tt></p>
<p>Searches for a general_ref with the given type.</p>
@ -1686,7 +1691,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="#id27">Constructions module</a></h3>
<h3><a class="toc-backref" href="#id29">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
@ -1702,7 +1707,7 @@ Returns <em>true, was_only_planned</em> if removed; or <em>false</em> if none fo
</ul>
</div>
<div class="section" id="screen-api">
<h3><a class="toc-backref" href="#id28">Screen API</a></h3>
<h3><a class="toc-backref" href="#id30">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>
@ -1890,7 +1895,7 @@ options; if multiple interpretations exist, the table will contain multiple keys
</ul>
</div>
<div class="section" id="internal-api">
<h3><a class="toc-backref" href="#id29">Internal API</a></h3>
<h3><a class="toc-backref" href="#id31">Internal API</a></h3>
<p>These functions are intended for the use by dfhack developers,
and are only documented here for completeness:</p>
<ul>
@ -1959,7 +1964,7 @@ Returns: <em>file_names</em> or empty table if not found.</p>
</div>
</div>
<div class="section" id="core-interpreter-context">
<h2><a class="toc-backref" href="#id30">Core interpreter context</a></h2>
<h2><a class="toc-backref" href="#id32">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>
@ -1990,7 +1995,7 @@ 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="#id31">Event type</a></h3>
<h3><a class="toc-backref" href="#id33">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.
@ -2022,7 +2027,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="#id32">Lua Modules</a></h1>
<h1><a class="toc-backref" href="#id34">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
@ -2051,7 +2056,7 @@ in this document.</p>
</li>
</ul>
<div class="section" id="global-environment">
<h2><a class="toc-backref" href="#id33">Global environment</a></h2>
<h2><a class="toc-backref" href="#id35">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>
@ -2114,7 +2119,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="#id34">utils</a></h2>
<h2><a class="toc-backref" href="#id36">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>
@ -2263,7 +2268,7 @@ throws an error.</p>
</ul>
</div>
<div class="section" id="dumper">
<h2><a class="toc-backref" href="#id35">dumper</a></h2>
<h2><a class="toc-backref" href="#id37">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>
@ -2276,7 +2281,7 @@ the other arguments see the original documentation link above.</p>
</ul>
</div>
<div class="section" id="class">
<h2><a class="toc-backref" href="#id36">class</a></h2>
<h2><a class="toc-backref" href="#id38">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>
@ -2367,7 +2372,7 @@ library itself uses them for constructors.</p>
</div>
</div>
<div class="section" id="in-game-ui-library">
<h1><a class="toc-backref" href="#id37">In-game UI Library</a></h1>
<h1><a class="toc-backref" href="#id39">In-game UI Library</a></h1>
<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
is easy to use. This allows relatively easily and naturally creating
@ -2376,12 +2381,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>
classes, to fully functional predefined dialogs.</p>
<div class="section" id="gui">
<h2><a class="toc-backref" href="#id38">gui</a></h2>
<h2><a class="toc-backref" href="#id40">gui</a></h2>
<p>This module defines the most important classes and functions for
implementing interfaces. This documents those of them that are
considered stable.</p>
<div class="section" id="misc">
<h3><a class="toc-backref" href="#id39">Misc</a></h3>
<h3><a class="toc-backref" href="#id41">Misc</a></h3>
<ul>
<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
@ -2420,7 +2425,7 @@ msec. This is intended for rendering blinking interface objects.</p>
</ul>
</div>
<div class="section" id="viewrect-class">
<h3><a class="toc-backref" href="#id40">ViewRect class</a></h3>
<h3><a class="toc-backref" href="#id42">ViewRect class</a></h3>
<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
<tt class="docutils literal">Views</tt> to track their client area.</p>
@ -2468,7 +2473,7 @@ it with the clip area of the original object.</p>
</ul>
</div>
<div class="section" id="painter-class">
<h3><a class="toc-backref" href="#id41">Painter class</a></h3>
<h3><a class="toc-backref" href="#id43">Painter class</a></h3>
<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>
<p>The Painter class inherits from ViewRect to provide clipping and local
@ -2539,7 +2544,7 @@ painter:pen(foo):seek(x,y):char(1):advance(1):string('bar')...
</pre>
</div>
<div class="section" id="view-class">
<h3><a class="toc-backref" href="#id42">View class</a></h3>
<h3><a class="toc-backref" href="#id44">View class</a></h3>
<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,
rendering and event handling framework.</p>
@ -2663,7 +2668,7 @@ Returns <em>true</em> if any of the subviews handled the event.</p>
</ul>
</div>
<div class="section" id="screen-class">
<h3><a class="toc-backref" href="#id43">Screen class</a></h3>
<h3><a class="toc-backref" href="#id45">Screen class</a></h3>
<p>This is a View subclass intended for use as a stand-alone dialog or screen.
It adds the following methods:</p>
<ul>
@ -2717,7 +2722,7 @@ the screen is removed by any means here.</p>
</ul>
</div>
<div class="section" id="framedscreen-class">
<h3><a class="toc-backref" href="#id44">FramedScreen class</a></h3>
<h3><a class="toc-backref" href="#id46">FramedScreen class</a></h3>
<p>A Screen subclass that paints a visible frame around its body.
Most dialogs should inherit from this class.</p>
<p>A framed screen has the following attributes:</p>
@ -2755,10 +2760,10 @@ Most dialogs should inherit from this class.</p>
</div>
</div>
<div class="section" id="gui-widgets">
<h2><a class="toc-backref" href="#id45">gui.widgets</a></h2>
<h2><a class="toc-backref" href="#id47">gui.widgets</a></h2>
<p>This module implements some basic widgets based on the View infrastructure.</p>
<div class="section" id="widget-class">
<h3><a class="toc-backref" href="#id46">Widget class</a></h3>
<h3><a class="toc-backref" href="#id48">Widget class</a></h3>
<p>Base of all the widgets. Inherits from View and has the following attributes:</p>
<ul>
<li><p class="first"><tt class="docutils literal">frame = <span class="pre">{...}</span></tt></p>
@ -2824,7 +2829,7 @@ inset, or a table with the following fields:</p>
</ul>
</div>
<div class="section" id="panel-class">
<h3><a class="toc-backref" href="#id47">Panel class</a></h3>
<h3><a class="toc-backref" href="#id49">Panel class</a></h3>
<p>Inherits from Widget, and intended for grouping a number of subviews.</p>
<p>Has attributes:</p>
<ul>
@ -2837,7 +2842,7 @@ inset, or a table with the following fields:</p>
</ul>
</div>
<div class="section" id="pages-class">
<h3><a class="toc-backref" href="#id48">Pages class</a></h3>
<h3><a class="toc-backref" href="#id50">Pages class</a></h3>
<p>Subclass of Panel; keeps exactly one child visible.</p>
<ul>
<li><p class="first"><tt class="docutils literal">Pages{ <span class="pre">...,</span> selected = ... }</tt></p>
@ -2853,7 +2858,7 @@ It is permitted to use the subview object, or its <tt class="docutils literal">v
</ul>
</div>
<div class="section" id="editfield-class">
<h3><a class="toc-backref" href="#id49">EditField class</a></h3>
<h3><a class="toc-backref" href="#id51">EditField class</a></h3>
<p>Subclass of Widget; implements a simple edit field.</p>
<p>Attributes:</p>
<table class="docutils field-list" frame="void" rules="none">
@ -2875,7 +2880,7 @@ If it returns false, the character is ignored.</td>
</table>
</div>
<div class="section" id="label-class">
<h3><a class="toc-backref" href="#id50">Label class</a></h3>
<h3><a class="toc-backref" href="#id52">Label class</a></h3>
<p>This Widget subclass implements flowing semi-static text.</p>
<p>It has the following attributes:</p>
<table class="docutils field-list" frame="void" rules="none">
@ -2971,7 +2976,7 @@ this may be extended with mouse click support.</p>
</ul>
</div>
<div class="section" id="list-class">
<h3><a class="toc-backref" href="#id51">List class</a></h3>
<h3><a class="toc-backref" href="#id53">List class</a></h3>
<p>The List widget implements a simple list with paging.</p>
<p>It has the following attributes:</p>
<table class="docutils field-list" frame="void" rules="none">
@ -3057,7 +3062,7 @@ with the following fields:</p>
</ul>
</div>
<div class="section" id="filteredlist-class">
<h3><a class="toc-backref" href="#id52">FilteredList class</a></h3>
<h3><a class="toc-backref" href="#id54">FilteredList class</a></h3>
<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>
<p>In addition to passing through all attributes supported by List, it
@ -3110,14 +3115,14 @@ index <tt class="docutils literal">pos</tt> in the <em>unfiltered</em> list if p
</div>
</div>
<div class="section" id="plugins">
<h1><a class="toc-backref" href="#id53">Plugins</a></h1>
<h1><a class="toc-backref" href="#id55">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="#id54">burrows</a></h2>
<h2><a class="toc-backref" href="#id56">burrows</a></h2>
<p>Implements extended burrow manipulations.</p>
<p>Events:</p>
<ul>
@ -3155,16 +3160,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>
</div>
<div class="section" id="sort">
<h2><a class="toc-backref" href="#id55">sort</a></h2>
<h2><a class="toc-backref" href="#id57">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 class="section" id="eventful">
<h2><a class="toc-backref" href="#id56">Eventful</a></h2>
<h2><a class="toc-backref" href="#id58">Eventful</a></h2>
<p>This plugin exports some events to lua thus allowing to run lua functions
on DF world events.</p>
<div class="section" id="list-of-events">
<h3><a class="toc-backref" href="#id57">List of events</a></h3>
<h3><a class="toc-backref" href="#id59">List of events</a></h3>
<ol class="arabic">
<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>
@ -3194,7 +3199,7 @@ tweaking (e.g. adding custom reactions)</p>
</ol>
</div>
<div class="section" id="events-from-eventmanager">
<h3><a class="toc-backref" href="#id58">Events from EventManager</a></h3>
<h3><a class="toc-backref" href="#id60">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>
<ol class="arabic">
<li><p class="first"><tt class="docutils literal">onBuildingCreatedDestroyed(building_id)</tt></p>
@ -3227,7 +3232,7 @@ tweaking (e.g. adding custom reactions)</p>
</ol>
</div>
<div class="section" id="functions">
<h3><a class="toc-backref" href="#id59">Functions</a></h3>
<h3><a class="toc-backref" href="#id61">Functions</a></h3>
<ol class="arabic">
<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>
@ -3241,10 +3246,13 @@ tweaking (e.g. adding custom reactions)</p>
<li><p class="first"><tt class="docutils literal">enableEvent(evType,frequency)</tt></p>
<p>Enable event checking for EventManager events. For event types use <tt class="docutils literal">eventType</tt> table. Note that different types of events require different frequencies to be effective. The frequency is how many ticks EventManager will wait before checking if that type of event has happened. If multiple scripts or plugins use the same event type, the smallest frequency is the one that is used, so you might get events triggered more often than the frequency you use here.</p>
</li>
<li><p class="first"><tt class="docutils literal">registerSidebar(shop_name,callback)</tt></p>
<p>Enable callback when sidebar for <tt class="docutils literal">shop_name</tt> is drawn. Usefull for custom workshop views e.g. using gui.dwarfmode lib.</p>
</li>
</ol>
</div>
<div class="section" id="examples">
<h3><a class="toc-backref" href="#id60">Examples</a></h3>
<h3><a class="toc-backref" href="#id62">Examples</a></h3>
<p>Spawn dragon breath on each item attempt to contaminate wound:</p>
<pre class="literal-block">
b=require &quot;plugins.eventful&quot;
@ -3256,13 +3264,13 @@ end
<pre class="literal-block">
b=require &quot;plugins.eventful&quot;
b.onReactionComplete.one=function(reaction,unit,in_items,in_reag,out_items,call_native)
b.registerReaction(&quot;LUA_HOOK_LAY_BOMB&quot;,function(reaction,unit,in_items,in_reag,out_items,call_native)
local pos=copyall(unit.pos)
-- spawn dragonbreath after 100 ticks
dfhack.timeout(100,&quot;ticks&quot;,function() dfhack.maps.spawnFlow(pos,6,0,0,50000) end)
--do not call real item creation code
call_native.value=false
end
end)
</pre>
<p>Grenade example:</p>
<pre class="literal-block">
@ -3279,9 +3287,57 @@ b.addReactionToShop(&quot;TAN_A_HIDE&quot;,&quot;LEATHERWORKS&quot;)
</pre>
</div>
</div>
<div class="section" id="building-hacks">
<h2><a class="toc-backref" href="#id63">Building-hacks</a></h2>
<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>
<div class="section" id="id1">
<h3><a class="toc-backref" href="#id64">Functions</a></h3>
<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>
<dd><ol class="first last arabic simple">
<li>name -- custom workshop id e.g. <tt class="docutils literal">SOAPMAKER</tt></li>
<li>fix_impassible -- if true make impassible tiles impassible to liquids too</li>
<li>consume -- how much machine power is needed to work. Disables reactions if not supplied enough</li>
<li>produce -- how much machine power is produced. Use discouraged as there is no way to change this at runtime</li>
<li>gears -- a table or <tt class="docutils literal"><span class="pre">{x=?,y=?}</span></tt> of connection points for machines</li>
<li>action -- a table of number (how much ticks to skip) and a function which gets called on shop update</li>
<li>animate -- a table of frames which can be a table of:<ol class="loweralpha">
<li>tables of 4 numbers <tt class="docutils literal">{tile,fore,back,bright}</tt> OR</li>
<li>empty table (tile not modified) OR</li>
<li><tt class="docutils literal"><span class="pre">{x=&lt;number&gt;</span> <span class="pre">y=&lt;number&gt;</span> + 4 numbers like in first case}</tt>, this generates full frame useful for animations that change little (1-2 tiles)</li>
</ol>
</li>
</ol>
</dd>
<dt>Animate table also might contain:</dt>
<dd><ol class="first last arabic simple">
<li>frameLenght -- how many ticks does one frame take OR</li>
<li>isMechanical -- a bool that says to try to match to mechanical system (i.e. how gears are turning)</li>
</ol>
</dd>
</dl>
</div>
<div class="section" id="id2">
<h3><a class="toc-backref" href="#id65">Examples</a></h3>
<p>Simple mechanical workshop:</p>
<pre class="literal-block">
require('plugins.building-hacks').registerBuilding{name=&quot;BONE_GRINDER&quot;,
consume=15,
gears={x=0,y=0}, --connection point
animate={
isMechanical=true, --animate the same connection point as vanilla gear
frames={
{{x=0,y=0,42,7,0,0}}, --first frame, 1 changed tile
{{x=0,y=0,15,7,0,0}} -- second frame, same
}
}
</pre>
</div>
</div>
</div>
<div class="section" id="scripts">
<h1><a class="toc-backref" href="#id61">Scripts</a></h1>
<h1><a class="toc-backref" href="#id66">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
@ -3312,7 +3368,7 @@ The <tt class="docutils literal">name</tt> argument should be the name stem, as
</ul>
<p>Note that this function lets errors propagate to the caller.</p>
<div class="section" id="save-init-script">
<h2><a class="toc-backref" href="#id62">Save init script</a></h2>
<h2><a class="toc-backref" href="#id67">Save init script</a></h2>
<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.
The same applies to any files called <tt class="docutils literal"><span class="pre">raw/init.d/*.lua</span></tt>. Every

50
Lua API.rst
Unescape Escape View File

@ -3179,6 +3179,10 @@ Functions
Enable event checking for EventManager events. For event types use ``eventType`` table. Note that different types of events require different frequencies to be effective. The frequency is how many ticks EventManager will wait before checking if that type of event has happened. If multiple scripts or plugins use the same event type, the smallest frequency is the one that is used, so you might get events triggered more often than the frequency you use here.
5. ``registerSidebar(shop_name,callback)``
Enable callback when sidebar for ``shop_name`` is drawn. Usefull for custom workshop views e.g. using gui.dwarfmode lib.
Examples
--------
Spawn dragon breath on each item attempt to contaminate wound::
@ -3192,13 +3196,13 @@ Reaction complete example::
b=require "plugins.eventful"
b.onReactionComplete.one=function(reaction,unit,in_items,in_reag,out_items,call_native)
b.registerReaction("LUA_HOOK_LAY_BOMB",function(reaction,unit,in_items,in_reag,out_items,call_native)
local pos=copyall(unit.pos)
-- spawn dragonbreath after 100 ticks
dfhack.timeout(100,"ticks",function() dfhack.maps.spawnFlow(pos,6,0,0,50000) end)
--do not call real item creation code
call_native.value=false
end
end)
Grenade example::
@ -3213,6 +3217,48 @@ Integrated tannery::
b=require "plugins.eventful"
b.addReactionToShop("TAN_A_HIDE","LEATHERWORKS")
Building-hacks
==============
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.
Functions
---------
``registerBuilding(table)`` where table must contain name, as a workshop raw name, the rest are optional:
1. name -- custom workshop id e.g. ``SOAPMAKER``
2. fix_impassible -- if true make impassible tiles impassible to liquids too
3. consume -- how much machine power is needed to work. Disables reactions if not supplied enough
4. produce -- how much machine power is produced. Use discouraged as there is no way to change this at runtime
5. gears -- a table or ``{x=?,y=?}`` of connection points for machines
6. action -- a table of number (how much ticks to skip) and a function which gets called on shop update
7. animate -- a table of frames which can be a table of:
a. tables of 4 numbers ``{tile,fore,back,bright}`` OR
b. empty table (tile not modified) OR
c. ``{x=<number> y=<number> + 4 numbers like in first case}``, this generates full frame useful for animations that change little (1-2 tiles)
Animate table also might contain:
1. frameLenght -- how many ticks does one frame take OR
2. isMechanical -- a bool that says to try to match to mechanical system (i.e. how gears are turning)
Examples
--------
Simple mechanical workshop::
require('plugins.building-hacks').registerBuilding{name="BONE_GRINDER",
consume=15,
gears={x=0,y=0}, --connection point
animate={
isMechanical=true, --animate the same connection point as vanilla gear
frames={
{{x=0,y=0,42,7,0,0}}, --first frame, 1 changed tile
{{x=0,y=0,15,7,0,0}} -- second frame, same
}
}
=======
Scripts
=======

2
NEWS
Unescape Escape View File

@ -5,6 +5,8 @@ DFHack future
- Lua API for listing files in directory. Needed for mod-manager.
- Lua API for creating unit combat reports and writing to gamelog.
- support for multiple raw/init.d/*.lua init scripts in one save.
- eventful now has a more friendly way of making custom sidebars
- new plugin: building-hacks. Allows to add custom functionality and/or animations to buildings.
New scripts:
- gui/mod-manager: allows installing/uninstalling mods into df from df/mods directory.

1
plugins/CMakeLists.txt
Unescape Escape View File

@ -164,6 +164,7 @@ if (BUILD_SUPPORTED)
DFHACK_PLUGIN(3dveins 3dveins.cpp)
DFHACK_PLUGIN(strangemood strangemood.cpp)
DFHACK_PLUGIN(command-prompt command-prompt.cpp)
DFHACK_PLUGIN(building-hacks building-hacks.cpp LINK_LIBRARIES lua)
endif()
# this is the skeleton plugin. If you want to make your own, make a copy and then change it

389
plugins/building-hacks.cpp
Unescape Escape View File

@ -0,0 +1,389 @@
//most of the code is shamelessly stolen from steam-engine.cpp
#include "Core.h"
#include "Error.h"
#include <Console.h>
#include <Export.h>
#include <PluginManager.h>
#include "LuaTools.h"
#include <VTableInterpose.h>
#include "MiscUtils.h"
#include "df/building_doorst.h"
#include "df/building_workshopst.h"
#include "df/machine.h"
#include "df/machine_tile_set.h"
#include "df/power_info.h"
#include "df/world.h"
#include "df/buildings_other_id.h"
#include "df/coord.h"
#include "df/tile_building_occ.h"
#include "df/building_drawbuffer.h"
#include <map>
using namespace DFHack;
using namespace df::enums;
using df::global::world;
DFHACK_PLUGIN("building-hacks");
struct graphic_tile //could do just 31x31 and be done, but it's nicer to have flexible imho.
{
int16_t tile; //originally uint8_t but we need to indicate non-animated tiles
int8_t fore;
int8_t back;
int8_t bright;
};
struct workshop_hack_data
{
int32_t myType;
bool impassible_fix;
//machine stuff
df::machine_tile_set connections;
df::power_info powerInfo;
//animation
std::vector<std::vector<graphic_tile> > frames;
bool machine_timing; //6 frames used in vanilla
int frame_skip; // e.g. 2 means have to ticks between frames
//updateCallback:
int skip_updates;
};
typedef std::map<int32_t,workshop_hack_data> workshops_data_t;
workshops_data_t hacked_workshops;
static void handle_update_action(color_ostream &out,df::building_workshopst*){};
DEFINE_LUA_EVENT_1(onUpdateAction,handle_update_action,df::building_workshopst*);
DFHACK_PLUGIN_LUA_EVENTS {
DFHACK_LUA_EVENT(onUpdateAction),
DFHACK_LUA_END
};
struct work_hook : df::building_workshopst{
typedef df::building_workshopst interpose_base;
workshop_hack_data* find_def()
{
if (type == workshop_type::Custom)
{
auto it=hacked_workshops.find(this->getCustomType());
if(it!=hacked_workshops.end())
return &(it->second);
}
return NULL;
}
inline bool is_fully_built()
{
return getBuildStage() >= getMaxBuildStage();
}
DEFINE_VMETHOD_INTERPOSE(uint32_t,getImpassableOccupancy,())
{
if(auto def = find_def())
{
if(def->impassible_fix)
return tile_building_occ::Impassable;
}
return INTERPOSE_NEXT(getImpassableOccupancy)();
}
DEFINE_VMETHOD_INTERPOSE(void, getPowerInfo, (df::power_info *info))
{
if (auto def = find_def())
{
info->produced = def->powerInfo.produced;
info->consumed = def->powerInfo.consumed;
return;
}
INTERPOSE_NEXT(getPowerInfo)(info);
}
DEFINE_VMETHOD_INTERPOSE(df::machine_info*, getMachineInfo, ())
{
if (find_def())
return &machine;
return INTERPOSE_NEXT(getMachineInfo)();
}
DEFINE_VMETHOD_INTERPOSE(bool, isPowerSource, ())
{
workshop_hack_data* def=find_def();
if (def && def->powerInfo.produced>0)
return true;
return INTERPOSE_NEXT(isPowerSource)();
}
DEFINE_VMETHOD_INTERPOSE(void, categorize, (bool free))
{
if (find_def())
{
auto &vec = world->buildings.other[buildings_other_id::ANY_MACHINE];
insert_into_vector(vec, &df::building::id, (df::building*)this);
}
INTERPOSE_NEXT(categorize)(free);
}
DEFINE_VMETHOD_INTERPOSE(void, uncategorize, ())
{
if (find_def())
{
auto &vec = world->buildings.other[buildings_other_id::ANY_MACHINE];
erase_from_vector(vec, &df::building::id, id);
}
INTERPOSE_NEXT(uncategorize)();
}
DEFINE_VMETHOD_INTERPOSE(bool, canConnectToMachine, (df::machine_tile_set *info))
{
if (auto def = find_def())
{
int real_cx = centerx, real_cy = centery;
bool ok = false;
for (size_t i = 0; i < def->connections.tiles.size(); i++)
{
// the original function connects to the center tile
centerx = x1 + def->connections.tiles[i].x;
centery = y1 + def->connections.tiles[i].y;
if (!INTERPOSE_NEXT(canConnectToMachine)(info))
continue;
ok = true;
break;
}
centerx = real_cx; centery = real_cy;
return ok;
}
else
return INTERPOSE_NEXT(canConnectToMachine)(info);
}
DEFINE_VMETHOD_INTERPOSE(bool, isUnpowered, ())
{
if (auto def = find_def())
{
if(def->powerInfo.consumed==0)
return false;
if(machine.machine_id==-1)
return true;
df::machine* target_machine=df::machine::find(machine.machine_id);
if(target_machine && target_machine->flags.bits.active)
return false;
return true;
}
return INTERPOSE_NEXT(isUnpowered)();
}
DEFINE_VMETHOD_INTERPOSE(void, updateAction, ())
{
if(auto def = find_def())
{
if(def->skip_updates!=0 && is_fully_built())
{
df::world* world = df::global::world;
if(world->frame_counter % def->skip_updates == 0)
{
CoreSuspendClaimer suspend;
color_ostream_proxy out(Core::getInstance().getConsole());
onUpdateAction(out,this);
}
}
}
INTERPOSE_NEXT(updateAction)();
}
DEFINE_VMETHOD_INTERPOSE(void, drawBuilding, (df::building_drawbuffer *db, int16_t unk))
{
INTERPOSE_NEXT(drawBuilding)(db, unk);
if (auto def = find_def())
{
if (!is_fully_built() || def->frames.size()==0)
return;
int frame=0;
if(!def->machine_timing)
{
int frame_mod=def->frames.size()* def->frame_skip;
df::world* world = df::global::world;
frame=(world->frame_counter % frame_mod)/def->frame_skip;
}
else
{
if(machine.machine_id!=-1)
{
df::machine* target_machine=df::machine::find(machine.machine_id);
if(target_machine)
{
frame=target_machine->visual_phase % def->frames.size();
}
}
}
int w=db->x2-db->x1+1;
std::vector<graphic_tile> &cur_frame=def->frames[frame];
for(int i=0;i<cur_frame.size();i++)
{
if(cur_frame[i].tile>=0)
{
int tx=i % w;
int ty=i / w;
db->tile[tx][ty]=cur_frame[i].tile;
db->back[tx][ty]=cur_frame[i].back;
db->bright[tx][ty]=cur_frame[i].bright;
db->fore[tx][ty]=cur_frame[i].fore;
}
}
}
}
};
IMPLEMENT_VMETHOD_INTERPOSE(work_hook, getImpassableOccupancy);
IMPLEMENT_VMETHOD_INTERPOSE(work_hook, getPowerInfo);
IMPLEMENT_VMETHOD_INTERPOSE(work_hook, getMachineInfo);
IMPLEMENT_VMETHOD_INTERPOSE(work_hook, isPowerSource);
IMPLEMENT_VMETHOD_INTERPOSE(work_hook, categorize);
IMPLEMENT_VMETHOD_INTERPOSE(work_hook, uncategorize);
IMPLEMENT_VMETHOD_INTERPOSE(work_hook, canConnectToMachine);
IMPLEMENT_VMETHOD_INTERPOSE(work_hook, isUnpowered);
IMPLEMENT_VMETHOD_INTERPOSE(work_hook, updateAction);
IMPLEMENT_VMETHOD_INTERPOSE(work_hook, drawBuilding);
void clear_mapping()
{
hacked_workshops.clear();
}
static void loadFrames(lua_State* L,workshop_hack_data& def,int stack_pos)
{
luaL_checktype(L,stack_pos,LUA_TTABLE);
lua_pushvalue(L,stack_pos);
lua_pushnil(L);
while (lua_next(L, -2) != 0) {
luaL_checktype(L,-1,LUA_TTABLE);
lua_pushnil(L);
std::vector<graphic_tile> frame;
while (lua_next(L, -2) != 0) {
graphic_tile t;
lua_pushnumber(L,1);
lua_gettable(L,-2);
if(lua_isnil(L,-1))
{
t.tile=-1;
lua_pop(L,1);
}
else
{
t.tile=lua_tonumber(L,-1);
lua_pop(L,1);
lua_pushnumber(L,2);
lua_gettable(L,-2);
t.fore=lua_tonumber(L,-1);
lua_pop(L,1);
lua_pushnumber(L,3);
lua_gettable(L,-2);
t.back=lua_tonumber(L,-1);
lua_pop(L,1);
lua_pushnumber(L,4);
lua_gettable(L,-2);
t.bright=lua_tonumber(L,-1);
lua_pop(L,1);
}
frame.push_back(t);
lua_pop(L,1);
}
lua_pop(L,1);
def.frames.push_back(frame);
}
lua_pop(L,1);
return ;
}
//arguments: custom type,impassible fix (bool), consumed power, produced power, list of connection points, update skip(0/nil to disable)
// table of frames,frame to tick ratio (-1 for machine control)
static int addBuilding(lua_State* L)
{
workshop_hack_data newDefinition;
newDefinition.myType=luaL_checkint(L,1);
newDefinition.impassible_fix=luaL_checkint(L,2);
newDefinition.powerInfo.consumed=luaL_checkint(L,3);
newDefinition.powerInfo.produced=luaL_checkint(L,4);
//table of machine connection points
luaL_checktype(L,5,LUA_TTABLE);
lua_pushvalue(L,5);
lua_pushnil(L);
while (lua_next(L, -2) != 0) {
lua_getfield(L,-1,"x");
int x=lua_tonumber(L,-1);
lua_pop(L,1);
lua_getfield(L,-1,"y");
int y=lua_tonumber(L,-1);
lua_pop(L,1);
newDefinition.connections.can_connect.push_back(-1);//TODO add this too...
newDefinition.connections.tiles.push_back(df::coord(x,y,0));
lua_pop(L,1);
}
lua_pop(L,1);
//updates
newDefinition.skip_updates=luaL_optinteger(L,6,0);
//animation
if(!lua_isnil(L,7))
{
loadFrames(L,newDefinition,7);
newDefinition.frame_skip=luaL_optinteger(L,8,-1);
if(newDefinition.frame_skip==0)
newDefinition.frame_skip=1;
if(newDefinition.frame_skip<0)
newDefinition.machine_timing=true;
else
newDefinition.machine_timing=false;
}
hacked_workshops[newDefinition.myType]=newDefinition;
return 0;
}
DFHACK_PLUGIN_LUA_COMMANDS{
DFHACK_LUA_COMMAND(addBuilding),
DFHACK_LUA_END
};
static void enable_hooks(bool enable)
{
INTERPOSE_HOOK(work_hook,getImpassableOccupancy).apply(enable);
//machine part
INTERPOSE_HOOK(work_hook,getPowerInfo).apply(enable);
INTERPOSE_HOOK(work_hook,getMachineInfo).apply(enable);
INTERPOSE_HOOK(work_hook,isPowerSource).apply(enable);
INTERPOSE_HOOK(work_hook,categorize).apply(enable);
INTERPOSE_HOOK(work_hook,uncategorize).apply(enable);
INTERPOSE_HOOK(work_hook,canConnectToMachine).apply(enable);
INTERPOSE_HOOK(work_hook,isUnpowered).apply(enable);
//update n render
INTERPOSE_HOOK(work_hook,updateAction).apply(enable);
INTERPOSE_HOOK(work_hook,drawBuilding).apply(enable);
}
DFhackCExport command_result plugin_onstatechange(color_ostream &out, state_change_event event)
{
switch (event) {
case SC_WORLD_LOADED:
enable_hooks(true);
break;
case SC_WORLD_UNLOADED:
enable_hooks(false);
clear_mapping();
break;
default:
break;
}
return CR_OK;
}
DFhackCExport command_result plugin_init ( color_ostream &out, std::vector <PluginCommand> &commands)
{
enable_hooks(true);
return CR_OK;
}
DFhackCExport command_result plugin_shutdown ( color_ostream &out )
{
plugin_onstatechange(out,SC_WORLD_UNLOADED);
return CR_OK;
}

109
plugins/lua/building-hacks.lua
Unescape Escape View File

@ -0,0 +1,109 @@
local _ENV = mkmodule('plugins.building-hacks')
--[[
from native:
addBuilding(custom type,impassible fix (bool), consumed power, produced power, list of connection points,
update skip(0/nil to disable),table of frames,frame to tick ratio (-1 for machine control))
from here:
registerBuilding{
name -- custom workshop id e.g. SOAPMAKER << required!
fix_impassible -- make impassible tiles impassible to liquids too
consume -- how much machine power is needed to work
produce -- how much machine power is produced
gears -- a table or {x=?,y=?} of connection points for machines
action -- a table of number (how much ticks to skip) and a function which gets called on shop update
animate -- a table of
frames -- a table of
tables of 4 numbers (tile,fore,back,bright) OR
empty table (tile not modified) OR
{x=<number> y=<number> + 4 numbers like in first case} -- this generates full frame even, usefull for animations that change little (1-2 tiles)
frameLenght -- how many ticks does one frame take OR
isMechanical -- a bool that says to try to match to mechanical system (i.e. how gears are turning)
}
]]
_registeredStuff={}
local function unregall(state)
if state==SC_WORLD_UNLOADED then
onUpdateAction._library=nil
dfhack.onStateChange.building_hacks= nil
_registeredStuff={}
end
end
local function onUpdateLocal(workshop)
local f=_registeredStuff[workshop:getCustomType()]
if f then
f(workshop)
end
end
local function findCustomWorkshop(name)
local raws=df.global.world.raws.buildings.all
for k,v in ipairs(raws) do
if v.code==name then
return v
end
end
end
local function registerUpdateAction(shopId,callback)
_registeredStuff[shopId]=callback
onUpdateAction._library=onUpdateLocal
dfhack.onStateChange.building_hacks=unregall
end
local function generateFrame(tiles,w,h)
local mTiles={}
for k,v in ipairs(tiles) do
mTiles[v.x]=mTiles[v.x] or {}
mTiles[v.x][v.y]=v
end
local ret={}
for ty=0,h-1 do
for tx=0,w-1 do
if mTiles[tx] and mTiles[tx][ty] then
table.insert(ret,mTiles[tx][ty]) -- leaves x and y in but who cares
else
table.insert(ret,{})
end
end
end
return ret
end
local function processFrames(shop_def,frames)
local w,h=shop_def.dim_x,shop_def.dim_y
for frame_id,frame in ipairs(frames) do
if frame[1].x~=nil then
frames[frame_id]=generateFrame(frame,w,h)
end
end
return frames
end
function registerBuilding(args)
local shop_def=findCustomWorkshop(args.name)
local shop_id=shop_def.id
local fix_impassible
if args.fix_impassible then
fix_impassible=1
else
fix_impassible=0
end
local consume=args.consume or 0
local produce=args.produce or 0
local gears=args.gears or {}
local action=args.action --could be nil
local updateSkip=0
if action~=nil then
updateSkip=action[1]
registerUpdateAction(shop_id,action[2])
end
local animate=args.animate
local frameLength=1
local frames
if animate~=nil then
frameLength=animate.frameLength
if animate.isMechanical then
frameLength=-1
end
frames=processFrames(shop_def,animate.frames)
end
addBuilding(shop_id,fix_impassible,consume,produce,gears,updateSkip,frames,frameLength)
end
return _ENV

23
plugins/lua/eventful.lua
Unescape Escape View File

@ -25,13 +25,13 @@ local function getShopName(btype,bsubtype,bcustom)
if typenames_shop[bsubtype]~=nil then
return typenames_shop[bsubtype]
else
return nil --todo add custom (not very useful)
return df.building_def_workshopst.find(bcustom).code
end
elseif btype==df.building_type.Furnace then
if typenames_furnace[bsubtype]~=nil then
return typenames_furnace[bsubtype]
else
return nil --todo add custom (not very useful)
return df.building_def_furnacest.find(bcustom).code
end
end
end
@ -77,9 +77,19 @@ local function onPostSidebar(workshop)
wjob.choices_visible:insert("#",new_button)
end
end
if _registeredStuff.customSidebar and _registeredStuff.customSidebar[shop_id] then
_registeredStuff.customSidebar[shop_id](workshop)
end
end
end
local function customSidebarsCallback(workshop)
local shop_id=getShopName(workshop:getType(),workshop:getSubtype(),workshop:getCustomType())
if shop_id then
if _registeredStuff.customSidebar and _registeredStuff.customSidebar[shop_id] then
_registeredStuff.customSidebar[shop_id](workshop)
end
end
end
function registerReaction(reaction_name,callback)
_registeredStuff.reactionCallbacks=_registeredStuff.reactionCallbacks or {}
_registeredStuff.reactionCallbacks[reaction_name]=callback
@ -87,6 +97,13 @@ function registerReaction(reaction_name,callback)
dfhack.onStateChange.eventful=unregall
end
function registerSidebar(shop_name,callback)
_registeredStuff.customSidebar=_registeredStuff.customSidebar or {}
_registeredStuff.customSidebar[shop_name]=callback
onWorkshopFillSidebarMenu._library=customSidebarsCallback
dfhack.onStateChange.eventful=unregall
end
function removeNative(shop_name,name)
_registeredStuff.shopNonNative=_registeredStuff.shopNonNative or {}
local shops=_registeredStuff.shopNonNative

2
scripts/gui/advfort.lua
Unescape Escape View File

@ -880,7 +880,7 @@ function usetool:init(args)
wid.Label{
view_id="mainLabel",
frame = {xalign=0,yalign=0},
text={{key=keybinds.prevJob.key},{gap=1,text=dfhack.curry(usetool.getModeName,self)},{gap=1,key=keybinds.nextJob.key},
text={{key=keybinds.prevJob.key},{gap=1,text=self:callback("getModeName")},{gap=1,key=keybinds.nextJob.key},
}
},