Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit eb0f016

Browse files
myk002myk002
committed
update docs for forceequip
1 parent 82953d8 commit eb0f016

2 files changed

Lines changed: 100 additions & 166 deletions

File tree

‎docs/plugins/forceequip.rst‎

Lines changed: 97 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,100 @@
11
forceequip
22
==========
3-
Forceequip moves local items into a unit's inventory. It is typically used to
4-
equip specific clothing/armor items onto a dwarf, but can also be used to put
5-
armor onto a war animal or to add unusual items (such as crowns) to any unit.
3+
Tags:
4+
:dfhack-keybind:`forceequip`
65

7-
For more information run ``forceequip help``. See also `modtools/equip-item`.
6+
Move items into a unit's inventory. This tool is typically used to equip
7+
specific clothing/armor items onto a dwarf, but can also be used to put armor
8+
onto a war animal or to add unusual items (such as crowns) to any unit. Make
9+
sure the unit you want to equip is standing on the target items, which must be
10+
on the ground and be unforbidden. If multiple units are standing on the same
11+
tile, the first one will be equipped.
12+
13+
The most reliable way to set up the environment for this command is to pile
14+
target items on a tile of floor with a garbage dump activity zone or the
15+
`autodump` command, then walk/pasture a unit (or use `gui/teleport`) on top of
16+
the items. Be sure to unforbid the items that you want to work with!
17+
18+
.. note::
19+
20+
Weapons are not currently supported.
21+
22+
Usage::
23+
24+
forceequip [<options>]
25+
26+
As mentioned above, this plugin can be used to equip items onto units (such as
27+
animals) who cannot normally equip gear. There's an important caveat here: such
28+
creatures will automatically drop inappropriate gear almost immediately (within
29+
10 game ticks). If you want them to retain their equipment, you must forbid it
30+
AFTER using forceequip to get it into their inventory. This technique can also
31+
be used to clothe dwarven infants, but only if you're able to separate them from
32+
their mothers.
33+
34+
By default, the ``forceequip`` command will attempt to abide by game rules as
35+
closely as possible. For instance, it will skip any item which is flagged for
36+
use in a job, and will not equip more than one piece of clothing/armor onto any
37+
given body part. These restrictions can be overridden via options, but doing so
38+
puts you at greater risk of unexpected consequences. For instance, a dwarf who
39+
is wearing three breastplates will not be able to move very quickly.
40+
41+
Items equipped by this plugin DO NOT become owned by the recipient. Adult
42+
dwarves are free to adjust their own wardrobe, and may promptly decide to doff
43+
your gear in favour of their owned items. Animals, as described above, will tend
44+
to discard ALL clothing immediately unless it is manually forbidden. Armor items
45+
seem to be an exception: an animal will tend to retain an equipped suit of mail"
46+
even if you neglect to forbid it.
47+
48+
Please note that armored animals are quite vulnerable to ranged attacks. Unlike
49+
dwarves, animals cannot block, dodge, or deflect arrows, and they are slowed by
50+
the weight of their armor.
51+
52+
Examples
53+
--------
54+
55+
``forceequip``
56+
Attempts to equip all of the clothing and armor under the cursor onto the
57+
unit under the cursor, following game rules regarding which item can be
58+
equipped on which body part and only equipping 1 item onto each body part.
59+
Items owned by other dwarves are ignored.
60+
``forceequip v bp QQQ``
61+
List the bodyparts of the selected unit.
62+
``forceequip bp LH``
63+
Equips an appopriate item onto the unit's left hand.
64+
``forceequip m bp LH``
65+
Equips ALL appropriate items onto the unit's left hand. The unit may end up
66+
wearing a dozen left-handed mittens. Use with caution, and remember that
67+
dwarves tend to drop extra items ASAP.
68+
``forceequip i bp NECK``
69+
Equips an item around the unit's neck, ignoring appropriateness
70+
restrictions. If there's a millstone or an albatross carcass sitting on the
71+
same square as the targeted unit, then there's a good chance that it will
72+
end up around his neck. For precise control, remember that you can
73+
selectively forbid some of the items that are piled on the ground.
74+
``forceequip s``
75+
Equips the item currently selected in the k menu, if possible.
76+
``forceequip s m i bp HD``
77+
Equips the selected item onto the unit's head. Ignores all restrictions and
78+
conflicts. If you know exactly what you want to equip, and exactly where you
79+
want it to go, then this is the most straightforward and reliable option.
80+
81+
Options
82+
-------
83+
84+
``i``, ``ignore``
85+
Bypasses the usual item eligibility checks (such as "Never equip gear
86+
belonging to another dwarf" and "Nobody is allowed to equip a Hive".
87+
``m``, ``multi``
88+
Bypasses the 1-item-per-bodypart limit. Useful for equipping both a mitten
89+
and a gauntlet on the same hand (or twelve breastplates on the upper body).
90+
``m2``, ``m3``, ``m4``
91+
Modifies the 1-item-per-bodypart limit, allowing each part to receive 2, 3,
92+
or 4 pieces of gear.
93+
``s``, ``selected``
94+
Equip only the item currently selected in the k menu and ignore all other
95+
items in the tile.
96+
``bp``, ``bodypart <body part code>``
97+
Specify which body part should be equipped.
98+
``v``, ``verbose``
99+
Provide detailed narration and error messages, including listing available
100+
body parts when an invalid ``bodypart`` code is specified.

‎plugins/forceequip.cpp‎

Lines changed: 3 additions & 162 deletions
Original file line numberDiff line numberDiff line change
@@ -55,171 +55,12 @@ const int const_GloveLeftHandedness = 2;
5555

5656
command_result df_forceequip(color_ostream &out, vector <string> & parameters);
5757

58-
const string forceequip_help =
59-
"ForceEquip moves local items into a unit's inventory. It is typically\n"
60-
"used to equip specific clothing/armor items onto a dwarf, but can also\n"
61-
"be used to put armor onto a war animal or to add unusual items (such\n"
62-
"as crowns) to any unit.\n"
63-
"This plugin can process multiple items in a single call, but will only\n"
64-
"work with a single unit (the first one it finds under the cursor).\n"
65-
"In order to minimize confusion, it is recommended that you use\n"
66-
"forceequip only when you have a unit standing alone atop a pile of\n"
67-
"gear that you would like it to wear. Items which are stored in bins\n"
68-
"or other containers (e.g. chests, armor racks) may also work, but\n"
69-
"piling items on the floor (via a garbage dump activity zone, of the\n"
70-
"DFHack autodump command) is the most reliable way to do it.\n"
71-
"The plugin will ignore any items that are forbidden. Hence, you\n"
72-
"can setup a large pile of surplus gear, walk a unit onto it (or\n"
73-
"pasture an animal on it), unforbid a few items and run forceequip.\n"
74-
"The (forbidden) majority of your gear will remain in-place, ready\n"
75-
"for the next passerby."
76-
"\n"
77-
"As mentioned above, this plugin can be used to equip items onto\n"
78-
"units (such as animals) which cannot normally equip gear. There's\n"
79-
"an important caveat here - such creatures will automatically drop\n"
80-
"inappropriate gear almost immediately (within 10 game ticks).\n"
81-
"If you want them to retain their equipment, you must forbid it\n"
82-
"AFTER using forceequip to get it into their inventory.\n"
83-
"This technique can also be used to clothe dwarven infants, but\n"
84-
"only if you're able to separate them from their mothers.\n"
85-
"\n"
86-
"By default, the forceequip plugin will attempt to avoid\n"
87-
"conflicts and outright cheating. For instance, it will skip\n"
88-
"any item which is flagged for use in a job, and will not\n"
89-
"equip more than one piece of clothing/armor onto any given\n"
90-
"body part. These restrictions can be overridden via command\n"
91-
"switches (see examples below) but doing so puts you at greater\n"
92-
"risk of unexpected consequences. For instance, a dwarf who\n"
93-
"is wearing three breastplates will not be able to move very\n"
94-
"quickly.\n"
95-
"\n"
96-
"Items equipped by this plugin DO NOT become owned by the\n"
97-
"recipient. Adult dwarves are free to adjust their own\n"
98-
"wardrobe, and may promptly decide to doff your gear in\n"
99-
"favour of their owned items. Animals, as described above,\n"
100-
"will tend to discard ALL clothing immediately unless it is\n"
101-
"manually forbidden. Armor items seem to be an exception;\n"
102-
"an animal will tend to retain an equipped suit of mail\n"
103-
"even if you neglect to Forbid it.\n"
104-
"\n"
105-
"Please note that armored animals are quite vulnerable to ranged\n"
106-
"attacks. Unlike dwarves, animals cannot block, dodge, or deflect\n"
107-
"arrows, and they are slowed by the weight of their armor.\n"
108-
"\n"
109-
"This plugin currently does not support weapons.\n"
110-
"\n"
111-
"Options:\n"
112-
" here, h - process the unit and item(s) under the cursor.\n"
113-
" - This option is enabled by default since the plugin\n"
114-
" - does not currently support remote equpping.\n"
115-
" ignore, i - bypasses the usual item eligibility checks (such as\n"
116-
" - \"Never equip gear belonging to another dwarf\" and\n"
117-
" - \"Nobody is allowed to equip a Hive\".)\n"
118-
" multi, m - bypasses the 1-item-per-bodypart limit, allowing\n"
119-
" - the unit to receive an unlimited amount of gear.\n"
120-
" - Can be used legitimately (e.g. mitten + gauntlet)\n"
121-
" - or for cheating (e.g. twelve breastplates).\n"
122-
" m2, m3, m4 - alters the 1-item-per-bodypart limit, allowing\n"
123-
" - each part to receive 2, 3, or 4 pieces of gear.\n"
124-
" selected, s - rather than processing all items piled at a unit's\n"
125-
" - feet, process only the one item currently selected.\n"
126-
" bodypart, bp - must be followed by a bodypart code (e.g. LH).\n"
127-
" - Instructs the plugin to equip all available items\n"
128-
" - onto this body part only. Typically used in\n"
129-
" - conjunction with the f switch (to over-armor\n"
130-
" - a particular bodypart) or the i switch (to equip\n"
131-
" - an unusual item onto a specific slot).\n"
132-
" verbose, v - provides detailed narration and error messages.\n"
133-
" - Can be helpful in resolving failures; not needed\n"
134-
" - for casual use.\n"
135-
"\n"
136-
"Examples:\n"
137-
" forceequip\n"
138-
" attempts to equip all of the items under the cursor onto the unit\n"
139-
" under the cursor. Uses only clothing/armor items; ignores all\n"
140-
" other types. Equips a maximum of 1 item onto each bodypart,\n"
141-
" and equips only \"appropriate\" items in each slot (e.g. glove\n"
142-
" --> hand). Bypasses any item which might cause a conflict,\n"
143-
" such as a Boot belonging to a different dwarf.\n"
144-
" forceequip bp LH\n"
145-
" attempts to equip all local items onto the left hand of the local\n"
146-
" unit. If the hand is already equipped then nothing will happen,\n"
147-
" and if it is not equipped then only one appropriate item (e.g. \n"
148-
" a single mitten or gauntlet) will be equipped. This command can\n"
149-
" be useful if you don't want to selectively forbid individual items\n"
150-
" and simply want the unit to equip, say, a Helmet while leaving\n"
151-
" the rest of the pile alone.\n"
152-
" forceequip m bp LH\n"
153-
" as above, but will equip ALL appropriate items onto the unit's\n"
154-
" left hand. After running this command, it might end up wearing\n"
155-
" a dozen left-handed mittens. Use with caution, and remember\n"
156-
" that dwarves will tend to drop supernumary items ASAP.\n"
157-
" forceequip m\n"
158-
" as above, but will equip ALL appropriate items onto any\n"
159-
" appropriate bodypart. Tends to put several boots onto the right\n"
160-
" foot while leaving the left foot bare.\n"
161-
" forceequip m2\n"
162-
" as above, but will equip up to two appropriate items onto each\n"
163-
" bodypart. Helps to balance footwear, but doesn't ensure proper\n"
164-
" placement (e.g. left foot gets two socks, right foot gets two\n"
165-
" shoes). For best results, use \"selected bp LH\" and\n"
166-
" \"selected bp RH\" instead.\n"
167-
" forceequip i\n"
168-
" performs the standard \"equip appropriate items onto appropriate\n"
169-
" bodyparts\" logic, but also includes items that would normally\n"
170-
" be considered ineligible (such as a sock which is owned by\n"
171-
" a different dwarf).\n"
172-
" forceequip bp NECK\n"
173-
" attempts to equip any appropriate gear onto the Neck of the\n"
174-
" local unit. Since the plugin believes that no items are actually\n"
175-
" appropriate for the Neck slot, this command does nothing.\n"
176-
" forceequip i bp NECK\n"
177-
" attempts to equip items from the local pile onto the Neck\n"
178-
" of the local unit. Ignores appropriateness restrictions.\n"
179-
" If there's a millstone or an albatross carcass sitting on\n"
180-
" the same square as the targeted unit, then there's a good\n"
181-
" chance that it will end up around his neck. For precise\n"
182-
" control, remember that you can selectively forbid some of\n"
183-
" the items that are piled on the ground.\n"
184-
" forceequip i m bp NECK\n"
185-
" as above, but equips an unlimited number of items onto the\n"
186-
" targeted bodypart. Effectively, all unforbidden items\n"
187-
" (including helms, millstones, boulders, etc) will be\n"
188-
" moved from the local pile and placed in the dwarf's\n"
189-
" inventory (specifically, on his neck). When used with\n"
190-
" a large pile of goods, this will leave the dwarf heavily\n"
191-
" encumbered and very slow to move.\n"
192-
" forceequip s\n"
193-
" requires that a single item be selected using the k menu.\n"
194-
" This item must occupy the same square as the target unit,\n"
195-
" and must be unforbidden. Attempts to equip this single\n"
196-
" item onto an appropriate slot in the unit's inventory.\n"
197-
" Can serve as a quicker alternative to the selective-\n"
198-
" unforbidding approach described above.\n"
199-
" forceequip s m i bp HD\n"
200-
" equips the selected item onto the unit's head. Ignores\n"
201-
" all possible restrictions and conflicts. If you know\n"
202-
" exactly what you want to equip, and exactly where you\n"
203-
" want it to go, then this is the most straightforward\n"
204-
" and reliable option.\n"
205-
" forceequip v bp QQQ\n"
206-
" guaranteed to fail (and accomplish nothing) because\n"
207-
" there are no bodyparts called QQQ. However, since the\n"
208-
" verbose switch is used, the resulting error messages\n"
209-
" will list every bodypart that the unit DOES possess.\n"
210-
" May be useful if you're unfamiliar with the BP codes\n"
211-
" used by Dwarf Fortress, or if you're experimenting\n"
212-
" with an exotic creature.\n"
213-
"\n"
214-
;
215-
21658
DFhackCExport command_result plugin_init ( color_ostream &out, vector <PluginCommand> &commands)
21759
{
21860
commands.push_back(PluginCommand(
219-
"forceequip", "Move items from the ground into a unit's inventory",
220-
df_forceequip, false,
221-
forceequip_help.c_str()
222-
));
61+
"forceequip",
62+
"Move items into a unit's inventory.",
63+
df_forceequip));
22364

22465
return CR_OK;
22566
}

0 commit comments

Comments
 (0)