add getunits() buildin

2 files changed, 49 insertions, 0 deletions

diff --git a/doc/constants.md b/doc/constants.md
index 22d285412..e6bf656d8 100644
--- a/doc/constants.md
+++ b/doc/constants.md
@@ -3758,6 +3758,21 @@
 - `BG_AREA_WOS`: 30
 - `BG_QUEUE`: 31
 
+### block_list types (units)
+
+- `BL_PC`: 1
+- `BL_MOB`: 2
+- `BL_PET`: 4
+- `BL_HOM`: 8
+- `BL_MER`: 16
+- `BL_ITEM`: 32
+- `BL_SKILL`: 64
+- `BL_NPC`: 128
+- `BL_CHAT`: 256
+- `BL_ELEM`: 512
+- `BL_CHAR`: 539 (shorthand for `BL_PC|BL_MOB|BL_HOM|BL_MER|BL_ELEM`)
+- `BL_ALL`: 4095
+
 ### LOOK_ constants, use in setlook/changelook script commands
 
 - `LOOK_BASE`: 0
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