v2.6.1 - BoxZone scale/offset, onPointInOut, and creation fixes

This release includes:

• Fixed BoxZone scale/offset support for the Z axis
• Start isInside as false for onPointInOut
  • onPointInOut will no longer trigger its callback on zone creation if the point starts outside of the zone
• Prevent creation from breaking in the presence of resources that disable certain keys

The resource itself can be found in PolyZone.zip. You can grab an example resource from release 2.2.0.

v2.6.0 - ComboZone:RemoveZone() and ComboZone/BoxZone performance improvements

This update has one new feature as well as performance optimizations for both ComboZones and BoxZones.

This release adds:

• ComboZone:RemoveZone()
  • A refactor and improvement of the ComboZone grid cache, as well as large performance optimizations to BoxZone creation has made it possible to finally add this method. See here for more info.
• Performance Optimizations
  • BoxZone:Create() is now ~50% faster in the most common case (no scale or offset), and ~30% faster otherwise.
  • ComboZone grid cache is now efficient enough to where we can place all the zones into it at ComboZone creation with no penalty. This avoids the runtime cost every time you enter a ComboZone grid cell.

The resource itself can be found in PolyZone.zip. You can grab an example resource from release 2.2.0.

v2.5.0 - Zone Events and PolyZone startup and memory optimization

This update has one new feature as well as one large performance optimization for PolyZones.

This release adds:

• Zone Events
  • You can add a zone event to any zone and then trigger that zone event from any client and that event will trigger on all clients on the server that are within that zone.
  • Useful for situations where one client triggers an action, but all clients in the zone should be affected by it. See here for more info.
• lazyGrid PolyZone optimization
  • This is a new option on PolyZones, enabled by default, that delays the grid optimization creation until it's necessary, and does it cell-by-cell, rather than for the whole zone at once. This reduces the startup cost for PolyZones by >99% (to near-zero) and reduces memory usage. See here for more info.

The resource itself can be found in PolyZone.zip. You can grab an example resource from release 2.2.0.

v2.4.0 - Height controls for CircleZone (sphere) creation, pzcomboinfo command, and pzcreate command shortcuts

Another relatively small but useful QoL update.

This release adds:

• Height controls for CircleZone creation in sphere mode
  • When creating a CircleZone in sphere mode (press Z), you can now use alt+scroll wheel to change the height (Z coord) of the sphere.
• New pzcomboinfo command
  • This command will print some information about any ComboZones that are created. The info includes how many zones are in the zone and the distribution of zone types (Circle, Box, etc.) of the ComboZone.
• pzcreate command shortcuts
  • You can now put all the info for a pzcreate call in the command itself, and avoid the popup text boxes. So instead of /pzcreate circle, and then filling out the text boxes, you could just do /pzcreate circle name 2.0 and skip the text boxes.

The resource itself can be found in PolyZone.zip. You can grab an example resource from release 2.2.0.

v2.3.0 - Optimization for exhaustive ComboZones, new debugBlip option, and new helper function

This is a pretty small but useful update, especially for those who are making use of exhaustive ComboZones.

This release adds:

• Optimization for exhaustive ComboZones
  • Completely removed the memory churn from exhaustive ComboZones. I wouldn't say it is 100% the same performance as regular ComboZones at this point, but it's closer than it's ever been. Basically, if you even think you need exhaustiveness, just use it, because you'll have a hard time finding any practical performance difference.
• New debugBlip option
  • This option, when set to true, will add a blip at the center of the zone. If set on a ComboZone, it will set debugBlip to true on every zone inside of or added to the ComboZone. This is useful for seeing the dispersion and number of zones you have.
• New ensureMetatable helper function
  • If you return a zone from an export, you probably will have found an issue. The data of the zone was transferred, but not the methods. This is because zones use metatables, which are not transferred by exports. To solve this, I added the PolyZone.ensureMetatable function. See here for more info.

The resource itself can be found in PolyZone.zip. You can grab an example resource from the last release (2.2.0).

v2.2.0 - Grid optimization for ComboZones, improved exhaustive helpers for ComboZones, and more controls for BoxZone creation

Given the performance improvements made on ComboZones, I think this release can only be summed up with the following gif. Just imagine each gold coin is a zone...

This release adds:

• Grid optimization for ComboZones
  • This enables an utterly massive amount of zones (if not all clustered together). When I say massive, I mean tens of thousands at 0.01-0.02ms before you hit the annoying memory warning banner in FiveM, and hundreds of thousands if you don't care about that (or spread them across multiple resources). So go wild I guess?
  • This optimization also removes a lot of the performance cost of using the exhaustive helpers. There is still an additional cost, but it's a lot smaller than it was before.
• AddZone() for ComboZones
  • You can now add zones to ComboZones post-creation. This is less performant, because it clears out the grid optimization, but because the optimization is built up on the fly, if this is done early enough (before any of the optimization has been built up), the hit won't be too much.
• More useful exhaustive helpers for ComboZones
  • onPointInOutExhaustive and onPlayerInOutExhaustive now also pass enteredZones and leftZones to the callback. See here for more info.
• Added height controls to BoxZone creation
  • There is now a special "Height" mode to BoxZone creation that allows you to change the Z of the center of the zone, the minZ, and the maxZ. See here for more info.
• Change datetime format on creation printout to ISO 8601
  • Yeah, I have no idea why I didn't do this before.
• New example resource that includes Circle, Box, and ComboZones, as well as shows off the exhaustive helpers for ComboZones.
• Various other memory and performance improvements

The resource itself can be found in PolyZone.zip. You can grab an example resource in PolyZone_Example.zip.

v2.1.0 - Optimized ComboZone helpers, data option for zones, and fixed potentially major bug

Well, a useful feature request and a possibly severe bug led to what some may say is a "swift" schedule between 2.0 and 2.1. There's also one breaking change, so listen up!

This release adds:

• Data option on all zones
  • You can give a data option to any zone that is a table that can store arbitrary additional info about your zone you want to keep on it. See here for more info
• /pzlast now asks for a name, or you can leave it empty to use the last created zone's name
  • This replaces the logic of always using the last zone's name, which I figured isn't always what people would want
• Added isPointInsideExhaustive(), onPointInOutExhaustive(), and onPlayerInOutExhaustive() to ComboZone
  • This replaces the exhaustive parameter on those functions, and was done to fix a bug and optimize the non-exhaustive version of these functions.
  • What this breaks:
    • If you are already using the regular versions of these functions, you'll need to replace the true you input for the exhaustive parameter, to using one of these functions instead.
      combo:isPointInside(point, true) turns to combo:isPointInsideExhaustive(point)
combo:onPlayerInOut(function(isPointInside, point, insideZones) end, 500, true) turns to combo:onPlayerInOutExhaustive(function(isPointInside, point, insideZones) end)
    • On the non-exhaustive versions of these functions, they no longer pass/return a table of zones consisting of the one the point is inside, but instead just that zone (shown below).

-- old
combo:onPlayerInOut(function(isPointInside, point, insideZones)
  -- insideZones here is a table of the zones you are currently in
  -- This is probably how you are using it currently
  if #insideZones > 0 then
    doSomething(insideZones[1].name)
  end
end)

-- new
combo:onPlayerInOut(function(isPointInside, point, zone)
  -- if isPointInside is true, zone is the zone the player just entered
  -- if isPointInside is false, zone is the last zone the player entered (aka the one the player is just leaving)
  -- NOTE: If the player STARTS outside of the zone, this will trigger once with isPointInside=false and zone=nil,
  --       so you should always check to make sure zone exists (not nil) if you are going to use it
  -- The code above would now be just
  if zone then
    doSomething(zone.name)
  end
end)

This new way of doing things also increases performance and avoids memory churn on non-exhaustive ComboZones. See here for more info about how these functions work now and how to use the exhaustive versions.

The resource itself can be found in PolyZone.zip. You can grab an example resource from the last release (2.0.0).

v2.0.0 - Three new zones, brand new creation system, improved performance, and more!

Version 2.0.0!

2.0.0 is officially here! The choice to go to 2.0.0 was about the size of this update and that it will be the first update in PolyZone history to introduce a breaking change. Don't worry, it's a small one involving EntityZones, something most of you probably aren't using, but a break is a break. More about that below though.

This release adds:

• Three new zones!
  • CircleZone
    • Has a center and radius. It's basically a distance check with all the PolyZone helpers on top.
    • Can operate as a circle or sphere by changing the useZ option.
    • CircleZones are for all intents and purposes, as performant as a distance check. So if all you want are the QoL features of PolyZone, you can use them now free of any guilt about "unnecessary" performance waste.
  • BoxZone
    • Has a center, length, and width.
    • This zone is an arbitrarily rotatable bounding box. It has a heading option to enable rotation (though 0 rotation is more performant).
  • ComboZone
    • Yo, heard you like zones, so I put a zone in your zone. Bad jokes aside, this zone is a collection or combination of zones, hence the name. It takes in a table of zones and all the functions, helpers, etc. operate on all the zones, while sharing resources. This is useful for if you have many zones that all do the same thing, for example a zone for each ATM in the city. Using a ComboZone instead of using all the zones separately can be many times more performant.
• Redid the creation system to be more interactive and easier to use.
  • Works with PolyZone, CircleZone, and BoxZone!
  • Uses popup input boxes instead of having to remember command syntax
  • Interactivity! Tweak your zone before you finish creating it by changing things like position, radius, length, width, etc. using controls.
  • /pzlast command to reuse the last zone you finished creating! Easily create many similar Circle or BoxZones in a row.
• onPlayerInOut() helper
  • Even less boilerplate when testing whether a player is in a zone!
• Pausing zones
  • Zones can now be paused, which involves all their helpers (onPointInOut, onPlayerInOut, onEntityDamaged, etc.) being temporarily put on hold until the zone is unpaused. This works on all zone types.
• Optimized PolyZone and EntityZone by separating them from one another to avoid a lot of branching
• Documentation moved to wiki
  • Readme was getting too cumbersome, so the documentation was moved out and core info was kept/added to readme, such as how to download PolyZone, how to include it in your script, FAQ, etc.
• Other various performance boosts and bug fixes!

Now back to that breaking change. Due to separating PolyZone and EntityZone from each other, you can't use EntityZones just by importing client.lua now. You have to explicitly import BoxZone.lua and EntityZone.lua as well, in that order. Also, EntityZones are not created with PolyZone:CreateAroundEntity() anymore, but instead EntityZone:Create() which follows the unified syntax for creating all zone types: ZoneType:Create()

The resource itself can be found in PolyZone.zip. You can grab an example resource in PolyZone_Example.zip.

v1.2.5 - Entity zones, new helper, new debug drawing, and performance boosts

Version 1.2.5!

This release adds:

• New entity zone specific helper onEntityDamaged (useful for destroying a zone if the entity is destroyed)

Plus everything from v1.2.0:

• Entity zones!
  • Create a PolyZone around an entity that follows its position and rotation
  • Arbitrarily scale and offset entity zones
  • New helper onEntityDamaged (useful for destroying a zone if the entity is destroyed)
• The walls of a PolyZone now are drawn as filled rectangles rather than horizontal lines, which looks better and is quite a bit more performant!
• Now can destroy zones (best used for entity zones)
• Various performance boosts and bug fixes!

We also updated the readme with information about entity zones and a new example picture showing off the new debug drawing.

The resource itself can be found in PolyZone.zip. You can grab an example resource in PolyZone_Example.zip.

v1.2.0 - Entity zones, new debug drawing, and performance boosts

Version 1.2.0!

This release adds:

• Entity zones!
  • Create a PolyZone around an entity that follows its position and rotation
  • Arbitrarily scale and offset entity zones
• The walls of a PolyZone now are drawn as filled rectangles rather than horizontal lines, which looks better and is quite a bit more performant!
• Now can destroy zones (best used for entity zones)
• Various performance boosts and bug fixes!

We also updated the readme with information about entity zones and a new example picture showing off the new debug drawing.

The resource itself can be found in PolyZone.zip. You can grab an example resource in PolyZone_Example.zip.