Obsi Lib (`obsi-lib`) is the shared library behind every Obsi Scripts resource.
It puts the framework, inventory, banking, target, clothing, vehicle keys and fuel behind one API, and adds notifications, a progress bar, a text UI and 3D sounds in the Obsi look.

![Obsi Lib](/media/lib/hero.webp)

:::hint{type="info" title="Free and open source"}
Obsi Lib is free software under GPL-3.0.
Download it from [GitHub releases](https://github.com/Obsi-Scripts/obsi-lib/releases).
:::

## One API for every server

Write a script once and it runs on ESX, QBCore and QBX, with whatever inventory the server uses:

```lua title="server.lua"
if ObsiLib.job.is(source, 'police')
   and ObsiLib.items.has(source, 'handcuffs') then
    ObsiLib.money.add(source, 500, 'bank', 'arrest bonus')
    ObsiLib.notify(source, {
        title = 'Bonus',
        description = 'You received **$500**.',
        type = 'success',
    })
end
```

```lua title="client.lua"
local done = ObsiLib.ui.progress({
    label = 'Picking the lock',
    duration = 5000,
    anim = { dict = 'mp_arresting', clip = 'a_uncuff' },
    cancelable = true,
})
if done then
    ObsiLib.sound.playAt(GetEntityCoords(PlayerPedId()), 'unlock', { range = 8.0 })
    ObsiLib.ui.showText({ key = 'E', label = 'Open door' })
end
```

:::frame{caption="Built-in UI: text UI, progress bar and notifications in the Obsi look"}
![Obsi Lib UI](/media/lib/ui-overview.webp)
:::

## Why use it

::::cards{cols="3"}
:::card{title="Zero setup" icon="zap"}
Framework, inventory, banking, target, clothing, keys and fuel are detected on start. Force or disable any of them in the config.
:::
:::card{title="Safe by default" icon="shield"}
Item and money writes check balances first. Stash moves are validated and rolled back on the server.
:::
:::card{title="Cleans up after you" icon="sparkles"}
Callbacks, usable items, points, target zones, keybinds, DUIs and state listeners are removed when your resource stops.
:::
:::card{title="Patch, don't fork" icon="puzzle"}
Replace one framework or inventory function from `editable/` without touching the library.
:::
:::card{title="UI included" icon="palette"}
Notifications, progress bar and text UI with an accent colour you choose.
:::
:::card{title="3D sounds" icon="volume"}
NUI sound engine with live distance falloff, or xsound when it is running.
:::
::::

## Supported resources

![Features](/media/lib/features.webp)

| Area | Supported |
| --- | --- |
| Frameworks | ESX Legacy, QBCore, QBX, custom |
| Inventories | ox_inventory, qb-inventory (v2 and v1), ps-inventory, lj-inventory, codem-inventory, jaksam_inventory, custom, framework items |
| Banking (society) | Renewed-Banking, okokBanking, qb-banking, qb-management, esx_society |
| Target | ox_target, qb-target |
| Clothing | illenium-appearance, fivem-appearance, qb-clothing, esx_skin / skinchanger |
| Vehicle keys | qbx_vehiclekeys, qb-vehiclekeys, wasabi_carlock, mk_vehiclekeys |
| Fuel | ox_fuel, LegacyFuel, cdn-fuel, ps-fuel, lc_fuel, native |
| Notifications | built-in, ESX, QBCore, ox_lib, custom |
| Sounds | built-in NUI player (live distance falloff), xsound |

Everything is detected automatically, and every integration can be forced or turned off in the [configuration](/lib/getting-started/configuration).