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

update docs for zone

develop
myk002 2022-08-05 08:08:34 -07:00
parent feed91d098
commit 46c3862a08
No known key found for this signature in database
GPG Key ID: 8A39CA0FA0C16E78
2 changed files with 150 additions and 244 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

240
docs/plugins/zone.rst
Unescape Escape View File

@ -1,130 +1,158 @@
zone zone
==== ====
Helps a bit with managing activity zones (pens, pastures and pits) and cages. Tags:
:dfhack-keybind:`zone` :dfhack-keybind:`zone`
Options: Manage activity zones, cages, and the animals therein.
:set: Set zone or cage under cursor as default for future assigns. Usage:
:assign: Assign unit(s) to the pen or pit marked with the 'set' command.
If no filters are set a unit must be selected in the in-game ui. ``enable zone``
Can also be followed by a valid zone id which will be set Add helpful filters to the pen/pasture sidebar menu (e.g. show only caged
instead. grazers).
:unassign: Unassign selected creature from it's zone. ``zone set``
:nick: Mass-assign nicknames, must be followed by the name you want Set zone or cage under cursor as default for future ``assign`` or ``tocages``
to set. commands.
:remnick: Mass-remove nicknames. ``zone assign [<zone id>] [<filter>]``
:enumnick: Assign enumerated nicknames (e.g. "Hen 1", "Hen 2"...). Must be Assign unit(s) to the zone with the given ID, or to the most recent pen or
followed by the prefix to use in nicknames. pit marked with the ``set`` command. If no filters are set, then a unit must
:tocages: Assign unit(s) to cages inside a pasture.
:uinfo: Print info about unit(s). If no filters are set a unit must
be selected in the in-game ui. be selected in the in-game ui.
:zinfo: Print info about zone(s). If no filters are set zones under ``zone unassign [<filter>]``
the cursor are listed. Unassign selected creature from its zone.
:verbose: Print some more info. ``zone nick <nickname> [<filter>]``
:filters: Print list of valid filter options. Assign the given nickname to the selected animal or the animals matched by
:examples: Print some usage examples. the given filter.
:not: Negates the next filter keyword. ``zone remnick [<filter>]``
Remove nicknames from the selected animal or the animals matched by the
Filters: given filter.
``zone enumnick <nickname prefix> [<filter>]``
:all: Process all units (to be used with additional filters). Assign enumerated nicknames (e.g. "Hen 1", "Hen 2"...).
:count: Must be followed by a number. Process only n units (to be used ``zone tocages [<filter>]``
with additional filters). Assign unit(s) to cages that have been built inside the pasture selected
with the ``set`` command.
``zone uinfo [<filter>]``
Print info about unit(s). If no filters are set, then a unit must be
selected in the in-game ui.
``zone zinfo``
Print info about the zone(s) and any buildings under the cursor.
Examples
--------
Before any ``assign`` or ``tocages`` examples can be used, you must first move
the cursor over a pen/pasture or pit zone and run ``zone set`` to select the
zone.
``zone assign all own ALPACA minage 3 maxage 10``
Assign all of your alpacas who are between 3 and 10 years old to the
selected pasture.
``zone assign all own caged grazer nick ineedgrass``
Assign all of your grazers who are sitting in cages on stockpiles (e.g.
after buying them from merchants) to the selected pasture and give them the
nickname 'ineedgrass'.
``zone assign all own not grazer not race CAT``
Assign all of your animals who are not grazers (excluding cats) to the
selected pasture.
" zone assign all own milkable not grazer\n"
``zone assign all own female milkable not grazer``
Assign all of your non-grazing milkable creatures to the selected pasture or
cage.
``zone assign all own race DWARF maxage 2``
Throw all useless kids into a pit :) They'll be fine I'm sure.
``zone nick donttouchme``
Nicknames all units in the current default zone or cage to 'donttouchme'.
This is especially useful for protecting a group of animals assigned to a
pasture or cage from being "processed" by `autobutcher`.
``zone tocages count 50 own tame male not grazer``
Stuff up to 50 of your tame male animals who are not grazers into cages
built on the current default zone.
Filters
-------
:all: Process all units.
:count <n>: Process only up to n units.
:unassigned: Not assigned to zone, chain or built cage. :unassigned: Not assigned to zone, chain or built cage.
:minage: Minimum age. Must be followed by number. :minage <years>: Minimum age. Must be followed by number.
:maxage: Maximum age. Must be followed by number. :maxage <years>: Maximum age. Must be followed by number.
:not: Negates the next filter keyword. All of the keywords documented
below are negatable.
:race: Must be followed by a race RAW ID (e.g. BIRD_TURKEY, ALPACA, :race: Must be followed by a race RAW ID (e.g. BIRD_TURKEY, ALPACA,
etc). Negatable. etc).
:caged: In a built cage. Negatable. :caged: In a built cage.
:own: From own civilization. Negatable. :own: From own civilization. You'll usually want to include this
:merchant: Is a merchant / belongs to a merchant. Should only be used for filter.
pitting, not for stealing animals (slaughter should work). :war: Trained war creature.
:war: Trained war creature. Negatable. :hunting: Trained hunting creature.
:hunting: Trained hunting creature. Negatable. :tamed: Creature is tame.
:tamed: Creature is tame. Negatable.
:trained: Creature is trained. Finds war/hunting creatures as well as :trained: Creature is trained. Finds war/hunting creatures as well as
creatures who have a training level greater than 'domesticated'. creatures who have a training level greater than 'domesticated'.
If you want to specifically search for war/hunting creatures use If you want to specifically search for war/hunting creatures
'war' or 'hunting' Negatable. use ``war`` or ``hunting``.
:trainablewar: Creature can be trained for war (and is not already trained for :trainablewar: Creature can be trained for war (and is not already trained for
war/hunt). Negatable. war/hunt).
:trainablehunt: Creature can be trained for hunting (and is not already trained :trainablehunt: Creature can be trained for hunting (and is not already trained
for war/hunt). Negatable. for war/hunt).
:male: Creature is male. Negatable. :male: Creature is male.
:female: Creature is female. Negatable. :female: Creature is female.
:egglayer: Race lays eggs. Negatable. :egglayer: Race lays eggs. If you want units who actually lay eggs, also
:grazer: Race is a grazer. Negatable. specify ``female``.
:milkable: Race is milkable. Negatable. :grazer: Race is a grazer.
:milkable: Race is milkable. If you want units who actually can be milked,
also specify ``female``.
:merchant: Is a merchant / belongs to a merchant. Should only be used for
pitting or slaughtering, not for stealing animals.
Usage with single units Usage with single units
----------------------- -----------------------
One convenient way to use the zone tool is to bind the command 'zone assign' to One convenient way to use the zone tool is to bind the commands ``zone assign``
a hotkey, maybe also the command 'zone set'. Place the in-game cursor over and ``zone set`` to hotkeys. Place the in-game cursor over a pen/pasture or pit
a pen/pasture or pit, use 'zone set' to mark it. Then you can select units and use the ``zone set`` hotkey to mark it. Then you can select units on the map
on the map (in 'v' or 'k' mode), in the unit list or from inside cages (in 'v' or 'k' mode), in the unit list or from inside cages and use the
and use 'zone assign' to assign them to their new home. Allows pitting your ``zone assign`` hotkey to assign them to their new home. Allows pitting your own
own dwarves, by the way. dwarves, by the way.
Usage with filters Matching with filters
------------------ ---------------------
All filters can be used together with the 'assign' command. All filters can be used together with the ``assign`` and ``tocages`` commands.
Restrictions: It's not possible to assign units who are inside built cages Note that it's not possible to reassign units who are inside built cages or
or chained because in most cases that won't be desirable anyways. chained, though this likely won't matter because if you have gone to the trouble
It's not possible to cage owned pets because in that case the owner of creating a zoo or chaining a creature, you probably wouldn't want them
reassigned anyways. Also, ``zone`` will avoid caging owned pets because the owner
uncages them after a while which results in infinite hauling back and forth. uncages them after a while which results in infinite hauling back and forth.
Usually you should always use the filter 'own' (which implies tame) unless you Most filters should include an ``own`` element (which implies ``tame``) unless
want to use the zone tool for pitting hostiles. 'own' ignores own dwarves unless you want to use ``zone assign`` for pitting hostiles. The ``own`` filter ignores
you specify 'race DWARF' (so it's safe to use 'assign all own' to one big dwarves unless you explicitly specify ``race DWARF`` (so it's safe to use
pasture if you want to have all your animals at the same place). 'egglayer' and ``assign all own`` to one big pasture if you want to have all your animals in
'milkable' should be used together with 'female' unless you have a mod with the same place).
egg-laying male elves who give milk or whatever. Merchants and their animals are
ignored unless you specify 'merchant' (pitting them should be no problem, The ``egglayer`` and ``milkable`` filters should be used together with
but stealing and pasturing their animals is not a good idea since currently they ``female`` unless you want the males of the race included. Merchants and their
are not properly added to your own stocks; slaughtering them should work). animals are ignored unless you specify ``merchant`` (pitting them should be no
problem, but stealing and pasturing their animals is not a good idea since
currently they are not properly added to your own stocks; slaughtering them
should work).
Most filters can be negated (e.g. 'not grazer' -> race is not a grazer). Most filters can be negated (e.g. ``not grazer`` -> race is not a grazer).
Mass-renaming Mass-renaming
------------- -------------
Using the 'nick' command you can set the same nickname for multiple units.
If used without 'assign', 'all' or 'count' it will rename all units in the Using the ``nick`` command, you can set the same nickname for multiple units.
current default target zone. Combined with 'assign', 'all' or 'count' (and If used without ``assign``, ``all``, or ``count``, it will rename all units in
further optional filters) it will rename units matching the filter conditions. the current default target zone. Combined with ``assign``, ``all``, or ``count``
(and likely further optional filters) it will rename units matching the filter
conditions.
Cage zones Cage zones
---------- ----------
Using the 'tocages' command you can assign units to a set of cages, for example
a room next to your butcher shop(s). They will be spread evenly among available
cages to optimize hauling to and butchering from them. For this to work you need
to build cages and then place one pen/pasture activity zone above them, covering
all cages you want to use. Then use 'zone set' (like with 'assign') and use
'zone tocages filter1 filter2 ...'. 'tocages' overwrites 'assign' because it
would make no sense, but can be used together with 'nick' or 'remnick' and all
the usual filters.
Examples The ``tocages`` command assigns units to a set of cages, for example a room next
-------- to your butcher shop(s). Units will be spread evenly among available cages to
``zone assign all own ALPACA minage 3 maxage 10`` optimize hauling to and butchering from them. For this to work you need to build
Assign all own alpacas who are between 3 and 10 years old to the selected cages and then place one pen/pasture activity zone above them, covering all
pasture. cages you want to use. Then use ``zone set`` (like with ``assign``) and run
``zone assign all own caged grazer nick ineedgrass`` ``zone tocages <filter>``. ``tocages`` can be used together with ``nick`` or
Assign all own grazers who are sitting in cages on stockpiles (e.g. after ``remnick`` to adjust nicknames while assigning to cages.
buying them from merchants) to the selected pasture and give them
the nickname 'ineedgrass'.
``zone assign all own not grazer not race CAT``
Assign all own animals who are not grazers, excluding cats.
``zone assign count 5 own female milkable``
Assign up to 5 own female milkable creatures to the selected pasture.
``zone assign all own race DWARF maxage 2``
Throw all useless kids into a pit :)
``zone nick donttouchme``
Nicknames all units in the current default zone or cage to 'donttouchme'.
Mostly intended to be used for special pastures or cages which are not marked
as rooms you want to protect from autobutcher.
``zone tocages count 50 own tame male not grazer``
Stuff up to 50 owned tame male animals who are not grazers into cages built
on the current default zone.

140
plugins/zone.cpp
Unescape Escape View File

@ -66,105 +66,6 @@ REQUIRE_GLOBAL(ui_building_in_assign);
REQUIRE_GLOBAL(ui_menu_width); REQUIRE_GLOBAL(ui_menu_width);
REQUIRE_GLOBAL(world); REQUIRE_GLOBAL(world);
static command_result df_zone (color_ostream &out, vector <string> & parameters);
const string zone_help =
"Allows easier management of pens/pastures, pits and cages.\n"
"Commands:\n"
" help - print this help message\n"
" filters - print list of supported filters\n"
" examples - print some usage examples\n"
" set - set zone under cursor as default for future assigns\n"
" assign - assign creature(s) to a pen or pit\n"
" if no filters are used, a single unit must be selected.\n"
" can be followed by valid building id which will then be set.\n"
" building must be a pen/pasture, pit or cage.\n"
" slaughter - mark creature(s) for slaughter\n"
" if no filters are used, a single unit must be selected.\n"
" with filters named units are ignored unless specified.\n"
" unassign - unassign selected creature(s) from zone or cage\n"
" nick - give unit(s) nicknames (e.g. all units in a cage)\n"
" enumnick - give unit(s) enumerated nicknames (e.g Hen 1, Hen 2)\n"
" remnick - remove nicknames\n"
" tocages - assign to (multiple) built cages inside a pen/pasture\n"
" spreads creatures evenly among cages for faster hauling.\n"
" uinfo - print info about selected units\n"
" zinfo - print info about zone(s) under cursor\n"
"Options:\n"
" verbose - print some more info, mostly useless debug stuff\n"
;
const string zone_help_filters =
"Filters (to be used in combination with 'all' or 'count'):\n"
"Required (one of):\n"
" all - process all units\n"
" should be used in combination with further filters\n"
" count - must be followed by number. process X units\n"
" should be used in combination with further filters\n"
"Others (may be used with 'not' prefix):\n"
" age - exact age. must be followed by number\n"
" caged - in a built cage\n"
" egglayer - race lays eggs (use together with 'female')\n"
" female - obvious\n"
" grazer - is a grazer\n"
" male - obvious\n"
" maxage - maximum age. must be followed by number\n"
" merchant - is a merchant / belongs to a merchant\n"
" can be used to pit merchants and slaughter their animals\n"
" (could have weird effects during trading, be careful)\n"
" ('not merchant' is set by default)\n"
" milkable - race is milkable (use together with 'female')\n"
" minage - minimum age. must be followed by number\n"
" named - has name or nickname\n"
" ('not named' is set by default when using the 'slaughter' command)\n"
" own - from own civilization\n"
" race - must be followed by a race raw id (e.g. BIRD_TURKEY)\n"
" tame - tamed\n"
" trainablehunt- can be trained for hunting (and is not already trained)\n"
" trainablewar - can be trained for war (and is not already trained)\n"
" trained - obvious\n"
" unassigned - not assigned to zone, chain or built cage\n"
" war - trained war creature\n"
;
const string zone_help_examples =
"Example for assigning single units:\n"
" (ingame) move cursor to a pen/pasture or pit zone\n"
" (dfhack) 'zone set' to use this zone for future assignments\n"
" (dfhack) map 'zone assign' to a hotkey of your choice\n"
" (ingame) select unit with 'v', 'k' or from unit list or inside a cage\n"
" (ingame) press hotkey to assign unit to it's new home (or pit)\n"
"Examples for assigning with filters:\n"
" (this assumes you have already set up a target zone)\n"
" zone assign all own grazer maxage 10\n"
" zone assign all own milkable not grazer\n"
" zone assign count 5 own female milkable\n"
" zone assign all own race DWARF maxage 2\n"
" throw all useless kids into a pit :)\n"
"Notes:\n"
" Unassigning per filters ignores built cages and chains currently. Usually you\n"
" should always use the filter 'own' (which implies tame) unless you want to\n"
" use the zone tool for pitting hostiles. 'own' ignores own dwarves unless you\n"
" specify 'race DWARF' and it ignores merchants and their animals unless you\n"
" specify 'merchant' (so it's safe to use 'assign all own' to one big pasture\n"
" if you want to have all your animals at the same place).\n"
" 'egglayer' and 'milkable' should be used together with 'female'\n"
" well, unless you have a mod with egg-laying male elves who give milk...\n";
///////////////
// Various small tool functions
// probably many of these should be moved to Unit.h and Building.h sometime later...
// static df::general_ref_building_civzone_assignedst * createCivzoneRef();
// static bool unassignUnitFromBuilding(df::unit* unit);
// static command_result assignUnitToZone(color_ostream& out, df::unit* unit, df::building* building, bool verbose);
// static void unitInfo(color_ostream & out, df::unit* creature, bool verbose);
// static void zoneInfo(color_ostream & out, df::building* building, bool verbose);
// static void cageInfo(color_ostream & out, df::building* building, bool verbose);
// static void chainInfo(color_ostream & out, df::building* building, bool verbose);
static bool isInBuiltCageRoom(df::unit*);
static void doMarkForSlaughter(df::unit* unit) static void doMarkForSlaughter(df::unit* unit)
{ {
unit->flags2.bits.slaughter = 1; unit->flags2.bits.slaughter = 1;
@ -184,6 +85,8 @@ static bool hasValidMapPos(df::unit* unit)
return false; return false;
} }
static bool isInBuiltCageRoom(df::unit*);
// dump some unit info // dump some unit info
static void unitInfo(color_ostream & out, df::unit* unit, bool verbose = false) static void unitInfo(color_ostream & out, df::unit* unit, bool verbose = false)
{ {
@ -1127,8 +1030,7 @@ static struct zone_param_filters_init { zone_param_filters_init() {
zone_param_filters["maxage"] = make_pair(1, createMaxAgeFilter); zone_param_filters["maxage"] = make_pair(1, createMaxAgeFilter);
}} zone_param_filters_init_; }} zone_param_filters_init_;
static command_result df_zone (color_ostream &out, vector <string> & parameters) static command_result df_zone(color_ostream &out, vector <string> & parameters) {
{
CoreSuspender suspend; CoreSuspender suspend;
if (!Maps::IsValid()) if (!Maps::IsValid())
@ -1160,18 +1062,7 @@ static command_result df_zone (color_ostream &out, vector <string> & parameters)
if (p0 == "help" || p0 == "?") if (p0 == "help" || p0 == "?")
{ {
out << zone_help << endl; return CR_WRONG_USAGE;
return CR_OK;
}
if (p0 == "filters")
{
out << zone_help_filters << endl;
return CR_OK;
}
if (p0 == "examples")
{
out << zone_help_examples << endl;
return CR_OK;
} }
else if(p0 == "zinfo") else if(p0 == "zinfo")
{ {
@ -2275,13 +2166,8 @@ IMPLEMENT_VMETHOD_INTERPOSE(zone_hook, feed);
IMPLEMENT_VMETHOD_INTERPOSE(zone_hook, render); IMPLEMENT_VMETHOD_INTERPOSE(zone_hook, render);
//END zone filters //END zone filters
DFhackCExport command_result plugin_enable ( color_ostream &out, bool enable) DFhackCExport command_result plugin_enable(color_ostream &out, bool enable) {
{ if (enable != is_enabled) {
if (!gps)
return CR_FAILURE;
if (enable != is_enabled)
{
if (!INTERPOSE_HOOK(zone_hook, feed).apply(enable) || if (!INTERPOSE_HOOK(zone_hook, feed).apply(enable) ||
!INTERPOSE_HOOK(zone_hook, render).apply(enable)) !INTERPOSE_HOOK(zone_hook, render).apply(enable))
return CR_FAILURE; return CR_FAILURE;
@ -2292,18 +2178,10 @@ DFhackCExport command_result plugin_enable ( color_ostream &out, bool enable)
return CR_OK; return CR_OK;
} }
DFhackCExport command_result plugin_init ( color_ostream &out, std::vector <PluginCommand> &commands) DFhackCExport command_result plugin_init(color_ostream &out, std::vector <PluginCommand> &commands) {
{
commands.push_back(PluginCommand( commands.push_back(PluginCommand(
"zone", "zone",
"manage activity zones.", "Manage activity zones.",
df_zone, df_zone));
false,
zone_help.c_str()));
return CR_OK;
}
DFhackCExport command_result plugin_shutdown ( color_ostream &out )
{
return CR_OK; return CR_OK;
} }