Open77.markers

Open77.markers.clear()

Removes every 3D marker owned by the calling resource.

Requires world.markers; other resources are unaffected.

-- The race is over: remove every checkpoint marker
AddEventHandler("race:finished", function()
    Open77.markers.clear()
end)

3D world markers guide · Registered in ResourceHost.cpp as LuaMarkerClear (line 25493).

Open77.markers.create(options)

Creates a resource-owned 3D world marker.

Requires world.markers. Options require position and accept shape, style, radius, height, scale = {x,y,z}, rotation = {x,y,z} in degrees, color = {r,g,b,a}, maxDistance, minDistance, and visible. Color channels are integers from 0 to 255; omitted alpha defaults to 180. Eight native mesh shapes are listed by shapes(). The returned decimal-string handle preserves its full 64-bit identity. Creation is asynchronous: inspect get(id).failed and error for loading failures. Markers are local, resource-owned and cleaned up when their resource stops; they do not provide collision or gameplay authority.

-- A cylinder marker at the delivery point, visible within 80 m
local marker = Open77.markers.create({
    position = { x = -1442.2, y = 127.4, z = 18.0 },
    shape = "cylinder",
    radius = 1.5,
    maxDistance = 80,
})

3D world markers guide · Registered in ResourceHost.cpp as LuaMarkerCreate (line 25490).

Open77.markers.get(id)

Reads one 3D marker owned by the calling resource.

Requires world.markers. Returns the same snapshot fields as list(), including height, scale, rotation, color, customColor, rendered, failed and optional error. Unknown or foreign handles return nil, not_found; a malformed handle returns nil, invalid_marker_id. A valid handle can still be loading: rendered does not certify on-screen visibility.

local state, reason = Open77.markers.get(marker)
if state and state.failed then
    print(state.error)
end

3D world markers guide · Registered in ResourceHost.cpp as LuaMarkerGet (line 25495).

Open77.markers.list()

Lists the calling resource's 3D markers.

Requires world.markers. Each snapshot includes its requested definition, effective color, and native loading state. rendered means attached and enabled, not necessarily on-screen or unoccluded. failed and optional error expose asynchronous asset or streaming failures.

-- Debug: are our markers actually rendered?
for _, marker in ipairs(Open77.markers.list() or {}) do
    print(marker.id, marker.rendered)
end

3D world markers guide · Registered in ResourceHost.cpp as LuaMarkerList (line 25494).

Open77.markers.remove(id)

Removes one resource-owned 3D marker.

Requires world.markers.

-- The player reached the checkpoint: remove its marker
Open77.markers.remove(checkpointMarker)

3D world markers guide · Registered in ResourceHost.cpp as LuaMarkerRemove (line 25492).

Open77.markers.shapes()

Lists the eight supported native 3D marker shapes.

Returns ring, cylinder, checkpoint, arrow, chevron, cone, diamond and sphere. These are stable string identifiers, not numeric marker types from another game. Reading this static catalogue needs no permission; creating or inspecting markers requires world.markers.

for _, shape in ipairs(Open77.markers.shapes()) do
    print(shape)
end

3D world markers guide · Registered in ResourceHost.cpp as LuaMarkerShapes (line 25496).

Open77.markers.update(id, patch)

Patches a resource-owned 3D marker.

Requires world.markers. Only supplied fields are changed, and ownership prevents mutation of another resource's marker. Accepts the create options, including height, scale, rotation and RGBA color. color = false restores the named style palette; alpha zero hides the marker. Invalid patches are rejected atomically. Color and shape changes replace the native entity asynchronously while preserving the handle; avoid per-frame color updates.

-- Move the marker to the next checkpoint
RegisterNetEvent("race:checkpoint", function(position)
    Open77.markers.update(checkpointMarker, { position = position })
end)

3D world markers guide · Registered in ResourceHost.cpp as LuaMarkerUpdate (line 25491).