diff --git a/docs/plugins/zone.rst b/docs/plugins/zone.rst index a3112c147..5e01a12ac 100644 --- a/docs/plugins/zone.rst +++ b/docs/plugins/zone.rst @@ -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 [] []`` + 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 []`` + Unassign selected creature from its zone. +``zone nick []`` + Assign the given nickname to the selected animal or the animals matched by + the given filter. +``zone remnick []`` + Remove nicknames from the selected animal or the animals matched by the + given filter. +``zone enumnick []`` + Assign enumerated nicknames (e.g. "Hen 1", "Hen 2"...). +``zone tocages []`` + Assign unit(s) to cages that have been built inside the pasture selected + with the ``set`` command. +``zone uinfo []`` + 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 : Process only up to n units. +: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. +: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 ``. ``tocages`` can be used together with ``nick`` or +``remnick`` to adjust nicknames while assigning to cages. diff --git a/plugins/zone.cpp b/plugins/zone.cpp index 60f1f2b61..a3a0f2431 100644 --- a/plugins/zone.cpp +++ b/plugins/zone.cpp @@ -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 & 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 & parameters) -{ +static command_result df_zone(color_ostream &out, vector & parameters) { CoreSuspender suspend; if (!Maps::IsValid()) @@ -1160,18 +1062,7 @@ static command_result df_zone (color_ostream &out, vector & 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 &commands) -{ +DFhackCExport command_result plugin_init(color_ostream &out, std::vector &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; }