📦Looting System

Table of Contents

1. Overview

2. Features

3. Installation

4. Configuration

5. Clothing System

6. Framework Support

7. UI Systems

8. Logging System

9. API Reference

10. Troubleshooting

Overview

Hate Looting is an advanced looting system for FiveM servers that supports both QBCore and ESX frameworks. It provides a comprehensive solution for searching objects, looting NPCs, and managing inventory with advanced clothing metadata generation and Discord logging integration.

Key Highlights

• Dual Framework Support: Works with both QBCore and ESX

• Advanced Clothing System: Automatic metadata generation with blacklist support

• Multiple UI Options: Built-in UI or core_inventory integration

• Discord Integration: Rich logging with inventory images

• Performance Optimized: Client-side detection and caching systems

• Highly Configurable: Extensive configuration options

Features

Core Features

• Object Looting: Search various props and objects in the game world

• NPC/Animal Looting: Loot zombies, animals, and other NPCs

• Progress Bar Integration: Support for multiple progress bar systems

• Target System: Integration with ox_target, qb-target, and qtarget

• Inventory Integration: Works with ox_inventory and core_inventory

• Anti-Exploit: Distance checks and search state management

Advanced Features

• Clothing Metadata System: Automatic generation of clothing metadata for core_inventory

• Client-Side Detection: Dynamic max value detection for clothing variations

• Blacklist System: Exclude specific clothing models from generation

• Unique Item Identification: Prevents UI selection issues with duplicate items

• Discord Logging: Rich webhook logging with inventory images

• Loot Zones: Configurable loot increase/decrease zones

• Item Requirements: Require specific items or weapons for certain loot types

UI Features

• Dual UI System: Choose between built-in UI or core_inventory

• Responsive Design: Mobile-friendly interface

• Sound Effects: Audio feedback for looting actions

• Visual Feedback: Progress indicators and animations

• Inventory Images: Display item images from inventory system

Installation

Requirements

• Framework: QBCore or ESX

• Dependencies (Optional):

  • ox_lib

  • mythic_progbar / esx_progressbar

  • ox_target / qb-target / qtarget

  • ox_inventory / core_inventory

Steps

1. Download: Extract hate-looting to your resources folder

2. Server Config: Add ensure hate-looting to your server.cfg

3. Framework Detection: The script auto-detects your framework

4. Configure: Edit configuration files as needed

5. Start Server: Restart your server

Configuration

Main Config (config.lua)

Basic Settings

Config.PedDeleteTime = 10 -- Time in seconds after which looted ped will be deleted
Config.TargetDistance = 4.0 -- Distance to target peds/objects
Config.animalLoot = true -- Enable animal looting
Config.enableZombieLoot = true -- Enable zombie looting
Config.Debug = false -- Enable debug mode
Config.lootRefreshTime = 30 -- Default refresh time for prop loot (minutes)
Config.emptyLootRefreshTime = 5 -- Empty loot location refresh time (minutes)

UI Configuration

Config.UseUIType = "ownui" -- "ownui" or "core_inventory"
Config.UseProgressBar = true -- Use progress bar
Config.UsePressE = false -- Use press E to loot instead of target system
Config.DistanceCheckProtection = 25.0 -- Security distance check
Config.InventoryImagePath = "nui://core_inventory/html/img/" -- Image path for inventory items

Clothing Configuration (clothing_config.lua)

Clothing Metadata System

Config.useCoreMetadataClothes = true -- Enable clothing metadata generation

Clothing Item Configuration

Config.ClothesConfig = {
    torso = {
        componentId = 11,
        propId = nil,
        maxModel = 500,
        maxTexture = 0,
        autoDetectMax = true -- Enable auto-detection for max values
    },
    -- ... other clothing items
}

Blacklist System

Config.ClothingBlacklist = {
    torso = {1, 2, 3, 15}, -- Exclude these model IDs
    pants = {0, 1},
    shoes = {},
    -- ... other clothing items
}

Torso Mappings

The script includes comprehensive torso mappings for proper clothing compatibility:

Config.TorsoMappings = {
    male = {
        [0] = {0, 1, 9, 16, 271, 345, ...}, -- Model mappings for torso 0
        [1] = {529, 6, 165, 397, ...}, -- Model mappings for torso 1
        -- ... extensive mappings
    },
    female = {
        -- Female-specific mappings (expandable)
    }
}

Loot Rewards Configuration

Loot Tables

Config.LootRewards = {
    ["zombie_default"] = {
        loop = 1, -- Number of loot rolls
        loopIncrease = nil, -- Additional rolls from zones
        {name = {'torso','pants','shoes'}, min = 1, max = 3, chance = 10},
        {name = {'field_dressing','packing_bandage'}, min = 1, max = 3, chance = 5},
        -- ... more loot entries
    },
    -- ... more loot types
}

Lootable Objects

Config.LootAbles = {
    ['prop_dumpster_3a'] = "trashBig",
    ['prop_gas_pump_old2'] = "benzin",
    ['prop_toolchest_01'] = "vehparts",
    -- ... extensive object list
}

Animal/NPC Loot Types

Config.lootByHashType = {
    ['a_c_boar'] = 'pig_loot',
    ['a_c_cat_01'] = 'cat_loot',
    ['a_c_deer'] = 'deer_loot',
    -- ... animal mappings
}

Advanced Configuration

Loot Zones

Config.lootIncreaseZones = {
    {coords = vector3(215.578, -1135.859, 29.29675), radious = 400.0, loopIncrease = 2}
}

Config.disableLootZones = {
    {coords = vector3(215.578, -1135.859, 29.29675), radius = 400.0}
}

Item/Weapon Requirements

Config.lootTypeItemNeeded = {
    ['gunloot'] = {items = {"blowtorch"}, remove = true},
    ['pistolCase'] = {items = {"blowtorch"}, remove = true}
}

Config.lootTypeWeaponNeeded = {
    ['pig_loot'] = {
        weapons = {"weapon_knife", "weapon_hatchet"}, 
        label = "You need a cutting weapon"
    }
}

Progress Bar Animations

Config.ProgressBars = {
    ["zombie_default"] = {
        duration = 1000,
        label = "Searching Corpse",
        animation = {
            animDict = 'amb@prop_human_bum_bin@base',
            anim = 'base'
        }
    },
    -- ... more progress bar configs
}

Clothing System

Overview

The clothing system automatically generates metadata for clothing items when using core_inventory, ensuring compatibility with clothing systems.

Features

• Auto-Detection: Automatically detects maximum model and texture variations

• Blacklist Support: Exclude problematic clothing models

• Gender Support: Separate configurations for male/female characters

• Torso Mapping: Proper torso compatibility for clothing items

• Caching System: Client-side caching for performance optimization

Configuration Examples

Basic Clothing Item

mask = {
    componentId = 1,
    propId = nil,
    maxModel = 200,
    maxTexture = 0,
    autoDetectMax = true
}

Prop Item (Hat/Glasses)

hat = {
    componentId = nil,
    propId = 0,
    maxModel = 200,
    maxTexture = 0,
    autoDetectMax = true
}

Blacklisting Models

Config.ClothingBlacklist = {
    mask = {1, 5, 10, 25}, -- These mask models will never be generated
    hat = {0, 3, 7}
}

Metadata Generation

The system generates metadata in the following format:

-- For component items (torso, pants, etc.)
{
    mModel = 15,
    mTexture = 2,
    mID = 11,
    mTorso = 1, -- For torso items
    image = 'male_11_15',
    mModelMax = 500,
    wModelMax = 500
}

-- For prop items (hat, glasses, etc.)
{
    mPropModel = 10,
    mPropTexture = 1,
    mPropID = 0,
    image = 'male_prop_0_10',
    mModelMax = 200,
    wModelMax = 200
}

Framework Support

Unified Framework System

The script uses a unified framework file (server/framework_unified.lua) that supports both QBCore and ESX with automatic detection.

Auto-Detection

if GetResourceState('es_extended') ~= 'missing' then
    Config.Framework = "ESX"
elseif GetResourceState('qb-core') ~= 'missing' then
    Config.Framework = "QB"
end

Framework Functions

The unified system provides consistent functions:

• GetPlayerFromId(src) - Get player object

• AddInventoryItem(player, item, count, metadata) - Add item to inventory

• RemoveInventoryItem(player, item, count) - Remove item from inventory

• HasEnoughtInventoryItem(player, item, count) - Check item availability

• GetItemLabel(item) - Get item display name

• ShowNotification(src, message) - Send notification

UI Systems

Built-in UI System

The script includes a custom HTML/CSS/JavaScript UI with the following features:

Features

• Responsive Design: Works on all screen sizes

• Sound Effects: Audio feedback for actions

• Animations: Smooth transitions and effects

• Item Images: Display inventory item images

• Drag and Drop: Interactive item management

Customization

The UI can be customized by editing files in the html/ folder:

• nui.html - HTML structure

• app.js - JavaScript functionality

• Sound files for audio feedback

Core Inventory Integration

When using core_inventory, the script integrates seamlessly:

Config.UseUIType = "core_inventory"

Features:

• Advanced Loot Interface: Uses core_inventory's openLootAdvanced

• Metadata Support: Full metadata preservation

• Inventory Management: Integrated with core_inventory systems

Logging System

Discord Webhook Integration

The script includes comprehensive Discord logging with the following features:

Log Types

• Loot Events: When players loot items

• Admin Actions: Administrative activities

• Error Logging: System errors and issues

Configuration (logs.lua)

Config.Webhooks = {
    ['loot'] = 'YOUR_DISCORD_WEBHOOK_URL',
    ['admin'] = 'YOUR_ADMIN_WEBHOOK_URL'
}

Features

• Rich Embeds: Detailed Discord embeds with colors and fields

• Item Images: Display inventory item images in logs

• Metadata Logging: Log item metadata for debugging

• Player Information: Include player details and coordinates

• Timestamp Support: Automatic timestamp generation

Example Log Entry

{
    "title": "Player Looted Items",
    "color": 3447003,
    "fields": [
        {"name": "Player", "value": "PlayerName (123)", "inline": true},
        {"name": "Item", "value": "torso x2", "inline": true},
        {"name": "Source", "value": "zombie_default", "inline": true},
        {"name": "Coordinates", "value": "123.45, 456.78, 789.01", "inline": true}
    ],
    "thumbnail": {"url": "inventory_item_image_url"},
    "timestamp": "2025-08-03T12:00:00.000Z"
}

API Reference

Server Events

Core Events

-- Start looting process
TriggerServerEvent('server:PropLoot', coords, model, k, prop)
TriggerServerEvent('server:PedLoot', coords, entityModel, model, k)

-- Take specific loot item
TriggerServerEvent('server:TakeLoot', lootId, itemName, count, uniqueId)

-- Search state management
TriggerServerEvent('server:StartLoot', coords)
TriggerServerEvent('server:StopLoot', coords)

Clothing System Events

-- Request max clothing values from client
TriggerClientEvent('server:requestClothingMaxValues', src, itemName, config)

-- Receive max values from client
TriggerServerEvent('client:responseClothingMaxValues', itemName, maxModel, maxTexture)

Client Events

UI Events

-- Show loot interface
TriggerClientEvent('showLootUI', src, lootData)

-- Update loot interface
TriggerClientEvent('updateLootUI', -1, updateData)

-- Delete NPC after looting
TriggerClientEvent('deleteped', -1, entityId)

Server Functions

Clothing Functions

-- Generate clothing metadata
generateClothingMetadata(itemName, src)

-- Check if item is clothing
isClothingItem(itemName)

-- Get torso mapping for model
GetTorsoForModel(mModel, gender)

-- Preload clothing max values
preloadClothingMaxValues(src)

Utility Functions

-- Generate random number for loot ID
returnRandomNumber()

-- Round coordinates for consistency
roundCoords(coords)

-- Find entity in loot table
findEntityInTable(entity, coords, model)

-- Get loop increase from zones
GetLoopAdd(lootType, coords)

Client Functions

Clothing Detection

-- Get max clothing variations
GetClothingMaxValues(clothesConfig)

-- Check required weapons
HasRequiredWeapon(lootType)

UI Management

-- NUI Callbacks
RegisterNUICallback('takeLoot', function(data, cb))
RegisterNUICallback('closeInventory', function(data, cb))

Troubleshooting

Common Issues

1. Clothing Metadata Not Working

Problem: Clothing items don't have proper metadata Solution:

• Ensure Config.useCoreMetadataClothes = true

• Verify core_inventory is installed and working

• Check if clothing items are properly configured in clothing_config.lua

2. UI Not Showing

Problem: Loot UI doesn't appear Solution:

• Check Config.UseUIType setting

• Verify NUI resource is properly started

• Check for JavaScript errors in console (F8)

3. Framework Detection Issues

Problem: Script doesn't detect framework Solution:

• Ensure framework resource is started before hate-looting

• Check framework resource names match expected names

• Verify framework is properly installed

4. Loot Not Refreshing

Problem: Loot locations don't refresh Solution:

• Check Config.lootRefreshTime and Config.emptyLootRefreshTime

• Verify server isn't restarting before refresh time

• Check for errors in server console

5. Distance/Target Issues

Problem: Can't target objects or distance issues Solution:

• Adjust Config.TargetDistance

• Check target system integration (ox_target, qb-target)

• Verify Config.DistanceCheckProtection isn't too restrictive

Debug Mode

Enable debug mode for troubleshooting:

Config.Debug = true

This will provide console output for:

• Loot generation processes

• Clothing metadata generation

• Framework detection

• Target system interactions

Performance Optimization

Client-Side Caching

The script uses client-side caching for clothing max values to reduce server load:

• Cache duration: 5 minutes

• Automatic cache refresh

• Fallback to config values if detection fails

Server-Side Optimization

• Unified framework system reduces code duplication

• Efficient loot generation algorithms

• Optimized database queries (if applicable)

Error Logging

The script includes comprehensive error logging:

• Server console errors

• Client console errors (when debug enabled)

• Discord webhook error notifications

• Fallback systems for critical failures

Support

For additional support:

1. Check this documentation first

2. Enable debug mode to identify issues

3. Check server/client console for errors

4. Verify all dependencies are properly installed

5. Ensure proper configuration of all systems

---

This documentation covers the complete feature set of Hate Looting. For the most up-to-date information, always refer to the latest version of this documentation.