add getunits() buildin

1 files changed, 34 insertions, 0 deletions

diff --git a/doc/script_commands.txt b/doc/script_commands.txt
index 581ec182c..e209b0e56 100644
--- a/doc/script_commands.txt
+++ b/doc/script_commands.txt
@@ -3229,6 +3229,40 @@ Notice that NPC objects disabled with disablenpc() will still be located.
 
 ---------------------------------------
 
+*getunits(<type>, <variable>, <limit>, "<map>"{, <x1>, <y1>, <x2>, <y2>})
+
+This function searches a whole map or area for units and adds their GID to
+the provided <variable> array. It filters units by <type> and stops searching
+after <limit> units have been found. Set <limit> to false (0) if you wish to
+disable the limit altogether.
+
+Type is the type of unit to search for:
+
+	BL_PC    - Character object
+	BL_MOB   - Monster object
+	BL_PET   - Pet object
+	BL_HOM   - Homunculus object
+	BL_MER   - Mercenary object
+	BL_IEM   - Item object (item drops)
+	BL_SKILL - Skill object (skill fx & sfx)
+	BL_NPC   - NPC object
+	BL_CHAT  - Chat object
+	BL_ELEM  - Elemental object
+	BL_CHAR  - Shorthand for (BL_PC|BL_MOB|BL_HOM|BL_MER|BL_ELEM)
+	BL_ALL   - Any kind of object
+
+** Do NOT use UNITTYPE_ constants here, they have different values.
+
+Example:
+
+	.@count = getunits((BL_PC | BL_NPC), .@units, false, "prontera");
+
+The above example would search the map "prontera" for all PC and NPC units and
+add them to the .@units array, while setting .@count to the amount of units
+added to the array (useful in for() loops).
+
+---------------------------------------
+
 *getgmlevel()
 
 This function will return the (GM) level of player group the account to