# Configuration

### Prerequisites

Before setting up the force-appearance, ensure that you have the following dependency installed:

* **ox\_lib**: This library is required for the resource to function correctly.
  * **GitHub Repository**: [ox\_lib](https://github.com/overextended/ox_lib)
  * **Documentation**: [ox\_lib Documentation](https://overextended.dev/ox_lib)

## Configuration

This page covers all configuration options available in Force Burglary. All configuration files are located in the `config/` folder.

### Table of Contents

* Installation
* Core Configuration
* House List Configuration
* Loot Pools Configuration
* Interiors Configuration
* Market Configuration
* Pawnshop Configuration

### Installation

#### 1. Database Setup

Run the SQL file to create necessary tables:

```sql
-- Execute force-burglary.sql
-- This will create the burglary_xp table for player progression
```

The SQL file creates:

* `burglary_xp` table - Stores player XP and level data

#### 2. Resource Installation

1. Extract `force-burglary` to your resources folder
2. Ensure dependencies are started before this resource
3. Add to your `server.cfg`:

```cfg
ensure oxmysql
ensure ox_lib
ensure force-burglary
```

4. Restart your server

#### 3. Framework Configuration

The system will auto-detect your framework, but you can manually configure it in `config/config.lua`.

### Core Configuration (`config/config.lua`)

#### Basic Settings

```lua
Config.Debug = false -- Enable debug prints (use only for development)
Config.Locale = 'en' -- Language: "ar", "en", "es", "fr", "pt", "de", "nl", "pl", "ru", "sv" or "auto"
```

#### Admin Configuration

Configure admin permissions for bypassing restrictions and managing the system:

```lua
Config.Admin = {
  Global = {
    enabled = true,
    ace = "admin", -- ACE permission required
    players = {
      "discord:453870580374962177", -- Add player identifiers
      "discord:566930948986241024"
    }
  },
  IgnoreCooldown = {
    enabled = true,
    ace = "admin",
    players = {
      "discord:453870580374962177",
      "discord:566930948986241024"
    }
  }
}
```

#### Framework Settings

```lua
Config.Framework = {
  name = "auto",    -- "esx", "qbcore", "qbox", "custom" or "auto"
  resource = "auto" -- Resource name for ESX, QBCore, qbox etc
}
```

* `name`: Specify your framework or use "auto" for automatic detection
* `resource`: Framework resource name (auto-detected if set to "auto")

#### Interior Resource

```lua
Config.InteriorResource = "auto" -- "qb-interior", "force-interior" or "custom"
```

Specify which interior shell resource you're using.

#### Stealth Configuration

```lua
Config.Stealth = {
  enabled = true,
  couching = {
    animSet = "move_ped_crouched" -- Animation set for crouching
  }
}
```

Enable stealth mechanics where players can crouch to reduce noise.

#### Dispatch Configuration

```lua
Config.Dispatch = {
  job = { "police" },          -- Police job names
  system = "auto",             -- "auto", "qs-dispatch", "core_dispatch", "custom" or "none"
  onPedSound = false,          -- Dispatch when NPC makes noise
  alarmSound = false,          -- Play sound when dispatch triggers
  time = 10,                   -- Blip duration in minutes
  sprite = 459,                -- Dispatch blip sprite
  noSystem = {
    blip = {
      sprite = 459,
      color = 1,
      scale = 0.8,
    }
  }
}
```

* `job`: Array of police job names that receive dispatches
* `system`: Dispatch system integration (auto-detects common systems)
* `onPedSound`: Send dispatch when NPCs shoot or make noise
* `alarmSound`: Play alarm sound when dispatch is triggered
* `time`: How long the dispatch blip stays on the map
* `noSystem`: Fallback blip settings if no dispatch system is detected

#### XP and Leveling System

```lua
Config.Levels = {
  xpToLevel = 100, -- XP required per level

  difficulty = {
    easy = 0,      -- Level 0 required for easy houses
    medium = 1000, -- Level 10 required for medium houses
    hard = 5000    -- Level 50 required for hard houses
  },

  toAddPerLoot = {
    easy = { 2, 3 },   -- Gain 2-3% XP per loot (easy)
    medium = { 5, 6 }, -- Gain 5-6% XP per loot (medium)
    hard = { 8, 10 }   -- Gain 8-10% XP per loot (hard)
  }
}
```

* `xpToLevel`: Amount of XP needed to gain one level
* `difficulty`: XP requirements to unlock each difficulty tier
* `toAddPerLoot`: Percentage of level XP gained per item looted

#### Progress Bar System

```lua
Config.Progressbar = {
  system = "auto" -- "auto", "none", "esx_progressbar", "qb-progress", "ox_lib" or "custom"
}
```

Specify which progress bar system to use. "none" uses built-in 3D text.

#### Active Burglary UID Range

```lua
Config.ActiveBurglaryUID = { 11111, 99999 }
```

Range of UIDs used for active burglary instances.

#### Interaction Configuration

Configure how players interact with robbery elements:

```lua
Config.Interaction = {
  keyCode = 38, -- E key (https://docs.fivem.net/docs/game-references/controls/)

  Text3D = {
    enabled = false,
    distance = 2.0,
    key = "E"
  },

  Marker = {
    enabled = false,
    distance = 2.0,
    id = 20, -- Marker type ID
  },

  HelpNotification = {
    enabled = false,
    distance = 2.0,
    key = "~INPUT_PICKUP~"
  },

  Target = {
    enabled = true,      -- Recommended
    distance = 1.8,
    system = "auto"      -- "ox_target", "qb-target", "custom" or "auto"
  },

  TextUI = {
    enabled = false,
    distance = 2.0,
    key = "E"
  }
}
```

Only enable ONE interaction method. Target system is recommended for best performance.

#### House Blip Configuration

```lua
Config.HouseBlip = {
  sprite = 40,  -- Blip sprite ID
  color = 3,    -- Blip color
  scale = 0.8,  -- Blip size
}
```

Blip that appears when a player starts a robbery.

#### Start Locations

```lua
Config.StartLocations = {
  {
    coords = vec3(264.41, -1108.59, 29.72),
    ped = {
      model = "a_m_m_business_01",
      heading = 140.0,
      animation = {
        scenario = "WORLD_HUMAN_AA_SMOKE", -- Scenario animation
        anim = nil,                        -- Or use dict + anim
        dict = nil
      }
    }
  }
}
```

Configure where players can access the burglary menu.

#### Lockpick Configuration

```lua
Config.Lockpick = {
  ChanceForDispatchOnFail = { 1, 10 }, -- 10% chance {min, max}
  Animation = {
    scenario = nil,
    dict = "missheistfbisetup1",
    anim = "hassle_intro_loop_f",
  }
}
```

* `ChanceForDispatchOnFail`: Chance to alert police on failed lockpick (set to false to disable)
* `Animation`: Animation played during lockpicking

#### Difficulty Scaling

```lua
Config.Difficulty = {
  scaling = {
    easy = {
      lockpickTime = 10,          -- Seconds to lockpick
      lootTime = 5,               -- Seconds to loot items
      noise = 0.7,                -- Noise multiplier (0.0-1.0)
      npcAggression = 0.3,        -- NPC aggression level (0.0-1.0)
      policeResponseTime = 180    -- Seconds before police arrive
    },
    medium = {
      lockpickTime = 8,
      lootTime = 4,
      noise = 0.85,
      npcAggression = 0.6,
      policeResponseTime = 120
    },
    hard = {
      lockpickTime = 6,
      lootTime = 3,
      noise = 1.0,
      npcAggression = 0.9,
      policeResponseTime = 60
    }
  }
}
```

Fine-tune difficulty parameters for each tier.

### House List Configuration (`config/houselist.lua`)

Configure individual houses that can be robbed:

```lua
Config.HouseList = {
  {
    title = "Davis Residence",
    description = "Street - Grove Street",
    difficulty = "easy", -- "easy", "medium", "hard"
    image = "house_1.png",

    requiredPolices = 0,  -- Minimum police online
    cooldown = 40,        -- Minutes before house can be robbed again

    interior = 'standardmotel_shell',
    entranceCoords = vector4(126.6, -1929.81, 21.38, 211.44),

    lockpick = {
      required = true,
      lockpickType = "basic",      -- Type of lockpick required
      item = "lockpick",           -- Item name
      removeLockpickOnFailAndSuccess = true, -- Remove item after use
      lockpickDifficulty = 1,      -- Difficulty level (1-5)
      lockpickPickNumber = 4       -- Number of pins to pick
    },

    crowbar = {
      required = false,
      item = "weapon_crowbar",
      difficulty = "easy"          -- Mini-game difficulty
    },

    requirements = {
      {
        title = "You need Lockpick",
        type = "item",             -- "item" or "xp"
        value = "lockpick",        -- Item name or XP amount
      },
    },

    buyableInformation = {
      -- Optional: Information that can be purchased
    },
  },
}
```

#### House Configuration Options

* `title`: Display name of the house
* `description`: Additional information shown to players
* `difficulty`: Determines loot quality and scaling
* `image`: Image file name in `html/houses/` folder
* `requiredPolices`: Minimum number of police required online
* `cooldown`: Minutes before house can be robbed again (0 to disable)
* `interior`: Interior shell name (must match Config.Interiors)
* `entranceCoords`: Where players enter the house

#### Lockpick Settings

* `required`: Whether lockpicking is required
* `lockpickType`: Type of lockpick (used for skill checks)
* `item`: Item name that will be consumed
* `removeLockpickOnFailAndSuccess`: Whether to remove item after attempt
* `lockpickDifficulty`: 1-5 difficulty rating
* `lockpickPickNumber`: Number of pins in the lockpick mini-game

#### Crowbar Settings

* `required`: Whether crowbar entry is available
* `item`: Crowbar item name
* `difficulty`: Mini-game difficulty level

#### Requirements

Define what players need to rob this house:

```lua
requirements = {
  {
    title = "Display text",
    type = "item",      -- "item" for inventory check
    value = "lockpick", -- Item name
  },
  {
    title = "You need Level 10",
    type = "xp",        -- "xp" for level requirement
    value = 1000,       -- Total XP required
  },
}
```

### Loot Pools Configuration (`config/lootpools.lua`)

Define what items can be found during burglaries:

```lua
Config.LootPools = {
  easy = {
    common = {
      { name = "phone", count = 1, chance = 70 },
      { name = "radio", count = 1, chance = 50 },
    },
    rare = {
      { name = "television", count = 1, chance = 35 },
      { name = "tablet", count = 1, chance = 25 },
    }
  },

  medium = {
    common = {
      { name = "perfume", count = 1, chance = 65 },
      { name = "dvd", count = 1, chance = 60 },
    },
    rare = {
      { name = "goldchain", count = 1, chance = 25, blackmoney = true },
    }
  },

  hard = {
    common = {
      { name = "laptop", count = 1, chance = 50 },
    },
    rare = {
      { name = "ipad", count = 1, chance = 35 },
    },
    epic = {
      { name = "diamond_ring", count = 1, chance = 10, blackmoney = true },
    }
  }
}
```

#### Loot Item Properties

* `name`: Item name (must match your inventory system)
* `count`: Quantity of item to give
* `chance`: Percentage chance to spawn (0-100)
* `blackmoney`: If true, gives black money equal to item value instead

#### Difficulty Loot Distribution

```lua
Config.DifficultyLoot = {
  easy = {
    pools = { "easy" },
    weights = {
      common = 75,  -- 75% chance for common items
      rare = 25     -- 25% chance for rare items
    }
  },
  medium = {
    pools = { "easy", "medium" },
    weights = {
      common = 60,
      rare = 40
    }
  },
  hard = {
    pools = { "medium", "hard" },
    weights = {
      common = 45,
      rare = 40,
      epic = 15
    }
  }
}
```

* `pools`: Which loot pools to pull from
* `weights`: Rarity distribution percentages

### Interiors Configuration (`config/interiors.lua`)

Configure interior shells with NPC behavior and loot points:

```lua
Config.Interiors = {
  ['furnitured_midapart'] = {
    interior = 'furnitured_midapart',
    interiorCoords = vector4(0.0, 0.0, -20.0, 0.0),
    exitCoords = vector4(1.42, -9.77, -18.95, 0.0),

    tenants = {
      ["easy"] = {
        {
          model = 'a_m_m_og_boss_01',
          isArmedWith = 'weapon_bat',
          hoursAtHome = { 7, 10 },      -- Home between 7 AM - 10 AM
          hoursAreSleeping = { 22, 6 }, -- Sleeping 10 PM - 6 AM

          activitesAtHome = {
            {
              coords = vector4(-2.94, 2.52, -18.95, 192.7),
              animation = {
                dict = 'timetable@ron@ig_3_couch',
                anim = 'base'
              }
            },
          },

          sleeping = {
            coords = vector4(-0.32, 0.06, -18.27, 167.96),
            animation = {
              dict = 'anim@amb@nightclub@lazlow@lo_sofa@',
              anim = 'lowsofa_dlg_fuckedup_laz'
            },
          },
        },
      },
    },

    loot = {
      {
        coords = vector4(0.75, 5.95, -19.335, 281.16),
        animation = {
          "anim@scripted@player@fix_chop_petting@male@",
          "petting",
          20000, -- Duration in ms
          1      -- Flag
        },
      },
    },

    propLoot = {
      -- Optional: Loot attached to specific props
    },
  },
}
```

#### Interior Properties

* `interior`: Interior shell name (must match your shell resource)
* `interiorCoords`: Offset coordinates for the interior instance
* `exitCoords`: Where players exit back to the world

#### Tenant Configuration

NPCs that live in the house, configured per difficulty:

* `model`: Ped model hash or name
* `isArmedWith`: Weapon they use when aggressive
* `hoursAtHome`: Hours they are present but not sleeping \[start, end]
* `hoursAreSleeping`: Hours they are asleep \[start, end]
* `activitesAtHome`: Array of locations and animations when awake
* `sleeping`: Location and animation when sleeping

#### Loot Points

Define where items can be looted:

* `coords`: Location of the loot point
* `animation`: Animation played when looting \[dict, anim, duration, flag]

### Market Configuration (`config/market.lua`)

Configure the black market where players buy tools:

```lua
Config.Market = {
  enabled = true,

  locations = {
    {
      model = "a_m_m_salton_03",

      blip = {
        enabled = false,
        sprite = 351,
        color = 2,
        scale = 0.8,
        name = "Market"
      },

      buyItems = {
        {
          name = "lockpick",
          label = "Lockpick",
          price = 250,
          image = "lockpick.png"
        },
        {
          name = "advancedlockpick",
          label = "Advanced Lockpick",
          price = 450,
          image = "advancedlockpick.png"
        },
      },

      coords = {
        ["monday"] = {
          animation = {
            scenario = "WORLD_HUMAN_SMOKING",
          },
          coords = vector4(-324.19, -598.85, 33.55, 49.16)
        },
        ["tuesday"] = {
          -- Different location for Tuesday
        },
        -- Configure for each day of the week
      },
    },
  },
}
```

#### Market Properties

* `enabled`: Enable/disable the market system
* `model`: NPC ped model
* `blip`: Map blip configuration (can be disabled for secrecy)
* `buyItems`: Array of items players can purchase
* `coords`: NPC location changes by day of the week

#### Buy Item Properties

* `name`: Item identifier
* `label`: Display name
* `price`: Cost in money
* `image`: Image file in `html/market/` folder

### Pawnshop Configuration (`config/pawnshop.lua`)

Configure pawnshops where players sell stolen goods:

```lua
Config.PawnShop = {
  enabled = true,

  locations = {
    {
      model = "a_m_m_mexlabor_01",

      blip = {
        enabled = true,
        sprite = 351,
        color = 2,
        scale = 0.8,
        name = "Pawn Shop"
      },

      sellItems = {
        {
          name = "ipad",
          label = "iPad",
          price = 1200,
          image = "ipad.png"
        },
        {
          name = "radio",
          label = "Radio",
          price = 100,
          image = "radio.png"
        },
      },

      coords = {
        ["monday"] = {
          animation = {
            scenario = "WORLD_HUMAN_CLIPBOARD",
          },
          coords = vector4(182.55, -1319.48, 29.32, 236.89)
        },
        -- Configure for each day of the week
      },
    },
  },
}
```

#### Pawnshop Properties

* `enabled`: Enable/disable the pawnshop system
* `model`: NPC ped model
* `blip`: Map blip configuration
* `sellItems`: Array of items players can sell
* `coords`: NPC location changes by day of the week

#### Sell Item Properties

* `name`: Item identifier (must match loot pool items)
* `label`: Display name
* `price`: How much players receive
* `image`: Image file in `html/pawnshop/` folder

### Tips for Configuration

#### Performance Optimization

1. **Limit active houses**: Don't enable all 1400+ houses at once if you have a small server
2. **Adjust cooldowns**: Higher cooldowns prevent server load from constant robberies
3. **Optimize loot pools**: Fewer items with higher chances = better performance
4. **Disable unused features**: Turn off market/pawnshop if not needed

#### Balancing Economy

1. **Tool costs**: Make lockpicks expensive enough to matter
2. **Loot values**: Balance pawnshop prices with house difficulty
3. **XP requirements**: Gate difficult houses behind progression
4. **Cooldowns**: Prevent house farming with appropriate cooldowns

#### Custom Integration

1. **Framework files**: Modify files in `client/custom/frameworks/` and `server/custom/frameworks/`
2. **Dispatch system**: Customize `client/custom/dispatch.lua`
3. **Progress bars**: Customize `client/custom/progressbar.lua`
4. **Target system**: Customize `client/custom/target.lua`

#### Testing Configuration

1. Enable `Config.Debug = true` during testing
2. Set cooldowns to 0.1 minutes for rapid testing
3. Set `requiredPolices = 0` for testing without police online
4. Use admin commands to reset player XP for progression testing


---

# 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.forcedevelopments.com/resources/force-burglary/configuration.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.