FreeScript
MapZones
by OffSey · version 2026.09.09 · updated 3 days ago
No reviews yet
- Downloads
- 0
- Reviews
- 0
- Size
- 37 KB
- Code check
- Clean
- Licence
- GPL-3.0
- Released
- Nov 2026
Draw custom polygon zones on the GTA V minimap and pause map in FiveM, with hover detection, player presence events, and full runtime rendering from world coord
MapZones
Draw colored polygonal zones / territories on the GTA V minimap and pause map in FiveM, and react when the map cursor hovers a zone or when the player physically enters one.
Zones are rendered with arbitrary shapes and custom colors — no pre-made images required. Everything is drawn at runtime from world coordinates.
Features
How it works
Because
> The export/resource name is your folder name. If you keep the folder as
Configuration
All settings live in
Option, Default, Description
Zone format
All exports are client-side. Replace
**
Creates and renders a zone. Returns a numeric
**
Removes a zone by id. Returns
**
Removes every zone.
**
Returns the zone currently under the pause-map cursor, plus its id, or
**
Returns the zone the player's ped is currently inside, plus its id, or
Events
All events are client-side and carry
Event, Trigger
Loading zones
File structure
MapZones/
├─ fxma
…
Draw colored polygonal zones / territories on the GTA V minimap and pause map in FiveM, and react when the map cursor hovers a zone or when the player physically enters one.
Zones are rendered with arbitrary shapes and custom colors — no pre-made images required. Everything is drawn at runtime from world coordinates.
Features
- Arbitrary polygon zones defined from in-game world coordinates.
- Per-zone color, fill opacity and border.
- Rendered on both the minimap and the pause (big) map.
- Map hover events — fired when the pause-map cursor enters/leaves a zone.
- Player presence events — fired when the player's ped physically enters/leaves a zone (polled on an interval).
- Simple exports API to add / remove / query zones at runtime.
- No textures to create: shapes are drawn on a canvas at runtime.
How it works
Because
DrawPoly / DrawLine are not rendered on the pause map, MapZones uses the runtime-texture overlay technique:
- For each zone, its polygon is reduced to a bounding box.
- An offscreen browser (DUI) renders the polygon on a `
(transparent outside the shape) —html/zone.html+html/zone.js`. - The DUI is converted to a runtime texture (
CreateRuntimeTextureFromDuiHandle). - The texture is placed on the map through a scaleform overlay (
MINIMAP_LOADER.gfx→ADD_SCALED_OVERLAY). - Hover detection:
GetPauseMapPointerWorldPositiongives the world position under the pause-map cursor; a point-in-polygon test resolves the hovered zone. - Player detection: the ped's world position is point-in-polygon tested against every zone on a fixed interval.
- A recent FiveM server artifacts build (the pause-map cursor native
GetPauseMapPointerWorldPositionmust be available). - **
MINIMAP_LOADER.gfx** must be present in the resource folder.
- Drop the resource folder into your server's
resourcesdirectory. - Make sure **
MINIMAP_LOADER.gfx** is in the folder (next tofxmanifest.lua). - Add it to your
server.cfg:
ensure MapZones> The export/resource name is your folder name. If you keep the folder as
MapZones, use exports['MapZones']. Rename consistently if you use another folder name.Configuration
All settings live in
config.lua.Option, Default, Description
FillAlpha, 150, Zone fill opacity (0–255). Can be overridden per zone with alpha.BorderScale, 0.0015, Border thickness as a fraction of the atlas size.BorderAlpha, 255, Border opacity (0–255).AtlasSize, 4096, Resolution (px) of the shared atlas texture holding every zone. Higher = sharper bordersPad, 25.0, Extra world-unit margin around the zone bounds so borders are never clipped.FlipY, true, Vertical orientation. Set to false if zones appear mirrored top/bottom.PlayerCheckInterval, 2000, How often (ms) the player's position is tested against zones.Zone format
{
name = 'Elysian Island', -- shown in event payloads
description = 'No gang controls this area.',
color = { 70, 130, 220 }, -- { r, g, b } 0-255
alpha = 150, -- optional, overrides Config.FillAlpha
points = { -- world coords, ordered (CW or CCW)
{ x = -126.0, y = -1543.9 },
{ x = -131.5, y = -1538.5 },
-- ...
}
}
Zones are 2D (X/Y footprint). Height is ignored for player detection.Exports
All exports are client-side. Replace
MapZones with your resource folder name.**
addZone(data)**Creates and renders a zone. Returns a numeric
id (or nil if invalid).
local id = exports['MapZones']:addZone({
name = 'Vespucci',
description = 'Contested territory.',
color = { 200, 70, 190 },
points = {
{ x = -1380.0, y = -1170.0 },
{ x = -1120.0, y = -1170.0 },
{ x = -1120.0, y = -920.0 },
{ x = -1380.0, y = -920.0 },
}
})**
removeZone(id)**Removes a zone by id. Returns
true if it existed.
exports['MapZones']:removeZone(id)**
clearZones()**Removes every zone.
exports['MapZones']:clearZones()**
getHoveredZone()**Returns the zone currently under the pause-map cursor, plus its id, or
nil.
local zone, id = exports['MapZones']:getHoveredZone()**
getPlayerZone()**Returns the zone the player's ped is currently inside, plus its id, or
nil.
local zone, id = exports['MapZones']:getPlayerZone()Events
All events are client-side and carry
(zone, id), where zone is the table you passed to addZone.Event, Trigger
mapzones:onMapEnter, The pause-map cursor moved onto a zone.mapzones:onMapExit, The pause-map cursor left a zone.mapzones:onPlayerEnter, The player's ped entered a zone (checked every PlayerCheckInterval ms).mapzones:onPlayerExit, The player's ped left a zone.
-- Enter Zone
AddEventHandler('mapzones:onPlayerEnter', function(zone, id)
print(('Entered %s'):format(zone.name))
-- e.g. show a HUD, notify the server, start a capture timer...
end)
AddEventHandler('mapzones:onMapEnter', function(zone, id)
-- e.g. open a custom NUI panel describing the zone
end)
-- Exit Zone
AddEventHandler('mapzones:onPlayerEnter', function(zone, id)
-- e.g. hide a HUD, notify the server, stop a capture timer...
end)
AddEventHandler('mapzones:onMapExit', function(zone, id)
-- e.g. hide custom NUI panel or other
end)Loading zones
test.lua is a minimal example: it loads every zone from Config.TestZones through addZone and logs all four events. Replace it with your own loader (database, server sync, etc.).
CreateThread(function()
for i = 1, #Config.TestZones do
exports[GetCurrentResourceName()]:addZone(Config.TestZones[i])
end
end)File structure
`MapZones/
├─ fxma
…