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

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

@ -1,130 +1,158 @@
zone
====
Helps a bit with managing activity zones (pens, pastures and pits) and cages.
Tags:
:dfhack-keybind:`zone`
Options:
:set: Set zone or cage under cursor as default for future assigns.
: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.
Can also be followed by a valid zone id which will be set
instead.
:unassign: Unassign selected creature from it's zone.
:nick: Mass-assign nicknames, must be followed by the name you want
to set.
:remnick: Mass-remove nicknames.
:enumnick: Assign enumerated nicknames (e.g. "Hen 1", "Hen 2"...). Must be
followed by the prefix to use in nicknames.
: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.
:zinfo: Print info about zone(s). If no filters are set zones under
the cursor are listed.
:verbose: Print some more info.
:filters: Print list of valid filter options.
:examples: Print some usage examples.
:not: Negates the next filter keyword.
Filters:
:all: Process all units (to be used with additional filters).
:count: Must be followed by a number. Process only n units (to be used
with additional filters).
:unassigned: Not assigned to zone, chain or built cage.
:minage: Minimum age. Must be followed by number.
:maxage: Maximum age. Must be followed by number.
:race: Must be followed by a race RAW ID (e.g. BIRD_TURKEY, ALPACA,
etc). Negatable.
:caged: In a built cage. Negatable.
:own: From own civilization. Negatable.
:merchant: Is a merchant / belongs to a merchant. Should only be used for
pitting, not for stealing animals (slaughter should work).
:war: Trained war creature. Negatable.
:hunting: Trained hunting creature. Negatable.
:tamed: Creature is tame. Negatable.
:trained: Creature is trained. Finds war/hunting creatures as well as
creatures who have a training level greater than 'domesticated'.
If you want to specifically search for war/hunting creatures use
'war' or 'hunting' Negatable.
:trainablewar: Creature can be trained for war (and is not already trained for
war/hunt). Negatable.
:trainablehunt: Creature can be trained for hunting (and is not already trained
for war/hunt). Negatable.
:male: Creature is male. Negatable.
:female: Creature is female. Negatable.
:egglayer: Race lays eggs. Negatable.
:grazer: Race is a grazer. Negatable.
:milkable: Race is milkable. Negatable.
Manage activity zones, cages, and the animals therein.
Usage:
``enable zone``
Add helpful filters to the pen/pasture sidebar menu (e.g. show only caged
grazers).
``zone set``
Set zone or cage under cursor as default for future ``assign`` or ``tocages``
commands.
``zone assign [<zone id>] [<filter>]``
Assign unit(s) to the zone with the given ID, or to the most recent pen or
pit marked with the ``set`` command. If no filters are set, then a unit must
be selected in the in-game ui.
``zone unassign [<filter>]``
Unassign selected creature from its zone.
``zone nick <nickname> [<filter>]``
Assign the given nickname to the selected animal or the animals matched by
the given filter.
``zone remnick [<filter>]``
Remove nicknames from the selected animal or the animals matched by the
given filter.
``zone enumnick <nickname prefix> [<filter>]``
Assign enumerated nicknames (e.g. "Hen 1", "Hen 2"...).
``zone tocages [<filter>]``
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.
:minage <years>: Minimum 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,
etc).
:caged: In a built cage.
:own: From own civilization. You'll usually want to include this
filter.
:war: Trained war creature.
:hunting: Trained hunting creature.
:tamed: Creature is tame.
:trained: Creature is trained. Finds war/hunting creatures as well as
creatures who have a training level greater than 'domesticated'.
If you want to specifically search for war/hunting creatures
use ``war`` or ``hunting``.
:trainablewar: Creature can be trained for war (and is not already trained for
war/hunt).
:trainablehunt: Creature can be trained for hunting (and is not already trained
for war/hunt).
:male: Creature is male.
:female: Creature is female.
:egglayer: Race lays eggs. If you want units who actually lay eggs, also
specify ``female``.
: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
-----------------------
One convenient way to use the zone tool is to bind the command 'zone assign' to
a hotkey, maybe also the command 'zone set'. Place the in-game cursor over
a pen/pasture or pit, use 'zone set' to mark it. Then you can select units
on the map (in 'v' or 'k' mode), in the unit list or from inside cages
and use 'zone assign' to assign them to their new home. Allows pitting your
own dwarves, by the way.
Usage with filters
------------------
All filters can be used together with the 'assign' command.
Restrictions: It's not possible to assign units who are inside built cages
or chained because in most cases that won't be desirable anyways.
It's not possible to cage owned pets because in that case the owner
One convenient way to use the zone tool is to bind the commands ``zone assign``
and ``zone set`` to hotkeys. Place the in-game cursor over a pen/pasture or pit
and use the ``zone set`` hotkey to mark it. Then you can select units on the map
(in 'v' or 'k' mode), in the unit list or from inside cages and use the
``zone assign`` hotkey to assign them to their new home. Allows pitting your own
dwarves, by the way.
Matching with filters
---------------------
All filters can be used together with the ``assign`` and ``tocages`` commands.
Note that it's not possible to reassign units who are inside built cages or
chained, though this likely won't matter because if you have gone to the trouble
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.
Usually you should always use the filter 'own' (which implies tame) unless you
want to use the zone tool for pitting hostiles. 'own' ignores own dwarves unless
you specify 'race DWARF' (so it's safe to use 'assign all own' to one big
pasture if you want to have all your animals at the same place). 'egglayer' and
'milkable' should be used together with 'female' unless you have a mod with
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,
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 should include an ``own`` element (which implies ``tame``) unless
you want to use ``zone assign`` for pitting hostiles. The ``own`` filter ignores
dwarves unless you explicitly specify ``race DWARF`` (so it's safe to use
``assign all own`` to one big pasture if you want to have all your animals in
the same place).
Most filters can be negated (e.g. 'not grazer' -> race is not a grazer).
The ``egglayer`` and ``milkable`` filters should be used together with
``female`` unless you want the males of the race included. Merchants and their
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).
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
current default target zone. Combined with 'assign', 'all' or 'count' (and
further optional filters) it will rename units matching the filter conditions.
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 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
----------
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
--------
``zone assign all own ALPACA minage 3 maxage 10``
Assign all own alpacas who are between 3 and 10 years old to the selected
pasture.
``zone assign all own caged grazer nick ineedgrass``
Assign all own 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 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.
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
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 run
``zone tocages <filter>``. ``tocages`` can be used together with ``nick`` or
``remnick`` to adjust nicknames while assigning to cages.

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(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)
{
unit->flags2.bits.slaughter = 1;
@ -184,6 +85,8 @@ static bool hasValidMapPos(df::unit* unit)
return false;
}
static bool isInBuiltCageRoom(df::unit*);
// dump some unit info
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_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;
if (!Maps::IsValid())
@ -1160,18 +1062,7 @@ static command_result df_zone (color_ostream &out, vector <string> & parameters)
if (p0 == "help" || p0 == "?")
{
out << zone_help << endl;
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;
return CR_WRONG_USAGE;
}
else if(p0 == "zinfo")
{
@ -2275,13 +2166,8 @@ IMPLEMENT_VMETHOD_INTERPOSE(zone_hook, feed);
IMPLEMENT_VMETHOD_INTERPOSE(zone_hook, render);
//END zone filters
DFhackCExport command_result plugin_enable ( color_ostream &out, bool enable)
{
if (!gps)
return CR_FAILURE;
if (enable != is_enabled)
{
DFhackCExport command_result plugin_enable(color_ostream &out, bool enable) {
if (enable != is_enabled) {
if (!INTERPOSE_HOOK(zone_hook, feed).apply(enable) ||
!INTERPOSE_HOOK(zone_hook, render).apply(enable))
return CR_FAILURE;
@ -2292,18 +2178,10 @@ DFhackCExport command_result plugin_enable ( color_ostream &out, bool enable)
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(
"zone",
"manage activity zones.",
df_zone,
false,
zone_help.c_str()));
return CR_OK;
}
DFhackCExport command_result plugin_shutdown ( color_ostream &out )
{
"Manage activity zones.",
df_zone));
return CR_OK;
}