Developer

Overview

ml_bridge exposes a unified API via the Bridge global table. Any ML script that loads @ml_bridge/init.lua can call Bridge.FunctionName() directly. External scripts can use exports.ml_bridge:FunctionName().

Server Exports

System Info

• Bridge.IsReady(): Returns true when the bridge is initialized
• Bridge.GetFramework(): Returns detected framework name ('qbox', 'qbcore', 'esx', 'standalone')
• Bridge.GetInventorySystem(): Returns detected inventory system ('ox', 'qb', 'ps', 'qs', 'codem', 'core', 'origen', 'tgiann')
• Bridge.SupportsMetadata(): Returns true if the detected inventory supports item metadata
• Bridge.GetPlayers(): Returns table of all online player source IDs

Player Identity

• Bridge.HasPermission(src, permission?): Returns true if the player has admin permission (checks Config.AdminPermissions)
• Bridge.GetPlayer(src): Returns the native framework player object
• Bridge.GetPlayerId(src): Returns the character ID (citizenid for QB, identifier for ESX)
• Bridge.GetPlayerName(src): Returns the Steam/FiveM player name
• Bridge.GetLicense(src): Returns the player's license identifier (license2 preferred)
• Bridge.GetDiscord(src): Returns Discord mention format (<@id>) or 'Not Linked'
• Bridge.GetSteam(src): Returns Steam identifier or 'Unknown'

Job and Duty

• Bridge.GetJob(src): Returns job data table ({ name, grade, label })
• Bridge.SetJob(src, jobName, grade): Sets the player's job
• Bridge.HasJob(src, jobName): Returns true if player has the specified job
• Bridge.GetDuty(src): Returns true if player is on duty
• Bridge.SetDuty(src, status): Sets duty status
• Bridge.GetPlayersByJob(jobName): Returns table of source IDs for all players with the specified job
• Bridge.GetFrameworkJobs(): Returns all registered jobs from the framework

Inventory

• Bridge.HasItem(src, item, amount?): Returns true if player has at least amount (default 1) of the item
• Bridge.GetItemCount(src, item): Returns the count of a specific item
• Bridge.GetItem(src, item): Returns item data object
• Bridge.GetItems(src): Returns all items in the player's inventory
• Bridge.GiveItem(src, item, amount, meta?): Gives an item to the player. Returns success boolean
• Bridge.RemoveItem(src, item, amount): Removes an item from the player. Returns success boolean
• Bridge.GetSlot(src, slot): Returns the item in a specific slot
• Bridge.RemoveSlot(src, slot, count?): Removes items from a specific slot
• Bridge.SetItemMeta(src, slot, metadata): Updates metadata for an item in a slot
• Bridge.CanCarry(src, item, count): Returns true if the player can carry the specified amount
• Bridge.ClearInventory(src): Wipes the player's entire inventory
• Bridge.ConfiscateInventory(src): Confiscates inventory (framework-specific)
• Bridge.RestoreInventory(src, items?): Restores a previously confiscated inventory
• Bridge.GetRegisteredItems(): Returns all items registered in the inventory system
• Bridge.BindUsableItem(item, callback): Registers a usable item handler
• Bridge.DegradeItem(src, slot, amount): Reduces item durability
• Bridge.DrainWeaponDurability(src, weaponHash, amount): Reduces weapon durability
• Bridge.GiveItemToFit(src, item, amount, meta?): Gives as many items as the player can carry. Returns success, actualAmount

Money

• Bridge.GetMoney(src, account?): Returns balance for the specified account (default 'cash')
• Bridge.AddMoney(src, account, amount): Adds money to the specified account
• Bridge.RemoveMoney(src, account, amount): Removes money from the specified account

Stash

• Bridge.OpenStash(src, id, label, slots, weight, items?, props?): Opens a stash for a player
• Bridge.OpenPlayerStash(src, targetSrc, slots, weight): Opens another player's inventory as a stash
• Bridge.GetStash(id): Returns the contents of a stash
• Bridge.IsStashEmpty(id): Returns true if the stash has no items
• Bridge.ClearStash(id): Empties a stash
• Bridge.RegisterInventoryHook(hookType, callback, options?): Registers a hook for inventory events (swapItems, buyItem, etc.)

Player Status

• Bridge.GetMeta(src, key): Returns player metadata for a specific key
• Bridge.SetMeta(src, key, value): Sets player metadata
• Bridge.GetDob(src): Returns the character's date of birth
• Bridge.GetPhone(src): Returns the character's phone number
• Bridge.GetGang(src): Returns the character's gang data
• Bridge.GetHunger(src): Returns hunger value
• Bridge.AddHunger(src, amount): Adds hunger
• Bridge.SetHunger(src, value): Sets hunger to an exact value
• Bridge.GetThirst(src): Returns thirst value
• Bridge.AddThirst(src, amount): Adds thirst
• Bridge.SetThirst(src, value): Sets thirst to an exact value
• Bridge.GetStress(src): Returns stress value
• Bridge.AddStress(src, amount): Adds stress
• Bridge.RemoveStress(src, amount): Removes stress

Life Cycle

• Bridge.Login(src, data): Triggers the player login flow
• Bridge.Logout(src): Triggers the player logout flow
• Bridge.IsPlayerDead(src): Returns true if the player is dead (alias: Bridge.IsDead)
• Bridge.Revive(src): Revives the player

Vehicles

• Bridge.GetOwnedVehicles(src): Returns all vehicles owned by the player
• Bridge.SetVehicleFuel(vehicle, amount): Sets fuel level (requires a server-side entity)

Notification and Logging

• Bridge.NotifyPlayer(src, type, message, duration?): Sends a notification to a player via client event. Types: 'info', 'success', 'error', 'warning'
• Bridge.Log(opts): Multi-provider logging (see Logging section below)

Callbacks

• Bridge.OnServerRequest(name, callback, secure?): Registers a named server-side callback that can be invoked from clients via Bridge.RequestServer. When secure = true, only the registering resource can invoke it

1-- Server: register a callback
2Bridge.OnServerRequest('myScript:getData', function(src, param1)
3    return { result = 'ok', value = param1 }
4end, true) -- secure = true, only this resource can call it

Client Exports

System Info

• Bridge.IsReady(): Returns true when the bridge is initialized
• Bridge.GetFramework(): Returns detected framework name
• Bridge.GetInventorySystem(): Returns detected inventory system
• Bridge.SupportsMetadata(): Returns true if the detected inventory supports item metadata
• Bridge.IsPlayerLoaded(): Returns true when the player character is fully loaded

Inventory

• Bridge.HasItem(item, amount?): Returns true if the local player has the item
• Bridge.GetItem(item): Returns item data for a specific item
• Bridge.GetItems(): Returns all items in the local inventory
• Bridge.GetItemLabel(item): Returns the display label for an item
• Bridge.GetItemDefinitions(): Returns all registered item definitions from the inventory system
• Bridge.GetInventoryImagePath(): Returns the path to inventory images
• Bridge.GetInventoryImageExt(): Returns the image file extension (default .png)
• Bridge.OpenInventory(): Opens the inventory UI
• Bridge.CloseInventory(): Closes the inventory UI
• Bridge.OpenStash(stashId, onClose?): Opens a stash. Accepts an optional onClose callback
• Bridge.OnInventoryChange(callback): Registers a callback fired when inventory content changes
• Bridge.SearchItems(item): Searches the inventory for an item
• Bridge.RegisterItemUse(item, callback): Registers a client-side usable item handler
• Bridge.DisplayMetadata(data): Displays metadata in the inventory UI

Weapons

• Bridge.GetCurrentWeapon(): Returns current weapon data ({ hash, name, slot, durability, melee }) or nil
• Bridge.HasWeaponEquipped(): Returns true if a weapon is equipped

Player State

• Bridge.GetJob(): Returns current job data ({ name, grade, label })
• Bridge.GetPlayerStatus(): Returns hunger, thirst values
• Bridge.IsPlayerDead(): Returns true if the player is dead

Vehicle

• Bridge.GiveVehicleKey(plate): Gives keys for the specified vehicle plate
• Bridge.RemoveVehicleKey(plate): Removes keys for the specified vehicle plate
• Bridge.GetVehicleFuel(vehicle): Returns fuel level
• Bridge.SetVehicleFuel(vehicle, amount): Sets fuel level

UI

• Bridge.Notify(msg, notifType?, duration?): Shows a notification. Types: 'info', 'success', 'error', 'warning'. Duration in ms (default 3000)
• Bridge.ShowTextUI(text, options?): Shows a help text UI element
• Bridge.HideTextUI(): Hides the help text
• Bridge.Progress(options): Shows a progress bar. Returns true if completed
• Bridge.ProgressCircle(options): Shows a circular progress bar
• Bridge.CancelProgress(): Cancels an active progress bar
• Bridge.InputDialog(title, inputs): Opens an input dialog. Returns submitted values
• Bridge.ContextMenu(options): Opens a context menu
• Bridge.ShowMenu(options): Opens a list menu
• Bridge.HideMenu(): Closes the active menu

Dispatch

• Bridge.AlertDispatch(data): Sends a dispatch alert. Auto-detects dispatch system (ps-dispatch, cd_dispatch, qs-dispatch, op-dispatch, rcore_dispatch, origen_police). Falls back to built-in blip+notification system

1Bridge.AlertDispatch({
2    message = 'Store Robbery',
3    description = 'Armed robbery in progress',
4    coords = GetEntityCoords(cache.ped),
5    jobs = { 'police', 'sheriff' },
6    code = '10-31',
7    blip = {
8        sprite = 58,
9        scale = 1.0,
10        color = 1,
11        flash = true,
12        text = 'Robbery'
13    },
14})

The fallback creates a map blip that lasts 2 minutes and shows a phone notification.

Target Interactions

Target interactions are handled through ml_bridge. Supports ox_target, qb-target, sleepless_interact, and a TextUI fallback.

• Bridge.AddEntityTarget(entity, options): Adds target options to a specific entity
• Bridge.RemoveEntityTarget(entity, options?): Removes target from an entity
• Bridge.AddModelTarget(model, options): Adds target to all entities with a specific model
• Bridge.RemoveModelTarget(model, options?): Removes model target
• Bridge.AddPlayerTarget(options): Adds target options to players
• Bridge.RemovePlayerTarget(options?): Removes player target
• Bridge.AddVehicleTarget(options): Adds target options to vehicles
• Bridge.RemoveVehicleTarget(options?): Removes vehicle target
• Bridge.AddPedTarget(options): Adds target options to peds
• Bridge.RemovePedTarget(options?): Removes ped target
• Bridge.AddNetEntityTarget(netId, options): Adds target to a network entity by net ID
• Bridge.RemoveNetEntityTarget(netId, options?): Removes target from net entity
• Bridge.AddZoneTarget(options): Adds a box-zone target
• Bridge.RemoveZoneTarget(name): Removes a zone target
• Bridge.AddTargetZone(options): Alias for AddZoneTarget
• Bridge.RemoveTargetZone(name): Alias for RemoveZoneTarget
• Bridge.AddTargetSphereZone(options): Adds a sphere-zone target
• Bridge.RemoveTargetSphereZone(name): Removes a sphere-zone target
• Bridge.DisableTargeting(disabled): Globally disables/enables the targeting system

Minigames

• Bridge.KeySequence(coords, length, hiddenMode, label?, infoText?): Shows a 3D key sequence minigame at world coords. Player must press length random keys (V, C, E, F, G, H, I, X) in order. hiddenMode scrambles upcoming keys. Returns true on success, false on ESC/wrong key
• Bridge.HoldKeySequence(coords, rows, length, timePerKey, label?, infoText?): Shows a multi-row hold-key minigame. Each key must be held for timePerKey ms. rows defines parallel sequences. Returns true on completion
• Bridge.ProgressBar3D(coords, duration, scale?, distance?): Shows a 3D progress bar in world space at coords. Fades in, fills over duration ms, then fades out. scale controls size (default 1), distance is max render distance (default 10). Returns true when done

Callbacks

• Bridge.RequestServer(name, ...): Sends a named request to the server and yields the current coroutine until a response arrives (10s timeout). Must be called inside a CreateThread. Returns the callback result

1-- Client: call a server callback
2CreateThread(function()
3    local data = Bridge.RequestServer('myScript:getData', 'hello')
4    print(data.result) -- 'ok'
5end)

Server Logging API

Bridge.Log sends logs to one or more providers (Discord, ox_lib, FiveManage) based on Config.LogProvider.

1Bridge.Log({
2    webhook = 'https://discord.com/api/webhooks/...',
3    title = 'Item Looted',
4    description = 'Player picked up AK-47',
5    color = 'green',
6    player = source,
7    target = targetSource,
8    fields = {
9        { name = 'Item', value = 'AK-47', inline = true },
10        { name = 'Zone', value = 'Military Base', inline = true },
11    },
12})

• webhook: Discord webhook URL. Set to false to skip this log
• title: Embed title
• description: Embed description
• color: Color name ('blue', 'green', 'yellow', 'orange', 'red', 'purple', 'white')
• player: Source ID. Automatically includes player name, RP name, citizen ID, job, license, Discord, Steam
• target: Target source ID. Same fields as player
• fields: Additional embed fields
• provider: Override the global Config.LogProvider for this specific log
• dataset: Override FiveManage dataset

Server Events

• ml_bridge:server:playerLoaded: Fires when a player finishes loading (any framework: QBCore, QBox, ESX). Automatically re-caches player identifiers
• ml_bridge:server:playerUnloaded: Fires when a player disconnects or unloads

Spatial Utility (Client)

The Spatial global provides a sector-based proximity tracker. It divides the map into 200m sectors and only checks nearby nodes, making it efficient for large numbers of tracked points.

• Spatial.Track(id, target, distance, onEnter?, onExit?): Tracks a position (vec3) or entity (number). Fires onEnter when player is within distance, onExit when leaving. Returns the node
• Spatial.Remove(id): Stops tracking a node
• Spatial.StartLoop(): Starts the proximity check loop (called automatically on first Track)

1Spatial.Track('mySpot', vec3(200, 300, 30), 5.0,
2    function(self) print('Entered zone') end,
3    function(self) print('Left zone') end
4)
5
6-- Later
7Spatial.Remove('mySpot')