diff --git a/docs/plugins/forceequip.rst b/docs/plugins/forceequip.rst index 2278bca22..2b8a55905 100644 --- a/docs/plugins/forceequip.rst +++ b/docs/plugins/forceequip.rst @@ -1,7 +1,100 @@ forceequip ========== -Forceequip moves local items into a unit's inventory. It is typically used to -equip specific clothing/armor items onto a dwarf, but can also be used to put -armor onto a war animal or to add unusual items (such as crowns) to any unit. +Tags: +:dfhack-keybind:`forceequip` -For more information run ``forceequip help``. See also `modtools/equip-item`. +Move items into a unit's inventory. This tool is typically used to equip +specific clothing/armor items onto a dwarf, but can also be used to put armor +onto a war animal or to add unusual items (such as crowns) to any unit. Make +sure the unit you want to equip is standing on the target items, which must be +on the ground and be unforbidden. If multiple units are standing on the same +tile, the first one will be equipped. + +The most reliable way to set up the environment for this command is to pile +target items on a tile of floor with a garbage dump activity zone or the +`autodump` command, then walk/pasture a unit (or use `gui/teleport`) on top of +the items. Be sure to unforbid the items that you want to work with! + +.. note:: + + Weapons are not currently supported. + +Usage:: + + forceequip [] + +As mentioned above, this plugin can be used to equip items onto units (such as +animals) who cannot normally equip gear. There's an important caveat here: such +creatures will automatically drop inappropriate gear almost immediately (within +10 game ticks). If you want them to retain their equipment, you must forbid it +AFTER using forceequip to get it into their inventory. This technique can also +be used to clothe dwarven infants, but only if you're able to separate them from +their mothers. + +By default, the ``forceequip`` command will attempt to abide by game rules as +closely as possible. For instance, it will skip any item which is flagged for +use in a job, and will not equip more than one piece of clothing/armor onto any +given body part. These restrictions can be overridden via options, but doing so +puts you at greater risk of unexpected consequences. For instance, a dwarf who +is wearing three breastplates will not be able to move very quickly. + +Items equipped by this plugin DO NOT become owned by the recipient. Adult +dwarves are free to adjust their own wardrobe, and may promptly decide to doff +your gear in favour of their owned items. Animals, as described above, will tend +to discard ALL clothing immediately unless it is manually forbidden. Armor items +seem to be an exception: an animal will tend to retain an equipped suit of mail" + even if you neglect to forbid it. + +Please note that armored animals are quite vulnerable to ranged attacks. Unlike +dwarves, animals cannot block, dodge, or deflect arrows, and they are slowed by +the weight of their armor. + +Examples +-------- + +``forceequip`` + Attempts to equip all of the clothing and armor under the cursor onto the + unit under the cursor, following game rules regarding which item can be + equipped on which body part and only equipping 1 item onto each body part. + Items owned by other dwarves are ignored. +``forceequip v bp QQQ`` + List the bodyparts of the selected unit. +``forceequip bp LH`` + Equips an appopriate item onto the unit's left hand. +``forceequip m bp LH`` + Equips ALL appropriate items onto the unit's left hand. The unit may end up + wearing a dozen left-handed mittens. Use with caution, and remember that + dwarves tend to drop extra items ASAP. +``forceequip i bp NECK`` + Equips an item around the unit's neck, ignoring appropriateness + restrictions. If there's a millstone or an albatross carcass sitting on the + same square as the targeted unit, then there's a good chance that it will + end up around his neck. For precise control, remember that you can + selectively forbid some of the items that are piled on the ground. +``forceequip s`` + Equips the item currently selected in the k menu, if possible. +``forceequip s m i bp HD`` + Equips the selected item onto the unit's head. Ignores all restrictions and + conflicts. If you know exactly what you want to equip, and exactly where you + want it to go, then this is the most straightforward and reliable option. + +Options +------- + +``i``, ``ignore`` + Bypasses the usual item eligibility checks (such as "Never equip gear + belonging to another dwarf" and "Nobody is allowed to equip a Hive". +``m``, ``multi`` + Bypasses the 1-item-per-bodypart limit. Useful for equipping both a mitten + and a gauntlet on the same hand (or twelve breastplates on the upper body). +``m2``, ``m3``, ``m4`` + Modifies the 1-item-per-bodypart limit, allowing each part to receive 2, 3, + or 4 pieces of gear. +``s``, ``selected`` + Equip only the item currently selected in the k menu and ignore all other + items in the tile. +``bp``, ``bodypart `` + Specify which body part should be equipped. +``v``, ``verbose`` + Provide detailed narration and error messages, including listing available + body parts when an invalid ``bodypart`` code is specified. diff --git a/plugins/forceequip.cpp b/plugins/forceequip.cpp index ab39bb0d6..10a157608 100644 --- a/plugins/forceequip.cpp +++ b/plugins/forceequip.cpp @@ -55,171 +55,12 @@ const int const_GloveLeftHandedness = 2; command_result df_forceequip(color_ostream &out, vector & parameters); -const string forceequip_help = - "ForceEquip moves local items into a unit's inventory. It is typically\n" - "used to equip specific clothing/armor items onto a dwarf, but can also\n" - "be used to put armor onto a war animal or to add unusual items (such\n" - "as crowns) to any unit.\n" - "This plugin can process multiple items in a single call, but will only\n" - "work with a single unit (the first one it finds under the cursor).\n" - "In order to minimize confusion, it is recommended that you use\n" - "forceequip only when you have a unit standing alone atop a pile of\n" - "gear that you would like it to wear. Items which are stored in bins\n" - "or other containers (e.g. chests, armor racks) may also work, but\n" - "piling items on the floor (via a garbage dump activity zone, of the\n" - "DFHack autodump command) is the most reliable way to do it.\n" - "The plugin will ignore any items that are forbidden. Hence, you\n" - "can setup a large pile of surplus gear, walk a unit onto it (or\n" - "pasture an animal on it), unforbid a few items and run forceequip.\n" - "The (forbidden) majority of your gear will remain in-place, ready\n" - "for the next passerby." - "\n" - "As mentioned above, this plugin can be used to equip items onto\n" - "units (such as animals) which cannot normally equip gear. There's\n" - "an important caveat here - such creatures will automatically drop\n" - "inappropriate gear almost immediately (within 10 game ticks).\n" - "If you want them to retain their equipment, you must forbid it\n" - "AFTER using forceequip to get it into their inventory.\n" - "This technique can also be used to clothe dwarven infants, but\n" - "only if you're able to separate them from their mothers.\n" - "\n" - "By default, the forceequip plugin will attempt to avoid\n" - "conflicts and outright cheating. For instance, it will skip\n" - "any item which is flagged for use in a job, and will not\n" - "equip more than one piece of clothing/armor onto any given\n" - "body part. These restrictions can be overridden via command\n" - "switches (see examples below) but doing so puts you at greater\n" - "risk of unexpected consequences. For instance, a dwarf who\n" - "is wearing three breastplates will not be able to move very\n" - "quickly.\n" - "\n" - "Items equipped by this plugin DO NOT become owned by the\n" - "recipient. Adult dwarves are free to adjust their own\n" - "wardrobe, and may promptly decide to doff your gear in\n" - "favour of their owned items. Animals, as described above,\n" - "will tend to discard ALL clothing immediately unless it is\n" - "manually forbidden. Armor items seem to be an exception;\n" - "an animal will tend to retain an equipped suit of mail\n" - "even if you neglect to Forbid it.\n" - "\n" - "Please note that armored animals are quite vulnerable to ranged\n" - "attacks. Unlike dwarves, animals cannot block, dodge, or deflect\n" - "arrows, and they are slowed by the weight of their armor.\n" - "\n" - "This plugin currently does not support weapons.\n" - "\n" - "Options:\n" - " here, h - process the unit and item(s) under the cursor.\n" - " - This option is enabled by default since the plugin\n" - " - does not currently support remote equpping.\n" - " ignore, i - bypasses the usual item eligibility checks (such as\n" - " - \"Never equip gear belonging to another dwarf\" and\n" - " - \"Nobody is allowed to equip a Hive\".)\n" - " multi, m - bypasses the 1-item-per-bodypart limit, allowing\n" - " - the unit to receive an unlimited amount of gear.\n" - " - Can be used legitimately (e.g. mitten + gauntlet)\n" - " - or for cheating (e.g. twelve breastplates).\n" - " m2, m3, m4 - alters the 1-item-per-bodypart limit, allowing\n" - " - each part to receive 2, 3, or 4 pieces of gear.\n" - " selected, s - rather than processing all items piled at a unit's\n" - " - feet, process only the one item currently selected.\n" - " bodypart, bp - must be followed by a bodypart code (e.g. LH).\n" - " - Instructs the plugin to equip all available items\n" - " - onto this body part only. Typically used in\n" - " - conjunction with the f switch (to over-armor\n" - " - a particular bodypart) or the i switch (to equip\n" - " - an unusual item onto a specific slot).\n" - " verbose, v - provides detailed narration and error messages.\n" - " - Can be helpful in resolving failures; not needed\n" - " - for casual use.\n" - "\n" - "Examples:\n" - " forceequip\n" - " attempts to equip all of the items under the cursor onto the unit\n" - " under the cursor. Uses only clothing/armor items; ignores all\n" - " other types. Equips a maximum of 1 item onto each bodypart,\n" - " and equips only \"appropriate\" items in each slot (e.g. glove\n" - " --> hand). Bypasses any item which might cause a conflict,\n" - " such as a Boot belonging to a different dwarf.\n" - " forceequip bp LH\n" - " attempts to equip all local items onto the left hand of the local\n" - " unit. If the hand is already equipped then nothing will happen,\n" - " and if it is not equipped then only one appropriate item (e.g. \n" - " a single mitten or gauntlet) will be equipped. This command can\n" - " be useful if you don't want to selectively forbid individual items\n" - " and simply want the unit to equip, say, a Helmet while leaving\n" - " the rest of the pile alone.\n" - " forceequip m bp LH\n" - " as above, but will equip ALL appropriate items onto the unit's\n" - " left hand. After running this command, it might end up wearing\n" - " a dozen left-handed mittens. Use with caution, and remember\n" - " that dwarves will tend to drop supernumary items ASAP.\n" - " forceequip m\n" - " as above, but will equip ALL appropriate items onto any\n" - " appropriate bodypart. Tends to put several boots onto the right\n" - " foot while leaving the left foot bare.\n" - " forceequip m2\n" - " as above, but will equip up to two appropriate items onto each\n" - " bodypart. Helps to balance footwear, but doesn't ensure proper\n" - " placement (e.g. left foot gets two socks, right foot gets two\n" - " shoes). For best results, use \"selected bp LH\" and\n" - " \"selected bp RH\" instead.\n" - " forceequip i\n" - " performs the standard \"equip appropriate items onto appropriate\n" - " bodyparts\" logic, but also includes items that would normally\n" - " be considered ineligible (such as a sock which is owned by\n" - " a different dwarf).\n" - " forceequip bp NECK\n" - " attempts to equip any appropriate gear onto the Neck of the\n" - " local unit. Since the plugin believes that no items are actually\n" - " appropriate for the Neck slot, this command does nothing.\n" - " forceequip i bp NECK\n" - " attempts to equip items from the local pile onto the Neck\n" - " of the local unit. Ignores appropriateness restrictions.\n" - " If there's a millstone or an albatross carcass sitting on\n" - " the same square as the targeted unit, then there's a good\n" - " chance that it will end up around his neck. For precise\n" - " control, remember that you can selectively forbid some of\n" - " the items that are piled on the ground.\n" - " forceequip i m bp NECK\n" - " as above, but equips an unlimited number of items onto the\n" - " targeted bodypart. Effectively, all unforbidden items\n" - " (including helms, millstones, boulders, etc) will be\n" - " moved from the local pile and placed in the dwarf's\n" - " inventory (specifically, on his neck). When used with\n" - " a large pile of goods, this will leave the dwarf heavily\n" - " encumbered and very slow to move.\n" - " forceequip s\n" - " requires that a single item be selected using the k menu.\n" - " This item must occupy the same square as the target unit,\n" - " and must be unforbidden. Attempts to equip this single\n" - " item onto an appropriate slot in the unit's inventory.\n" - " Can serve as a quicker alternative to the selective-\n" - " unforbidding approach described above.\n" - " forceequip s m i bp HD\n" - " equips the selected item onto the unit's head. Ignores\n" - " all possible restrictions and conflicts. If you know\n" - " exactly what you want to equip, and exactly where you\n" - " want it to go, then this is the most straightforward\n" - " and reliable option.\n" - " forceequip v bp QQQ\n" - " guaranteed to fail (and accomplish nothing) because\n" - " there are no bodyparts called QQQ. However, since the\n" - " verbose switch is used, the resulting error messages\n" - " will list every bodypart that the unit DOES possess.\n" - " May be useful if you're unfamiliar with the BP codes\n" - " used by Dwarf Fortress, or if you're experimenting\n" - " with an exotic creature.\n" - "\n" - ; - DFhackCExport command_result plugin_init ( color_ostream &out, vector &commands) { commands.push_back(PluginCommand( - "forceequip", "Move items from the ground into a unit's inventory", - df_forceequip, false, - forceequip_help.c_str() - )); + "forceequip", + "Move items into a unit's inventory.", + df_forceequip)); return CR_OK; }