Events and State Bags

Use exports for direct client integrations when one exists. Events are provided for compatibility bridges, server-to-client UI calls, configurable phone hooks, and common framework resources. State bags are preferred for continuously owned gameplay state because they replicate and survive resource boundaries cleanly.

Public events

See Interface APIs for notification, Text UI, progress bar, and skill-check payloads.

Trigger and close onboarding

From another client resource:

TriggerEvent('orbit-dynamichud:client:openOnboarding')

Close the current flow from another client resource:

TriggerEvent('orbit-dynamichud:client:closeOnboarding')

From the server, target the player after your character, spawn, or tutorial flow is complete:

TriggerClientEvent(
    'orbit-dynamichud:client:openOnboarding',
    source
)

-- The same event can be targeted later if an external flow must close it.
TriggerClientEvent(
    'orbit-dynamichud:client:closeOnboarding',
    source
)

The open event never forces onboarding onto a client that already completed it. Start requests are ignored when onboarding is disabled or settings are locked, and manual starts do not create the automatic first-run polling thread. The close event is idempotent and may be called even when onboarding is already closed. Prefer the matching startOnboarding and closeOnboarding client exports when integrating from another local resource. See Onboarding for the complete mode and lifecycle guide.

Open a control-panel page

TriggerEvent('orbit-dynamichud:openControlPanel', 'customize', 'shape_selector')

From a server script, target the player:

TriggerClientEvent(
    'orbit-dynamichud:openControlPanel',
    source,
    'settings',
    'audio'
)

Supported category and subcategory IDs are:

The requested category and subcategory must be enabled by Config.ControlPanel. The car-control category opens only while the player is in a vehicle. Settings Share does not open while settings are locked or its launcher is disabled. Omitting IDs opens the normal/default control-panel page.

Phone open and close events

The event names are configurable in Config.PhoneOffset:

Config.PhoneOffset = {
    enabled = true,
    side = 'right',
    offset = 18.0,
    openEvent = 'orbit-dynamichud:phoneOpened',
    closeEvent = 'orbit-dynamichud:phoneClosed'
}

Trigger the configured events from the phone resource:

TriggerEvent('orbit-dynamichud:phoneOpened', 'right')
TriggerEvent('orbit-dynamichud:phoneClosed')

The open payload may be "left", "right", or a table with side or position. A valid payload overrides the configured side for that opening. The events are registered as network events, so server resources may target a client when necessary.

Framework compatibility events

These events exist for compatibility with common ESX, QB, and QBX resources. New standalone integrations should prefer the state bags in the next section.

TriggerEvent('hud:client:UpdateNeeds', 82, 64)
TriggerEvent('hud:client:UpdateStress', 15)

State bags

Player state

Set authoritative player state on the server with replication enabled:

Player(source).state:set('hud:deathState', 2, true)
Player(source).state:set('stress', 35, true)
Player(source).state:set('hud:showHud', true, true)

A client-owned vehicle resource can update its local state when appropriate:

LocalPlayer.state:set('seatbelt', true, true)
LocalPlayer.state:set('cruiseControl', false, true)

Do not write unchanged state every frame. Update only when the value changes.

Vehicle state

DynamicHUD reads these state bags from the current vehicle:

local vehicle = cache.vehicle
if vehicle then
    Entity(vehicle).state:set('nitro', 75, true)
    Entity(vehicle).state:set('nitroFlames', true, true)
end

DynamicHUD checks that the changed vehicle matches the player's current vehicle before updating the speedometer.

Global state

DynamicHUD publishes server population values for its own player-count UI. Other resources may read them without polling GetPlayers():

These values are outputs owned by DynamicHUD. Do not overwrite them from another resource.

Inventory and death handlers

For inventories that publish invOpen, no extra hide/show event is needed. Otherwise, use the server toggleHud export in your inventory's server handlers:

AddEventHandler('my_inventory:opened', function(source)
    exports['orbit-dynamichud-v2']:toggleHud(source, false)
end)

AddEventHandler('my_inventory:closed', function(source)
    exports['orbit-dynamichud-v2']:toggleHud(source, true)
end)

For custom medical resources, set hud:deathState rather than calling internal NUI events.

The editable server/handlers.lua file contains starter hooks for common inventory, QB hospital, and ESX death events. Event names and signatures vary between resource versions, so keep only the handlers that match your server and adapt them to the state/export patterns above.

Internal events

Sound synchronization, Settings Share callbacks, car-control status, NUI callbacks, and orbit-dynamichud:client:updateSound are internal implementation details. Do not call them from third-party resources. Their payloads are validated for the owning UI flow and can change without being part of the public API.