Guides
Item Images
Every way to get an image onto an item, weapon, container, or clothing piece, and the order they're checked in.
An item's image can come from several places at once. One Inventory checks them in a fixed order and uses the first one that actually loads.
Ways to add an image
Drop a file into web/images/
Any supported extension resolves once the file is in the folder (see Supported extensions).
Upload in-game
The create/edit modal's image picker (shared by items, weapons, containers, and clothing) accepts a paste (
Ctrl+V) or a Browse file dialog. Paste is the primary method. Uploads save into web/images/ and are visible to everyone instantly, no restart required.External host / CDN
Add a host in the admin panel under Configuration -> Image Hosts as a
{ label, base URL } pair. Configured hosts are checked, in order, both as fallback locations for bare filenames and as the allowlist for full URLs.Per-item metadata
Set
metadata.image (or metadata.imageurl, identical behavior, image wins if both are set) on an item instance. Accepts a bare filename (burger.png), an extensionless name (burger), or a full URL.Paste is the primary upload path. Dragging a file from the desktop into the picker doesn't work in FiveM: the game's CEF browser never receives OS drag events, so it isn't offered. The Browse dialog is best-effort. It can stop reopening after a use in the same game session, a known FiveM bug, so reach for paste if Browse stops responding.
Resolution order
For any given item, the first candidate that actually loads wins:
- Metadata override -
metadata.image, thenmetadata.imageurl. - The definition's image field - set through the picker; can itself be a host-allowed URL.
- The item's name - as an extensionless fallback, so naming the file after the item needs zero configuration.
Every bare or extensionless reference is expanded the same way: the local web/images/ folder is tried first, across every supported extension, then each configured image host, in configured order, also across every extension.
Supported extensions
png, webp, jpg, jpeg, gif
Checked in that order for every bare/extensionless reference.
URL allowlisting
A full http(s) URL, wherever it comes from (metadata, an item's image field, a file host), only loads when it starts with a configured image host's base URL. Anything else is dropped.
Fallback
When every method above misses, a placeholder icon shows instead.