> For the complete documentation index, see [llms.txt](https://docs.warostudios.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.warostudios.com/core/waro-lib.md). # waro\_lib The shared engine every Waro Studios script runs on. ## Overview `waro_lib` is the engine behind every Waro script. You install it once, and every Waro script uses it. It does three jobs: * **Framework bridge.** It detects Qbox, QBCore or ESX and gives our scripts one way to read jobs, names and money. * **Inventory and banking bridge.** It detects your inventory and company-account resource, so scripts can give items and pay companies on any setup. * **Player settings.** It saves each player's personal settings in the database. There is nothing to configure. `waro_lib` has no `config.lua`. ## Requirements | Resource | Needed? | | --------- | ------- | | `ox_lib` | Yes | | `oxmysql` | Yes | ## Installation 1. Drag `waro_lib` into your `resources` folder. 2. Add it to `server.cfg` right after `ox_lib` and `oxmysql`, and before your framework: ```cfg ensure ox_lib ensure oxmysql ensure waro_lib ``` 3. Restart the server. In the console you'll see `[waro_lib] v1.x.x started`. {% hint style="success" %} The `waro_settings` table is created automatically on first start. There is no SQL to import. {% endhint %} ## What it detects Detection happens automatically each time it's needed. Whatever is **started** wins, checked in this order: | Kind | Checked in order | | ---------------- | ------------------------------------------------------------------------------- | | Framework | `qbx_core` → `qb-core` → `es_extended` | | Inventory | `ox_inventory` → `qb-inventory` / `ps-inventory` / `lj-inventory` → ESX default | | Company accounts | Renewed-Banking, qb-banking, qb-management or esx\_society | ## Player settings Some scripts let players change their own settings. `waro_lib` stores them: * Settings are saved per **game license** (the player's `license2` / `license` identifier), so they follow the player across characters. * Only changes are stored. If a player never changed an option, they get the server's default, and if you change the default later, they get your new value. * Every value is checked on the server. Numbers are kept within their limits, and only allowed choices are accepted. * An owner can **lock** an option. Locked options always use the server default and can't be changed by players. ## For developers All exports are called as `exports.waro_lib:(...)`. ### Framework (server) | Export | Returns | | ---------------------------------------------- | -------------------------------------------------------------------------- | | `getFramework()` | `'qbx'`, `'qb'`, `'esx'` or `nil` | | `getPlayerJob(source)` | `{ name, label, grade, onDuty }` or `nil` | | `getCharacterName(source)` | `'Jamal Sutton'` or `nil` | | `getCharacterId(source)` | Stable character id (citizenid on Qbox/QBCore, identifier on ESX) or `nil` | | `getSourceByCharacterId(id)` | The online player's server id, or `nil` | | `getMoney(source, account)` | Balance of `'cash'` or `'bank'` | | `addMoney(source, account, amount, reason)` | `true` / `false` | | `removeMoney(source, account, amount, reason)` | `true` / `false` (`false` if they don't have enough) | | `addSocietyMoney(job, amount)` | `true` / `false` | ### Inventory (server) | Export | Returns | | ---------------------------------------- | ---------------------------------------------------- | | `getInventory()` | `'ox'`, `'qb'`, `'esx'` or `nil` | | `addItem(source, item, count, metadata)` | `true` / `false` | | `removeItem(source, item, count)` | `true` / `false` (`false` if they don't have enough) | | `getItemCount(source, item)` | Number | | `canCarry(source, item, count)` | `true` / `false` | | `getItemLabel(item)` | `'Iron Ore'` (falls back to the item name) | ### Framework (client) | Export | Returns | | -------------------- | ----------------------------------------------------- | | `getCharacterName()` | `'Jamal Sutton'` or `nil` | | `getPlayerJob()` | `{ name, label, grade, gradeLabel, onDuty }` or `nil` | | `getMoney()` | `{ cash, bank }` or `nil` | ### Version (client and server) ```lua local version = exports.waro_lib:getVersion() -- e.g. '1.0.0' ``` ### Settings Register a settings schema from your resource's **server** side: ```lua exports.waro_lib:registerSettings('my_resource', { version = 1, options = { ['hud.scale'] = { type = 'number', min = 0.8, max = 1.3, step = 0.05, default = 1.0 }, ['hud.style'] = { type = 'enum', values = { 'minimal', 'full' }, default = 'full' }, ['hud.accent'] = { type = 'color', default = '#7020F5', locked = true }, ['hud.show'] = { type = 'boolean', default = true }, }, }) ``` Option types: `boolean`, `number` (`min`, `max`, `step`), `enum` (`values`) and `color` (`#RRGGBB`). `locked = true` forces the default for everyone. Read and change settings on the **client**: ```lua -- Fires when settings load or change. `settings` holds the effective values. AddEventHandler('waro_lib:settingsChanged', function(scope, settings) if scope == 'my_resource' then print(settings['hud.scale']) end end) local settings = exports.waro_lib:getSettings('my_resource') -- nil until loaded local schema = exports.waro_lib:getSettingsSchema('my_resource') exports.waro_lib:setSetting('my_resource', 'hud.scale', 1.1) exports.waro_lib:setSettings('my_resource', { ['hud.scale'] = 1.1, ['hud.show'] = false }) exports.waro_lib:resetSettings('my_resource') -- all options exports.waro_lib:resetSettings('my_resource', 'hud.scale') -- one option exports.waro_lib:resetSettings('my_resource', nil, { 'hud.show' }) -- all except the ones listed ``` If the server refuses a change, the local event `waro_lib:settingRejected` fires with `(scope, key, reason)`. ## FAQ
Do I need to buy waro_lib? No. It comes with every Waro script, and you only need one copy no matter how many scripts you run.
Where are player settings saved? In the `waro_settings` table in your database, one row per player and script.
I switched from QBCore to Qbox. Do I need to change anything? No. `waro_lib` checks which framework is started and uses it.
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.warostudios.com/core/waro-lib.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.