Images Settings

This page explains how to configure item images, add custom graphics, and manage image paths in Koja-Crafting.

🔧 Configuration Options

All image settings are located in shared/config.lua under the IMAGES SETTINGS section.

-- ════════════════════════════════════════════════════════════════════════════════════
--  IMAGES SETTINGS
-- ════════════════════════════════════════════════════════════════════════════════════

Config.Images = {
    globalImagesPath = 'default',
    format = 'webp'
}

📝 Setting Descriptions

Global Images Path

globalImagesPath = 'default'

Purpose: Define where item images are loaded from - either local crafting images or external inventory images.

Options:

Value

Description

Use Case

'default'

Uses images from koja-crafting/web/build/images/

Default, uses built-in images

'nui://inventory/html/images/'

Links to QB inventory

QBCore servers using qb-inventory

'nui://ox_inventory/web/build/images/'

Links to ox_inventory

ESX/Standalone using ox_inventory

Custom path

Any NUI resource path

Custom inventory systems

How it works:

The path is prepended to all item image paths
Allows using existing inventory images
No need to duplicate images across resources

Image Format

format = 'webp'

Purpose: Specify the file extension for item images.

Options:

'webp' - Modern format, smaller file size, faster loading (recommended)
'png' - Traditional format, wider compatibility, larger files

When to use each:

✅ Use 'webp' if your inventory uses WebP format
✅ Use 'png' if your inventory uses PNG format
✅ Match your inventory system's format for consistency

🎨 Image Path System

How Image Paths Work

There are two ways to define item images in your crafting configuration:

Method 1: Relative Path

{
    respname = 'bandage',
    name = 'Bandage',
    image = 'bandage.png', -- No leading './' or full path
    -- Will use: Config.Images.globalImagesPath + 'bandage.png'
}

Method 2: Absolute Path

{
    respname = 'bandage',
    name = 'Bandage',
    image = './images/bandage.png', -- Starts with './'
    -- Will use: koja-crafting/web/build/images/bandage.png
}

🔄 Configuration Examples

Example 1: Using Default Built-in Images

Config.Images = {
    globalImagesPath = 'default',
    format = 'webp'
}

-- In items configuration:
items = {
    {
        respname = 'bandage',
        image = './images/bandage.webp', -- Uses local images
    }
}

Result: Loads from koja-crafting/web/build/images/bandage.webp

Example 2: Using ox_inventory Images

Config.Images = {
    globalImagesPath = 'nui://ox_inventory/web/images/',
    format = 'png'
}

-- In items configuration:
items = {
    {
        respname = 'bandage',
        image = 'bandage.png', -- No './' prefix
    }
}

Result: Loads from ox_inventory/web/images/bandage.png

Example 3: Using qb-inventory Images

Config.Images = {
    globalImagesPath = 'nui://qb-inventory/html/images/',
    format = 'png'
}

-- In items configuration:
items = {
    {
        respname = 'bandage',
        image = 'bandage.png',
    }
}

Result: Loads from qb-inventory/html/images/bandage.png

Example 4: Mixed Sources

Config.Images = {
    globalImagesPath = 'nui://ox_inventory/web/images/',
    format = 'png'
}

items = {
    {
        respname = 'bandage',
        image = 'bandage.png', -- From ox_inventory
    },
    {
        respname = 'custom_item',
        image = './images/custom_item.png', -- From koja-crafting (override)
    }
}

Result:

bandage loads from ox_inventory
custom_item loads from koja-crafting local images

📁 Adding Custom Images

Step-by-Step Guide

Option A: Add to Built-in Images (Recommended)

Prepare your image:
- Recommended size: 256x256px or 512x512px
- Format: .webp (smaller) or .png
- Transparent background recommended
- File naming: lowercase, no spaces (e.g., my_item.webp)

Add image to folder:

koja-crafting/
└── web/
    └── build/
        └── images/
            ├── bandage.webp
            ├── lockpick.webp
            └── my_custom_item.webp  ← Add here

Configure in config.lua:

{
    respname = 'my_custom_item',
    name = 'My Custom Item',
    image = './images/my_custom_item.webp',
    -- ... other settings
}

Restart resource:
```
restart koja-crafting
```

Option B: Use External Inventory Images

Set global path:

Config.Images = {
    globalImagesPath = 'nui://ox_inventory/web/images/',
    format = 'png'
}

Ensure image exists in inventory:

ox_inventory/
└── web/
    └── images/
        └── my_item.png  ← Must exist here

Reference in config:

{
    respname = 'my_item',
    image = 'my_item.png', -- No './' prefix
}

🎯 Best Practices

Image Optimization

Use WebP format when possible:
- 25-35% smaller than PNG
- Faster loading times
- Better performance
Optimize file size:
- Keep images under 100KB each
- Use compression tools
- Remove unnecessary metadata
- Use appropriate resolution (256x256 or 512x512)
Consistent naming:

✅ Good: bandage.webp, lockpick.webp, repair_kit.webp
❌ Bad: Bandage.WEBP, lock pick.png, Repair-Kit.PNG

Transparent backgrounds:
- Better visual integration
- Professional appearance
- Matches inventory style

File Organization (Optional)

Organize images by category for easier management:

web/build/images/
├── medical/
│   ├── bandage.webp
│   ├── medikit.webp
│   └── armour.webp
├── tools/
│   ├── lockpick.webp
│   ├── repair_kit.webp
│   └── radio.webp
└── weapons/
    ├── pistol.webp
    └── ammo.webp

Then reference with subdirectories:

image = './images/medical/bandage.webp'

🔍 Troubleshooting

Images Not Showing

Problem: White/blank squares instead of images

Solutions:

Check file exists in correct location
Verify file extension matches config
Check for typos in image path
Ensure image format is supported (webp/png)
Clear FiveM cache (client)
Restart resource after adding images

For item configuration, see Crafting Stations
For resource management, see Server Settings
For general setup, see Installation

PreviousServer Settings NextPlayer Progression Settings

Last updated 7 days ago