Skip to content

Commit 763a301

Browse files
angavrilovangavrilov
committed
Add a few more lua api functions, documentation, and unit sort orders.
Units::getProfessionName appears to work correctly for everything except nobles.
1 parent 125cd66 commit 763a301

9 files changed

Lines changed: 449 additions & 80 deletions

File tree

‎LUA_API.rst‎

Lines changed: 90 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -594,41 +594,44 @@ C++ function wrappers
594594
=====================
595595

596596
Thin wrappers around C++ functions, similar to the ones for virtual methods.
597+
One notable difference is that these explicit wrappers allow argument count
598+
adjustment according to the usual lua rules, so trailing false/nil arguments
599+
can be omitted.
597600

598-
* ``dfhack.TranslateName(name,in_english,only_last_name)``
601+
* ``dfhack.TranslateName(name[,in_english,only_last_name])``
599602

600603
Convert a language_name or only the last name part to string.
601604

602605
Gui module
603606
----------
604607

605-
* ``dfhack.gui.getSelectedWorkshopJob(silent)``
608+
* ``dfhack.gui.getSelectedWorkshopJob([silent])``
606609

607610
When a job is selected in *'q'* mode, returns the job, else
608611
prints error unless silent and returns *nil*.
609612

610-
* ``dfhack.gui.getSelectedJob(silent)``
613+
* ``dfhack.gui.getSelectedJob([silent])``
611614

612615
Returns the job selected in a workshop or unit/jobs screen.
613616

614-
* ``dfhack.gui.getSelectedUnit(silent)``
617+
* ``dfhack.gui.getSelectedUnit([silent])``
615618

616619
Returns the unit selected via *'v'*, *'k'*, unit/jobs, or
617620
a full-screen item view of a cage or suchlike.
618621

619-
* ``dfhack.gui.getSelectedItem(silent)``
622+
* ``dfhack.gui.getSelectedItem([silent])``
620623

621624
Returns the item selected via *'v'* ->inventory, *'k'*, *'t'*, or
622625
a full-screen item view of a container. Note that in the
623626
last case, the highlighted *contained item* is returned, not
624627
the container itself.
625628

626-
* ``dfhack.gui.showAnnouncement(text,color,is_bright)``
629+
* ``dfhack.gui.showAnnouncement(text,color[,is_bright])``
627630

628631
Adds a regular announcement with given text, color, and brightness.
629632
The is_bright boolean actually seems to invert the brightness.
630633

631-
* ``dfhack.gui.showPopupAnnouncement(text,color,is_bright)``
634+
* ``dfhack.gui.showPopupAnnouncement(text,color[,is_bright])``
632635

633636
Pops up a titan-style modal announcement window.
634637

@@ -688,6 +691,10 @@ Units module
688691

689692
Returns the language_name object visible in game, accounting for false identities.
690693

694+
* ``dfhack.units.getIdentity(unit)``
695+
696+
Returns the false identity of the unit if it has one, or *nil*.
697+
691698
* ``dfhack.units.getNemesis(unit)``
692699

693700
Returns the nemesis record of the unit if it has one, or *nil*.
@@ -716,6 +723,19 @@ Units module
716723

717724
Adds or removes the unit from the burrow.
718725

726+
* ``dfhack.units.getAge(unit[,true_age])``
727+
728+
Returns the age of the unit in years as a floating-point value.
729+
If ``true_age`` is true, ignores false identities.
730+
731+
* ``dfhack.units.getProfessionName(unit[,plural])``
732+
733+
Retrieves the profession name using custom profession or raws.
734+
735+
* ``dfhack.units.getCasteProfessionName(race,caste,prof_id[,plural])``
736+
737+
Retrieves the profession name for the given race/caste using raws.
738+
719739

720740
Items module
721741
------------
@@ -856,3 +876,66 @@ Features:
856876

857877
Invokes all listeners contained in the event in an arbitrary
858878
order using ``dfhack.safecall``.
879+
880+
=======
881+
Plugins
882+
=======
883+
884+
DFHack plugins may export native functions and events
885+
to lua contexts. They are automatically imported by
886+
``mkmodule('plugins.<name>')``; this means that a lua
887+
module file is still necessary for ``require`` to read.
888+
889+
The following plugins have lua support.
890+
891+
burrows
892+
=======
893+
894+
Implements extended burrow manipulations.
895+
896+
Events:
897+
898+
* ``onBurrowRename.foo = function(burrow)``
899+
900+
Emitted when a burrow might have been renamed either through
901+
the game UI, or ``renameBurrow()``.
902+
903+
* ``onDigComplete.foo = function(job_type,pos,old_tiletype,new_tiletype)``
904+
905+
Emitted when a tile might have been dug out. Only tracked if the
906+
auto-growing burrows feature is enabled.
907+
908+
Native functions:
909+
910+
* ``renameBurrow(burrow,name)``
911+
912+
Renames the burrow, emitting ``onBurrowRename`` and updating auto-grow state properly.
913+
914+
* ``findByName(burrow,name)``
915+
916+
Finds a burrow by name, using the same rules as the plugin command line interface.
917+
Namely, trailing ``'+'`` characters marking auto-grow burrows are ignored.
918+
919+
* ``copyUnits(target,source,enable)``
920+
921+
Applies units from ``source`` burrow to ``target``. The ``enable``
922+
parameter specifies if they are to be added or removed.
923+
924+
* ``copyTiles(target,source,enable)``
925+
926+
Applies tiles from ``source`` burrow to ``target``. The ``enable``
927+
parameter specifies if they are to be added or removed.
928+
929+
* ``setTilesByKeyword(target,keyword,enable)``
930+
931+
Adds or removes tiles matching a predefined keyword. The keyword
932+
set is the same as used by the command line.
933+
934+
The lua module file also re-exports or wraps some of the
935+
functions implemented by the dfhack core for convenience.
936+
937+
sort
938+
====
939+
940+
Does not export any native functions as of now. Instead, it
941+
calls lua code to perform the actual ordering of list items.

‎Lua API.html‎

Lines changed: 81 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -350,6 +350,11 @@ <h1 class="title">DFHack Lua API</h1>
350350
</li>
351351
</ul>
352352
</li>
353+
<li><a class="reference internal" href="#plugins" id="id21">Plugins</a><ul>
354+
<li><a class="reference internal" href="#burrows" id="id22">burrows</a></li>
355+
<li><a class="reference internal" href="#sort" id="id23">sort</a></li>
356+
</ul>
357+
</li>
353358
</ul>
354359
</div>
355360
<div class="section" id="df-structure-wrapper">
@@ -842,37 +847,40 @@ <h2><a class="toc-backref" href="#id12">Material info lookup</a></h2>
842847
</div>
843848
<div class="section" id="c-function-wrappers">
844849
<h2><a class="toc-backref" href="#id13">C++ function wrappers</a></h2>
845-
<p>Thin wrappers around C++ functions, similar to the ones for virtual methods.</p>
850+
<p>Thin wrappers around C++ functions, similar to the ones for virtual methods.
851+
One notable difference is that these explicit wrappers allow argument count
852+
adjustment according to the usual lua rules, so trailing false/nil arguments
853+
can be omitted.</p>
846854
<ul>
847-
<li><p class="first"><tt class="docutils literal">dfhack.TranslateName(name,in_english,only_last_name)</tt></p>
855+
<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.TranslateName(name[,in_english,only_last_name])</span></tt></p>
848856
<p>Convert a language_name or only the last name part to string.</p>
849857
</li>
850858
</ul>
851859
<div class="section" id="gui-module">
852860
<h3><a class="toc-backref" href="#id14">Gui module</a></h3>
853861
<ul>
854-
<li><p class="first"><tt class="docutils literal">dfhack.gui.getSelectedWorkshopJob(silent)</tt></p>
862+
<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.gui.getSelectedWorkshopJob([silent])</span></tt></p>
855863
<p>When a job is selected in <em>'q'</em> mode, returns the job, else
856864
prints error unless silent and returns <em>nil</em>.</p>
857865
</li>
858-
<li><p class="first"><tt class="docutils literal">dfhack.gui.getSelectedJob(silent)</tt></p>
866+
<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.gui.getSelectedJob([silent])</span></tt></p>
859867
<p>Returns the job selected in a workshop or unit/jobs screen.</p>
860868
</li>
861-
<li><p class="first"><tt class="docutils literal">dfhack.gui.getSelectedUnit(silent)</tt></p>
869+
<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.gui.getSelectedUnit([silent])</span></tt></p>
862870
<p>Returns the unit selected via <em>'v'</em>, <em>'k'</em>, unit/jobs, or
863871
a full-screen item view of a cage or suchlike.</p>
864872
</li>
865-
<li><p class="first"><tt class="docutils literal">dfhack.gui.getSelectedItem(silent)</tt></p>
873+
<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.gui.getSelectedItem([silent])</span></tt></p>
866874
<p>Returns the item selected via <em>'v'</em> -&gt;inventory, <em>'k'</em>, <em>'t'</em>, or
867875
a full-screen item view of a container. Note that in the
868876
last case, the highlighted <em>contained item</em> is returned, not
869877
the container itself.</p>
870878
</li>
871-
<li><p class="first"><tt class="docutils literal">dfhack.gui.showAnnouncement(text,color,is_bright)</tt></p>
879+
<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.gui.showAnnouncement(text,color[,is_bright])</span></tt></p>
872880
<p>Adds a regular announcement with given text, color, and brightness.
873881
The is_bright boolean actually seems to invert the brightness.</p>
874882
</li>
875-
<li><p class="first"><tt class="docutils literal">dfhack.gui.showPopupAnnouncement(text,color,is_bright)</tt></p>
883+
<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.gui.showPopupAnnouncement(text,color[,is_bright])</span></tt></p>
876884
<p>Pops up a titan-style modal announcement window.</p>
877885
</li>
878886
</ul>
@@ -923,6 +931,9 @@ <h3><a class="toc-backref" href="#id16">Units module</a></h3>
923931
<li><p class="first"><tt class="docutils literal">dfhack.units.getVisibleName(unit)</tt></p>
924932
<p>Returns the language_name object visible in game, accounting for false identities.</p>
925933
</li>
934+
<li><p class="first"><tt class="docutils literal">dfhack.units.getIdentity(unit)</tt></p>
935+
<p>Returns the false identity of the unit if it has one, or <em>nil</em>.</p>
936+
</li>
926937
<li><p class="first"><tt class="docutils literal">dfhack.units.getNemesis(unit)</tt></p>
927938
<p>Returns the nemesis record of the unit if it has one, or <em>nil</em>.</p>
928939
</li>
@@ -944,6 +955,16 @@ <h3><a class="toc-backref" href="#id16">Units module</a></h3>
944955
<li><p class="first"><tt class="docutils literal">dfhack.units.setInBurrow(unit,burrow,enable)</tt></p>
945956
<p>Adds or removes the unit from the burrow.</p>
946957
</li>
958+
<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.units.getAge(unit[,true_age])</span></tt></p>
959+
<p>Returns the age of the unit in years as a floating-point value.
960+
If <tt class="docutils literal">true_age</tt> is true, ignores false identities.</p>
961+
</li>
962+
<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.units.getProfessionName(unit[,plural])</span></tt></p>
963+
<p>Retrieves the profession name using custom profession or raws.</p>
964+
</li>
965+
<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.units.getCasteProfessionName(race,caste,prof_id[,plural])</span></tt></p>
966+
<p>Retrieves the profession name for the given race/caste using raws.</p>
967+
</li>
947968
</ul>
948969
</div>
949970
<div class="section" id="items-module">
@@ -1061,6 +1082,58 @@ <h3><a class="toc-backref" href="#id20">Event type</a></h3>
10611082
</div>
10621083
</div>
10631084
</div>
1085+
<div class="section" id="plugins">
1086+
<h1><a class="toc-backref" href="#id21">Plugins</a></h1>
1087+
<p>DFHack plugins may export native functions and events
1088+
to lua contexts. They are automatically imported by
1089+
<tt class="docutils literal"><span class="pre">mkmodule('plugins.&lt;name&gt;')</span></tt>; this means that a lua
1090+
module file is still necessary for <tt class="docutils literal">require</tt> to read.</p>
1091+
<p>The following plugins have lua support.</p>
1092+
<div class="section" id="burrows">
1093+
<h2><a class="toc-backref" href="#id22">burrows</a></h2>
1094+
<p>Implements extended burrow manipulations.</p>
1095+
<p>Events:</p>
1096+
<ul>
1097+
<li><p class="first"><tt class="docutils literal">onBurrowRename.foo = function(burrow)</tt></p>
1098+
<p>Emitted when a burrow might have been renamed either through
1099+
the game UI, or <tt class="docutils literal">renameBurrow()</tt>.</p>
1100+
</li>
1101+
<li><p class="first"><tt class="docutils literal">onDigComplete.foo = function(job_type,pos,old_tiletype,new_tiletype)</tt></p>
1102+
<p>Emitted when a tile might have been dug out. Only tracked if the
1103+
auto-growing burrows feature is enabled.</p>
1104+
</li>
1105+
</ul>
1106+
<p>Native functions:</p>
1107+
<ul>
1108+
<li><p class="first"><tt class="docutils literal">renameBurrow(burrow,name)</tt></p>
1109+
<p>Renames the burrow, emitting <tt class="docutils literal">onBurrowRename</tt> and updating auto-grow state properly.</p>
1110+
</li>
1111+
<li><p class="first"><tt class="docutils literal">findByName(burrow,name)</tt></p>
1112+
<p>Finds a burrow by name, using the same rules as the plugin command line interface.
1113+
Namely, trailing <tt class="docutils literal">'+'</tt> characters marking auto-grow burrows are ignored.</p>
1114+
</li>
1115+
<li><p class="first"><tt class="docutils literal">copyUnits(target,source,enable)</tt></p>
1116+
<p>Applies units from <tt class="docutils literal">source</tt> burrow to <tt class="docutils literal">target</tt>. The <tt class="docutils literal">enable</tt>
1117+
parameter specifies if they are to be added or removed.</p>
1118+
</li>
1119+
<li><p class="first"><tt class="docutils literal">copyTiles(target,source,enable)</tt></p>
1120+
<p>Applies tiles from <tt class="docutils literal">source</tt> burrow to <tt class="docutils literal">target</tt>. The <tt class="docutils literal">enable</tt>
1121+
parameter specifies if they are to be added or removed.</p>
1122+
</li>
1123+
<li><p class="first"><tt class="docutils literal">setTilesByKeyword(target,keyword,enable)</tt></p>
1124+
<p>Adds or removes tiles matching a predefined keyword. The keyword
1125+
set is the same as used by the command line.</p>
1126+
</li>
1127+
</ul>
1128+
<p>The lua module file also re-exports or wraps some of the
1129+
functions implemented by the dfhack core for convenience.</p>
1130+
</div>
1131+
<div class="section" id="sort">
1132+
<h2><a class="toc-backref" href="#id23">sort</a></h2>
1133+
<p>Does not export any native functions as of now. Instead, it
1134+
calls lua code to perform the actual ordering of list items.</p>
1135+
</div>
1136+
</div>
10641137
</div>
10651138
</body>
10661139
</html>

‎library/LuaApi.cpp‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,7 @@ distribution.
5858
#include "df/unit.h"
5959
#include "df/item.h"
6060
#include "df/material.h"
61+
#include "df/assumed_identity.h"
6162
#include "df/nemesis_record.h"
6263
#include "df/historical_figure.h"
6364
#include "df/plant_raw.h"
@@ -608,6 +609,7 @@ static const LuaWrapper::FunctionReg dfhack_units_module[] = {
608609
WRAPM(Units, getContainer),
609610
WRAPM(Units, setNickname),
610611
WRAPM(Units, getVisibleName),
612+
WRAPM(Units, getIdentity),
611613
WRAPM(Units, getNemesis),
612614
WRAPM(Units, isDead),
613615
WRAPM(Units, isAlive),
@@ -616,6 +618,8 @@ static const LuaWrapper::FunctionReg dfhack_units_module[] = {
616618
WRAPM(Units, isInBurrow),
617619
WRAPM(Units, setInBurrow),
618620
WRAPM(Units, getAge),
621+
WRAPM(Units, getProfessionName),
622+
WRAPM(Units, getCasteProfessionName),
619623
{ NULL, NULL }
620624
};
621625

‎library/include/modules/Translation.h‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,8 @@ DFHACK_EXPORT bool copyName(df::language_name * address, df::language_name * tar
5252

5353
DFHACK_EXPORT void setNickname(df::language_name *name, std::string nick);
5454

55+
DFHACK_EXPORT std::string capitalize(const std::string &str, bool all_words = false);
56+
5557
// translate a name using the loaded dictionaries
5658
DFHACK_EXPORT std::string TranslateName (const df::language_name * name, bool inEnglish = true,
5759
bool onlyLastPart = false);

‎library/include/modules/Units.h‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ namespace df
3737
{
3838
struct nemesis_record;
3939
struct burrow;
40+
struct assumed_identity;
4041
}
4142

4243
/**
@@ -201,6 +202,7 @@ DFHACK_EXPORT df::item *getContainer(df::unit *unit);
201202
DFHACK_EXPORT void setNickname(df::unit *unit, std::string nick);
202203
DFHACK_EXPORT df::language_name *getVisibleName(df::unit *unit);
203204

205+
DFHACK_EXPORT df::assumed_identity *getIdentity(df::unit *unit);
204206
DFHACK_EXPORT df::nemesis_record *getNemesis(df::unit *unit);
205207

206208
DFHACK_EXPORT bool isDead(df::unit *unit);
@@ -214,8 +216,10 @@ DFHACK_EXPORT void clearBurrowMembers(df::burrow *burrow);
214216
DFHACK_EXPORT bool isInBurrow(df::unit *unit, df::burrow *burrow);
215217
DFHACK_EXPORT void setInBurrow(df::unit *unit, df::burrow *burrow, bool enable);
216218

217-
DFHACK_EXPORT double getAge(df::unit *unit);
219+
DFHACK_EXPORT double getAge(df::unit *unit, bool true_age = false);
218220

221+
DFHACK_EXPORT std::string getProfessionName(df::unit *unit, bool plural = false);
222+
DFHACK_EXPORT std::string getCasteProfessionName(int race, int caste, df::profession pid, bool plural = false);
219223
}
220224
}
221225
#endif

0 commit comments

Comments
 (0)