Markers

The Markers module provides comprehensive marker, blip, and checkpoint management for FiveM resources with advanced rendering, interaction handling, and performance optimization.

createMarker

Creates a 3D world marker with customizable properties and callbacks.

B2Lib.Markers.createMarker(options)

Parameters:

  • options (table): Marker configuration options

    • coords (vector3): Marker position

    • type (number): Marker type (1-43, see GTA marker types)

    • color (table): RGBA color {r, g, b, a} (0-255)

    • scale (vector3): Marker scale {x, y, z}

    • name (string, optional): Unique marker name

    • visibleDistance (number, optional): Maximum visible distance (default: 50.0)

    • fadeDistance (number, optional): Distance to start fading (default: 10.0)

    • interactDistance (number, optional): Interaction distance (default: 2.0)

    • bobUpAndDown (boolean, optional): Animate up and down

    • faceCamera (boolean, optional): Always face camera

    • rotate (boolean, optional): Rotate animation

    • textureDict (string, optional): Texture dictionary

    • textureName (string, optional): Texture name

    • data (table, optional): Custom data storage

    • tags (table, optional): Array of tags for organization

    • onEnter (function, optional): Callback when player enters

    • onExit (function, optional): Callback when player exits

    • onInside (function, optional): Callback while player inside

    • onInteract (function, optional): Callback on interaction

Returns: string - Marker ID for management

Example:

local markerId = B2Lib.Markers.createMarker({
    coords = vector3(100.0, 200.0, 30.0),
    type = 1,  -- Cylinder marker
    color = {r = 255, g = 0, b = 0, a = 150},
    scale = vector3(2.0, 2.0, 1.0),
    onEnter = function(markerId, marker)
        print("Player entered marker:", markerId)
    end,
    onInteract = function(markerId, marker)
        print("Player interacted with marker")
    end
})

createBlip

Creates a map blip with customizable properties.

B2Lib.Markers.createBlip(options)

Parameters:

  • options (table): Blip configuration options

    • coords (vector3): Blip position

    • sprite (number): Blip sprite ID

    • color (number): Blip color ID

    • scale (number, optional): Blip scale (default: 1.0)

    • label (string, optional): Blip label text

    • name (string, optional): Unique blip name

    • shortRange (boolean, optional): Short range visibility

    • category (number, optional): Blip category

    • priority (number, optional): Blip priority

    • flash (boolean, optional): Flash animation

    • flashTimer (number, optional): Flash duration in ms

    • route (boolean, optional): Show route to blip

    • routeColor (number, optional): Route color

Returns: string - Blip ID for management

Example:

local blipId = B2Lib.Markers.createBlip({
    coords = vector3(100.0, 200.0, 30.0),
    sprite = 1,
    color = 2,
    scale = 0.8,
    label = "Shop",
    shortRange = true
})

createBlipForEntity

Creates a blip attached to an entity.

B2Lib.Markers.createBlipForEntity(entity, options)

Parameters:

  • entity (number): Entity handle to attach blip to

  • options (table): Blip configuration options (same as createBlip)

Returns: string - Blip ID for management

Example:

local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)
if vehicle ~= 0 then
    local vehicleBlip = B2Lib.Markers.createBlipForEntity(vehicle, {
        sprite = 225,
        color = 5,
        label = "My Vehicle"
    })
end

createCheckpoint

Creates a race-style checkpoint with collision detection.

B2Lib.Markers.createCheckpoint(options)

Parameters:

  • options (table): Checkpoint configuration options

    • coords (vector3): Checkpoint position

    • nextCoords (vector3, optional): Next checkpoint position (for arrow direction)

    • radius (number): Checkpoint radius

    • color (table): RGBA color {r, g, b, a}

    • type (number, optional): Checkpoint type (default: 1)

    • name (string, optional): Unique checkpoint name

    • data (table, optional): Custom data storage

    • onEnter (function, optional): Callback when player enters

    • onExit (function, optional): Callback when player exits

Returns: string - Checkpoint ID for management

Example:

local checkpointId = B2Lib.Markers.createCheckpoint({
    coords = vector3(100.0, 200.0, 30.0),
    nextCoords = vector3(150.0, 250.0, 30.0),
    radius = 5.0,
    color = {r = 255, g = 255, b = 0, a = 150},
    onEnter = function(checkpointId, checkpoint)
        print("Checkpoint reached!")
    end
})

updateMarker

Updates an existing marker's properties.

B2Lib.Markers.updateMarker(markerId, options)

Parameters:

  • markerId (string): The marker ID to update

  • options (table): Properties to update

Returns: boolean - True if marker was updated, false if not found

Example:

B2Lib.Markers.updateMarker(markerId, {
    color = {r = 0, g = 255, b = 0, a = 200},
    scale = vector3(2.5, 2.5, 1.5),
    visibleDistance = 75.0
})

updateBlip

Updates an existing blip's properties.

B2Lib.Markers.updateBlip(blipId, options)

Parameters:

  • blipId (string): The blip ID to update

  • options (table): Properties to update

Returns: boolean - True if blip was updated, false if not found

removeMarker

Removes a marker from the world.

B2Lib.Markers.removeMarker(markerId)

Parameters:

  • markerId (string): The marker ID to remove

Returns: boolean - True if marker was removed, false if not found

removeBlip

Removes a blip from the map.

B2Lib.Markers.removeBlip(blipId)

Parameters:

  • blipId (string): The blip ID to remove

Returns: boolean - True if blip was removed, false if not found

removeCheckpoint

Removes a checkpoint from the world.

B2Lib.Markers.removeCheckpoint(checkpointId)

Parameters:

  • checkpointId (string): The checkpoint ID to remove

Returns: boolean - True if checkpoint was removed, false if not found

setMarkerActive

Enables or disables a marker.

B2Lib.Markers.setMarkerActive(markerId, active)

Parameters:

  • markerId (string): The marker ID

  • active (boolean): True to enable, false to disable

Returns: boolean - True if state was changed, false if marker not found

setBlipActive

Enables or disables a blip.

B2Lib.Markers.setBlipActive(blipId, active)

Parameters:

  • blipId (string): The blip ID

  • active (boolean): True to enable, false to disable

Returns: boolean - True if state was changed, false if blip not found

getMarker

Gets information about a specific marker.

B2Lib.Markers.getMarker(markerId)

Parameters:

  • markerId (string): The marker ID

Returns: table|nil - Marker information or nil if not found

getBlip

Gets information about a specific blip.

B2Lib.Markers.getBlip(blipId)

Parameters:

  • blipId (string): The blip ID

Returns: table|nil - Blip information or nil if not found

getAllMarkers

Gets all active markers.

B2Lib.Markers.getAllMarkers()

Returns: table - Array of all marker objects

getAllBlips

Gets all active blips.

B2Lib.Markers.getAllBlips()

Returns: table - Array of all blip objects

getNearestMarker

Gets the nearest marker to specified coordinates.

B2Lib.Markers.getNearestMarker(coords, maxDistance)

Parameters:

  • coords (vector3): Reference coordinates

  • maxDistance (number, optional): Maximum search distance

Returns: table|nil - Nearest marker information or nil if none found

getMarkersInRange

Gets all markers within a specified distance.

B2Lib.Markers.getMarkersInRange(coords, distance)

Parameters:

  • coords (vector3): Reference coordinates

  • distance (number): Search radius

Returns: table - Array of markers within range

getMarkersByTag

Gets all markers with a specific tag.

B2Lib.Markers.getMarkersByTag(tag)

Parameters:

  • tag (string): Tag to search for

Returns: table - Array of markers with the specified tag

clearAllMarkers

Removes all markers from the world.

B2Lib.Markers.clearAllMarkers()

Returns: number - Number of markers removed

clearAllBlips

Removes all blips from the map.

B2Lib.Markers.clearAllBlips()

Returns: number - Number of blips removed

createTemporaryMarker

Creates a marker that automatically removes itself after a duration.

B2Lib.Markers.createTemporaryMarker(options, duration)

Parameters:

  • options (table): Marker configuration options

  • duration (number): Duration in milliseconds before auto-removal

Returns: string - Marker ID for management

Example:

-- Create a marker that disappears after 10 seconds
local tempMarker = B2Lib.Markers.createTemporaryMarker({
    coords = vector3(100.0, 200.0, 30.0),
    type = 1,
    color = {r = 255, g = 0, b = 0, a = 150}
}, 10000)

createMarkerBatch

Creates multiple markers efficiently.

B2Lib.Markers.createMarkerBatch(markerList)

Parameters:

  • markerList (table): Array of marker configuration objects

Returns: table - Array of created marker IDs

isPlayerInMarker

Checks if a player is currently inside a specific marker.

B2Lib.Markers.isPlayerInMarker(markerId, playerId)

Parameters:

  • markerId (string): The marker ID to check

  • playerId (number, optional): Player ID (default: current player)

Returns: boolean - True if player is inside the marker

getMarkerDistance

Gets the distance from coordinates to a marker.

B2Lib.Markers.getMarkerDistance(markerId, coords)

Parameters:

  • markerId (string): The marker ID

  • coords (vector3, optional): Reference coordinates (default: player position)

Returns: number|nil - Distance to marker or nil if marker not found

Configuration

Configure the markers system in config.lua:

Config.Markers = {
    defaultVisibleDistance = 50.0,  -- Default visible distance
    defaultFadeDistance = 10.0,     -- Default fade distance
    defaultInteractDistance = 2.0,  -- Default interaction distance
    renderFrameRate = 0,            -- Render frame rate (0 = every frame)
    enableInteractionKey = true,    -- Enable interaction key (E)
    interactionKey = 38,            -- Interaction key code (E)
    enableDebugMode = false,        -- Enable debug rendering
    maxMarkers = 500,               -- Maximum number of markers
    maxBlips = 200,                 -- Maximum number of blips
    cleanupInterval = 60000         -- Cleanup interval in milliseconds
}

Marker Types Reference

Common marker types for the type parameter:

  • 1 - Cylinder (most common)

  • 2 - Arrow pointing up

  • 3 - Arrow pointing down

  • 6 - Traffic cone

  • 7 - Cube/box

  • 9 - Ring/circle

  • 10 - Sphere/ball

  • 27 - Checkpoint arrow

  • 28 - Checkpoint cylinder

Troubleshooting

Markers Not Visible

  1. Check that visibleDistance is appropriate for your use case

  2. Verify coordinates are valid and accessible

  3. Ensure marker type is valid (1-43)

  4. Check if marker is active with getMarker()

Performance Issues

  1. Reduce the number of active markers

  2. Increase renderFrameRate to reduce update frequency

  3. Use appropriate visibleDistance to limit rendering

  4. Remove unused markers with removeMarker()

Interaction Not Working

  1. Verify interactDistance is appropriate

  2. Check that interaction callbacks are properly defined

  3. Ensure interaction key is enabled in configuration

  4. Test with isPlayerInMarker() to verify detection

Blips Not Showing

  1. Check that sprite and color IDs are valid

  2. Verify coordinates are within map bounds

  3. Ensure blip is active with getBlip()

  4. Check if shortRange is appropriate for your use case

Memory Leaks

  1. Always remove markers when no longer needed

  2. Use temporary markers for short-lived indicators

  3. Monitor marker count with getAllMarkers()

  4. Enable cleanup interval in configuration

PreviousEntitiesNextRaycast

Last updated