Vanilla blips and mappins

CyberM.blips creates real Cyberpunk 2077 mappins. Depending on the vanilla profile attached to the sprite, the same blip can appear in the HUD, the minimap, and the world map. The API requires this permission:

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 = CyberM.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(CyberM.blips.setPosition(blip, { x = -1440.0, y = 130.0, z = 18.0 }))
assert(CyberM.blips.setSprite(blip, "VehicleVariant"))
assert(CyberM.blips.remove(blip))

Custom PNG icons#

Declare every client asset in cyberm.lua. Undeclared files cannot be used as textures:

files { "assets/blips/*.png" }
permissions { "ui.vanilla.map" }

Then validate the texture and associate it with the blip. The native sprite provides the actual rendering, selection, filtering, GPS routing, and fullscreen-map tooltip on Cyberpunk 2077 2.31.

local jobIcon, reason = CyberM.assets.texture("assets/blips/job-center.png")
assert(jobIcon, reason)

local jobCenter = assert(CyberM.blips.create({
    position = { x = -1442.2, y = 127.4, z = 18.0 },
    sprite = "tech",
    title = "Job Center",
    description = "Browse available civilian jobs and city contracts.",
    icon = { asset = jobIcon.asset, size = 56 }
}))

assert(CyberM.blips.setIcon(jobCenter, "assets/blips/job-center.png"))
assert(CyberM.blips.setIcon(jobCenter, false)) -- restore the native sprite

icon accepts a declared asset path, the descriptor returned by CyberM.assets.texture, or a table { asset = path, size = pixels }. Display size is limited to 16..128 pixels. Textures are currently PNG only, at most 512 KiB and 512×512. The test asset is 128×128 with transparency.

The downloaded PNG compositor is disabled on Cyberpunk 2077 2.31. REDengine applies mappin projection after the normal Ink transform pass: script-visible widget coordinates remain local, and reading or forcing fullscreen-map layout while its native tree is being constructed causes an engine null dereference. CyberM therefore keeps and validates the icon metadata but deliberately renders the native sprite. This is a compatibility fallback, not a promise that the PNG appears.

CyberM.assets.list() returns the current resource's declared files; texture(path) returns { type, asset, mime, width, height, bytes } without exposing the file contents.

A blip can follow a CyberM entity instead of a position:

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

CyberM.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.

Full API#

create options: position or entity, sprite, title, description, icon, active, visibleThroughWalls, plus slot and offset for an entity. label remains an alias for title; do not provide both. update accepts the same fields, 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; 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, CyberM replaces the variant-specific tooltip with those exact values. Variant-specific fixer progress, threat, journal, price and travel panels are hidden for CyberM 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.

Colour, size, text, and tracking#

gamemappinsMappinData carries neither colour nor scale. Those properties belong to the UI/TweakDB profile the game picks. The API therefore offers no fake color or scale that would do nothing.

title and description are kept in CyberM's private mappin data. The fullscreen-map tooltip reads those values after vanilla setup, so a highlighted blip can display guaranteed free-form text such as Job Center and a multiline description. Limits are 128 and 1024 UTF-8 bytes respectively. The HUD does not permanently draw that text next to the icon.

Custom PNG icons are not converted into gamedataMappinVariant values. CyberM keeps the native mappin and its declared icon metadata, but 2.31 renders only the native sprite for stability. WebP and runtime REDengine archive mounting are not supported.

The native system can clear the current tracking and set an alternative, but offers no safe TrackMappin(id). The world map tracks a UI controller, not a raw id. untrack(id) therefore checks that the requested mappin really is the tracked one before doing anything; it cannot remove a vanilla objective.