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

update docs for forceequip

develop
myk002 2022-07-25 16:40:19 -07:00
parent 82953d8b2f
commit eb0f016804
No known key found for this signature in database
GPG Key ID: 8A39CA0FA0C16E78
2 changed files with 100 additions and 166 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

101
docs/plugins/forceequip.rst
Unescape Escape View File

@ -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 [<options>]
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 <body part code>``
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.

165
plugins/forceequip.cpp
Unescape Escape View File

@ -55,171 +55,12 @@ const int const_GloveLeftHandedness = 2;
command_result df_forceequip(color_ostream &out, vector <string> & 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 <PluginCommand> &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;
}