Native HUD and menus

Native HUD and menus

Core API available since G1R:MP 0.1.7. These are client-side Lua APIs. The additional crafting component is available from 0.1.9; use matching current client/server versions. This does not make old clients understand the new component.

This API lets a resource hide selected native HUD groups and disable selected native management menus without removing custom RmlUi interfaces or blocking physical keys globally. It does not implement a replacement inventory, character system or quest system.

API overview

Function	Purpose
showNativeHud	Hide or release the six original native HUD groups; from 0.1.9 also crafting presentation, for the calling resource.
setNativeHudComponentVisible	Hide or release one HUD group.
setNativeMenuEnabled	Disable or release a native management menu.
getNativeUiState	Inspect requested and acknowledged policy, readiness and freshness.
resetNativeUi	Release only the calling resource's HUD/menu restrictions.

Results arrive through onClientNativeUiResult. Function and key names are case-sensitive; only the documented lower-camel function names are provided.

HUD component keys

Key	Presentation controlled
bars	Native health, mana, oxygen and related casting/armour bars.
crosshair	Native aiming crosshair.
interaction	Native interaction hints; the underlying interaction remains available.
hotbar	Native hotbar/ammunition presentation, not equipment data or weapon-selection logic.
notifications	Native HUD notification groups. This is not a universal switch for custom RmlUi, chapter or area overlays.
combat_markers	Native overhead health, boss and warning displays; not multiplayer nameplates.
crafting	From 0.1.9: native recipe/main and crafting-progress windows, while preserving station interaction. See Native crafting UI.
all	All supported groups: six before 0.1.9, seven including crafting from 0.1.9.

Hiding HUD components does not disable menus. Disabling menus does not hide the HUD. Neither operation hides multiplayer chat or custom RmlUi documents. The entire native UI root is not removed; unrelated interfaces such as trading, books and lockpicking are outside these component groups.

Native menu keys

Key	Native menu	Default game key
inventory	Inventory	I
stats	Character statistics/development	K
journal	Quest journal	J
glossary	Glossary/information	G
all	All four menus	All above

The policy targets native opening actions, not just these default keyboard mappings. A disabled menu that is already open is closed safely on a later game tick. Allowed menus remain available.

Resource ownership and restoration

• false adds a restriction owned by the calling resource; true releases that resource's restriction. An enabled flag is permission, not a request to open/show a widget.
• Restrictions from multiple resources combine. One resource cannot override another resource's hidden HUD or disabled menu.
• resetNativeUi and resource shutdown release only that resource's restrictions. Restoration respects native visibility rather than making every widget visible unconditionally.
• Desired policies are reapplied when native widgets are recreated. A lost runtime connection or expired 6-second lease releases transient restrictions.
• The always-on multiplayer save/load protections below cannot be released by this API.

Asynchronous results

Mutators return a positive request ID when queued, or false when rejected. A request ID is not confirmation that the native UI has applied the policy. Register the event handler before submitting requests. After several consecutive changes, track the last request: changes are coalesced into the latest complete resource policy, so an acknowledgement is not promised for every intermediate ID.

-- client.lua
local latestRequest

addEventHandler("onClientNativeUiResult", resourceRoot,
    function(requestId, ok, reason, stateJson)
        if requestId ~= latestRequest then return end
        local state = getNativeUiState()
        outputDebugString("Native UI: " .. tostring(reason))
        if ok and state.fresh and state.applied then
            -- The latest restriction has been acknowledged.
            -- Your custom interface may now use its ordinary Lua bindings.
        end
    end)

latestRequest = setNativeMenuEnabled("inventory", false)
if latestRequest == false then
    outputDebugString("Native inventory policy could not be queued")
end

bindKey("i", "down", function()
    -- Show your own declared RmlUi inventory document here.
    -- This example does not create inventory data or a GUI document.
    outputDebugString("Custom inventory key pressed")
end)

-- Independent cinematic HUD policy:
-- latestRequest = showNativeHud(false)
-- Release this resource's restrictions when finished:
-- latestRequest = resetNativeUi()

The result can initially be ok=false with waiting-for-native-ui, followed by applied for the same request when the UI becomes ready. Do not assume one event per request. pending=false alone does not mean success. Check the latest ID, ok, fresh and applied.

The event's stateJson is a JSON string containing the native snapshot; getNativeUiState returns a Lua table that also includes the calling resource's requested state. Before any observation, known and fresh are false and native fields may be absent. Component/menu booleans describe effective permission, not whether a native widget currently exists or is visible.

Input and custom GUI

Use ordinary bindKey bindings for I/K/J/G or your chosen keys. Disabling the native menu does not itself install a binding. Normal chat/GUI focus rules still apply: a focused text field should not trigger gameplay binds. Manage your own RmlUi focus, cursor and bindings separately; resetNativeUi does not close custom documents or remove their bindings.

For per-player control initiated by the server, send a resource-scoped event to the selected player's client script and call the API there. Validate server-side permissions before granting privileged UI actions; hiding menus is not an anti-cheat boundary.

Always-on multiplayer save/load protection

After entering the multiplayer world, native quicksave and quickload actions (normally F5/F9) are blocked. Native Save, Load and Return to Main Menu pause actions are removed/disabled; Resume, Settings and Quit remain available. The native New Game opening route is also guarded. The initial template load needed to enter multiplayer and settings persistence are preserved.

There is no global physical F5/F9 key blocker: resources can bind those keys normally, subject to ordinary input-focus rules. Lua cannot re-enable native single-player save/load with true or resetNativeUi. These protections are independent of whether a resource hides the HUD or disables inventory.

See Scripting limits for ownership/freshness limits and Update 0.1.7 for the release overview.

Crafting presentation from 0.1.9

Available from 0.1.9. Use matching updated clients and server.

Native crafting UI documents the new crafting component, recipe/progress windows, preserved station entry/exit and prevention of invisible recipe starts. It is not a setNativeMenuEnabled key or a custom recipe API. getNativeUiState gains components.crafting, craftingReady, craftingGuardReady, craftingWidgets and craftingObserved; HUD bit 64 is appended, older bits unchanged. Existing resource ownership, asynchronous result handling and restoration still apply. Full station-by-station in-game qualification remains pending.