90 online 3 members  + Join RP Base  +
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
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
  • 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.
Preview (Exemple)

How it works
Because DrawPoly / DrawLine are not rendered on the pause map, MapZones uses the runtime-texture overlay technique:

  1. For each zone, its polygon is reduced to a bounding box.
  2. An offscreen browser (DUI) renders the polygon on a ` (transparent outside the shape) — html/zone.html + html/zone.js`.
  3. The DUI is converted to a runtime texture (CreateRuntimeTextureFromDuiHandle).
  4. The texture is placed on the map through a scaleform overlay (MINIMAP_LOADER.gfx → ADD_SCALED_OVERLAY).
  5. Hover detection: GetPauseMapPointerWorldPosition gives the world position under the pause-map cursor; a point-in-polygon test resolves the hovered zone.
  6. Player detection: the ped's world position is point-in-polygon tested against every zone on a fixed interval.

Requirements
  • A recent FiveM server artifacts build (the pause-map cursor native GetPauseMapPointerWorldPosition must be available).
  • **MINIMAP_LOADER.gfx** must be present in the resource folder.

Installation
  1. Drop the resource folder into your server's resources directory.
  2. Make sure **MINIMAP_LOADER.gfx** is in the folder (next to fxmanifest.lua).
  3. 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 borders
Pad, 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

…