Configuration
Kivo Inventory has two places where you configure things:
| What | Where |
|---|---|
| Bridge settings (avatars, debug) | kivo-inv-bridge/shared/config.lua |
| Everything else (slots, weight, items, shops, language and so on) | The normal ox_inventory places, see ox_inventory settings |
After you change kivo-inv-bridge/shared/config.lua, restart kivo-inv-bridge and then ox_inventory, or restart the server.
Bridge config file
Section titled “Bridge config file”The file kivo-inv-bridge/shared/config.lua contains two tables. This is the layout of the file (replace the placeholder values with your own):
Config.Avatar = { DiscordBotToken = "your-discord-bot-token", SteamApiKey = "", Priority = "discord", CacheDuration = 0,}
Config.Debug = { Enabled = false, LogAvatar = false,}The file also has three small helper functions below these tables. Leave them as they are.
Avatar settings (Config.Avatar)
Section titled “Avatar settings (Config.Avatar)”| Option | Default | Valid values | What it does |
|---|---|---|---|
DiscordBotToken |
A value is pre-filled in the shipped file. Replace it with your own. | Text, or "" |
The token of your Discord bot. Used to look up the player’s Discord profile picture. Leave it as "" to skip Discord, or to read the token from the discord_bot_token convar instead. |
SteamApiKey |
"" |
Text, or "" |
Your Steam Web API key. Used to look up the player’s Steam profile picture. Leave it as "" to skip Steam, or to read the key from the steam_webApiKey convar instead. |
Priority |
"discord" |
"discord" or "steam" |
Meant to choose which service is tried first. In this release it has no effect: Discord is always tried first, and Steam is used when Discord gives no result. |
CacheDuration |
0 |
Number of seconds | Meant to set how long an avatar is kept. In this release it has no effect: the avatar is kept until the player disconnects. |
To get a bot token, create an application and a bot in the Discord Developer Portal (discord.com/developers/applications). To get a Steam Web API key, use steamcommunity.com/dev/apikey.
Debug settings (Config.Debug)
Section titled “Debug settings (Config.Debug)”| Option | Default | Valid values | What it does |
|---|---|---|---|
Enabled |
false |
true or false |
Master switch for the bridge debug messages. In this release the bridge does not print any debug messages, so changing it has no visible effect. |
LogAvatar |
false |
true or false |
Meant to log avatar lookups when Enabled is true. Same note as above. |
Settings in server.cfg instead of the config file
Section titled “Settings in server.cfg instead of the config file”Instead of writing the token and key into the config file, you can set them as convars in server.cfg and leave the config values empty (""). The bridge reads the config file first and only uses the convar when the config value is empty.
| Convar | Replaces | Example |
|---|---|---|
discord_bot_token |
Config.Avatar.DiscordBotToken |
set discord_bot_token "your-discord-bot-token" |
steam_webApiKey |
Config.Avatar.SteamApiKey |
set steam_webApiKey "your-steam-api-key" |
Use set, not setr, so the value stays on the server and is not sent to players.
FiveM uses the same steam_webApiKey convar to hand out Steam identifiers, so for Steam avatars setting it in server.cfg is the recommended route.
How avatars are chosen
Section titled “How avatars are chosen”Each player’s avatar is looked up once, when they join. The bridge also does this for everyone already online when the bridge starts. The steps are:
- If a Discord bot token is available (config or convar) and the player has a linked Discord account, the bridge asks Discord for the profile picture. Players without a custom Discord picture get one of Discord’s default pictures. Animated Discord pictures stay animated.
- If Discord is skipped or gives no result, and the player has a Steam identifier and a Steam Web API key is available, the bridge asks Steam.
- If neither works, the interface shows the default profile picture.
The result is kept until the player disconnects. A lookup is not repeated while the player stays connected, so a player who changes their Discord picture sees the new one after they reconnect. Restarting kivo-inv-bridge looks the avatars up again for everyone online.
The lookups need these on the player’s side and on your server:
| Needs | For |
|---|---|
| Discord desktop app running on the player’s PC | FiveM provides the player’s Discord ID |
| Steam running on the player’s PC | FiveM provides the player’s Steam ID |
Your server can open connections to discord.com and api.steampowered.com |
The lookups themselves |
| The player’s PC can reach the Discord and Steam image servers | Showing the picture |
Framework detection
Section titled “Framework detection”The bridge detects the framework once, shortly after it starts. It checks the resources in this order and uses the first one that is started:
| Order | Framework | Resource it looks for | Name printed in the console |
|---|---|---|---|
| 1 | ESX | es_extended |
ESX |
| 2 | QBX | qbx_core |
QBX |
| 3 | QB-Core | qb-core |
QB-Core |
| 4 | OX Core | ox_core |
OX Core |
Things to know:
- Your framework must be started before the bridge. If it starts later, the bridge does not see it until the bridge is restarted.
- If more than one of these resources is running, the first one in the table wins.
- If none is found, the console shows
[kivo-inv-bridge] WARNING: No supported framework detected!. The inventory still opens, but cash and bank show0, the name is the FiveM name and the ID is the server ID. Avatars still work, because they do not depend on the framework. - Other scripts can ask for the result with the
GetFrameworkexport. See Exports and integration.
What the interface shows for each framework:
| Framework | Cash | Bank | Name | ID |
|---|---|---|---|---|
| ESX | The money account |
The bank account |
The ESX character name | Server ID |
| QB-Core | cash |
bank |
First and last name | The character cid value if set, otherwise the server ID |
| QBX | cash |
bank |
First and last name | The character cid value if set, otherwise the server ID |
| OX Core | Cash from the character accounts | Bank from the character accounts | First and last name | The character ID |
| None found | 0 |
0 |
FiveM name | Server ID |
If your framework is not in this list, or you keep money somewhere else (a custom economy), see Feed the interface from another framework or script.
ox_inventory settings
Section titled “ox_inventory settings”Kivo Inventory does not change how the ox_inventory settings work. This site does not repeat the ox_inventory documentation. The upstream documentation (Overextended, overextended.dev/ox_inventory) lists every option. This table says where each kind of setting lives in your server:
| What | Where |
|---|---|
| General settings (framework, slots, weight, keys, markers, logging and more) | setr inventory:... convars in server.cfg. Their defaults live in ox_inventory/init.lua, which you should not edit. |
| Items | ox_inventory/data/items.lua |
| Weapons | ox_inventory/data/weapons.lua |
| Shops | ox_inventory/data/shops.lua |
| Stashes | ox_inventory/data/stashes.lua |
| Crafting | ox_inventory/data/crafting.lua |
| Evidence, vehicles, animations | ox_inventory/data/evidence.lua, vehicles.lua and animations.lua |
| Language | ox_inventory/locales/*.json. The language follows the ox_lib locale convar, for example setr ox:locale "en". |
| Item images | ox_inventory/web/images/, one .png file named after the item |
| Interface source (only if you rebuild it) | ox_inventory/web/src/ |
The convars you are most likely to change:
| Convar | Default | What it does |
|---|---|---|
inventory:framework |
esx |
Which framework module ox_inventory loads. The modules shipped here are esx, ox, nd and qbx. |
inventory:slots |
50 |
Number of slots in a player inventory. |
inventory:weight |
30000 |
Maximum carry weight of a player. |
inventory:target |
0 |
Set to 1 to use ox_target. It must start before ox_inventory. |
inventory:police |
["police", "sheriff"] |
Job names treated as police by ox_inventory. |
inventory:imagepath |
nui://ox_inventory/web/images |
Where item images are loaded from. |
All of these are set in server.cfg above the ensure lines, for example:
setr inventory:framework "esx"setr inventory:slots 50setr inventory:weight 30000