# Images Settings

***

## 🔧 Configuration Options

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

```lua
-- ════════════════════════════════════════════════════════════════════════════════════
--  IMAGES SETTINGS
-- ════════════════════════════════════════════════════════════════════════════════════

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

***

## 📝 Setting Descriptions

### Global Images Path

```lua
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

```lua
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

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

#### Method 2: Absolute Path

```lua
{
    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

```lua
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

```lua
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

```lua
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

```lua
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

{% stepper %}
{% step %}

### 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:

   ```lua
   {
       respname = 'my_custom_item',
       name = 'My Custom Item',
       image = './images/my_custom_item.webp',
       -- ... other settings
   }
   ```
4. Restart resource:

   ```
   restart koja-crafting
   ```

{% endstep %}

{% step %}

### Option B: Use External Inventory Images

1. Set global path:

   ```lua
   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:

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

{% endstep %}
{% endstepper %}

***

## 🎯 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
```

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

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

***

## 🔍 Troubleshooting

<details>

<summary>Images Not Showing</summary>

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

</details>

***

## 📚 Related Settings

* For item configuration, see [Crafting Stations](https://docs.kojascripts.eu/new/crafting/configuration/broken-reference)
* For resource management, see [Server Settings](https://docs.kojascripts.eu/new/crafting/configuration/broken-reference)
* For general setup, see [Installation](https://docs.kojascripts.eu/new/crafting/configuration/broken-reference)