Client Sync
How ItemsDB keeps connected clients in sync with runtime item changes.
Network Thread Hitch Warning
Broadcasting to a large number of connected clients can cause a network thread hitch. Be careful when applying changes on a live server and try to do so during low player count windows where possible.
To mitigate this, ItemsDB batches rapid changes into a single broadcast - if multiple items are updated within 100ms of each other, they are flushed together in one network event rather than one per item. A broadcast to all clients is still unavoidable, but this significantly reduces the impact of bulk operations.
ItemsDB is open source and improving this further is an active area of interest. Ideas and discussion from the community are welcome.
Without ItemsDB, runtime item changes are invisible to clients until the server restarts. The patched module keeps clients in sync through three mechanisms:
- Broadcast on swap - When ItemsDB finishes loading, the server broadcasts the full item list to all connected clients.
- Per-client request on join - Each client requests the current item list on startup, catching players who connect after the initial broadcast.
- Update on changes - Saves and deletes are pushed to all clients automatically, no restart needed.
What Gets Synced
- Label, weight, stack, close, description
- The full
clientsub-table: image, anim, prop, status, usetime, notification, etc. - Weapon metadata: model, hash, ammoName, throwable
- Button labels (not action functions)
What Does Not Sync
Function callbacks (client.add, client.remove, client.effect, buttons[N].action, server.cb) cannot be sent over the network. These live in shared/callbacks.lua and are applied server-side only.
Inventory UI Display Cache
ox_inventory's NUI caches item metadata the first time each item is displayed. This cache is not invalidated by runtime updates.
| What changes immediately | What requires NUI reload |
|---|---|
/give availability | Label shown in inventory slots |
| Item use / callbacks | Description shown on hover |
| Weight / stack behaviour | Image (if changed) |
| New players (empty cache) | Existing players who already viewed the item |