Merge branch 'development' into main

.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+    "Lua.diagnostics.disable": [
+        "unused-local",
+        "empty-block"
+    ]
+}

docs/api/zone.md

@@ -2,6 +2,8 @@
 [Detection Enum]: https://github.com/1ForeverHD/ZonePlus/blob/main/src/Zone/Enum/Detection.lua
 [setAccuracy]: https://1foreverhd.github.io/ZonePlus/api/zone/#setaccuracy
 [setDetection]: https://1foreverhd.github.io/ZonePlus/api/zone/#setdetection
+[icon:trackItem]: https://1foreverhd.github.io/ZonePlus/api/zone/#trackitem
+[ZoneController.setGroup]: https://1foreverhd.github.io/ZonePlus/api/zone/#setgroup
 
 ## Construtors
 
@@ -31,7 +33,19 @@ local isWithinZoneBool = zone:findPlayer(player)
 ----
 #### findPart
 ```lua
-local isWithinZoneBool = zone:findPart(basePart)
+local isWithinZoneBool, touchingZoneParts = zone:findPart(basePart)
+```
+
+----
+#### findItem
+```lua
+local isWithinZoneBool, touchingZoneParts = zone:findItem(basePartOrCharacter)
+```
+
+----
+#### findPoint
+```lua
+local isWithinZoneBool, touchingZoneParts = zone:findPoint(position)
 ```
 
 ----
@@ -46,19 +60,52 @@ local playersArray = zone:getPlayers()
 local partsArray = zone:getParts()
 ```
 
+----
+#### getItems
+```lua
+local itemsArray = zone:getItems()
+```
+
 ----
 #### getRandomPoint
 ```lua
-local randomVector, touchingGroupPartsArray = zone:getRandomPoint()
+local randomVector, touchingZonePartsArray = zone:getRandomPoint()
 ```
 Generates random points within the zones region until one falls within its bounds. It then returns this ``Vector3`` and a ``table array`` of group parts the point falls within.
 
 ----
-#### setAccuracy
+#### trackItem
+```lua
+zone:trackItem(characterOrBasePart)
+```
+This is used to detect your own custom instances within zones, such as NPCs, and is a recommended replacement for part-events/methods.
+
+An item can be any BasePart or Character/NPC (i.e. a model with a Humanoid and HumanoidRootPart). Once tracked, it can be listened for with the ``zone.itemEntered`` and ``zone.itemExited`` events.
+
+An item will be automatically untracked if destroyed or has its parent set to ``nil``.
+
+
+----
+#### untrackItem
+```lua
+zone:untrackItem(characterOrBasePart)
+```
+
+----
+#### bindToGroup
 ```lua
-zone:setAccuracy(enumIdOrName)
+zone:bindToGroup(settingsGroupName)
+```
+This is used to bind the zone to a settingsGroup to enhance the default behaviour of a collection of zones. The properties of a settingsGroup can be viewed at and customised using [ZoneController.setGroup].
+
+This method is particularly useful for zones where you want to guarantee the player/item is not in two zones at once. For example, when working with ambient/music/lighting zones which perfectly border each other.
+
+
+----
+#### unbindFromGroup
+```lua
+zone:bindToGroup(settingsGroupName)
 ```
-Sets the frequency of checks based upon the [Accuracy Enum]. Defaults to 'High'.
 
 ----
 #### setDetection
@@ -121,7 +168,7 @@ end)
 ```
 
 !!! info
-    This event works only for unanchored parts
+    This event works only for unanchored parts and may interfere with the parts CanCollide property. It's recommended to use itemEntered instead where possible which is more optimal and overcomes these problems. 
 
 ----
 #### partExited
@@ -132,7 +179,27 @@ end)
 ```
 
 !!! info
-    This event works only for unanchored parts
+    This event works only for unanchored parts and may interfere with the parts CanCollide property. It's recommended to use itemExited instead where possible which is more optimal and overcomes these problems. 
+
+----
+#### itemEntered
+```lua
+zone.itemEntered:Connect(function(item)
+    print(("item '%s' entered the zone!"):format(item.Name))
+end)
+```
+See [icon:trackItem] for further details on items.
+
+
+----
+#### itemExited
+```lua
+zone.itemExited:Connect(function(item)
+    print(("item '%s' exited the zone!"):format(item.Name))
+end)
+```
+See [icon:trackItem] for further details on items.
+
 
 ----
 
@@ -192,15 +259,15 @@ local bool = zone.respectUpdateQueue --[default: 'true']
 When ``true``, will prevent the internal ``_update()`` from being called multiple times within a 0.1 second period.
 
 ----
-#### groupParts
+#### zoneParts
 {read-only}
 
-An array of baseparts, defined in the ``group`` constructor parameter, that form the zone.
+An array of baseparts, defined in the ``zoneGroup`` constructor parameter, that form the zone.
 
 ----
 #### region
 {read-only}
 
 ----
 #### volume
-{read-only}
+{read-only}

docs/api/zone_controller.md

@@ -1,38 +1,36 @@
+[zone:bindToGroup]: https://1foreverhd.github.io/ZonePlus/api/zone/#bindtogroup
+
 ## Functions
 
 #### getZones
 ```lua
 local zonesArray = ZoneController.getZones()
 ```
 
-----
-#### getCharacterRegion
-```lua
-local charRegion, regionCFrame, charSize = ZoneController.getCharacterRegion(player)
-```
-
 ----
 #### getTouchingZones
 ```lua
 local touchingZonesArray, touchingPartsDictionary = ZoneController.getTouchingZones(player)
 ```
 
 ----
-#### getHeightOfParts
+#### setGroup
 ```lua
-local height, minY, maxY = ZoneController.getHeightOfParts(tableOfParts)
+local settingsGroup = ZoneController.setGroup(settingsGroupName, properties)
 ```
 
-----
-#### vectorIsBetweenYBounds
+``properties`` is a dictionary defining the groups settings. The default properties are:
 ```lua
-local bool = ZoneController.vectorIsBetweenYBounds(vector, tableOfParts)
+{
+	onlyEnterOnceExitedAll = true, -- When set to `true`, it prevents items (players, parts, etc) from entering multiple zones at once within that group.
+}
 ```
+A zone can be bound to a group using [zone:bindToGroup].
 
 ----
-#### verifyTouchingParts
+#### getGroup
 ```lua
-local bool = ZoneController.verifyTouchingParts(vectors, tableOfParts)
+local settingsGroup = ZoneController.getGroup(settingsGroupName)
 ```
 
-----
+----

docs/changelog.md

@@ -1,3 +1,39 @@
+## [3.0.0] - August 27 2021
+### Added
+- ``Zone:trackItem(characterOrBasePart)``
+- ``Zone:untrackItem(characterOrBasePart)``
+- ``Zone.itemEntered`` event
+- ``Zone.itemExited`` event
+- ``Zone:findItem(characterOrBasePart)``
+- ``ZoneController.setGroup(settingsGroupName, properties)``
+- ``ZoneController.getGroup(settingsGroupName)``
+- ``SettingsGroup.onlyEnterOnceExitedAll`` property
+- ``Zone:bindToGroup(settingsGroupName)``
+- ``Zone:unbindFromGroup(settingsGroupName)``
+- ``Zone.settingsGroupName`` property
+- ``Zone:findPoint(position)``
+- ``ZoneController.getCharacterSize(character)``
+
+### Changed
+- Internal behaviour to use the new Spatial [Query API](https://devforum.roblox.com/t/introducing-overlapparams-new-spatial-query-api/1435720) instead of the Region3 API.
+- The default Detection from ``Automatic`` to ``Centre``.
+- The behaviour of Detection ``Centre`` to include the whole HumanoidRootPart instead of a singular Vector within (this was required due to the new Spatial Query API).  
+- ``Zone:findPart`` now returns array ``touchingZoneParts`` as its second value.
+- ``Maid`` to [``Janitor``](https://github.com/howmanysmall/Janitor) by howmanysmall.
+- ``Signal`` to [``GoodSignal``](https://devforum.roblox.com/t/lua-signal-class-comparison-optimal-goodsignal-class/1387063) by stravant.
+- ``ZoneController.getTouchingZones(player)`` to ``ZoneController.getTouchingZones(characterOrBasePart)``.
+
+### Removed
+- RotatedRegion3
+- ``ZoneController.getCharacterRegion``
+- ``ZoneController.verifyTouchingParts``
+- ``ZoneController.vectorIsBetweenYBounds``
+- ``ZoneController.getHeightOfParts``
+- ``Automatic`` Detection Enum.
+
+
+
+--------
 ## [2.2.3] - June 17 2021
 ### Fixed
 - The incorrect disabling of Seats and VehicleSeats within Part Zones.
@@ -85,6 +121,7 @@
 - Made Zone the parent module and others as descendants
 - Removed the ``additonalHeight`` constructor argument - this caused confusion and added additional complexities to support
 - ``:getRandomPoint()`` now returns ``randomVector, touchingGroupParts`` instead of ``randomCFrame, hitPart, hitIntersection``
+- ``zone.groupParts`` to ``zone.zoneParts``
 
 ### Fixed
 - Rotational and complex geometry detection

docs/examples.md

@@ -28,4 +28,9 @@
 
 -------------------------------------
 
+### NPC Damager
+<video src="https://thumbs.gfycat.com/PerkyIndelibleIndochinesetiger-mobile.mp4" width="100%" controls></video>
+
+-------------------------------------
+
 All examples can be tested, viewed and edited at the [Playground](https://www.roblox.com/games/6166477769/ZonePlus-Playground).

docs/index.md

@@ -7,7 +7,7 @@
 
 ## Summary
 
-ZonePlus is a module enabling the construction of dynamic zones. These zones utilise region checking, raycasting and the new [BasePart.CanTouch] property to effectively determine players and parts within their boundaries.
+ZonePlus is a module enabling the construction of dynamic zones. These zones utilise the new Spacial Query API and [BasePart.CanTouch] property to effectively determine players and parts within their boundaries.
 
 Creating a zone is as simple as:
 
@@ -18,11 +18,11 @@ local zoneGroup = workspace.SafeZoneGroup
 local zone = Zone.new(zoneGroup)
 ```
 
-Zones take one argument: a **group**. A group can be any non-basepart instance (such as a Model, Folder, etc) that contain descendant [baseparts]. Alternatively a group can be a singular basepart instance, or a table containing an array of baseparts. 
+Zones take one argument: a **zoneGroup**. A zoneGroup can be any non-basepart instance (such as a Model, Folder, etc) that contain descendant [baseparts]. Alternatively a zoneGroup can be a singular basepart instance, or a table containing an array of baseparts. 
 
 !!! info
-    Zones are compatible with all basepart classes, however it's recommended to use simple parts (blocks, balls, cylinders, wedges, etc) where possible as these are more efficient and accurate. Some classes for instance, such as MeshParts and UnionOperations, require additional raycast checks to verify their surface geometries.
-
+    Zones are compatible with all basepart classes however it's recommended to use solely Blocks (i.e. Parts with Shape 'Block') when possible as these are better optimised (since only ``WorldRoot:GetPartBoundsInBox`` needs to be called instead of ``WorldRoot:GetPartsInPart``).
+    
 These group parts are then used to define the region and precise bounds of the zone.
 
 !!! info
@@ -87,20 +87,20 @@ The way a zone detects players and parts can be changed two ways with a correspo
 
 1. Using the ``zone:setDetection(itemName)`` method:
     ```lua
-    zone:setDetection("Automatic")
+    zone:setDetection("WholeBody")
     ```
 
 2. Setting the ``zone.enterDetection`` and ``zone.exitDetection`` properties:
     ```lua
-    zone.enterDetection = Zone.enum.Detection.Automatic
-    zone.exitDetection = Zone.enum.Detection.Automatic
+    zone.enterDetection = Zone.enum.Detection.WholeBody
+    zone.exitDetection = Zone.enum.Detection.WholeBody
     ```
 
-By default enterDetection and exitDetection are ``Automatic``.
+By default enterDetection and exitDetection are ``Centre``.
 
 !!! info
     Modifying the detection of one zone may impact the detection of another due to the modules collaborative nature.
 
 !!! warning
-    Setting ``enterDetection`` to (``Zone.enum.Detection.WholeBody`` or ``Zone.enum.Detection.Automatic``) and ``exitDetection`` to ``Zone.enum.Detection.Centre`` will cause the entered and exit events to trigger rapidly when the player lies on the bounds of the zone.
+    Setting ``enterDetection`` to (``Zone.enum.Detection.WholeBody`` or ``Zone.enum.Detection.Automatic``) and ``exitDetection`` to ``Zone.enum.Detection.Centre`` may cause the entered and exit events to trigger rapidly when the player lies on the bounds of the zone.