Cara Install ox_inventory dan ox_lib di QBCore (Panduan 2026)

Kalau kamu sudah pernah membangun server QBCore, cepat atau lambat kamu akan bertemu nama ox_lib dan ox_inventory. Keduanya dipakai luas di komunitas FiveM karena ox_lib menyediakan banyak utilitas siap pakai (notifikasi, progress bar, menu, callback, zona), sementara ox_inventory menawarkan sistem inventory berbasis slot dan berat yang rapi serta mudah diatur.

Di artikel ini kita bahas cara memasang keduanya di server QBCore secara berurutan, hal yang perlu kamu cek sebelum mulai, dan kesalahan yang paling sering bikin server error setelah instalasi. Tutorial ini mengasumsikan server QBCore kamu sudah berjalan. Kalau belum, mulai dulu dari cara install QBCore menggunakan txAdmin.

Sebelum mulai: cek kompatibilitas dulu

Ini langkah yang paling sering dilewati. ox_inventory tidak berjalan sendirian: ia bergantung pada framework (melalui "bridge"), database, dan ox_lib. Dukungan resmi terhadap framework tertentu bisa berubah antar versi, jadi sebelum mengunduh apa pun:

• Buka README dan dokumentasi resmi ox_inventory di repositori GitHub-nya, lalu cek framework apa saja yang didukung pada versi terbaru.
• Baca catatan rilis (release notes) versi yang akan kamu pasang, terutama bagian breaking changes.
• Pastikan versi FXServer (artifact) kamu cukup baru. Resource modern sering memakai fitur Lua 5.4 dan native yang tidak ada di artifact lama.

Kalau ternyata versi ox_inventory terbaru tidak lagi mendukung QBCore secara resmi, kamu punya dua pilihan: memakai versi yang masih mendukung QBCore (dengan risiko tidak lagi mendapat update), atau mempertimbangkan migrasi ke Qbox yang memang dibangun di atas ekosistem ox. Perbandingan lengkapnya ada di artikel QBCore vs ESX vs QBox.

Satu catatan lagi: status maintenance resource open-source bisa berubah, termasuk siapa yang memelihara repositorinya. Selalu ambil file dari repositori dan halaman rilis resmi, bukan dari re-upload di Discord atau forum.

Yang kamu butuhkan

• Server QBCore yang sudah jalan (qb-core, oxmysql, database MariaDB/MySQL).
• oxmysql versi terbaru. QBCore modern sudah memakainya, tapi pastikan versinya tidak tertinggal.
• ox_lib dari halaman Releases resminya.
• ox_inventory dari halaman Releases resminya.
• Akses ke database (HeidiSQL, DBeaver, atau mysql CLI) dan backup sebelum mulai.

Soal backup jangan ditawar. Migrasi inventory mengubah data pemain. Kalau kamu belum punya rutinitas backup, baca dulu cara backup dan restore database server FiveM.

Langkah 1: Unduh file rilis, bukan source code

Ini kesalahan klasik. Di halaman GitHub, tombol hijau "Code → Download ZIP" memberimu source code mentah. Untuk ox_lib dan ox_inventory, antarmuka web (NUI) perlu di-build dulu. File yang sudah di-build tersedia di halaman Releases, biasanya bernama seperti ox_inventory.zip atau ox_lib.zip.

Kalau kamu memakai source code mentah tanpa build, gejalanya biasanya UI inventory tidak muncul sama sekali atau muncul error di console F8 tentang file web yang tidak ditemukan.

Ekstrak keduanya ke folder resources kamu. Struktur yang rapi misalnya:

resources/
├── [ox]/
│   ├── ox_lib/
│   └── ox_inventory/
├── [qb]/
│   ├── qb-core/
│   └── ...
└── [standalone]/
    └── oxmysql/

Pastikan nama foldernya persis ox_lib dan ox_inventory, tanpa akhiran seperti -main atau nomor versi. Resource lain mencari nama ini melalui export.

Langkah 2: Atur urutan ensure di server.cfg

Urutan start resource sangat penting karena ox_inventory butuh oxmysql, ox_lib, dan framework sudah siap ketika ia mulai. Contoh urutan yang umum:

ensure oxmysql
ensure ox_lib
ensure qb-core

# resource QBCore lain yang tidak bergantung pada inventory
ensure [qb]

ensure ox_inventory

# resource yang memakai export ox_inventory
ensure [jobs]

Kalau kamu memakai ensure [qb] untuk seluruh folder, perhatikan bahwa resource yang memanggil inventory pada saat start bisa error jika dimulai sebelum ox_inventory. Solusinya, pisahkan resource seperti itu ke folder lain yang di-ensure setelah ox_inventory, atau deklarasikan dependency 'ox_inventory' di fxmanifest resource tersebut.

Langkah 3: Tambahkan convar yang dibutuhkan

ox_lib dan ox_inventory dikonfigurasi lewat convar di server.cfg, bukan dengan mengedit file config Lua. Contoh pengaturan dasar:

# ox_lib
setr ox:locale "id"

# ox_inventory
setr inventory:slots 50
setr inventory:weight 30000
setr inventory:target false
set inventory:versioncheck true

Perhatikan perbedaan set dan setr. setr artinya nilainya ikut direplikasi ke client, jadi script client bisa membacanya. set hanya ada di server. Daftar convar lengkap, nama persisnya, dan nilai default untuk versi kamu ada di dokumentasi resmi ox_inventory. Jangan menyalin convar dari tutorial lama tanpa mengecek apakah namanya masih sama.

Untuk pemilihan framework, versi ox_inventory yang mendukung banyak framework biasanya memakai convar framework (misalnya inventory:framework). Cek dokumentasi versi yang kamu pakai untuk nilai yang benar bagi QBCore. Jika nilai ini salah, ox_inventory tidak akan bisa membaca data pemain dari framework.

Langkah 4: Lepaskan qb-inventory

Dua sistem inventory tidak boleh jalan bersamaan. Hentikan qb-inventory (dan resource yang secara eksplisit hanya bekerja dengan qb-inventory, seperti beberapa versi lama qb-shops atau qb-weapons) dengan menghapusnya dari server.cfg atau memindahkannya keluar folder resources.

Lalu cari di seluruh kode kamu pemanggilan yang langsung ke qb-inventory, misalnya:

grep -rn "qb-inventory" resources/ --include=*.lua

Setiap pemanggilan event atau export qb-inventory perlu diganti ke export ox_inventory. Beberapa script populer sudah menyediakan opsi config untuk ox_inventory, jadi cek dulu config-nya sebelum mengubah kode.

Langkah 5: Pindahkan definisi item

QBCore menyimpan definisi item di qb-core/shared/items.lua. ox_inventory memakai file sendiri, yaitu ox_inventory/data/items.lua. Formatnya berbeda. Contoh item di ox_inventory:

['kopi_susu'] = {
    label = 'Kopi Susu',
    weight = 250,
    stack = true,
    close = true,
    description = 'Kopi susu hangat, menambah sedikit stamina.',
    client = {
        status = { thirst = 150000 },
        anim = { dict = 'mp_player_intdrink', clip = 'loop_bottle' },
        usetime = 2500,
    }
},

Field weight dalam gram, dan total berat inventory pemain dibatasi convar inventory:weight. Kalau item terasa "terlalu berat" setelah migrasi, biasanya itu karena nilai berat dari QBCore tidak sesuai skala yang kamu inginkan.

Gambar item diletakkan di ox_inventory/web/images/ dengan nama file sesuai nama item, misalnya kopi_susu.png.

Untuk server dengan banyak item, beberapa versi ox_inventory menyediakan perintah konversi data dari format inventory lain. Ketersediaan dan nama perintahnya tergantung versi, jadi cek dokumentasi. Jalankan konversi hanya setelah backup, idealnya di server staging lebih dulu.

Langkah 6: Pasang ox_lib di resource kamu

ox_lib bukan hanya dependensi ox_inventory. Kamu juga bisa memakainya di script sendiri. Tambahkan ke fxmanifest:

fx_version 'cerulean'
game 'gta5'
lua54 'yes'

shared_scripts {
    '@ox_lib/init.lua',
}

client_scripts { 'client.lua' }
server_scripts { 'server.lua' }

dependencies { 'ox_lib', 'ox_inventory' }

lua54 'yes' wajib karena ox_lib memakai Lua 5.4. Setelah itu objek global lib tersedia, misalnya:

-- client.lua
lib.notify({ title = 'Kafe', description = 'Pesanan siap!', type = 'success' })

if lib.progressBar({ duration = 3000, label = 'Menyeduh kopi...', canCancel = true }) then
    TriggerServerEvent('kafe:server:selesaiSeduh')
end

Langkah 7: Memakai export ox_inventory di server

Semua perubahan isi inventory sebaiknya dilakukan di server, bukan client. Contoh memberi dan memeriksa item:

-- server.lua
RegisterNetEvent('kafe:server:selesaiSeduh', function()
    local src = source

    -- validasi: punya bahan?
    local biji = exports.ox_inventory:Search(src, 'count', 'biji_kopi')
    if not biji or biji < 1 then
        return lib.notify(src, { description = 'Bahan tidak cukup', type = 'error' })
    end

    if not exports.ox_inventory:CanCarryItem(src, 'kopi_susu', 1) then
        return lib.notify(src, { description = 'Inventory penuh', type = 'error' })
    end

    exports.ox_inventory:RemoveItem(src, 'biji_kopi', 1)
    exports.ox_inventory:AddItem(src, 'kopi_susu', 1)
end)

Perhatikan validasi di server. Event yang dipicu client bisa dipanggil oleh cheater dengan argumen apa pun, jadi jangan pernah mempercayai jumlah item atau harga yang dikirim client. Pola lengkap untuk job seperti ini ada di cara membuat sistem job custom di QBCore.

Langkah 8: Uji di server staging

Restart penuh server (bukan hanya restart ox_inventory), lalu periksa:

1. Console server bersih dari error merah saat ox_lib dan ox_inventory start.
2. Inventory terbuka dengan tombol default (biasanya F2 atau Tab, tergantung config) dan menampilkan item pemain.
3. Item bisa dipakai, dijatuhkan, dan diberikan ke pemain lain.
4. Toko, stash, dan glovebox kendaraan bekerja.
5. Setelah reconnect, isi inventory tetap ada (data tersimpan ke database).

Masalah yang sering muncul

"No such export ... in resource ox_inventory"

Biasanya karena resource pemanggil start lebih dulu dari ox_inventory, nama folder salah, atau ox_inventory gagal start karena error lain. Cek console dari atas, bukan hanya error terakhir.

UI inventory tidak muncul

Hampir selalu karena memakai source code, bukan file rilis yang sudah di-build. Unduh ulang dari halaman Releases.

Item tidak punya gambar atau label

Item ada di database pemain tapi tidak didefinisikan di data/items.lua, atau nama file gambar tidak sama persis dengan nama item.

Error "attempt to index a nil value (global 'lib')"

Kamu lupa menambahkan '@ox_lib/init.lua' di shared_scripts atau lua54 'yes' di fxmanifest.

Server terasa lebih berat setelah migrasi

Inventory sendiri jarang jadi penyebab utama. Lebih sering pelakunya script lain yang memanggil export di loop setiap frame. Ukur dulu dengan resmon dan profiler FiveM sebelum menebak.

Ringkasan

• Cek dulu dukungan framework di dokumentasi versi ox_inventory yang akan kamu pakai.
• Unduh dari halaman Releases resmi, bukan source code.
• Urutan ensure: oxmysql → ox_lib → qb-core → ox_inventory → resource yang memakainya.
• Konfigurasi lewat convar, definisi item di data/items.lua.
• Semua perubahan item dilakukan dan divalidasi di server.
• Backup dan uji di staging sebelum production.

Butuh server staging terpisah?

Migrasi inventory paling aman dilakukan di server kedua sebelum menyentuh kota yang sedang ramai. Kalau kamu butuh mesin dengan root penuh untuk staging atau production, lihat hosting FiveM Noctis. Paket vDedicated kami memakai AMD Ryzen, DDR5, dan NVMe di Singapore dengan anti-DDoS aktif, dan VDS Mini (2 vCPU, 4 GB RAM) cocok sebagai mesin development. Detail paket ada di halaman Noctis Cloud.