Merge branch 'master' of https://github.com/angavrilov/dfhack

LUA_API.rst

@@ -426,13 +426,17 @@ not destroy any objects allocated in this way, so the user
 should be prepared to catch the error and do the necessary
 cleanup.
 
-================
-DFHack utilities
-================
+==========
+DFHack API
+==========
 
 DFHack utility functions are placed in the ``dfhack`` global tree.
 
-Currently it defines the following features:
+Native utilities
+================
+
+Input & Output
+--------------
 
 * ``dfhack.print(args...)``
 
@@ -451,6 +455,7 @@ Currently it defines the following features:
 * ``dfhack.color([color])``
 
   Sets the current output color. If color is *nil* or *-1*, resets to default.
+  Returns the previous color value.
 
 * ``dfhack.is_interactive()``
 
@@ -473,23 +478,9 @@ Currently it defines the following features:
 
   If the interactive console is not accessible, returns *nil, error*.
 
-* ``dfhack.pcall(f[,args...])``
-
-  Invokes f via xpcall, using an error function that attaches
-  a stack trace to the error. The same function is used by SafeCall
-  in C++, and dfhack.safecall.
-
-  The returned error is a table with separate ``message`` and
-  ``stacktrace`` string fields; it implements ``__tostring``.
-
-* ``safecall(f[,args...])``, ``dfhack.safecall(f[,args...])``
-
-  Just like pcall, but also prints the error using printerr before
-  returning. Intended as a convenience function.
-
-* ``dfhack.saferesume(coroutine[,args...])``
 
-  Compares to coroutine.resume like dfhack.safecall vs pcall.
+Miscellaneous
+-------------
 
 * ``dfhack.run_script(name[,args...])``
 
@@ -510,6 +501,36 @@ Currently it defines the following features:
   to group operations together in one big critical section. A plugin
   can choose to run all lua code inside a C++-side suspend lock.
 
+
+Exception handling
+------------------
+
+* ``dfhack.error(msg[,level[,verbose]])``
+
+  Throws a dfhack exception object with location and stack trace.
+  The verbose parameter controls whether the trace is printed by default.
+
+* ``qerror(msg[,level])``
+
+  Calls ``dfhack.error()`` with ``verbose`` being *false*. Intended to
+  be used for user-caused errors in scripts, where stack traces are not
+  desirable.
+
+* ``dfhack.pcall(f[,args...])``
+
+  Invokes f via xpcall, using an error function that attaches
+  a stack trace to the error. The same function is used by SafeCall
+  in C++, and dfhack.safecall.
+
+* ``safecall(f[,args...])``, ``dfhack.safecall(f[,args...])``
+
+  Just like pcall, but also prints the error using printerr before
+  returning. Intended as a convenience function.
+
+* ``dfhack.saferesume(coroutine[,args...])``
+
+  Compares to coroutine.resume like dfhack.safecall vs pcall.
+
 * ``dfhack.call_with_finalizer(num_cleanup_args,always,cleanup_fn[,cleanup_args...],fn[,args...])``
 
   Invokes ``fn`` with ``args``, and after it returns or throws an
@@ -534,9 +555,33 @@ Currently it defines the following features:
 
   Calls ``fn(obj,args...)``, then finalizes with ``obj:delete()``.
 
+* ``dfhack.exception``
+
+  Metatable of error objects used by dfhack. The objects have the
+  following properties:
+
+  ``err.where``
+    The location prefix string, or *nil*.
+  ``err.message``
+    The base message string.
+  ``err.stacktrace``
+    The stack trace string, or *nil*.
+  ``err.cause``
+    A different exception object, or *nil*.
+  ``err.thread``
+    The coroutine that has thrown the exception.
+  ``err.verbose``
+    Boolean, or *nil*; specifies if where and stacktrace should be printed.
+  ``tostring(err)``, or ``err:tostring([verbose])``
+    Converts the exception to string.
+
+* ``dfhack.exception.verbose``
+
+  The default value of the ``verbose`` argument of ``err:tostring()``.
+
 
 Persistent configuration storage
-================================
+--------------------------------
 
 This api is intended for storing configuration options in the world itself.
 It probably should be restricted to data that is world-dependent.
@@ -578,7 +623,7 @@ functions can just copy values in memory without doing any actual I/O.
 However, currently every entry has a 180+-byte dead-weight overhead.
 
 Material info lookup
-====================
+--------------------
 
 A material info record has fields:
 

Lua API.html

@@ -333,30 +333,36 @@ ul.auto-toc {
 <li><a class="reference internal" href="#recursive-table-assignment" id="id9">Recursive table assignment</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#dfhack-utilities" id="id10">DFHack utilities</a><ul>
-<li><a class="reference internal" href="#persistent-configuration-storage" id="id11">Persistent configuration storage</a></li>
-<li><a class="reference internal" href="#material-info-lookup" id="id12">Material info lookup</a></li>
-<li><a class="reference internal" href="#c-function-wrappers" id="id13">C++ function wrappers</a><ul>
-<li><a class="reference internal" href="#gui-module" id="id14">Gui module</a></li>
-<li><a class="reference internal" href="#job-module" id="id15">Job module</a></li>
-<li><a class="reference internal" href="#units-module" id="id16">Units module</a></li>
-<li><a class="reference internal" href="#items-module" id="id17">Items module</a></li>
-<li><a class="reference internal" href="#maps-module" id="id18">Maps module</a></li>
-<li><a class="reference internal" href="#burrows-module" id="id19">Burrows module</a></li>
-<li><a class="reference internal" href="#buildings-module" id="id20">Buildings module</a></li>
-<li><a class="reference internal" href="#constructions-module" id="id21">Constructions module</a></li>
-<li><a class="reference internal" href="#internal-api" id="id22">Internal API</a></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="#miscellaneous" id="id13">Miscellaneous</a></li>
+<li><a class="reference internal" href="#exception-handling" id="id14">Exception handling</a></li>
+<li><a class="reference internal" href="#persistent-configuration-storage" id="id15">Persistent configuration storage</a></li>
+<li><a class="reference internal" href="#material-info-lookup" id="id16">Material info lookup</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#core-interpreter-context" id="id23">Core interpreter context</a><ul>
-<li><a class="reference internal" href="#event-type" id="id24">Event type</a></li>
+<li><a class="reference internal" href="#c-function-wrappers" id="id17">C++ function wrappers</a><ul>
+<li><a class="reference internal" href="#gui-module" id="id18">Gui module</a></li>
+<li><a class="reference internal" href="#job-module" id="id19">Job module</a></li>
+<li><a class="reference internal" href="#units-module" id="id20">Units module</a></li>
+<li><a class="reference internal" href="#items-module" id="id21">Items module</a></li>
+<li><a class="reference internal" href="#maps-module" id="id22">Maps module</a></li>
+<li><a class="reference internal" href="#burrows-module" id="id23">Burrows module</a></li>
+<li><a class="reference internal" href="#buildings-module" id="id24">Buildings module</a></li>
+<li><a class="reference internal" href="#constructions-module" id="id25">Constructions module</a></li>
+<li><a class="reference internal" href="#internal-api" id="id26">Internal API</a></li>
 </ul>
 </li>
+<li><a class="reference internal" href="#core-interpreter-context" id="id27">Core interpreter context</a><ul>
+<li><a class="reference internal" href="#event-type" id="id28">Event type</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#plugins" id="id25">Plugins</a><ul>
-<li><a class="reference internal" href="#burrows" id="id26">burrows</a></li>
-<li><a class="reference internal" href="#sort" id="id27">sort</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#plugins" id="id29">Plugins</a><ul>
+<li><a class="reference internal" href="#burrows" id="id30">burrows</a></li>
+<li><a class="reference internal" href="#sort" id="id31">sort</a></li>
 </ul>
 </li>
 </ul>
@@ -717,10 +723,13 @@ should be prepared to catch the error and do the necessary
 cleanup.</p>
 </div>
 </div>
-<div class="section" id="dfhack-utilities">
-<h1><a class="toc-backref" href="#id10">DFHack utilities</a></h1>
+<div class="section" id="dfhack-api">
+<h1><a class="toc-backref" href="#id10">DFHack API</a></h1>
 <p>DFHack utility functions are placed in the <tt class="docutils literal">dfhack</tt> global tree.</p>
-<p>Currently it defines the following features:</p>
+<div class="section" id="native-utilities">
+<h2><a class="toc-backref" href="#id11">Native utilities</a></h2>
+<div class="section" id="input-output">
+<h3><a class="toc-backref" href="#id12">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,
@@ -734,7 +743,8 @@ works with DFHack output infrastructure.</p>
 <p>Same as println; intended for errors. Uses red color and logs to stderr.log.</p>
 </li>
 <li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.color([color])</span></tt></p>
-<p>Sets the current output color. If color is <em>nil</em> or <em>-1</em>, resets to default.</p>
+<p>Sets the current output color. If color is <em>nil</em> or <em>-1</em>, resets to default.
+Returns the previous color value.</p>
 </li>
 <li><p class="first"><tt class="docutils literal">dfhack.is_interactive()</tt></p>
 <p>Checks if the thread can access the interactive console and returns <em>true</em> or <em>false</em>.</p>
@@ -752,20 +762,11 @@ this, forcing the function to block on input with lock held.</p>
 string, global environment and command-line history file.</p>
 <p>If the interactive console is not accessible, returns <em>nil, error</em>.</p>
 </li>
-<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.pcall(f[,args...])</span></tt></p>
-<p>Invokes f via xpcall, using an error function that attaches
-a stack trace to the error. The same function is used by SafeCall
-in C++, and dfhack.safecall.</p>
-<p>The returned error is a table with separate <tt class="docutils literal">message</tt> and
-<tt class="docutils literal">stacktrace</tt> string fields; it implements <tt class="docutils literal">__tostring</tt>.</p>
-</li>
-<li><p class="first"><tt class="docutils literal"><span class="pre">safecall(f[,args...])</span></tt>, <tt class="docutils literal"><span class="pre">dfhack.safecall(f[,args...])</span></tt></p>
-<p>Just like pcall, but also prints the error using printerr before
-returning. Intended as a convenience function.</p>
-</li>
-<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.saferesume(coroutine[,args...])</span></tt></p>
-<p>Compares to coroutine.resume like dfhack.safecall vs pcall.</p>
-</li>
+</ul>
+</div>
+<div class="section" id="miscellaneous">
+<h3><a class="toc-backref" href="#id13">Miscellaneous</a></h3>
+<ul>
 <li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.run_script(name[,args...])</span></tt></p>
 <p>Run a lua script in hack/scripts/, as if it was started from dfhack command-line.
 The <tt class="docutils literal">name</tt> argument should be the name stem, as would be used on the command line.
@@ -781,6 +782,32 @@ the lock. It is safe to nest suspends.</p>
 to group operations together in one big critical section. A plugin
 can choose to run all lua code inside a C++-side suspend lock.</p>
 </li>
+</ul>
+</div>
+<div class="section" id="exception-handling">
+<h3><a class="toc-backref" href="#id14">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.
+The verbose parameter controls whether the trace is printed by default.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">qerror(msg[,level])</span></tt></p>
+<p>Calls <tt class="docutils literal">dfhack.error()</tt> with <tt class="docutils literal">verbose</tt> being <em>false</em>. Intended to
+be used for user-caused errors in scripts, where stack traces are not
+desirable.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.pcall(f[,args...])</span></tt></p>
+<p>Invokes f via xpcall, using an error function that attaches
+a stack trace to the error. The same function is used by SafeCall
+in C++, and dfhack.safecall.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">safecall(f[,args...])</span></tt>, <tt class="docutils literal"><span class="pre">dfhack.safecall(f[,args...])</span></tt></p>
+<p>Just like pcall, but also prints the error using printerr before
+returning. Intended as a convenience function.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.saferesume(coroutine[,args...])</span></tt></p>
+<p>Compares to coroutine.resume like dfhack.safecall vs pcall.</p>
+</li>
 <li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.call_with_finalizer(num_cleanup_args,always,cleanup_fn[,cleanup_args...],fn[,args...])</span></tt></p>
 <p>Invokes <tt class="docutils literal">fn</tt> with <tt class="docutils literal">args</tt>, and after it returns or throws an
 error calls <tt class="docutils literal">cleanup_fn</tt> with <tt class="docutils literal">cleanup_args</tt>. Any return values from
@@ -800,9 +827,40 @@ Implemented using <tt class="docutils literal"><span class="pre">call_with_final
 <li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.with_temp_object(obj,fn[,args...])</span></tt></p>
 <p>Calls <tt class="docutils literal"><span class="pre">fn(obj,args...)</span></tt>, then finalizes with <tt class="docutils literal">obj:delete()</tt>.</p>
 </li>
+<li><p class="first"><tt class="docutils literal">dfhack.exception</tt></p>
+<p>Metatable of error objects used by dfhack. The objects have the
+following properties:</p>
+<dl class="docutils">
+<dt><tt class="docutils literal">err.where</tt></dt>
+<dd><p class="first last">The location prefix string, or <em>nil</em>.</p>
+</dd>
+<dt><tt class="docutils literal">err.message</tt></dt>
+<dd><p class="first last">The base message string.</p>
+</dd>
+<dt><tt class="docutils literal">err.stacktrace</tt></dt>
+<dd><p class="first last">The stack trace string, or <em>nil</em>.</p>
+</dd>
+<dt><tt class="docutils literal">err.cause</tt></dt>
+<dd><p class="first last">A different exception object, or <em>nil</em>.</p>
+</dd>
+<dt><tt class="docutils literal">err.thread</tt></dt>
+<dd><p class="first last">The coroutine that has thrown the exception.</p>
+</dd>
+<dt><tt class="docutils literal">err.verbose</tt></dt>
+<dd><p class="first last">Boolean, or <em>nil</em>; specifies if where and stacktrace should be printed.</p>
+</dd>
+<dt><tt class="docutils literal">tostring(err)</tt>, or <tt class="docutils literal"><span class="pre">err:tostring([verbose])</span></tt></dt>
+<dd><p class="first last">Converts the exception to string.</p>
+</dd>
+</dl>
+</li>
+<li><p class="first"><tt class="docutils literal">dfhack.exception.verbose</tt></p>
+<p>The default value of the <tt class="docutils literal">verbose</tt> argument of <tt class="docutils literal">err:tostring()</tt>.</p>
+</li>
 </ul>
+</div>
 <div class="section" id="persistent-configuration-storage">
-<h2><a class="toc-backref" href="#id11">Persistent configuration storage</a></h2>
+<h3><a class="toc-backref" href="#id15">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
@@ -837,7 +895,7 @@ functions can just copy values in memory without doing any actual I/O.
 However, currently every entry has a 180+-byte dead-weight overhead.</p>
 </div>
 <div class="section" id="material-info-lookup">
-<h2><a class="toc-backref" href="#id12">Material info lookup</a></h2>
+<h3><a class="toc-backref" href="#id16">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>
@@ -880,8 +938,9 @@ Accept dfhack_material_category auto-assign table.</p>
 </li>
 </ul>
 </div>
+</div>
 <div class="section" id="c-function-wrappers">
-<h2><a class="toc-backref" href="#id13">C++ function wrappers</a></h2>
+<h2><a class="toc-backref" href="#id17">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
@@ -910,7 +969,7 @@ can be omitted.</p>
 </li>
 </ul>
 <div class="section" id="gui-module">
-<h3><a class="toc-backref" href="#id14">Gui module</a></h3>
+<h3><a class="toc-backref" href="#id18">Gui module</a></h3>
 <ul>
 <li><p class="first"><tt class="docutils literal">dfhack.gui.getCurViewscreen()</tt></p>
 <p>Returns the viewscreen that is current in the core.</p>
@@ -946,7 +1005,7 @@ The is_bright boolean actually seems to invert the brightness.</p>
 </ul>
 </div>
 <div class="section" id="job-module">
-<h3><a class="toc-backref" href="#id15">Job module</a></h3>
+<h3><a class="toc-backref" href="#id19">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>
@@ -983,7 +1042,7 @@ a lua list containing them.</p>
 </ul>
 </div>
 <div class="section" id="units-module">
-<h3><a class="toc-backref" href="#id16">Units module</a></h3>
+<h3><a class="toc-backref" href="#id20">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>
@@ -1037,7 +1096,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="#id17">Items module</a></h3>
+<h3><a class="toc-backref" href="#id21">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>
@@ -1080,7 +1139,7 @@ Returns <em>false</em> in case of error.</p>
 </ul>
 </div>
 <div class="section" id="maps-module">
-<h3><a class="toc-backref" href="#id18">Maps module</a></h3>
+<h3><a class="toc-backref" href="#id22">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>
@@ -1121,7 +1180,7 @@ burrows, or the presence of invaders.</p>
 </ul>
 </div>
 <div class="section" id="burrows-module">
-<h3><a class="toc-backref" href="#id19">Burrows module</a></h3>
+<h3><a class="toc-backref" href="#id23">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>
@@ -1156,7 +1215,7 @@ burrows, or the presence of invaders.</p>
 </ul>
 </div>
 <div class="section" id="buildings-module">
-<h3><a class="toc-backref" href="#id20">Buildings module</a></h3>
+<h3><a class="toc-backref" href="#id24">Buildings module</a></h3>
 <ul>
 <li><p class="first"><tt class="docutils literal">dfhack.buildings.getSize(building)</tt></p>
 <p>Returns <em>width, height, centerx, centery</em>.</p>
@@ -1296,7 +1355,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="#id21">Constructions module</a></h3>
+<h3><a class="toc-backref" href="#id25">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
@@ -1312,7 +1371,7 @@ Returns <em>true, was_only_planned</em> if removed; or <em>false</em> if none fo
 </ul>
 </div>
 <div class="section" id="internal-api">
-<h3><a class="toc-backref" href="#id22">Internal API</a></h3>
+<h3><a class="toc-backref" href="#id26">Internal API</a></h3>
 <p>These functions are intended for the use by dfhack developers,
 and are only documented here for completeness:</p>
 <ul>
@@ -1329,8 +1388,8 @@ global environment, persistent between calls to the script.</p>
 <li><p class="first"><tt class="docutils literal">dfhack.internal.getVTable(name)</tt></p>
 <p>Returns the pre-extracted vtable address <tt class="docutils literal">name</tt>, or <em>nil</em>.</p>
 </li>
-<li><p class="first"><tt class="docutils literal">dfhack.internal.getBase()</tt></p>
-<p>Returns the base address of the process.</p>
+<li><p class="first"><tt class="docutils literal">dfhack.internal.getRebaseDelta()</tt></p>
+<p>Returns the ASLR rebase offset of the DF executable.</p>
 </li>
 <li><p class="first"><tt class="docutils literal">dfhack.internal.getMemRanges()</tt></p>
 <p>Returns a sequence of tables describing virtual memory ranges of the process.</p>
@@ -1355,7 +1414,7 @@ Returns: <em>found_index</em>, or <em>nil</em> if end reached.</p>
 </div>
 </div>
 <div class="section" id="core-interpreter-context">
-<h2><a class="toc-backref" href="#id23">Core interpreter context</a></h2>
+<h2><a class="toc-backref" href="#id27">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>
@@ -1386,7 +1445,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="#id24">Event type</a></h3>
+<h3><a class="toc-backref" href="#id28">Event type</a></h3>
 <p>An event is just a lua table with a predefined metatable that
 contains a __call metamethod. When it is invoked, it loops
 through the table with next and calls all contained values.
@@ -1412,14 +1471,14 @@ order using <tt class="docutils literal">dfhack.safecall</tt>.</p>
 </div>
 </div>
 <div class="section" id="plugins">
-<h1><a class="toc-backref" href="#id25">Plugins</a></h1>
+<h1><a class="toc-backref" href="#id29">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="#id26">burrows</a></h2>
+<h2><a class="toc-backref" href="#id30">burrows</a></h2>
 <p>Implements extended burrow manipulations.</p>
 <p>Events:</p>
 <ul>
@@ -1457,7 +1516,7 @@ 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="#id27">sort</a></h2>
+<h2><a class="toc-backref" href="#id31">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>

library/LuaApi.cpp

@@ -1036,7 +1036,7 @@ static void *checkaddr(lua_State *L, int idx, bool allow_null = false)
     return rv;
 }
 
-static uint32_t getRebaseDelta() { return Core::getInstance().vinfo->getRebaseDelta(); }
+static int getRebaseDelta() { return Core::getInstance().vinfo->getRebaseDelta(); }
 
 static const LuaWrapper::FunctionReg dfhack_internal_module[] = {
     WRAP(getRebaseDelta),
@@ -1074,9 +1074,9 @@ static int internal_setAddress(lua_State *L)
     }
 
     // Print via printerr, so that it is definitely logged to stderr.log.
-    addr -= Core::getInstance().vinfo->getRebaseDelta();
-    std::string msg = stl_sprintf("<global-address name='%s' value='0x%x'/>", name.c_str(), addr);
-    dfhack_printerr(L, msg);
+    uint32_t iaddr = addr - Core::getInstance().vinfo->getRebaseDelta();
+    fprintf(stderr, "Setting global '%s' to %x (%x)\n", name.c_str(), addr, iaddr);
+    fflush(stderr);
 
     return 1;
 }

library/LuaTools.cpp

@@ -256,8 +256,11 @@ static int lua_dfhack_color(lua_State *S)
         luaL_argerror(S, 1, "invalid color value");
 
     color_ostream *out = Lua::GetOutput(S);
-    if (out)
+    if (out) {
+        lua_pushinteger(S, (int)out->color());
         out->color(color_ostream::color_value(cv));
+        return 1;
+    }
     return 0;
 }
 
@@ -423,10 +426,12 @@ static bool convert_to_exception(lua_State *L, int slevel, lua_State *thread = N
 
             // Create a new exception for this thread
             lua_newtable(L);
-            luaL_where(L, 1);
+            luaL_where(L, slevel);
+            lua_setfield(L, -2, "where");
             lua_pushstring(L, "coroutine resume failed");
-            lua_concat(L, 2);
             lua_setfield(L, -2, "message");
+            lua_getfield(L, -2, "verbose");
+            lua_setfield(L, -2, "verbose");
             lua_swap(L);
             lua_setfield(L, -2, "cause");
         }
@@ -480,12 +485,57 @@ static int dfhack_onerror(lua_State *L)
     return 1;
 }
 
+static int dfhack_error(lua_State *L)
+{
+    luaL_checkany(L, 1);
+    lua_settop(L, 3);
+    int level = std::max(1, luaL_optint(L, 2, 1));
+
+    lua_pushvalue(L, 1);
+
+    if (convert_to_exception(L, level))
+    {
+        luaL_where(L, level);
+        lua_setfield(L, -2, "where");
+
+        if (!lua_isnil(L, 3))
+        {
+            lua_pushvalue(L, 3);
+            lua_setfield(L, -2, "verbose");
+        }
+    }
+
+    return lua_error(L);
+}
+
 static int dfhack_exception_tostring(lua_State *L)
 {
     luaL_checktype(L, 1, LUA_TTABLE);
+    lua_settop(L, 2);
+
+    if (lua_isnil(L, 2))
+    {
+        lua_rawgetp(L, LUA_REGISTRYINDEX, &DFHACK_EXCEPTION_META_TOKEN);
+        lua_getfield(L, -1, "verbose");
+        lua_insert(L, 2);
+        lua_settop(L, 2);
+    }
+
+    lua_getfield(L, 1, "verbose");
+
+    bool verbose =
+        lua_toboolean(L, 2) || lua_toboolean(L, 3) ||
+        (lua_isnil(L, 2) && lua_isnil(L, 3));
 
     int base = lua_gettop(L);
 
+    if (verbose || lua_isnil(L, 3))
+    {
+        lua_getfield(L, 1, "where");
+        if (!lua_isstring(L, -1))
+            lua_pop(L, 1);
+    }
+
     lua_getfield(L, 1, "message");
     if (!lua_isstring(L, -1))
     {
@@ -493,15 +543,26 @@ static int dfhack_exception_tostring(lua_State *L)
         lua_pushstring(L, "(error message is not a string)");
     }
 
+    if (verbose)
+    {
         lua_pushstring(L, "\n");
         lua_getfield(L, 1, "stacktrace");
         if (!lua_isstring(L, -1))
             lua_pop(L, 2);
+    }
 
     lua_pushstring(L, "\ncaused by:\n");
     lua_getfield(L, 1, "cause");
     if (lua_isnil(L, -1))
         lua_pop(L, 2);
+    else if (lua_istable(L, -1))
+    {
+        lua_pushcfunction(L, dfhack_exception_tostring);
+        lua_swap(L);
+        lua_pushvalue(L, 2);
+        if (lua_pcall(L, 2, 1, 0) != LUA_OK)
+            error_tostring(L);
+    }
     else
         error_tostring(L);
 
@@ -652,7 +713,12 @@ static int dfhack_coauxwrap (lua_State *L) {
     if (Lua::IsSuccess(r))
         return lua_gettop(L);
     else
+    {
+        if (lua_checkstack(L, LUA_MINSTACK))
+            convert_to_exception(L, 1);
+
         return lua_error(L);
+    }
 }
 
 static int dfhack_cowrap (lua_State *L) {
@@ -1159,6 +1225,7 @@ static const luaL_Reg dfhack_funcs[] = {
     { "safecall", dfhack_safecall },
     { "saferesume", dfhack_saferesume },
     { "onerror", dfhack_onerror },
+    { "error", dfhack_error },
     { "call_with_finalizer", dfhack_call_with_finalizer },
     { "with_suspend", lua_dfhack_with_suspend },
     { "open_plugin", dfhack_open_plugin },
@@ -1359,6 +1426,8 @@ lua_State *DFHack::Lua::Open(color_ostream &out, lua_State *state)
     lua_newtable(state);
     lua_pushcfunction(state, dfhack_exception_tostring);
     lua_setfield(state, -2, "__tostring");
+    lua_pushcfunction(state, dfhack_exception_tostring);
+    lua_setfield(state, -2, "tostring");
     lua_dup(state);
     lua_rawsetp(state, LUA_REGISTRYINDEX, &DFHACK_EXCEPTION_META_TOKEN);
     lua_setfield(state, -2, "exception");

library/include/ColorText.h

@@ -111,6 +111,8 @@ namespace  DFHack
         void printerr(const char *format, ...);
         void vprinterr(const char *format, va_list args);
 
+        /// Get color
+        color_value color() { return cur_color; }
         /// Set color (ANSI color number)
         void color(color_value c);
         /// Reset color to default

library/lua/dfhack.lua

@@ -49,6 +49,10 @@ function dfhack.pcall(f, ...)
     return xpcall(f, dfhack.onerror, ...)
 end
 
+function qerror(msg, level)
+    dfhack.error(msg, (level or 1) + 1, false)
+end
+
 function dfhack.with_finalize(...)
     return dfhack.call_with_finalizer(0,true,...)
 end

library/lua/memscan.lua

@@ -154,7 +154,8 @@ function MemoryArea.new(astart, aend)
         int16_t = CheckedArray.new('int16_t',astart,aend),
         uint16_t = CheckedArray.new('uint16_t',astart,aend),
         int32_t = CheckedArray.new('int32_t',astart,aend),
-        uint32_t = CheckedArray.new('uint32_t',astart,aend)
+        uint32_t = CheckedArray.new('uint32_t',astart,aend),
+        float = CheckedArray.new('float',astart,aend)
     }
     setmetatable(obj, MemoryArea)
     return obj
@@ -168,7 +169,7 @@ function MemoryArea:__tostring()
     return string.format('<MemoryArea: %x..%x>', self.start_addr, self.end_addr)
 end
 function MemoryArea:contains_range(start,size)
-    return start >= self.start_addr and (start+size) <= self.end_addr
+    return size >= 0 and start >= self.start_addr and (start+size) <= self.end_addr
 end
 function MemoryArea:contains_obj(obj,count)
     local size, base = df.sizeof(obj)
@@ -234,7 +235,7 @@ function found_offset(name,val)
     if not val then
         print('Could not find offset '..name)
         if not cval and not utils.prompt_yes_no('Continue with the script?') then
-            error('User quit')
+            qerror('User quit')
         end
         return
     end
@@ -251,6 +252,16 @@ function found_offset(name,val)
         end
     else
         dfhack.internal.setAddress(name, val)
+
+        local ival = val - dfhack.internal.getRebaseDelta()
+        local entry = string.format("<global-address name='%s' value='0x%x'/>\n", name, ival)
+
+        local ccolor = dfhack.color(COLOR_LIGHTGREEN)
+        dfhack.print(entry)
+        dfhack.color(ccolor)
+
+        io.stdout:write(entry)
+        io.stdout:flush()
     end
 end
 
@@ -453,4 +464,30 @@ function DiffSearcher:find_counter(prompt,data_type,delta,action_prompt)
     )
 end
 
+-- Screen size
+
+function get_screen_size()
+    -- Use already known globals
+    if dfhack.internal.getAddress('init') then
+        local d = df.global.init.display
+        return d.grid_x, d.grid_y
+    end
+    if dfhack.internal.getAddress('gps') then
+        local g = df.global.gps
+        return g.dimx, g.dimy
+    end
+
+    -- Parse stdout.log for resize notifications
+    io.stdout:flush()
+
+    local w,h = 80,25
+    for line in io.lines('stdout.log') do
+        local cw, ch = string.match(line, '^Resizing grid to (%d+)x(%d+)$')
+        if cw and ch then
+            w, h = tonumber(cw), tonumber(ch)
+        end
+    end
+    return w,h
+end
+
 return _ENV

library/lua/utils.lua

@@ -379,7 +379,7 @@ function prompt_yes_no(msg,default)
             elseif string.match(rv,'^[Nn]') then
                 return false
             elseif rv == 'abort' then
-                error('User abort in utils.prompt_yes_no()')
+                qerror('User abort in utils.prompt_yes_no()')
             elseif rv == '' and default ~= nil then
                 return default
             end

scripts/devel/find-offsets.lua

@@ -5,6 +5,8 @@ local ms = require 'memscan'
 
 local is_known = dfhack.internal.getAddress
 
+local os_type = dfhack.getOSType()
+
 local force_scan = {}
 for _,v in ipairs({...}) do
     force_scan[v] = true
@@ -22,7 +24,10 @@ PERMANENT SAVE CORRUPTION.
 
 Finding the first few globals requires this script to be
 started immediately after loading the game, WITHOUT
-first loading a world.
+first loading a world. The rest expect a loaded save,
+not a fresh embark. Finding current_weather requires
+a special save previously processed with devel/prepare-save
+on a DF version with working dfhack.
 
 The script expects vanilla game configuration, without
 any custom tilesets or init file changes. Never unpause
@@ -38,12 +43,12 @@ end
 
 local data = ms.get_data_segment()
 if not data then
-    error('Could not find data segment')
+    qerror('Could not find data segment')
 end
 
 print('\nData section: '..tostring(data))
 if data.size < 5000000 then
-    error('Data segment too short.')
+    qerror('Data segment too short.')
 end
 
 local searcher = ms.DiffSearcher.new(data)
@@ -56,6 +61,34 @@ local function validate_offset(name,validator,addr,tname,...)
     ms.found_offset(name,obj)
 end
 
+local function zoomed_searcher(startn, end_or_sz)
+    if force_scan.nozoom then
+        return nil
+    end
+    local sv = is_known(startn)
+    if not sv then
+        return nil
+    end
+    local ev
+    if type(end_or_sz) == 'number' then
+        ev = sv + end_or_sz
+        if end_or_sz < 0 then
+            sv, ev = ev, sv
+        end
+    else
+        ev = is_known(end_or_sz)
+        if not ev then
+            return nil
+        end
+    end
+    sv = sv - (sv % 4)
+    ev = ev + 3
+    ev = ev - (ev % 4)
+    if data:contains_range(sv, ev-sv) then
+        return ms.DiffSearcher.new(ms.MemoryArea.new(sv,ev))
+    end
+end
+
 local function exec_finder(finder, names)
     if type(names) ~= 'table' then
         names = { names }
@@ -70,7 +103,7 @@ local function exec_finder(finder, names)
         if not dfhack.safecall(finder) then
             if not utils.prompt_yes_no('Proceed with the rest of the script?') then
                 searcher:reset()
-                error('Quit')
+                qerror('Quit')
             end
         end
     else
@@ -80,7 +113,8 @@ end
 
 local ordinal_names = {
     [0] = '1st entry',
-    [1] = '2nd entry'
+    [1] = '2nd entry',
+    [2] = '3rd entry'
 }
 setmetatable(ordinal_names, {
     __index = function(self,idx) return (idx+1)..'th entry' end
@@ -218,6 +252,83 @@ local function find_gview()
     dfhack.printerr('Could not find gview')
 end
 
+--
+-- enabler
+--
+
+local function is_valid_enabler(e)
+    if not ms.is_valid_vector(e.textures.raws, 4)
+    or not ms.is_valid_vector(e.text_system, 4)
+    then
+        dfhack.printerr('Vector layout check failed.')
+        return false
+    end
+
+    return true
+end
+
+local function find_enabler()
+    -- Data from data/init/colors.txt
+    local colors = {
+        0, 0, 0,       0, 0, 128,      0, 128, 0,
+        0, 128, 128,   128, 0, 0,      128, 0, 128,
+        128, 128, 0,   192, 192, 192,  128, 128, 128,
+        0, 0, 255,     0, 255, 0,      0, 255, 255,
+        255, 0, 0,     255, 0, 255,    255, 255, 0,
+        255, 255, 255
+    }
+
+    for i = 1,#colors do colors[i] = colors[i]/255 end
+
+    local idx, addr = data.float:find_one(colors)
+    if idx then
+        validate_offset('enabler', is_valid_enabler, addr, df.enabler, 'ccolor')
+        return
+    end
+
+    dfhack.printerr('Could not find enabler')
+end
+
+--
+-- gps
+--
+
+local function is_valid_gps(g)
+    if g.clipx[0] < 0 or g.clipx[0] > g.clipx[1] or g.clipx[1] >= g.dimx then
+        dfhack.printerr('Invalid clipx: ', g.clipx[0], g.clipx[1], g.dimx)
+    end
+    if g.clipy[0] < 0 or g.clipy[0] > g.clipy[1] or g.clipy[1] >= g.dimy then
+        dfhack.printerr('Invalid clipy: ', g.clipy[0], g.clipy[1], g.dimy)
+    end
+
+    return true
+end
+
+local function find_gps()
+    print('\nPlease ensure the mouse cursor is not over the game window.')
+    if not utils.prompt_yes_no('Proceed?', true) then
+        return
+    end
+
+    local zone
+    if os_type == 'windows' or os_type == 'linux' then
+        zone = zoomed_searcher('cursor', 0x1000)
+    elseif os_type == 'darwin' then
+        zone = zoomed_searcher('enabler', 0x1000)
+    end
+    zone = zone or searcher
+
+    local w,h = ms.get_screen_size()
+
+    local idx, addr = zone.area.int32_t:find_one{w, h, -1, -1}
+    if idx then
+        validate_offset('gps', is_valid_gps, addr, df.graphic, 'dimx')
+        return
+    end
+
+    dfhack.printerr('Could not find gps')
+end
+
 --
 -- World
 --
@@ -356,6 +467,88 @@ number, so when it shows "Min (5000df", it means 50000:]],
                     addr, df.ui_build_selector, 'plate_info', 'unit_min')
 end
 
+--
+-- init
+--
+
+local function is_valid_init(i)
+    -- derived from curses_*.png image sizes presumably
+    if i.font.small_font_dispx ~= 8 or i.font.small_font_dispy ~= 12 or
+       i.font.large_font_dispx ~= 10 or i.font.large_font_dispy ~= 12 then
+        print('Unexpected font sizes: ',
+              i.font.small_font_dispx, i.font.small_font_dispy,
+              i.font.large_font_dispx, i.font.large_font_dispy)
+        if not utils.prompt_yes_no('Ignore?') then
+            return false
+        end
+    end
+
+    return true
+end
+
+local function find_init()
+    local zone
+    if os_type == 'windows' then
+        zone = zoomed_searcher('ui_build_selector', 0x3000)
+    elseif os_type == 'linux' or os_type == 'darwin' then
+        zone = zoomed_searcher('d_init', -0x2000)
+    end
+    zone = zone or searcher
+
+    local idx, addr = zone.area.int32_t:find_one{250, 150, 15, 0}
+    if idx then
+        validate_offset('init', is_valid_init, addr, df.init, 'input', 'hold_time')
+        return
+    end
+
+    local w,h = ms.get_screen_size()
+
+    local idx, addr = zone.area.int32_t:find_one{w, h}
+    if idx then
+        validate_offset('init', is_valid_init, addr, df.init, 'display', 'grid_x')
+        return
+    end
+
+    dfhack.printerr('Could not find init')
+end
+
+--
+-- current_weather
+--
+
+local function find_current_weather()
+    print('\nPlease load the save previously processed with prepare-save.')
+    if not utils.prompt_yes_no('Proceed?', true) then
+        return
+    end
+
+    local zone
+    if os_type == 'windows' then
+        zone = zoomed_searcher('crime_next_id', 512)
+    elseif os_type == 'darwin' then
+        zone = zoomed_searcher('cursor', -64)
+    elseif os_type == 'linux' then
+        zone = zoomed_searcher('ui_building_assign_type', -512)
+    end
+    zone = zone or searcher
+
+    local wbytes = {
+        2, 1, 0, 2, 0,
+        1, 2, 1, 0, 0,
+        2, 0, 2, 1, 2,
+        1, 2, 0, 1, 1,
+        2, 0, 1, 0, 2
+    }
+
+    local idx, addr = zone.area.int8_t:find_one(wbytes)
+    if idx then
+        ms.found_offset('current_weather', addr)
+        return
+    end
+
+    dfhack.printerr('Could not find current_weather - must be a wrong save.')
+end
+
 --
 -- ui_menu_width
 --
@@ -578,6 +771,124 @@ NOTE: If not done after first 3-4 steps, resize the game window.]],
     ms.found_offset('window_z', addr)
 end
 
+--
+-- cur_year
+--
+
+local function find_cur_year()
+    local zone
+    if os_type == 'windows' then
+        zone = zoomed_searcher('formation_next_id', 32)
+    elseif os_type == 'darwin' then
+        zone = zoomed_searcher('cursor', -32)
+    elseif os_type == 'linux' then
+        zone = zoomed_searcher('ui_building_assign_type', -512)
+    end
+    if not zone then
+        dfhack.printerr('Cannot search for cur_year - prerequisites missing.')
+        return
+    end
+
+    local yvalue = utils.prompt_input('Please enter current in-game year: ', utils.check_number)
+    local idx, addr = zone.area.int32_t:find_one{yvalue}
+    if idx then
+        ms.found_offset('cur_year', addr)
+        return
+    end
+
+    dfhack.printerr('Could not find cur_year')
+end
+
+--
+-- cur_year_tick
+--
+
+local function find_cur_year_tick()
+    local zone
+    if os_type == 'windows' then
+        zone = zoomed_searcher('artifact_next_id', -32)
+    else
+        zone = zoomed_searcher('cur_year', 128)
+    end
+    if not zone then
+        dfhack.printerr('Cannot search for cur_year_tick - prerequisites missing.')
+        return
+    end
+
+    local addr = zone:find_counter([[
+Searching for cur_year_tick. Please exit to main dwarfmode
+menu, then do as instructed below:]],
+        'int32_t', 1,
+        "Please press '.' to step the game one frame."
+    )
+    ms.found_offset('cur_year_tick', addr)
+end
+
+--
+-- process_jobs
+--
+
+local function get_process_zone()
+    if os_type == 'windows' then
+        return zoomed_searcher('ui_workshop_job_cursor', 'ui_building_in_resize')
+    elseif os_type == 'linux' or os_type == 'darwin' then
+        return zoomed_searcher('cur_year', 'cur_year_tick')
+    end
+end
+
+local function find_process_jobs()
+    local zone = get_process_zone() or searcher
+
+    local addr = zone:find_menu_cursor([[
+Searching for process_jobs. Please do as instructed below:]],
+        'int8_t',
+        { 1, 0 },
+        { [1] = 'designate a building to be constructed, e.g a bed',
+          [0] = 'step or unpause the game to reset the flag' }
+    )
+    ms.found_offset('process_jobs', addr)
+end
+
+--
+-- process_dig
+--
+
+local function find_process_dig()
+    local zone = get_process_zone() or searcher
+
+    local addr = zone:find_menu_cursor([[
+Searching for process_dig. Please do as instructed below:]],
+        'int8_t',
+        { 1, 0 },
+        { [1] = 'designate a tile to be mined out',
+          [0] = 'step or unpause the game to reset the flag' }
+    )
+    ms.found_offset('process_dig', addr)
+end
+
+--
+-- pause_state
+--
+
+local function find_pause_state()
+    local zone
+    if os_type == 'linux' or os_type == 'darwin' then
+        zone = zoomed_searcher('ui_look_cursor', 32)
+    elseif os_type == 'windows' then
+        zone = zoomed_searcher('ui_workshop_job_cursor', 80)
+    end
+    zone = zone or searcher
+
+    local addr = zone:find_menu_cursor([[
+Searching for pause_state. Please do as instructed below:]],
+        'int8_t',
+        { 1, 0 },
+        { [1] = 'PAUSE the game',
+          [0] = 'UNPAUSE the game' }
+    )
+    ms.found_offset('pause_state', addr)
+end
+
 --
 -- MAIN FLOW
 --
@@ -588,6 +899,8 @@ exec_finder(find_cursor, { 'cursor', 'selection_rect', 'gamemode', 'gametype' })
 exec_finder(find_announcements, 'announcements')
 exec_finder(find_d_init, 'd_init')
 exec_finder(find_gview, 'gview')
+exec_finder(find_enabler, 'enabler')
+exec_finder(find_gps, 'gps')
 
 print('\nCompound globals (need loaded world):\n')
 
@@ -595,9 +908,11 @@ exec_finder(find_world, 'world')
 exec_finder(find_ui, 'ui')
 exec_finder(find_ui_sidebar_menus, 'ui_sidebar_menus')
 exec_finder(find_ui_build_selector, 'ui_build_selector')
+exec_finder(find_init, 'init')
 
 print('\nPrimitive globals:\n')
 
+exec_finder(find_current_weather, 'current_weather')
 exec_finder(find_ui_menu_width, { 'ui_menu_width', 'ui_area_map_width' })
 exec_finder(find_ui_selected_unit, 'ui_selected_unit')
 exec_finder(find_ui_unit_view_mode, 'ui_unit_view_mode')
@@ -611,5 +926,13 @@ exec_finder(find_window_x, 'window_x')
 exec_finder(find_window_y, 'window_y')
 exec_finder(find_window_z, 'window_z')
 
+print('\nUnpausing globals:\n')
+
+exec_finder(find_cur_year, 'cur_year')
+exec_finder(find_cur_year_tick, 'cur_year_tick')
+exec_finder(find_process_jobs, 'process_jobs')
+exec_finder(find_process_dig, 'process_dig')
+exec_finder(find_pause_state, 'pause_state')
+
 print('\nDone. Now add newly-found globals to symbols.xml.')
 searcher:reset()

scripts/devel/prepare-save.lua

@@ -0,0 +1,71 @@
+-- Prepare the current save for use with devel/find-offsets.
+
+df.global.pause_state = true
+
+--[[print('Placing anchor...')
+
+do
+    local wp = df.global.ui.waypoints
+
+    for _,pt in ipairs(wp.points) do
+        if pt.name == 'dfhack_anchor' then
+            print('Already placed.')
+            goto found
+        end
+    end
+
+    local x,y,z = pos2xyz(df.global.cursor)
+
+    if not x then
+        error("Place cursor at your preferred anchor point.")
+    end
+
+    local id = wp.next_point_id
+    wp.next_point_id = id + 1
+
+    wp.points:insert('#',{
+        new = true, id = id, name = 'dfhack_anchor',
+        comment=(x..','..y..','..z),
+        tile = string.byte('!'), fg_color = COLOR_LIGHTRED, bg_color = COLOR_BLUE,
+        pos = xyz2pos(x,y,z)
+    })
+
+::found::
+end]]
+
+print('Nicknaming units...')
+
+for i,unit in ipairs(df.global.world.units.active) do
+    dfhack.units.setNickname(unit, i..':'..unit.id)
+end
+
+print('Setting weather...')
+
+local wbytes = {
+    2, 1, 0, 2, 0,
+    1, 2, 1, 0, 0,
+    2, 0, 2, 1, 2,
+    1, 2, 0, 1, 1,
+    2, 0, 1, 0, 2
+}
+
+for i=0,4 do
+    for j = 0,4 do
+        df.global.current_weather[i][j] = (wbytes[i*5+j+1] or 2)
+    end
+end
+
+local yearstr = df.global.cur_year..','..df.global.cur_year_tick
+
+print('Cur year and tick: '..yearstr)
+
+dfhack.persistent.save{
+    key='prepare-save/cur_year',
+    value=yearstr,
+    ints={df.global.cur_year, df.global.cur_year_tick}
+}
+
+-- Save
+
+dfhack.run_script('quicksave')
+

scripts/fix/item-occupancy.lua

@@ -116,8 +116,7 @@ if opt then
     if opt == '--fix' then
         fix = true
     else
-        dfhack.printerr('Invalid option: '..opt)
-        return
+        qerror('Invalid option: '..opt)
     end
 end
 

scripts/quicksave.lua

@@ -1,8 +1,7 @@
 -- Makes the game immediately save the state.
 
 if not dfhack.isMapLoaded() then
-    dfhack.printerr("World and map aren't loaded.")
-    return
+    qerror("World and map aren't loaded.")
 end
 
 local ui_main = df.global.ui.main