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

Edit documentation for some scripts, and fix syntax in Lua API.rst.

develop
Alexander Gavrilov 2013-02-26 12:27:37 +04:00
parent 2bbe6824fb
commit bf0795d738
5 changed files with 274 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

98
Lua API.html
Unescape Escape View File

@ -402,10 +402,16 @@ ul.auto-toc {
<li><a class="reference internal" href="#plugins" id="id52">Plugins</a><ul> <li><a class="reference internal" href="#plugins" id="id52">Plugins</a><ul>
<li><a class="reference internal" href="#burrows" id="id53">burrows</a></li> <li><a class="reference internal" href="#burrows" id="id53">burrows</a></li>
<li><a class="reference internal" href="#sort" id="id54">sort</a></li> <li><a class="reference internal" href="#sort" id="id54">sort</a></li>
<li><a class="reference internal" href="#eventful" id="id55">Eventful</a><ul>
<li><a class="reference internal" href="#list-of-events" id="id56">List of events</a></li>
<li><a class="reference internal" href="#functions" id="id57">Functions</a></li>
<li><a class="reference internal" href="#examples" id="id58">Examples</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference internal" href="#scripts" id="id55">Scripts</a><ul> </ul>
<li><a class="reference internal" href="#save-init-script" id="id56">Save init script</a></li> </li>
<li><a class="reference internal" href="#scripts" id="id59">Scripts</a><ul>
<li><a class="reference internal" href="#save-init-script" id="id60">Save init script</a></li>
</ul> </ul>
</li> </li>
</ul> </ul>
@ -3038,9 +3044,93 @@ set is the same as used by the command line.</p>
<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">
<h2><a class="toc-backref" href="#id55">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="#id56">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>
</li>
<li><p class="first"><tt class="docutils literal">onItemContaminateWound(item,unit,wound,number1,number2)</tt></p>
<p>Is called when item tries to contaminate wound (e.g. stuck in).</p>
</li>
<li><p class="first"><tt class="docutils literal">onProjItemCheckMovement(projectile)</tt></p>
<p>Is called when projectile moves.</p>
</li>
<li><p class="first"><tt class="docutils literal">onProjItemCheckImpact(projectile,somebool)</tt></p>
<p>Is called when projectile hits something.</p>
</li>
<li><p class="first"><tt class="docutils literal">onProjUnitCheckMovement(projectile)</tt></p>
<p>Is called when projectile moves.</p>
</li>
<li><p class="first"><tt class="docutils literal">onProjUnitCheckImpact(projectile,somebool)</tt></p>
<p>Is called when projectile hits something.</p>
</li>
<li><p class="first"><tt class="docutils literal">onWorkshopFillSidebarMenu(workshop,callnative)</tt></p>
<p>Is called when viewing a workshop in 'q' mode, to populate reactions, usefull for custom viewscreens for shops.</p>
</li>
<li><p class="first"><tt class="docutils literal">postWorkshopFillSidebarMenu(workshop)</tt></p>
<p>Is called after calling (or not) native fillSidebarMenu(). Usefull for job button
tweaking (e.g. adding custom reactions)</p>
</li>
</ol>
</div>
<div class="section" id="functions">
<h3><a class="toc-backref" href="#id57">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>
</li>
<li><p class="first"><tt class="docutils literal">removeNative(shop_name)</tt></p>
<p>Removes native choice list from the building.</p>
</li>
<li><p class="first"><tt class="docutils literal">addReactionToShop(reaction_name,shop_name)</tt></p>
<p>Add a custom reaction to the building.</p>
</li>
</ol>
</div>
<div class="section" id="examples">
<h3><a class="toc-backref" href="#id58">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;
b.onItemContaminateWound.one=function(item,unit,un_wound,x,y)
local flw=dfhack.maps.spawnFlow(unit.pos,6,0,0,50000)
end
</pre>
<p>Reaction complete example:</p>
<pre class="literal-block">
b=require &quot;plugins.eventful&quot;
b.onReactionComplete.one=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
</pre>
<p>Granade example:</p>
<pre class="literal-block">
b=require &quot;plugins.eventful&quot;
b.onProjItemCheckImpact.one=function(projectile)
-- you can check if projectile.item e.g. has correct material
dfhack.maps.spawnFlow(projectile.cur_pos,6,0,0,50000)
end
</pre>
<p>Integrated tannery:</p>
<pre class="literal-block">
b=require &quot;plugins.eventful&quot;
b.addReactionToShop(&quot;TAN_A_HIDE&quot;,&quot;LEATHERWORKS&quot;)
</pre>
</div>
</div>
</div> </div>
<div class="section" id="scripts"> <div class="section" id="scripts">
<h1><a class="toc-backref" href="#id55">Scripts</a></h1> <h1><a class="toc-backref" href="#id59">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 sans
@ -3071,7 +3161,7 @@ The <tt class="docutils literal">name</tt> argument should be the name stem, as
</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>
<div class="section" id="save-init-script"> <div class="section" id="save-init-script">
<h2><a class="toc-backref" href="#id56">Save init script</a></h2> <h2><a class="toc-backref" href="#id60">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. It automatically loaded and executed every time the save is loaded. It
can also define the following functions to be called by dfhack:</p> can also define the following functions to be called by dfhack:</p>

76
Lua API.rst
Unescape Escape View File

@ -2967,51 +2967,85 @@ on DF world events.
List of events List of events
-------------- --------------
1. onReactionComplete(reaction,unit,input_items,input_reagents,output_items,call_native) - auto activates if detects reactions starting with ``LUA_HOOK_``. Is called when reaction finishes. 1. ``onReactionComplete(reaction,unit,input_items,input_reagents,output_items,call_native)``
2. onItemContaminateWound(item,unit,wound,number1,number2) - Is called when item tries to contaminate wound (e.g. stuck in)
3. onProjItemCheckMovement(projectile) - is called when projectile moves Auto activates if detects reactions starting with ``LUA_HOOK_``. Is called when reaction finishes.
4. onProjItemCheckImpact(projectile,somebool) - is called when projectile hits something
5. onProjUnitCheckMovement(projectile) - is called when projectile moves 2. ``onItemContaminateWound(item,unit,wound,number1,number2)``
6. onProjUnitCheckImpact(projectile,somebool) - is called when projectile hits something
7. onWorkshopFillSidebarMenu(workshop,callnative) - is called when viewing a workshop in 'q' mode, to populate reactions, usefull for custom viewscreens for shops Is called when item tries to contaminate wound (e.g. stuck in).
8. postWorkshopFillSidebarMenu(workshop) - is called after calling (or not) native fillSidebarMenu(). Usefull for job button tweaking (e.g. adding custom reactions)
3. ``onProjItemCheckMovement(projectile)``
Is called when projectile moves.
4. ``onProjItemCheckImpact(projectile,somebool)``
Is called when projectile hits something.
5. ``onProjUnitCheckMovement(projectile)``
Is called when projectile moves.
6. ``onProjUnitCheckImpact(projectile,somebool)``
Is called when projectile hits something.
7. ``onWorkshopFillSidebarMenu(workshop,callnative)``
Is called when viewing a workshop in 'q' mode, to populate reactions, usefull for custom viewscreens for shops.
8. ``postWorkshopFillSidebarMenu(workshop)``
Is called after calling (or not) native fillSidebarMenu(). Usefull for job button
tweaking (e.g. adding custom reactions)
Functions Functions
--------- ---------
1. registerReaction(reaction_name,callback) - simplified way of using onReactionComplete, the callback is function (same params as event) 1. ``registerReaction(reaction_name,callback)``
2. removeNative(shop_name) - removes native choice list from the building
3. addReactionToShop(reaction_name,shop_name) - add a custom reaction to the building Simplified way of using onReactionComplete; the callback is function (same params as event).
2. ``removeNative(shop_name)``
Removes native choice list from the building.
3. ``addReactionToShop(reaction_name,shop_name)``
Add a custom reaction to the building.
Examples Examples
-------- --------
Spawn dragon breath on each item attempt to contaminate wound: Spawn dragon breath on each item attempt to contaminate wound::
::
b=require "plugins.eventful" b=require "plugins.eventful"
b.onItemContaminateWound.one=function(item,unit,un_wound,x,y) b.onItemContaminateWound.one=function(item,unit,un_wound,x,y)
local flw=dfhack.maps.spawnFlow(unit.pos,6,0,0,50000) local flw=dfhack.maps.spawnFlow(unit.pos,6,0,0,50000)
end end
Reaction complete example: Reaction complete example::
::
b=require "plugins.eventful" b=require "plugins.eventful"
b.onReactionComplete.one=function(reaction,unit,in_items,in_reag,out_items,call_native) b.onReactionComplete.one=function(reaction,unit,in_items,in_reag,out_items,call_native)
local pos=copyall(unit.pos) local pos=copyall(unit.pos)
dfhack.timeout(100,"ticks",function() dfhack.maps.spawnFlow(pos,6,0,0,50000) end) -- spawn dragonbreath after 100 ticks -- spawn dragonbreath after 100 ticks
call_native.value=false --do not call real item creation code 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
Granade example: Granade example::
::
b=require "plugins.eventful" b=require "plugins.eventful"
b.onProjItemCheckImpact.one=function(projectile) b.onProjItemCheckImpact.one=function(projectile)
-- you can check if projectile.item e.g. has correct material -- you can check if projectile.item e.g. has correct material
dfhack.maps.spawnFlow(projectile.cur_pos,6,0,0,50000) dfhack.maps.spawnFlow(projectile.cur_pos,6,0,0,50000)
end end
Integrated tannery: Integrated tannery::
::
b=require "plugins.eventful" b=require "plugins.eventful"
b.addReactionToShop("TAN_A_HIDE","LEATHERWORKS") b.addReactionToShop("TAN_A_HIDE","LEATHERWORKS")

4
NEWS
Unescape Escape View File

@ -4,7 +4,8 @@ DFHack future
- support for displaying active keybindings properly. - support for displaying active keybindings properly.
- support for reusable widgets in lua screen library. - support for reusable widgets in lua screen library.
- Maps::canStepBetween: returns whether you can walk between two tiles in one step. - Maps::canStepBetween: returns whether you can walk between two tiles in one step.
- EventManager: monitors various in game events centrally so that individual plugins don't have to monitor the same things redundantly. - EventManager: monitors various in game events centrally so that individual plugins
don't have to monitor the same things redundantly.
Notable bugfixes: Notable bugfixes:
- autobutcher can be re-enabled again after being stopped. - autobutcher can be re-enabled again after being stopped.
- stopped Dwarf Manipulator from unmasking vampires. - stopped Dwarf Manipulator from unmasking vampires.
@ -28,6 +29,7 @@ DFHack future
- stripcaged: mark items inside cages for dumping, eg caged goblin weapons. - stripcaged: mark items inside cages for dumping, eg caged goblin weapons.
- soundsense-season: writes the correct season to gamelog.txt on world load. - soundsense-season: writes the correct season to gamelog.txt on world load.
- create-items: spawn items - create-items: spawn items
- fix/cloth-stockpile: fixes bug 5739; needs to be run after savegame load every time.
New GUI scripts: New GUI scripts:
- gui/guide-path: displays the cached path for minecart Guide orders. - gui/guide-path: displays the cached path for minecart Guide orders.
- gui/workshop-job: displays inputs of a workshop job and allows tweaking them. - gui/workshop-job: displays inputs of a workshop job and allows tweaking them.

141
Readme.html
Unescape Escape View File

@ -510,41 +510,42 @@ access DF memory and allow for easier development of new tools.</p>
<li><a class="reference internal" href="#lever" id="id132">lever</a></li> <li><a class="reference internal" href="#lever" id="id132">lever</a></li>
<li><a class="reference internal" href="#stripcaged" id="id133">stripcaged</a></li> <li><a class="reference internal" href="#stripcaged" id="id133">stripcaged</a></li>
<li><a class="reference internal" href="#create-items" id="id134">create-items</a></li> <li><a class="reference internal" href="#create-items" id="id134">create-items</a></li>
<li><a class="reference internal" href="#soundsense-season" id="id135">soundsense-season</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference internal" href="#in-game-interface-tools" id="id135">In-game interface tools</a><ul> <li><a class="reference internal" href="#in-game-interface-tools" id="id136">In-game interface tools</a><ul>
<li><a class="reference internal" href="#dwarf-manipulator" id="id136">Dwarf Manipulator</a></li> <li><a class="reference internal" href="#dwarf-manipulator" id="id137">Dwarf Manipulator</a></li>
<li><a class="reference internal" href="#search" id="id137">Search</a></li> <li><a class="reference internal" href="#search" id="id138">Search</a></li>
<li><a class="reference internal" href="#automaterial" id="id138">AutoMaterial</a></li> <li><a class="reference internal" href="#automaterial" id="id139">AutoMaterial</a></li>
<li><a class="reference internal" href="#gui-liquids" id="id139">gui/liquids</a></li> <li><a class="reference internal" href="#gui-liquids" id="id140">gui/liquids</a></li>
<li><a class="reference internal" href="#gui-mechanisms" id="id140">gui/mechanisms</a></li> <li><a class="reference internal" href="#gui-mechanisms" id="id141">gui/mechanisms</a></li>
<li><a class="reference internal" href="#gui-rename" id="id141">gui/rename</a></li> <li><a class="reference internal" href="#gui-rename" id="id142">gui/rename</a></li>
<li><a class="reference internal" href="#gui-room-list" id="id142">gui/room-list</a></li> <li><a class="reference internal" href="#gui-room-list" id="id143">gui/room-list</a></li>
<li><a class="reference internal" href="#gui-choose-weapons" id="id143">gui/choose-weapons</a></li> <li><a class="reference internal" href="#gui-choose-weapons" id="id144">gui/choose-weapons</a></li>
<li><a class="reference internal" href="#gui-guide-path" id="id144">gui/guide-path</a></li> <li><a class="reference internal" href="#gui-guide-path" id="id145">gui/guide-path</a></li>
<li><a class="reference internal" href="#gui-workshop-job" id="id145">gui/workshop-job</a></li> <li><a class="reference internal" href="#gui-workshop-job" id="id146">gui/workshop-job</a></li>
<li><a class="reference internal" href="#gui-workflow" id="id146">gui/workflow</a></li> <li><a class="reference internal" href="#gui-workflow" id="id147">gui/workflow</a></li>
<li><a class="reference internal" href="#gui-assign-rack" id="id147">gui/assign-rack</a></li> <li><a class="reference internal" href="#gui-assign-rack" id="id148">gui/assign-rack</a></li>
<li><a class="reference internal" href="#gui-advfort" id="id148">gui/advfort</a></li> <li><a class="reference internal" href="#gui-advfort" id="id149">gui/advfort</a></li>
<li><a class="reference internal" href="#gui-gm-editor" id="id149">gui/gm-editor</a></li> <li><a class="reference internal" href="#gui-gm-editor" id="id150">gui/gm-editor</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference internal" href="#behavior-mods" id="id150">Behavior Mods</a><ul> <li><a class="reference internal" href="#behavior-mods" id="id151">Behavior Mods</a><ul>
<li><a class="reference internal" href="#siege-engine" id="id151">Siege Engine</a><ul> <li><a class="reference internal" href="#siege-engine" id="id152">Siege Engine</a><ul>
<li><a class="reference internal" href="#rationale" id="id152">Rationale</a></li> <li><a class="reference internal" href="#rationale" id="id153">Rationale</a></li>
<li><a class="reference internal" href="#configuration-ui" id="id153">Configuration UI</a></li> <li><a class="reference internal" href="#configuration-ui" id="id154">Configuration UI</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference internal" href="#power-meter" id="id154">Power Meter</a></li> <li><a class="reference internal" href="#power-meter" id="id155">Power Meter</a></li>
<li><a class="reference internal" href="#steam-engine" id="id155">Steam Engine</a><ul> <li><a class="reference internal" href="#steam-engine" id="id156">Steam Engine</a><ul>
<li><a class="reference internal" href="#id1" id="id156">Rationale</a></li> <li><a class="reference internal" href="#id1" id="id157">Rationale</a></li>
<li><a class="reference internal" href="#construction" id="id157">Construction</a></li> <li><a class="reference internal" href="#construction" id="id158">Construction</a></li>
<li><a class="reference internal" href="#operation" id="id158">Operation</a></li> <li><a class="reference internal" href="#operation" id="id159">Operation</a></li>
<li><a class="reference internal" href="#explosions" id="id159">Explosions</a></li> <li><a class="reference internal" href="#explosions" id="id160">Explosions</a></li>
<li><a class="reference internal" href="#save-files" id="id160">Save files</a></li> <li><a class="reference internal" href="#save-files" id="id161">Save files</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference internal" href="#add-spatter" id="id161">Add Spatter</a></li> <li><a class="reference internal" href="#add-spatter" id="id162">Add Spatter</a></li>
</ul> </ul>
</li> </li>
</ul> </ul>
@ -2628,6 +2629,12 @@ state however, use <tt class="docutils literal">tweak <span class="pre">stable-t
<p>Diagnoses and fixes issues with nonexistant 'items occupying site', usually <p>Diagnoses and fixes issues with nonexistant 'items occupying site', usually
caused by autodump bugs or other hacking mishaps.</p> caused by autodump bugs or other hacking mishaps.</p>
</li> </li>
<li><p class="first">fix/cloth-stockpile</p>
<p>Fixes erratic behavior of cloth stockpiles by scanning material objects
in memory and patching up some invalid reference fields. Needs to be run
every time a save game is loaded; putting <tt class="docutils literal"><span class="pre">fix/cloth-stockpile</span> enable</tt>
in <tt class="docutils literal">dfhack.init</tt> makes it run automatically.</p>
</li>
</ul> </ul>
</div> </div>
<div class="section" id="gui"> <div class="section" id="gui">
@ -2847,9 +2854,18 @@ create-items bar CREATURE:CAT:SOAP
create-items bar adamantine create-items bar adamantine
</pre> </pre>
</div> </div>
<div class="section" id="soundsense-season">
<h2><a class="toc-backref" href="#id135">soundsense-season</a></h2>
<p>It is a well known issue that Soundsense cannot detect the correct
current season when a savegame is loaded and has to play random
season music until a season switch occurs.</p>
<p>This script registers a hook that prints the appropriate string
to gamelog.txt on every map load to fix this. For best results
call the script from <tt class="docutils literal">dfhack.init</tt>.</p>
</div>
</div> </div>
<div class="section" id="in-game-interface-tools"> <div class="section" id="in-game-interface-tools">
<h1><a class="toc-backref" href="#id135">In-game interface tools</a></h1> <h1><a class="toc-backref" href="#id136">In-game interface tools</a></h1>
<p>These tools work by displaying dialogs or overlays in the game window, and <p>These tools work by displaying dialogs or overlays in the game window, and
are mostly implemented by lua scripts.</p> are mostly implemented by lua scripts.</p>
<div class="note"> <div class="note">
@ -2862,7 +2878,7 @@ existing DF screens, they deliberately use red instead of green for the key.</p>
guideline because it arguably just fixes small usability bugs in the game UI.</p> guideline because it arguably just fixes small usability bugs in the game UI.</p>
</div> </div>
<div class="section" id="dwarf-manipulator"> <div class="section" id="dwarf-manipulator">
<h2><a class="toc-backref" href="#id136">Dwarf Manipulator</a></h2> <h2><a class="toc-backref" href="#id137">Dwarf Manipulator</a></h2>
<p>Implemented by the manipulator plugin. To activate, open the unit screen and <p>Implemented by the manipulator plugin. To activate, open the unit screen and
press 'l'.</p> press 'l'.</p>
<img alt="images/manipulator.png" src="images/manipulator.png" /> <img alt="images/manipulator.png" src="images/manipulator.png" />
@ -2901,7 +2917,7 @@ cursor onto that cell instead of toggling it.</li>
directly to the main dwarf mode screen.</p> directly to the main dwarf mode screen.</p>
</div> </div>
<div class="section" id="search"> <div class="section" id="search">
<h2><a class="toc-backref" href="#id137">Search</a></h2> <h2><a class="toc-backref" href="#id138">Search</a></h2>
<p>The search plugin adds search to the Stocks, Animals, Trading, Stockpile, <p>The search plugin adds search to the Stocks, Animals, Trading, Stockpile,
Noble (assignment candidates), Military (position candidates), Burrows Noble (assignment candidates), Military (position candidates), Burrows
(unit list), Rooms, Announcements, Job List and Unit List screens.</p> (unit list), Rooms, Announcements, Job List and Unit List screens.</p>
@ -2931,7 +2947,7 @@ only fat or tallow by forbidding fats, then searching for fat/tallow, and
using Permit Fats again while the list is filtered.</p> using Permit Fats again while the list is filtered.</p>
</div> </div>
<div class="section" id="automaterial"> <div class="section" id="automaterial">
<h2><a class="toc-backref" href="#id138">AutoMaterial</a></h2> <h2><a class="toc-backref" href="#id139">AutoMaterial</a></h2>
<p>The automaterial plugin makes building constructions (walls, floors, fortifications, <p>The automaterial plugin makes building constructions (walls, floors, fortifications,
etc) a little bit easier by saving you from having to trawl through long lists of etc) a little bit easier by saving you from having to trawl through long lists of
materials each time you place one.</p> materials each time you place one.</p>
@ -2958,14 +2974,27 @@ materials, it returns you back to this screen. If you use this along with severa
enabled materials, you should be able to place complex constructions more conveniently.</p> enabled materials, you should be able to place complex constructions more conveniently.</p>
</div> </div>
<div class="section" id="gui-liquids"> <div class="section" id="gui-liquids">
<h2><a class="toc-backref" href="#id139">gui/liquids</a></h2> <h2><a class="toc-backref" href="#id140">gui/liquids</a></h2>
<p>To use, bind to a key (the example config uses Alt-L) and activate in the 'k' mode.</p> <p>To use, bind to a key (the example config uses Alt-L) and activate in the 'k' mode.</p>
<img alt="images/liquids.png" src="images/liquids.png" /> <img alt="images/liquids.png" src="images/liquids.png" />
<p>While active, use the suggested keys to switch the usual liquids parameters, and Enter <p>This script is a gui front-end to the liquids plugin and works similar to it,
to select the target area and apply changes.</p> allowing you to add or remove water &amp; magma, and create obsidian walls &amp; floors.
Note that there is <strong>no undo support</strong>, and that bugs in this plugin have been
known to create pathfinding problems and heat traps.</p>
<p>The <tt class="docutils literal">b</tt> key changes how the affected area is selected. The default <em>Rectangle</em>
mode works by selecting two corners like any ordinary designation. The <tt class="docutils literal">p</tt>
key chooses between adding water, magma, obsidian walls &amp; floors, or just
tweaking flags.</p>
<p>When painting liquids, it is possible to select the desired level with <tt class="docutils literal">+-</tt>,
and choose between setting it exactly, only increasing or only decreasing
with <tt class="docutils literal">s</tt>.</p>
<p>In addition, <tt class="docutils literal">f</tt> allows disabling or enabling the flowing water computations
for an area, and <tt class="docutils literal">r</tt> operates on the &quot;permanent flow&quot; property that makes
rivers power water wheels even when full and technically not flowing.</p>
<p>After setting up the desired operations using the described keys, use <tt class="docutils literal">Enter</tt> to apply them.</p>
</div> </div>
<div class="section" id="gui-mechanisms"> <div class="section" id="gui-mechanisms">
<h2><a class="toc-backref" href="#id140">gui/mechanisms</a></h2> <h2><a class="toc-backref" href="#id141">gui/mechanisms</a></h2>
<p>To use, bind to a key (the example config uses Ctrl-M) and activate in the 'q' mode.</p> <p>To use, bind to a key (the example config uses Ctrl-M) and activate in the 'q' mode.</p>
<img alt="images/mechanisms.png" src="images/mechanisms.png" /> <img alt="images/mechanisms.png" src="images/mechanisms.png" />
<p>Lists mechanisms connected to the building, and their links. Navigating the list centers <p>Lists mechanisms connected to the building, and their links. Navigating the list centers
@ -2975,7 +3004,7 @@ focus on the current one. Shift-Enter has an effect equivalent to pressing Enter
re-entering the mechanisms ui.</p> re-entering the mechanisms ui.</p>
</div> </div>
<div class="section" id="gui-rename"> <div class="section" id="gui-rename">
<h2><a class="toc-backref" href="#id141">gui/rename</a></h2> <h2><a class="toc-backref" href="#id142">gui/rename</a></h2>
<p>Backed by the rename plugin, this script allows entering the desired name <p>Backed by the rename plugin, this script allows entering the desired name
via a simple dialog in the game ui.</p> via a simple dialog in the game ui.</p>
<ul> <ul>
@ -2998,7 +3027,7 @@ their species string.</p>
unit profession change to Ctrl-Shift-T.</p> unit profession change to Ctrl-Shift-T.</p>
</div> </div>
<div class="section" id="gui-room-list"> <div class="section" id="gui-room-list">
<h2><a class="toc-backref" href="#id142">gui/room-list</a></h2> <h2><a class="toc-backref" href="#id143">gui/room-list</a></h2>
<p>To use, bind to a key (the example config uses Alt-R) and activate in the 'q' mode, <p>To use, bind to a key (the example config uses Alt-R) and activate in the 'q' mode,
either immediately or after opening the assign owner page.</p> either immediately or after opening the assign owner page.</p>
<img alt="images/room-list.png" src="images/room-list.png" /> <img alt="images/room-list.png" src="images/room-list.png" />
@ -3006,7 +3035,7 @@ either immediately or after opening the assign owner page.</p>
list, and allows unassigning them.</p> list, and allows unassigning them.</p>
</div> </div>
<div class="section" id="gui-choose-weapons"> <div class="section" id="gui-choose-weapons">
<h2><a class="toc-backref" href="#id143">gui/choose-weapons</a></h2> <h2><a class="toc-backref" href="#id144">gui/choose-weapons</a></h2>
<p>Bind to a key (the example config uses Ctrl-W), and activate in the Equip-&gt;View/Customize <p>Bind to a key (the example config uses Ctrl-W), and activate in the Equip-&gt;View/Customize
page of the military screen.</p> page of the military screen.</p>
<p>Depending on the cursor location, it rewrites all 'individual choice weapon' entries <p>Depending on the cursor location, it rewrites all 'individual choice weapon' entries
@ -3017,7 +3046,7 @@ only that entry, and does it even if it is not 'individual choice'.</p>
and may lead to inappropriate weapons being selected.</p> and may lead to inappropriate weapons being selected.</p>
</div> </div>
<div class="section" id="gui-guide-path"> <div class="section" id="gui-guide-path">
<h2><a class="toc-backref" href="#id144">gui/guide-path</a></h2> <h2><a class="toc-backref" href="#id145">gui/guide-path</a></h2>
<p>Bind to a key (the example config uses Alt-P), and activate in the Hauling menu with <p>Bind to a key (the example config uses Alt-P), and activate in the Hauling menu with
the cursor over a Guide order.</p> the cursor over a Guide order.</p>
<img alt="images/guide-path.png" src="images/guide-path.png" /> <img alt="images/guide-path.png" src="images/guide-path.png" />
@ -3025,7 +3054,7 @@ the cursor over a Guide order.</p>
computes it when the order is executed for the first time.</p> computes it when the order is executed for the first time.</p>
</div> </div>
<div class="section" id="gui-workshop-job"> <div class="section" id="gui-workshop-job">
<h2><a class="toc-backref" href="#id145">gui/workshop-job</a></h2> <h2><a class="toc-backref" href="#id146">gui/workshop-job</a></h2>
<p>Bind to a key (the example config uses Alt-A), and activate with a job selected in <p>Bind to a key (the example config uses Alt-A), and activate with a job selected in
a workshop in the 'q' mode.</p> a workshop in the 'q' mode.</p>
<img alt="images/workshop-job.png" src="images/workshop-job.png" /> <img alt="images/workshop-job.png" src="images/workshop-job.png" />
@ -3061,7 +3090,7 @@ and then try to change the input item type, now it won't let you select <em>plan
you have to unset the material first.</p> you have to unset the material first.</p>
</div> </div>
<div class="section" id="gui-workflow"> <div class="section" id="gui-workflow">
<h2><a class="toc-backref" href="#id146">gui/workflow</a></h2> <h2><a class="toc-backref" href="#id147">gui/workflow</a></h2>
<p>Bind to a key (the example config uses Alt-W), and activate with a job selected <p>Bind to a key (the example config uses Alt-W), and activate with a job selected
in a workshop in the 'q' mode.</p> in a workshop in the 'q' mode.</p>
<img alt="images/workflow.png" src="images/workflow.png" /> <img alt="images/workflow.png" src="images/workflow.png" />
@ -3108,7 +3137,7 @@ the current stock value. The bright green dashed line is the target
limit (maximum) and the dark green line is that minus the gap (minimum).</p> limit (maximum) and the dark green line is that minus the gap (minimum).</p>
</div> </div>
<div class="section" id="gui-assign-rack"> <div class="section" id="gui-assign-rack">
<h2><a class="toc-backref" href="#id147">gui/assign-rack</a></h2> <h2><a class="toc-backref" href="#id148">gui/assign-rack</a></h2>
<p>Bind to a key (the example config uses P), and activate when viewing a weapon <p>Bind to a key (the example config uses P), and activate when viewing a weapon
rack in the 'q' mode.</p> rack in the 'q' mode.</p>
<img alt="images/assign-rack.png" src="images/assign-rack.png" /> <img alt="images/assign-rack.png" src="images/assign-rack.png" />
@ -3132,7 +3161,7 @@ the intended user. In order to aid in the choice, it shows the number
of currently assigned racks for every valid squad.</p> of currently assigned racks for every valid squad.</p>
</div> </div>
<div class="section" id="gui-advfort"> <div class="section" id="gui-advfort">
<h2><a class="toc-backref" href="#id148">gui/advfort</a></h2> <h2><a class="toc-backref" href="#id149">gui/advfort</a></h2>
<p>This script allows to perform jobs in adventure mode. For more complete help <p>This script allows to perform jobs in adventure mode. For more complete help
press '?' while script is running. It's most confortable to use this as a press '?' while script is running. It's most confortable to use this as a
keybinding. (e.g. keybinding set Ctrl-T gui/advfort). Possible arguments:</p> keybinding. (e.g. keybinding set Ctrl-T gui/advfort). Possible arguments:</p>
@ -3145,7 +3174,7 @@ implies -a</li>
</ul> </ul>
</div> </div>
<div class="section" id="gui-gm-editor"> <div class="section" id="gui-gm-editor">
<h2><a class="toc-backref" href="#id149">gui/gm-editor</a></h2> <h2><a class="toc-backref" href="#id150">gui/gm-editor</a></h2>
<p>There are three ways to open this editor:</p> <p>There are three ways to open this editor:</p>
<ul class="simple"> <ul class="simple">
<li>using gui/gm-editor command/keybinding - opens editor on what is selected <li>using gui/gm-editor command/keybinding - opens editor on what is selected
@ -3160,7 +3189,7 @@ in-game help.</p>
</div> </div>
</div> </div>
<div class="section" id="behavior-mods"> <div class="section" id="behavior-mods">
<h1><a class="toc-backref" href="#id150">Behavior Mods</a></h1> <h1><a class="toc-backref" href="#id151">Behavior Mods</a></h1>
<p>These plugins, when activated via configuration UI or by detecting certain <p>These plugins, when activated via configuration UI or by detecting certain
structures in RAWs, modify the game engine behavior concerning the target structures in RAWs, modify the game engine behavior concerning the target
objects to add features not otherwise present.</p> objects to add features not otherwise present.</p>
@ -3171,20 +3200,20 @@ technical challenge, and do not represent any long-term plans to produce more
similar modifications of the game.</p> similar modifications of the game.</p>
</div> </div>
<div class="section" id="siege-engine"> <div class="section" id="siege-engine">
<h2><a class="toc-backref" href="#id151">Siege Engine</a></h2> <h2><a class="toc-backref" href="#id152">Siege Engine</a></h2>
<p>The siege-engine plugin enables siege engines to be linked to stockpiles, and <p>The siege-engine plugin enables siege engines to be linked to stockpiles, and
aimed at an arbitrary rectangular area across Z levels, instead of the original aimed at an arbitrary rectangular area across Z levels, instead of the original
four directions. Also, catapults can be ordered to load arbitrary objects, not four directions. Also, catapults can be ordered to load arbitrary objects, not
just stones.</p> just stones.</p>
<div class="section" id="rationale"> <div class="section" id="rationale">
<h3><a class="toc-backref" href="#id152">Rationale</a></h3> <h3><a class="toc-backref" href="#id153">Rationale</a></h3>
<p>Siege engines are a very interesting feature, but sadly almost useless in the current state <p>Siege engines are a very interesting feature, but sadly almost useless in the current state
because they haven't been updated since 2D and can only aim in four directions. This is an because they haven't been updated since 2D and can only aim in four directions. This is an
attempt to bring them more up to date until Toady has time to work on it. Actual improvements, attempt to bring them more up to date until Toady has time to work on it. Actual improvements,
e.g. like making siegers bring their own, are something only Toady can do.</p> e.g. like making siegers bring their own, are something only Toady can do.</p>
</div> </div>
<div class="section" id="configuration-ui"> <div class="section" id="configuration-ui">
<h3><a class="toc-backref" href="#id153">Configuration UI</a></h3> <h3><a class="toc-backref" href="#id154">Configuration UI</a></h3>
<p>The configuration front-end to the plugin is implemented by the gui/siege-engine <p>The configuration front-end to the plugin is implemented by the gui/siege-engine
script. Bind it to a key (the example config uses Alt-A) and activate after selecting script. Bind it to a key (the example config uses Alt-A) and activate after selecting
a siege engine in 'q' mode.</p> a siege engine in 'q' mode.</p>
@ -3207,7 +3236,7 @@ menu.</p>
</div> </div>
</div> </div>
<div class="section" id="power-meter"> <div class="section" id="power-meter">
<h2><a class="toc-backref" href="#id154">Power Meter</a></h2> <h2><a class="toc-backref" href="#id155">Power Meter</a></h2>
<p>The power-meter plugin implements a modified pressure plate that detects power being <p>The power-meter plugin implements a modified pressure plate that detects power being
supplied to gear boxes built in the four adjacent N/S/W/E tiles.</p> supplied to gear boxes built in the four adjacent N/S/W/E tiles.</p>
<p>The configuration front-end is implemented by the gui/power-meter script. Bind it to a <p>The configuration front-end is implemented by the gui/power-meter script. Bind it to a
@ -3218,11 +3247,11 @@ in the build menu.</p>
configuration page, but configures parameters relevant to the modded power meter building.</p> configuration page, but configures parameters relevant to the modded power meter building.</p>
</div> </div>
<div class="section" id="steam-engine"> <div class="section" id="steam-engine">
<h2><a class="toc-backref" href="#id155">Steam Engine</a></h2> <h2><a class="toc-backref" href="#id156">Steam Engine</a></h2>
<p>The steam-engine plugin detects custom workshops with STEAM_ENGINE in <p>The steam-engine plugin detects custom workshops with STEAM_ENGINE in
their token, and turns them into real steam engines.</p> their token, and turns them into real steam engines.</p>
<div class="section" id="id1"> <div class="section" id="id1">
<h3><a class="toc-backref" href="#id156">Rationale</a></h3> <h3><a class="toc-backref" href="#id157">Rationale</a></h3>
<p>The vanilla game contains only water wheels and windmills as sources of <p>The vanilla game contains only water wheels and windmills as sources of
power, but windmills give relatively little power, and water wheels require power, but windmills give relatively little power, and water wheels require
flowing water, which must either be a real river and thus immovable and flowing water, which must either be a real river and thus immovable and
@ -3233,7 +3262,7 @@ it can be done just by combining existing features of the game engine
in a new way with some glue code and a bit of custom logic.</p> in a new way with some glue code and a bit of custom logic.</p>
</div> </div>
<div class="section" id="construction"> <div class="section" id="construction">
<h3><a class="toc-backref" href="#id157">Construction</a></h3> <h3><a class="toc-backref" href="#id158">Construction</a></h3>
<p>The workshop needs water as its input, which it takes via a <p>The workshop needs water as its input, which it takes via a
passable floor tile below it, like usual magma workshops do. passable floor tile below it, like usual magma workshops do.
The magma version also needs magma.</p> The magma version also needs magma.</p>
@ -3257,7 +3286,7 @@ short axles that can be built later than both of the engines.</p>
</div> </div>
</div> </div>
<div class="section" id="operation"> <div class="section" id="operation">
<h3><a class="toc-backref" href="#id158">Operation</a></h3> <h3><a class="toc-backref" href="#id159">Operation</a></h3>
<p>In order to operate the engine, queue the Stoke Boiler job (optionally <p>In order to operate the engine, queue the Stoke Boiler job (optionally
on repeat). A furnace operator will come, possibly bringing a bar of fuel, on repeat). A furnace operator will come, possibly bringing a bar of fuel,
and perform it. As a result, a &quot;boiling water&quot; item will appear and perform it. As a result, a &quot;boiling water&quot; item will appear
@ -3288,7 +3317,7 @@ decrease it by further 4%, and also decrease the whole steam
use rate by 10%.</p> use rate by 10%.</p>
</div> </div>
<div class="section" id="explosions"> <div class="section" id="explosions">
<h3><a class="toc-backref" href="#id159">Explosions</a></h3> <h3><a class="toc-backref" href="#id160">Explosions</a></h3>
<p>The engine must be constructed using barrel, pipe and piston <p>The engine must be constructed using barrel, pipe and piston
from fire-safe, or in the magma version magma-safe metals.</p> from fire-safe, or in the magma version magma-safe metals.</p>
<p>During operation weak parts get gradually worn out, and <p>During operation weak parts get gradually worn out, and
@ -3297,7 +3326,7 @@ toppled during operation by a building destroyer, or a
tantruming dwarf.</p> tantruming dwarf.</p>
</div> </div>
<div class="section" id="save-files"> <div class="section" id="save-files">
<h3><a class="toc-backref" href="#id160">Save files</a></h3> <h3><a class="toc-backref" href="#id161">Save files</a></h3>
<p>It should be safe to load and view engine-using fortresses <p>It should be safe to load and view engine-using fortresses
from a DF version without DFHack installed, except that in such from a DF version without DFHack installed, except that in such
case the engines won't work. However actually making modifications case the engines won't work. However actually making modifications
@ -3308,7 +3337,7 @@ being generated.</p>
</div> </div>
</div> </div>
<div class="section" id="add-spatter"> <div class="section" id="add-spatter">
<h2><a class="toc-backref" href="#id161">Add Spatter</a></h2> <h2><a class="toc-backref" href="#id162">Add Spatter</a></h2>
<p>This plugin makes reactions with names starting with <tt class="docutils literal">SPATTER_ADD_</tt> <p>This plugin makes reactions with names starting with <tt class="docutils literal">SPATTER_ADD_</tt>
produce contaminants on the items instead of improvements. The produced produce contaminants on the items instead of improvements. The produced
contaminants are immune to being washed away by water or destroyed by contaminants are immune to being washed away by water or destroyed by

38
Readme.rst
Unescape Escape View File

@ -1773,6 +1773,12 @@ Scripts in this subdirectory fix various bugs and issues, some of them obscure.
Diagnoses and fixes issues with nonexistant 'items occupying site', usually Diagnoses and fixes issues with nonexistant 'items occupying site', usually
caused by autodump bugs or other hacking mishaps. caused by autodump bugs or other hacking mishaps.
* fix/cloth-stockpile
Fixes erratic behavior of cloth stockpiles by scanning material objects
in memory and patching up some invalid reference fields. Needs to be run
every time a save game is loaded; putting ``fix/cloth-stockpile enable``
in ``dfhack.init`` makes it run automatically.
gui/* gui/*
===== =====
@ -2032,6 +2038,17 @@ Exemples::
create-items bar CREATURE:CAT:SOAP create-items bar CREATURE:CAT:SOAP
create-items bar adamantine create-items bar adamantine
soundsense-season
=================
It is a well known issue that Soundsense cannot detect the correct
current season when a savegame is loaded and has to play random
season music until a season switch occurs.
This script registers a hook that prints the appropriate string
to gamelog.txt on every map load to fix this. For best results
call the script from ``dfhack.init``.
======================= =======================
In-game interface tools In-game interface tools
======================= =======================
@ -2185,8 +2202,25 @@ To use, bind to a key (the example config uses Alt-L) and activate in the 'k' mo
.. image:: images/liquids.png .. image:: images/liquids.png
While active, use the suggested keys to switch the usual liquids parameters, and Enter This script is a gui front-end to the liquids plugin and works similar to it,
to select the target area and apply changes. allowing you to add or remove water & magma, and create obsidian walls & floors.
Note that there is **no undo support**, and that bugs in this plugin have been
known to create pathfinding problems and heat traps.
The ``b`` key changes how the affected area is selected. The default *Rectangle*
mode works by selecting two corners like any ordinary designation. The ``p``
key chooses between adding water, magma, obsidian walls & floors, or just
tweaking flags.
When painting liquids, it is possible to select the desired level with ``+-``,
and choose between setting it exactly, only increasing or only decreasing
with ``s``.
In addition, ``f`` allows disabling or enabling the flowing water computations
for an area, and ``r`` operates on the "permanent flow" property that makes
rivers power water wheels even when full and technically not flowing.
After setting up the desired operations using the described keys, use ``Enter`` to apply them.
gui/mechanisms gui/mechanisms