Images Settings#

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

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

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:

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

🔍 Troubleshooting#

📚 Related Settings#

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

Related pages#

• General Settings — This page covers the basic configuration options for Koja-Crafting that control debug mode, language, and player behavior.
• Server Settings — This page covers server-side configuration options including database management, crafting recovery, and shared table functionality.
• Player Progression Settings — This page covers the player progression system including levels, experience points, and how to configure the leveling system in Koja-Crafting.
• Admin Settings — This page covers admin permission configuration and available admin commands for managing Koja-Crafting.
• Interaction Settings — This page covers how players interact with crafting stations - either through key press or target system (ox_target,qb-target,).
• Crafting Queue Settings — This page covers the crafting queue system that manages distance checking, warnings, and crafting cancellation when players move away from stations.
• Configuration — back to the section overview