Open77.map

Open77.map.addTab(options)

Add a resource WebUI tab beside the native Map tab.

Client-only, map.control; after resource preparation. Options: id, label, exactly one of url (declared local web file) or page (owned, hidden WebUI), optional integer order. Returns qualified resource:id and the page. Max five custom tabs. Shell owns visibility/focus/bounds; pages keep state between visits. See native-map.md for events, ready handshake, errors and cleanup.

AddEventHandler('onClientResourceStart', function()
    local id, page = Open77.map.addTab({id='jobs', label='Jobs', url='web/jobs.html', order=10})
    if not id then print(page) end
end)

Native map & waypoints guide · Registered in ResourceHost.cpp as LuaMapAddTab (line 25357).

Open77.map.cancelPick()

Cancels this resource's outstanding native map request.

Requires map.control. Returns true or false, reason. The requester receives open77:map:pointPicked with status='cancelled' when a picker was active. Resource shutdown also releases its UI ownership without delivering events to its replacement instance.

-- ESC cancels the pending "choose a destination" picker
RegisterKeyMapping("taxi_cancel", "Cancel destination", "BACKSPACE", function()
    Open77.map.cancelPick()
end)

Native map & waypoints guide · Registered in ResourceHost.cpp as LuaMapCancelPick (line 25368).

Open77.map.close()

Closes a map session opened by this resource.

Requires map.control. Returns true on accepted closure, otherwise false, reason. Cannot close a user-opened map or another resource's map. Closure is asynchronous. A pending picker is cancelled.

-- Close the map this resource opened once the destination is chosen
AddEventHandler("open77:map:pointPicked", function(result)
    if result.status == "selected" then Open77.map.close() end
end)

Native map & waypoints guide · Registered in ResourceHost.cpp as LuaMapClose (line 25366).

Open77.map.focus(position)

Focus an owned map on a world position without moving the player.

Requires map.control and ownership acquired through open or pickPoint. Pass finite x/y/z within +/-16000. Returns an asynchronous request ID; commandResult reports application. Rejects closed, busy, unready or foreign-owned maps. See native-map.md.

-- After opening this resource's map and observing ready=true:
local request, reason = Open77.map.focus({x=600, y=-2200, z=180})

Native map & waypoints guide · Registered in ResourceHost.cpp as LuaMapFocus (line 25361).

Open77.map.getScreen()

Read the native map shell, appearance and registered tabs.

Client-only, map.read. Returns title, accentColor, activeTab, open, revision and tabs. Available while closed. Map is built in; resource tabs are namespaced. See native-map.md for WebUI lifecycle and ownership.

local screen = Open77.map.getScreen()
if screen then print(screen.title, screen.activeTab) end

Native map & waypoints guide · Registered in ResourceHost.cpp as LuaMapGetScreen (line 25353).

Open77.map.getSelectedMarker()

Reads the marker highlighted in the vanilla map.

Requires map.read. Returns a marker table or nil. kind distinguishes waypoint, quest, poi, resource and unknown. Selection is not the same as the player's waypoint; highlighting a marker does not change navigation.

-- Read what the player highlighted on the map
local marker = Open77.map.getSelectedMarker()
if marker then print(marker.kind, marker.position.x, marker.position.y) end

Native map & waypoints guide · Registered in ResourceHost.cpp as LuaMapGetSelectedMarker (line 25349).

Open77.map.getView()

Read the native map camera and readiness snapshot.

Requires map.read. Returns ready, zoomLevel, zoomLevels, zoom and cameraMode, or nil, reason. The native scalar zoom is not a world distance. Wait for ready before controlling an owned map. See native-map.md.

local view, reason = Open77.map.getView()
if view and view.ready then print(view.cameraMode, view.zoomLevel) end

Native map & waypoints guide · Registered in ResourceHost.cpp as LuaMapGetView (line 25352).

Open77.map.getWaypoint()

Reads the player's manual vanilla waypoint.

Returns nil (without an error) when no player waypoint is tracked. Quest, POI and Open77 resource markers are excluded. Requires map.read. The result has a string id, kind='waypoint', source='player', position={x,y,z} and revision. Errors return nil, reason; map_unavailable means the world snapshot is unavailable or stale.

-- Send the player's manual waypoint to the server as the taxi destination
local waypoint = Open77.map.getWaypoint()
if waypoint then TriggerServerEvent("taxi:order", waypoint.position) end

Native map & waypoints guide · Registered in ResourceHost.cpp as LuaMapGetWaypoint (line 25348).

Open77.map.isOpen()

Checks whether the vanilla world map is open.

Requires map.read. Returns a boolean, or nil, reason when map state is unavailable. Uses native map controller lifecycle callbacks.

-- Pause the HUD timer while the map is open
SetTick(function()
    if not Open77.map.isOpen() then timer = timer + 1 end
end)

Native map & waypoints guide · Registered in ResourceHost.cpp as LuaMapIsOpen (line 25350).

Open77.map.open([options])

Opens the standalone native map, optionally focused on a world location.

Requires map.control. options.position={x,y,z} optionally focuses the map. Returns requestId, or nil, reason. Acceptance is asynchronous; observe open77:map:opened or open77:map:requestFailed. Respects game UI restrictions and exclusive ownership; map_busy means another map session exists.

-- Open the map focused on the meeting point
Open77.map.open({ position = { x = -1442.2, y = 127.4, z = 18.0 } })

Native map & waypoints guide · Registered in ResourceHost.cpp as LuaMapOpen (line 25365).

Open77.map.pickPoint([options])

Lets the player select a native map point without travel.

Requires map.control. Optional position={x,y,z} and timeoutMilliseconds (1000..300000, default 60000). Returns requestId or nil, reason. open77:map:pointPicked is delivered only to the requesting resource, with requestId, status, position and marker. Use the vanilla waypoint gesture to select. Fast travel, taxi confirmation and Open77 admin map teleport are suppressed during the picker.

-- Let the player pick a taxi destination on the map, one minute to decide
local requestId = Open77.map.pickPoint({ timeoutMilliseconds = 60000 })
AddEventHandler("open77:map:pointPicked", function(result)
    if result.requestId ~= requestId then return end
    if result.status == "selected" then TriggerServerEvent("taxi:order", result.position) end
end)

Native map & waypoints guide · Registered in ResourceHost.cpp as LuaMapPickPoint (line 25367).

Open77.map.recenter()

Recenter an owned native map on the local player.

Requires map.control and an open, ready map owned by this resource. Moves only the map camera. Returns a request ID or nil, reason; observe open77:map:commandResult. User-opened maps cannot be hijacked.

local request, reason = Open77.map.recenter()
if not request then print(reason) end

Native map & waypoints guide · Registered in ResourceHost.cpp as LuaMapRecenter (line 25362).

Open77.map.removeTab(id)

Unregister this resource's map shell tab.

Client-only, map.control. Local or qualified owned ID. Cannot remove Map or a foreign tab. Active removal returns to Map and releases focus. The page remains hidden; explicitly destroy it when no longer needed. Resource-stop cleanup is automatic.

local ok, reason = Open77.map.removeTab('jobs')

Native map & waypoints guide · Registered in ResourceHost.cpp as LuaMapRemoveTab (line 25358).

Open77.map.resetAppearance()

Release this resource's map title and accent overrides.

Client-only, map.control; after resource preparation. Restores preceding resource claims or defaults, without clearing another resource's settings or unregistering any tabs.

local ok, reason = Open77.map.resetAppearance()

Native map & waypoints guide · Registered in ResourceHost.cpp as LuaMapResetAppearance (line 25356).

Open77.map.selectTab(id)

Select an owned WebUI tab or the native Map on an open shell.

Client-only, map.control. Accepts own local/qualified ID or map. Requires an open shell, rejects point-picker sessions and foreign tabs. Returns queue acceptance; applied next tick. Observe tabEntered/tabLeft (owner), tabChanged (map.read), or JS tabState. Does not implicitly open the map.

local ok, reason = Open77.map.selectTab('map')

Native map & waypoints guide · Registered in ResourceHost.cpp as LuaMapSelectTab (line 25359).

Open77.map.setAccentColor(color)

Set the native map shell's resource-owned accent color.

Client-only, map.control; after resource preparation. Exact #RRGGBB string. Updates the selected native tab and supplies the color to resource WebUIs through screenChanged/tabState events. Does not recolor the native roads or markers. See native-map.md.

AddEventHandler('onClientResourceStart', function()
    Open77.map.setAccentColor('#FFB347')
end)

Native map & waypoints guide · Registered in ResourceHost.cpp as LuaMapSetAccent (line 25355).

Open77.map.setCameraMode(mode)

Select the native top-down or perspective map camera.

Requires map.control and ownership of an open, ready map. mode must be top_down or perspective. Returns a request ID or nil, reason. Never changes the gameplay camera or teleports the player. See native-map.md for asynchronous result events and cleanup.

local request, reason = Open77.map.setCameraMode("perspective")

Native map & waypoints guide · Registered in ResourceHost.cpp as LuaMapSetCameraMode (line 25364).

Open77.map.setTabLabel(id, label)

Rename this resource's native map shell tab.

Client-only, map.control. Local or qualified owned ID; label is 1-40 UTF-8 bytes, without controls or pipe. Updates live without recreating the browser or losing page state. Map and other resources' tabs are immutable to the caller.

local ok, reason = Open77.map.setTabLabel('jobs', 'Contracts')

Native map & waypoints guide · Registered in ResourceHost.cpp as LuaMapSetTabLabel (line 25360).

Open77.map.setTitle(text)

Customize the upper-left native map shell title.

Client-only, map.control; call after resource preparation. 1-120 UTF-8 bytes, no control characters or pipe. Resource-owned override: latest setter wins, resetAppearance or resource stop restores the preceding claim. See native-map.md.

AddEventHandler('onClientResourceStart', function()
    Open77.map.setTitle('NIGHT CITY ROLEPLAY')
end)

Native map & waypoints guide · Registered in ResourceHost.cpp as LuaMapSetTitle (line 25354).

Open77.map.setZoomLevel(level)

Select a native discrete zoom level on an owned map.

Requires map.control and ownership of an open, ready map. level is an integer from 0 to getView().zoomLevels-1. Returns request ID or nil, reason. The ID acknowledges queueing, not camera-transition completion; observe commandResult and viewChanged.

local view = Open77.map.getView()
if view and view.ready and view.zoomLevels > 2 then Open77.map.setZoomLevel(2) end

Native map & waypoints guide · Registered in ResourceHost.cpp as LuaMapSetZoomLevel (line 25363).

Open77.map.state()

Reads a coherent native map snapshot.

Requires map.read. Returns open, picking, waypoint, selectedMarker, revision and sampleAgeMs, or nil, reason. Read this on resource startup before subscribing to change events; no historical placement event is synthesized.

-- Read the whole map state once at startup, before subscribing to events
local map = Open77.map.state()
if map and map.waypoint then print("waypoint already set at", map.waypoint.position.x) end

Native map & waypoints guide · Registered in ResourceHost.cpp as LuaMapState (line 25351).