Vanilla blips and mappins

Open77.blips creates native mappins for the HUD, minimap and world map. Visibility depends on the sprite's native profile. Client resources require ui.vanilla.map:

permissions { "ui.vanilla.map" }

The ids returned are 64-bit decimal strings. Keep them as they are: never convert them with tonumber.

Use this guide to mark a position or an entity on the player's map, minimap, and HUD.

A first blip#

local blip, reason = Open77.blips.create({
    position = { x = -1442.2, y = 127.4, z = 18.0 },
    sprite = "objective",
    title = "Vehicle Dealership",
    description = "Purchase and collect street-legal vehicles.",
    active = true,
    visibleThroughWalls = false
})

assert(blip, reason)
assert(Open77.blips.setPosition(blip, { x = -1440.0, y = 130.0, z = 18.0 }))
assert(Open77.blips.setSprite(blip, "VehicleVariant"))
assert(Open77.blips.remove(blip))

Custom SVG icons and colors#

Client only · Experimental. SVG rendering and per-blip colors require Cyberpunk 2077 2.31 and an OPEN//77 client with the native SVG adapter. See Custom SVG blips for a complete resource, supported SVG features, limits and troubleshooting.

Declare the icon in your resource's manifest:

files { "icons/fuel.svg" }
permissions { "ui.vanilla.map" }

Create the blip in its client script after the player has entered the world:

local station, reason = Open77.blips.create({
    position = { x = -595.785522, y = -722.328979, z = 8.715637 },
    sprite = "tech",
    title = "Fuel station",
    icon = { asset = "icons/fuel.svg", size = 48 },
    color = "#FFCC00"
})
assert(station, reason)

assert(Open77.blips.setColor(station, "#00CCFF80"))
assert(Open77.blips.setColor(station, false)) -- source colors
assert(Open77.blips.setIcon(station, false)) -- native sprite

The icon is rendered as native Ink geometry, while the mappin retains selection, tracking and tooltips. Use a declared resource-relative SVG path or { asset, size }; URLs and raster images are rejected. Size defaults to 48 and accepts 16–128 native Ink units.

color accepts #RRGGBB, #RRGGBBAA or false. It also works without an SVG and affects only that owned blip. Clearing an icon preserves its color override. For SVGs the override replaces RGB and multiplies source alpha. Invalid replacements leave the existing icon unchanged.

Following an entity#

A blip can follow an Open77 entity instead of a position:

local playerBlip = assert(Open77.blips.create({
    entity = remotePlayerEntityId,
    sprite = "remote_player",
    slot = "poi_mappin",
    offset = { x = 0.0, y = 0.0, z = 2.0 }
}))

Open77.blips.attachToEntity(playerBlip, anotherEntityId, "poi_mappin", {
    x = 0.0, y = 0.0, z = 2.0
})

position and entity are mutually exclusive at creation. setPosition turns an attached blip into a positional one. In update, entity = false only detaches when a new position is supplied.

A calculated GPS route#

Tracking a normal static point selects its mappin but does not make REDengine calculate a road path. Create a positional blip with routable = true, then track it:

local destination = assert(Open77.blips.create({
    position = { x = -1442.2, y = 127.4, z = 18.0 },
    routable = true,
    title = "Next checkpoint"
}))

local ok, changed = Open77.blips.track(destination)
assert(ok, changed)

The routable form uses the trusted Mappins.CustomPositionMappinDefinition and CustomPositionVariant pair used by a right-click waypoint. Its sprite is therefore fixed to the custom-waypoint variant. It cannot follow an entity. REDengine owns the road calculation and the minimap/HUD path. A generic waypoint does not automatically create the orange 3D chevrons used by the authored sq024 street race; those are separate world entities. update can move the destination but cannot change routable; remove and recreate it to change kind.

Full API#

create options: position or entity, sprite, title, description, icon, color, active, visibleThroughWalls, range, routable, plus slot and offset for an entity. label remains an alias for title; do not provide both. update accepts the mutable fields (not routable), and the dedicated setters can change text at runtime. The quotas are 128 blips per resource and 512 per client. Stopping, reloading, and leaving the world clean up blips automatically.

A resource can neither read, change, nor delete another resource's blip. The TweakDB type is fixed to Mappins.DefaultStaticMappin, or to the single trusted custom-position definition when routable = true; downloaded packages cannot inject an arbitrary UI profile.

title and description are resource-owned text. When the player highlights the blip on the fullscreen map, Open77 replaces the variant-specific tooltip with those exact values. Variant-specific fixer progress, threat, journal, price and travel panels are hidden for Open77 blips. HUD-only variants can still be absent from the fullscreen map; use a map-capable sprite such as objective, quest, fast_travel, vehicle, or a service-point variant when map selection is required.

Stable aliases#

Exact names are insensitive to case, spaces, hyphens, and underscores. Aliases are preferable for generic gameplay; full names are useful when a server wants one specific vanilla asset.

Complete sprite list (Cyberpunk 2077 2.31)#

Count=147 and Invalid=148 are sentinels and are not accepted. The usable values are:

A variant existing in the enum does not guarantee its profile renders on every surface. The CPO_* variants, for instance, come from a dormant multiplayer HUD and must be checked visually in the server's context.

A blip that only shows up close#

range switches a blip off once the player is further away than the given number of metres, and back on when they return. This visibility gate is independent of SVG styling and color.

-- A shop pin that stops cluttering the map from across the city.
local shop = assert(Open77.blips.create({
    position = { x = -1442.2, y = 127.4, z = 18.0 },
    sprite = "vendor",
    title = "Kabuki Market",
    range = 180
}))

Open77.blips.setRange(shop, 400)     -- widen it
Open77.blips.setRange(shop, false)   -- or take the gate off entirely
print(Open77.blips.get(shop).range)  -- 0 when there is no gate

It is Open77's own doing, not an engine property. There is no range field on a mappin. What the engine publishes is SetMappinActive, so Open77 measures the distance from the player on the game thread and drives that one call — only on a transition, and only for blips that asked for a range, so a client whose resources never use it pays nothing. An entity-following blip is measured from the body it follows; while that body is not streamed in, the gate keeps whatever state it last wrote rather than guessing a distance.

It is therefore not FiveM's SetBlipAsShortRange. That one hides a blip from the minimap and leaves it on the world map. Cyberpunk offers no per-surface control here, so out of range means off on the HUD, the minimap and the world map. The name is range and not shortRange for exactly that reason, and shortRange is refused by name rather than quietly given these different manners.

range composes with active instead of overriding it: a blip you set inactive stays inactive in range, and a ranged blip you re-activate while out of range stays hidden until you walk back. Limits are 0 (no gate, the default) to 4000 metres; anything else is invalid_range.

Unsupported FiveM options#

Use the OPEN//77 options instead of FiveM palette IDs or per-surface visibility flags. Unsupported properties return a reason on both create and update.

Native sprites keep their default colors unless color overrides them. Custom SVGs do not add native variant IDs or mount archives. Keep a suitable sprite for native behavior and fallback.

track(id) selects the blip as the manually tracked mappin and returns changed = false when it is already tracked. A road route additionally requires routable = true at creation. untrack(id) only clears tracking if that blip is selected; it does not remove another resource's destination or a vanilla objective.

The player's waypoint#

track and untrack above act on your blip. The waypoint is the other half: the destination the player chose, which until now no resource could see or move.

-- A taxi fare: take the destination the player pinned on their own map.
local to = Open77.blips.waypoint()
if to then
    Open77.events.emitServer("taxi:requestRide", to)
end

-- Or route them somewhere the job picked.
Open77.blips.setWaypoint({ x = -1540.0, y = -2020.0, z = 24.0 })

AddEventHandler("open77:waypointChanged", function(state)
    if state.present then
        print(("waypoint moved to %.0f, %.0f"):format(state.position.x, state.position.y))
    else
        print("waypoint cleared")
    end
end)

In this engine a waypoint is not a separate thing: it is the manually tracked mappin, the same selection track writes. setWaypoint registers a routable custom-position pin and tracks it, so the vanilla GPS calculates a road route exactly as it does for a waypoint the player set by hand.

Four behaviours worth knowing, each of which exists because the alternative bites:

• nil and nil, reason are different answers. nil alone means there is no waypoint; nil with a reason means the question could not be asked. A GPS script must branch on that, because cancelling a fare is correct for only the first.
• The pin is yours and dies with you. It is an ordinary blip owned by the calling resource, so a crashed taxi script leaves no permanent arrow on the player's map. It also counts against your 128-blip quota -- but calling setWaypoint again moves the same pin rather than registering another, so updating a destination on a timer is safe.
• clearWaypoint is not owner-scoped, and untrack is. Clearing the waypoint means the player's waypoint, whoever set it, because that is what a route-cancel button does. It still refuses to destroy another resource's pin: only the tracking selection is released.
• The event covers waypoints Open77 did not set. The engine raises nothing when a player right-clicks the fullscreen map, so Open77 polls the tracked mappin and publishes the difference. That poll is the only channel by which a player-chosen destination reaches a resource at all.

open77:waypointChanged carries one table, { present, position }, rather than three loose coordinates: a cleared waypoint has to be a value a handler can read, not an absence of arguments.