<li>Four space indents for C++. Never use tabs for indentation in any language.</li>
<li>LF (Unix style) line terminators</li>
<li>Avoid trailing whitespace</li>
<li>UTF-8 encoding</li>
<li>For C++:<ul>
<li>Opening and closing braces on their own lines or opening brace at the end of the previous line</li>
<li>Braces placed at original indent level if on their own lines</li>
<li>#includes should be sorted. C++ libraries first, then dfhack modules, then df structures, then local includes. Within each category they should be sorted alphabetically. This policy is currently broken by most C++ files but try to follow it if you can.</li>
<h2><aclass="toc-backref"href="#id4">How to get new code into DFHack</a></h2>
<ulclass="simple">
<li>Submit pull requests to the develop branch, not the master branch. The master branch always points at the most recent release.</li>
<li>Use new branches for each feature/fix so that your changes can be merged independently.</li>
<li>If possible, compile on multiple platforms</li>
<li>Do update NEWS/Contributors.rst</li>
<li>Do <strong>NOT</strong> run fix-texts.sh or update .html files (except to locally test changes to .rst files)</li>
<li>Create a Github Pull Request once finished</li>
<li>Work done against <aclass="reference external"href="http://github.com/DFHack/dfhack/issues">issues</a> that are tagged "bug report" gets priority<ul>
<li>Submit ideas and bug reports as issues on github. Posts in the forum thread are also acceptable but can get missed or forgotten more easily.</li>
<p>Creates a new directory. Returns <ttclass="docutils literal">false</tt> if unsuccessful, including if <ttclass="docutils literal">path</tt> already exists.</p>
<p>A number of lua modules with names starting with <ttclass="docutils literal">gui</tt> are dedicated
<p>A number of lua modules with names starting with <ttclass="docutils literal">gui</tt> are dedicated
to wrapping the natives of the <ttclass="docutils literal">dfhack.screen</tt> module in a way that
to wrapping the natives of the <ttclass="docutils literal">dfhack.screen</tt> module in a way that
is easy to use. This allows relatively easily and naturally creating
is easy to use. This allows relatively easily and naturally creating
@ -2400,12 +2452,12 @@ dialogs that integrate in the main game UI window.</p>
things ranging from the basic <ttclass="docutils literal">Painter</tt>, <ttclass="docutils literal">View</tt> and <ttclass="docutils literal">Screen</tt>
things ranging from the basic <ttclass="docutils literal">Painter</tt>, <ttclass="docutils literal">View</tt> and <ttclass="docutils literal">Screen</tt>
classes, to fully functional predefined dialogs.</p>
classes, to fully functional predefined dialogs.</p>
<h3><aclass="toc-backref"href="#id60">Events from EventManager</a></h3>
<h3><aclass="toc-backref"href="#id61">Events from EventManager</a></h3>
<p>These events are straight from EventManager module. Each of them first needs to be enabled. See functions for more info. If you register a listener before the game is loaded, be aware that no events will be triggered immediately after loading, so you might need to add another event listener for when the game first loads in some cases.</p>
<p>These events are straight from EventManager module. Each of them first needs to be enabled. See functions for more info. If you register a listener before the game is loaded, be aware that no events will be triggered immediately after loading, so you might need to add another event listener for when the game first loads in some cases.</p>
<p>Any files with the .lua extension placed into hack/scripts/*
<p>Any files with the .lua extension placed into hack/scripts/*
are automatically used by the DFHack core as commands. The
are automatically used by the DFHack core as commands. The
matching command name consists of the name of the file sans
matching command name consists of the name of the file without
the extension.</p>
the extension. First DFHack searches for the script in the save folder/raw/scripts folder. If it is not found there, it searches in the DF/raw/scripts folder. If it is not there, it searches in DF/hack/scripts. If it is not there, it gives up.</p>
<p>If the first line of the script is a one-line comment, it is
<p>If the first line of the script is a one-line comment, it is
used by the built-in <ttclass="docutils literal">ls</tt> and <ttclass="docutils literal">help</tt> commands.</p>
used by the built-in <ttclass="docutils literal">ls</tt> and <ttclass="docutils literal">help</tt> commands.</p>
<p><strong>NOTE:</strong> Scripts placed in subdirectories still can be accessed, but
<p><strong>NOTE:</strong> Scripts placed in subdirectories still can be accessed, but
@ -3400,8 +3452,22 @@ The <tt class="docutils literal">name</tt> argument should be the name stem, as
</li>
</li>
</ul>
</ul>
<p>Note that this function lets errors propagate to the caller.</p>
<p>Note that this function lets errors propagate to the caller.</p>
This command allows you to use scripts like modules for increased portability.
It is highly recommended that if you are a modder you put your custom modules in <ttclass="docutils literal">raw/scripts</tt> and use <ttclass="docutils literal">script_environment</tt> instead of <ttclass="docutils literal">require</tt> so that saves with your mod installed will be self-contained and can be transferred to people who do have DFHack but do not have your mod installed.
You can say <ttclass="docutils literal"><spanclass="pre">dfhack.script_environment('add-thought').addEmotionToUnit([arguments</span> go here])</tt> and it will have the desired effect.
It will call the script in question with the global <ttclass="docutils literal">moduleMode</tt> set to <ttclass="docutils literal">true</tt> so that the script can return early.
This is useful because if the script is called from the console it should deal with its console arguments and if it is called by <ttclass="docutils literal">script_environment</tt> it should only create its global functions and return.
You can also access global variables with, for example <ttclass="docutils literal"><spanclass="pre">print(dfhack.script_environment('add-thought').validArgs)</span></tt>
The function <ttclass="docutils literal">script_environment</tt> is fast enough that it is recommended that you not store its result in a nonlocal variable, because your script might need to load a different version of that script if the save is unloaded and a save with a different mod that overrides the same script with a slightly different functionality is loaded.
This will not be an issue in most cases.
This function also permits circular dependencies of scripts.</p>
@ -789,6 +789,8 @@ by whitespace. To include whitespace in an argument, quote it in double quotes.
To include a double quote character, use <ttclass="docutils literal">\"</tt> inside double quotes.</p>
To include a double quote character, use <ttclass="docutils literal">\"</tt> inside double quotes.</p>
<p>If the first non-whitespace character of a line is <ttclass="docutils literal">#</tt>, the line is treated
<p>If the first non-whitespace character of a line is <ttclass="docutils literal">#</tt>, the line is treated
as a comment, i.e. a silent no-op command.</p>
as a comment, i.e. a silent no-op command.</p>
<p>When reading commands from dfhack.init or with the <ttclass="docutils literal">script</tt> command, if the final character on a line is a backslash then the next uncommented line is considered a continuation of that line, with the backslash deleted.
Commented lines are skipped, so it is possible to comment out parts of a command with the <ttclass="docutils literal">#</tt> character.</p>
<p>If the first non-whitespace character is <ttclass="docutils literal">:</tt>, the command is parsed in a special
<p>If the first non-whitespace character is <ttclass="docutils literal">:</tt>, the command is parsed in a special
alternative mode: first, non-whitespace characters immediately following the <ttclass="docutils literal">:</tt>
alternative mode: first, non-whitespace characters immediately following the <ttclass="docutils literal">:</tt>
are used as the command name; the remaining part of the line, starting with the first
are used as the command name; the remaining part of the line, starting with the first
@ -2666,6 +2668,8 @@ units or with 'zone nick' to mass-rename units in pastures and cages).</p>
<p>Creatures trained for war or hunting will be ignored as well.</p>
<p>Creatures trained for war or hunting will be ignored as well.</p>
<p>Creatures assigned to cages will be ignored if the cage is defined as a room
<p>Creatures assigned to cages will be ignored if the cage is defined as a room
(to avoid butchering unnamed zoo animals).</p>
(to avoid butchering unnamed zoo animals).</p>
<p>Creatures who will not reproduce (because they're not interested in the opposite
sex or have been gelded) have first priority for butchering.</p>
<p>Once you have too much adults, the oldest will be butchered first.
<p>Once you have too much adults, the oldest will be butchered first.
Once you have too much kids, the youngest will be butchered first.
Once you have too much kids, the youngest will be butchered first.
If you don't set any target count the following default will be used:
If you don't set any target count the following default will be used:
@ -3051,10 +3055,6 @@ directory.</p>
<li><pclass="first">gui/stockpiles</p>
<li><pclass="first">gui/stockpiles</p>
<p>Load and save stockpile settings from the 'q' menu.
<p>Load and save stockpile settings from the 'q' menu.
Usage:</p>
Usage:</p>
<divclass="system-message">
<pclass="system-message-title">System Message: ERROR/3 (<ttclass="docutils">Readme.rst</tt>, line 2225)</p>
<p>Unexpected indentation.</p>
</div>
<blockquote>
<blockquote>
<p>gui/stockpiles -save to save the current stockpile
<p>gui/stockpiles -save to save the current stockpile
gui/stockpiles -load to load settings into the current stockpile
gui/stockpiles -load to load settings into the current stockpile
expwnent