Installation

Veltar Core is a framework-agnostic base resource for ESX / QBCore / QBox. It ships prebuilt — the React UI is already compiled into ui/dist and there is no build step — so installation is drop-in. This page walks through every step, what each one does, and how to confirm it worked.

Before you start, it helps to understand what the core actually is:

• It is a shared library + export layer, not a standalone gameplay script. On its own it adds no visible features — it provides a unified API (players, money, inventory, licenses, jobs, society, phone, dispatch, entities, UI, sounds) that your other scripts build on.
• It auto-detects your framework and inventory at startup and adapts. You do not tell it what you run; it figures that out.
• The only file you edit is shared/config.lua. Everything else can stay encrypted.

Requirements

Install and confirm these are working before adding Veltar Core.

Version notes. Use a current ox_lib build (the core relies on lib.zones and lib.notify). Any recent oxmysql works. On QBox, both qbx_core and a compatibility qb-core may be present — the core handles both.

> Only ox_lib is truly mandatory. Everything else is optional and detected automatically — you never wire adapters by hand.

Step 1 — Add the resource

Place the veltar_core folder anywhere under your server's resources directory. A grouping folder such as [veltar] keeps things tidy.

resources/
└── [veltar]/
    └── veltar_core/
        ├── fxmanifest.lua
        ├── shared/
        ├── server/
        ├── client/
        └── ui/dist/        ← prebuilt React UI (do not delete)

> If you received the core as an escrow/encrypted asset, do not try to open the encrypted files — only shared/config.lua and shared/locales/ are meant to be edited.

Step 2 — Set the start order

Start order is the single most common source of problems. Veltar Core must start after its dependencies and before any script that consumes it. Add these to your server.cfg:

# dependencies first
ensure ox_lib
ensure oxmysql

# your framework (example — use whichever you run)
ensure es_extended
# or: ensure qbx_core
# or: ensure qb-core

# your inventory (must come before veltar_core so it's detected)
ensure ox_inventory

# the core — after everything it detects, before scripts that use it
ensure veltar_core

# your Veltar-based scripts come AFTER this line
# ensure my_onboarding

> Why order matters. Detection runs once, at the moment veltar_core starts, by checking which resources are already started. If your inventory starts after the core, the core sees NONE and item calls silently fail. When in doubt, put veltar_core as late as possible while still being before your own scripts.

Step 3 — Database setup (only with oxmysql)

There is no SQL file to import. When oxmysql is running, Veltar creates its own tables automatically on first start.

-- created automatically at boot when oxmysql is present:
veltar_kv                  -- Veltar.KV persistent key/value store
veltar_ledger              -- transaction audit log (if Veltar.Ledger.enabled)
veltar_society_accounts    -- QB/QBox society balances (if SocietyMoney = 'native')

> All DB features are optional and self-healing. If oxmysql is absent, the core prints warnings and keeps running — nothing crashes. Add oxmysql later and the tables build themselves on the next restart.

Step 4 — Configure (optional)

Open shared/config.lua. It works untouched, so a first run needs no edits. When you are ready, the values you most likely want to review are:

Veltar.Debug           = false     -- keep false in production
Veltar.Lang            = 'en'       -- 'pl' or 'en' (or your own locale)
Veltar.InventorySystem = 'auto'     -- leave on auto unless forcing
Veltar.AntiCheat.entities.blacklist = { 'rhino', 'cargoplane' }  -- recommended

> The full breakdown of every option is on the Configuration page. Remember: config is read once at start — restart veltar_core after editing.

Step 5 — Verify the install

Start (or restart) the server and run the diagnostic from the server console or as an admin in-game:

/veltar

Expected output — check each line matches your setup:

Then smoke-test the UI end to end:

/veltar test notify      -- a notification pops
/veltar test progress    -- a cancellable progress bar runs
/veltar test textui      -- a TextUI box shows for a few seconds
/veltar test sound       -- a frontend sound plays

> If /veltar prints nothing, the resource didn't start — check the server console for a startup error in veltar_core (usually a missing ox_lib).

Using the core in your scripts

Once installed, there are two ways to consume it.

1. Shared library (@veltar_core/...)

Include the core's files directly in a Veltar script's fxmanifest.lua for full in-process access to the Veltar.* tables:

-- in your script's fxmanifest.lua
shared_scripts {
    '@ox_lib/init.lua',
    '@veltar_core/shared/config.lua',
    '@veltar_core/shared/utils.lua',
}
server_scripts {
    '@veltar_core/server/bridge/init.lua',
    -- ...the bridge modules you need
}

-- then call it directly
local player = Veltar.Bridge.GetPlayer(source)
Veltar.Bridge.AddMoney(source, 'bank', 500, 'payout')

2. Exports (any resource)

From a script that is not part of the Veltar ecosystem, use exports — no @include needed:

-- server
local player = exports.veltar_core:GetPlayer(source)
exports.veltar_core:AddMoney(source, 'bank', 500, 'payout')
exports.veltar_core:DispatchAlert({ title = 'Robbery', coords = coords, jobs = { 'police' } })

-- client
exports.veltar_core:Notify('Welcome!', 'success')
exports.veltar_core:SpawnVehicle('adder', coords, 90.0, { plate = 'VLT00001' }, function(veh, netId)
    -- vehicle created fully server-side, returned here
end)

> Use the shared-library approach for tightly-integrated Veltar scripts, and exports for one-off integrations. The full list of functions and exports is on the API page.

Updating

Replace the veltar_core folder with the new version and restart it.

restart veltar_core

> Enable Veltar.VersionCheck in the config to get a console notice when a newer version is published.

Troubleshooting

> Still stuck? Turn on Veltar.Debug = true temporarily, restart, and re-read the console — the core logs each detection step and adapter bind at startup.