# 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](broken://pages/80010baab5264d0e3981f139b8c90759d0d6edec)
* For resource management, see [Server Settings](broken://pages/dc10acda3885de3c999012ee46bd261e0f56e025)
* For general setup, see [Installation](broken://pages/4c205acd964633ec3c6f4aeb01f5cdad748b931d)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kojascripts.eu/new/crafting/configuration/images-settings.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.