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

1

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

1. 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)

2. Add image to folder:

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

3. Configure in config.lua:

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

4. Restart resource:

   restart koja-crafting

2

Option B: Use External Inventory Images

1. Set global path:

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

2. Ensure image exists in inventory:

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

3. Reference in config:

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

---

🎯 Best Practices

Image Optimization

1. Use WebP format when possible:

   • 25-35% smaller than PNG

   • Faster loading times

   • Better performance

2. Optimize file size:

   • Keep images under 100KB each

   • Use compression tools

   • Remove unnecessary metadata

   • Use appropriate resolution (256x256 or 512x512)

3. Consistent naming:

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

1. 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:

1. Check file exists in correct location

2. Verify file extension matches config

3. Check for typos in image path

4. Ensure image format is supported (webp/png)

5. Clear FiveM cache (client)

6. Restart resource after adding images

---

📚 Related Settings

• For item configuration, see Crafting Stations

• For resource management, see Server Settings

• For general setup, see Installation