Developer

8 min readUpdated 2 weeks ago

Overview

Scripts that load @ml_bridge/init.lua call the Bridge table directly, such as Bridge.GiveItem(source, 'bread', 1). Other resources call the same functions as exports: exports.ml_bridge:GiveItem(source, 'bread', 1).

fxmanifest.lua
1shared_scripts {
2    '@ox_lib/init.lua',
3    '@ml_bridge/init.lua',
4}

Server Functions

System

  • Bridge.IsReady(): true once detection has finished
  • Bridge.GetFramework(): 'qbox', 'qbcore', 'esx', 'oxcore' or 'standalone'
  • Bridge.GetInventorySystem(): detected inventory, such as 'ox' or 'qb'
  • Bridge.SupportsMetadata(): true when the inventory stores item metadata
  • Bridge.HasTargetSystem(), Bridge.GetTargetSystem(): whether a target resource runs, and which one
  • Bridge.GetPlayers(): sources of every online player

Identity

  • Bridge.HasPermission(src, permission?): true for admins listed in Config.AdminPermissions, or for one specific permission
  • Bridge.GetPlayer(src): framework player object
  • Bridge.GetPlayerId(src): character ID (citizenid or identifier)
  • Bridge.GetPlayerName(src): FiveM player name
  • Bridge.GetLicense(src): license identifier, license2 first
  • Bridge.GetDiscord(src): Discord mention (<@id>) or 'Not Linked'
  • Bridge.GetSteam(src): Steam identifier or 'Unknown'
  • Bridge.GetPlayerIdentifiers(src): every identifier of the player except the IP

Jobs and Gangs

  • Bridge.GetJob(src): { name, grade, label }
  • Bridge.SetJob(src, jobName, grade): sets the job
  • Bridge.HasJob(src, jobName, minGrade?): true when the player has the job
  • Bridge.GetDuty(src), Bridge.SetDuty(src, status): reads or sets duty
  • Bridge.GetPlayersByJob(jobName): sources of every player with that job
  • Bridge.GetFrameworkJobs(): every job registered in the framework
  • Bridge.GetGang(src), Bridge.GetGangGrade(src): gang name and grade
  • Bridge.HasGang(src, gangName, minGrade?): true when the player is in the gang
  • Bridge.HasGroup(src, groupName, minGrade?): true when the name matches the job or the gang
  • Bridge.GetGroupContext(src): { job, jobGrade, gang, gangGrade } in one call
  • Bridge.MatchesAnyGroup(src, list, ctx?): true when the player is in any job or gang of the list. An empty list allows everyone

Inventory

  • Bridge.HasItem(src, item, amount?): true when the player holds at least amount (default 1)
  • Bridge.GetItemCount(src, item): amount held
  • Bridge.GetItem(src, item): item data
  • Bridge.GetItems(src): every item, each with name, count, slot and metadata on any inventory
  • Bridge.GiveItem(src, item, amount, meta?): gives an item. Returns true on success
  • Bridge.GiveItemToFit(src, item, amount, meta?): gives as many as fit. Returns success, given
  • Bridge.GiveItemOrDrop(src, item, amount, meta?, coords?): gives what fits and drops the rest on the ground. Returns the amount given, the amount dropped and the amount that could not be placed
  • Bridge.DropItem(coords, items, options?): creates a ground drop with a list of items
  • Bridge.RemoveItem(src, item, amount): removes an item. Returns true on success
  • Bridge.GetSlot(src, slot), Bridge.RemoveSlot(src, slot, count?): reads or empties a slot
  • Bridge.SetItemMeta(src, slot, metadata): replaces the metadata of a slot
  • Bridge.ResolveMetadata(meta): resolves random metadata values (mathRandom, listRandom, probabilityRandom) into final values. Every give and drop function above already calls it
  • Bridge.CanCarry(src, item, count): true when the amount fits
  • Bridge.CanExchangeItems(), Bridge.ExchangeItems(src, removals, additions): removes and adds items in one step, all or nothing. ML Inventory only
  • Bridge.ClearInventory(src): empties the inventory
  • Bridge.ConfiscateInventory(src), Bridge.RestoreInventory(src, items?): takes the inventory away and gives it back
  • Bridge.GetRegisteredItems(): every item registered in the inventory
  • Bridge.BindUsableItem(item, callback), Bridge.UnbindUsableItem(item): adds or removes a usable item handler
  • Bridge.DegradeItem(src, slot, amount): lowers durability of a slot
  • Bridge.DrainWeaponDurability(src, weaponHash, amount): lowers durability of a weapon
  • Bridge.GetEquippedWeaponSlot(src): inventory slot of the weapon in hand, or nil

Stashes

  • Bridge.RegisterStash(id, label, slots, weight, props?): registers a stash
  • Bridge.OpenStash(src, id, label, slots, weight, items?, props?): opens a stash, filled with items when given
  • Bridge.OpenPersistentStash(src, id, label, slots, weight, props?): opens a stash that keeps its content
  • Bridge.OpenPlayerStash(src, targetSrc, slots, weight): opens another player's inventory
  • Bridge.GetStash(id), Bridge.IsStashEmpty(id), Bridge.ClearStash(id): reads, checks or empties a stash
  • Bridge.RegisterInventoryHook(hookType, callback, options?): hooks inventory events such as swapItems or buyItem

Money

  • Bridge.GetMoney(src, account?): balance, 'cash' by default
  • Bridge.AddMoney(src, account, amount), Bridge.RemoveMoney(src, account, amount): changes a balance

Character

  • Bridge.GetMeta(src, key), Bridge.SetMeta(src, key, value): player metadata
  • Bridge.GetDob(src), Bridge.GetPhone(src): date of birth and phone number
  • Bridge.GetHunger(src), Bridge.AddHunger(src, amount), Bridge.SetHunger(src, value)
  • Bridge.GetThirst(src), Bridge.AddThirst(src, amount), Bridge.SetThirst(src, value)
  • Bridge.GetStress(src), Bridge.AddStress(src, amount), Bridge.RemoveStress(src, amount)
  • Bridge.Login(src, data), Bridge.Logout(src): character login and logout
  • Bridge.IsPlayerDead(src): true when dead. Export alias IsDead
  • Bridge.Revive(src): revives the player

Vehicles

  • Bridge.GetOwnedVehicles(src): vehicles owned by the player
  • Bridge.GetVehicleModelsByPlates(plates): model of each owned plate in the list
  • Bridge.SetVehicleFuel(vehicle, amount): sets fuel on a server entity
  • Bridge.SetVehicleLockProtected(vehicle, protected): blocks lockpicking of a vehicle. ml_vehiclekeys only

World

  • Bridge.GetWeather(), Bridge.GetGameTime(): current weather and in-game hour and minute from the detected weather script

Notifications and Logs

  • Bridge.NotifyPlayer(src, type, message, duration?): 'info', 'success', 'error' or 'warning'
  • Bridge.Log(opts): sends a log. See Logs below

Callbacks

  • Bridge.OnServerRequest(name, callback, secure?): registers a callback that clients call with Bridge.RequestServer. With secure = true, only the resource that registered it can use it
lua
1Bridge.OnServerRequest('myScript:getData', function(src, param1)
2    return { result = 'ok', value = param1 }
3end, true)

Client Functions

System

  • Bridge.IsReady(), Bridge.GetFramework(), Bridge.GetInventorySystem(), Bridge.SupportsMetadata(): same as on the server
  • Bridge.IsPlayerLoaded(): true once the character is loaded
  • Bridge.HasTargetSystem(), Bridge.GetTargetSystem(): whether a target resource runs, and which one

Inventory

  • Bridge.HasItem(item, amount?), Bridge.GetItem(item), Bridge.GetItems(): local inventory
  • Bridge.GetItemLabel(item): display label
  • Bridge.GetItemDefinitions(): every registered item
  • Bridge.GetInventoryImagePath(), Bridge.GetInventoryImageExt(): where item images live
  • Bridge.OpenInventory(), Bridge.CloseInventory()
  • Bridge.OpenStash(stashId, onClose?): opens a stash, with a callback on close
  • Bridge.OnInventoryChange(callback): runs when the inventory changes
  • Bridge.SearchItems(item): searches the inventory
  • Bridge.RegisterItemUse(item, callback): client usable item handler
  • Bridge.DisplayMetadata(data): metadata labels shown in the inventory

Weapons

  • Bridge.GetCurrentWeapon(): { hash, name, slot, durability, melee } or nil
  • Bridge.HasWeaponEquipped(): true with a weapon in hand

Player

  • Bridge.GetJob(): { name, grade, label }
  • Bridge.MatchesAnyGroup(list): true when the local player is in any job or gang of the list
  • Bridge.GetPlayerStatus(): hunger and thirst
  • Bridge.IsPlayerDead(): true when dead

Vehicles

  • Bridge.GiveVehicleKey(plate), Bridge.RemoveVehicleKey(plate)
  • Bridge.GetVehicleFuel(vehicle), Bridge.SetVehicleFuel(vehicle, amount)
  • Bridge.GetVehicleFuelType(vehicle): fuel type, with ml_fuel

World

  • Bridge.GetWeather(), Bridge.GetGameTime(): weather and in-game time

UI

  • Bridge.Notify(message, type?, duration?): notification. Duration in ms, 3000 by default
  • Bridge.ShowTextUI(text, options?), Bridge.HideTextUI(): help text
  • Bridge.Progress(options), Bridge.ProgressCircle(options): progress bar. Returns true when completed
  • Bridge.CancelProgress(): stops the active progress bar
  • Bridge.InputDialog(title, inputs): input dialog. Returns the values
  • Bridge.ContextMenu(options), Bridge.ShowMenu(options), Bridge.HideMenu(): menus

Dispatch

  • Bridge.AlertDispatch(data): police alert through the detected dispatch. Without one, a map blip lasts 2 minutes and the job gets a notification
lua
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})

Target

Works with ox_target, qb-target, sleepless_interact, or a press-E prompt when none runs.

  • Bridge.AddEntityTarget(entity, options), Bridge.RemoveEntityTarget(entity, options?)
  • Bridge.AddNetEntityTarget(netId, options), Bridge.RemoveNetEntityTarget(netId, options?)
  • Bridge.AddModelTarget(model, options), Bridge.RemoveModelTarget(model, options?)
  • Bridge.AddPlayerTarget(options), Bridge.RemovePlayerTarget(options?)
  • Bridge.AddVehicleTarget(options), Bridge.RemoveVehicleTarget(options?)
  • Bridge.AddPedTarget(options), Bridge.RemovePedTarget(options?)
  • Bridge.AddZoneTarget(options), Bridge.RemoveZoneTarget(name): box zone. Also as AddTargetZone and RemoveTargetZone
  • Bridge.AddTargetSphereZone(options), Bridge.RemoveTargetSphereZone(name): sphere zone
  • Bridge.DisableTargeting(disabled): turns targeting off or on
lua
1Bridge.AddEntityTarget(entity, {
2    label = 'Search',
3    icon = 'fas fa-search',
4    distance = 2.0,
5    onSelect = function()
6        print('Searched')
7    end,
8})

Callbacks

  • Bridge.RequestServer(name, ...): calls a server callback and waits for the answer, up to 10 seconds. Call it inside a thread
lua
1CreateThread(function()
2    local data = Bridge.RequestServer('myScript:getData', 'hello')
3    print(data.result)
4end)

Logs

Bridge.Log sends to Discord, ox_lib or FiveManage depending on Config.LogProvider.

lua
1Bridge.Log({
2    webhook = 'https://discord.com/api/webhooks/...',
3    title = 'Item Looted',
4    description = 'Player picked up an 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. false skips the log
  • title, description: text of the entry
  • color: 'blue', 'green', 'yellow', 'orange', 'red', 'purple' or 'white'
  • player, target: sources. Name, character name, character ID, job, license, Discord and Steam are added for each
  • fields: extra fields
  • provider: destination for this log only
  • dataset: FiveManage dataset for this log only

Server Events

  • ml_bridge:server:playerLoaded: a player finished loading, on any framework
  • ml_bridge:server:playerUnloaded: a player logged out or left

Spatial

Spatial is a client global available to scripts that load @ml_bridge/init.lua. It splits the map into 200 meter sectors and only checks points near the player, so many points cost little.

  • Spatial.Track(id, target, distance, onEnter?, onExit?): tracks a vec3 or an entity. onEnter and onExit run when the player crosses distance
  • Spatial.Remove(id): stops tracking
lua
1Spatial.Track('mySpot', vec3(200, 300, 30), 5.0,
2    function(self) print('Entered') end,
3    function(self) print('Left') end
4)
5
6Spatial.Remove('mySpot')