# Introduction ## Introduction ### Overview **Force Burglary** is an advanced, highly optimized FiveM house robbery system designed for modern roleplay servers. Built with performance and immersion in mind, it offers a comprehensive burglary experience with multi-framework support, modern React UI, XP progression system, dynamic NPC interactions, and extensive configuration options. ### Key Features #### Performance Optimized * **Efficient resource usage** - Minimal impact on server performance * **Optimized interior loading** - Async operations for smooth transitions * **Smart caching** - Reduced database queries with intelligent caching * **Proper error handling** - pcall wrappers and validation throughout * **Throttled NUI updates** - Minimal communication between client and NUI #### Modern User Interface * **React + TypeScript** - Built with modern web technologies * **Shadcn UI + Tailwind CSS** - Beautiful, responsive design * **House selection menu** - Browse available houses with detailed information * **Market system** - Purchase tools and equipment from dynamic NPC locations * **Pawnshop system** - Sell stolen goods at configured pawnshop locations * **XP progression display** - Track your burglary level and progress #### Multi-Framework Support Supports all major FiveM frameworks out of the box: * **ESX** - Full ESX framework support * **QBCore** - Complete QBCore integration * **QBox** - Native QBox support * **Custom frameworks** - Easily adaptable to any custom framework * **Auto-detection** - Automatically detects your framework #### Comprehensive Burglary Features * **Dynamic difficulty system** - Easy, medium, and hard houses with scaling rewards * **XP progression** - Level up to unlock more difficult heists * **Lockpicking mechanics** - Multiple lockpick types and difficulties * **Crowbar entry** - Alternative entry method with mini-game * **Interior instancing** - Each robbery happens in a separate instance * **NPC tenants** - Dynamic NPC behavior with sleeping, awake, and aggression states * **Loot system** - Randomized loot with rarity tiers (common, rare, epic) * **Noise detection** - Make too much noise and alert the police * **Police dispatch** - Automatic dispatch integration with multiple systems * **Cooldown system** - Per-house cooldowns to prevent farming * **Stealth mechanics** - Crouch to reduce noise and avoid detection #### Market System * **Dynamic NPC locations** - Market NPC moves to different locations each day * **Purchase tools** - Buy lockpicks, crowbars, sleep gas, and more * **Configurable prices** - Easily adjust item prices * **Inventory integration** - Seamless integration with framework inventories #### Pawnshop System * **Sell stolen goods** - Turn your loot into cash * **Multiple locations** - Configure multiple pawnshop locations * **Dynamic pricing** - Set custom prices for each item * **Item verification** - Only sell items that were obtained from burglaries #### Interior System * **Multiple shell support** - Compatible with popular shell resources * **Configurable tenants** - Define NPC behavior per difficulty level * **Loot spawn points** - Pre-configured loot locations in each interior * **Interactive props** - Specific animations for looting different objects * **Exit system** - Return to the real world at any time #### Police Integration * **Automatic dispatch** - Supports qs-dispatch, core\_dispatch, and custom systems * **Alarm system** - Triggered alarms send police to the location * **NPC alerts** - NPCs can alert police when woken or when they hear noise * **Configurable response** - Set required police count, response times, and more #### Admin Features * **Admin menu** - Manage burglaries and player XP * **Cooldown override** - Admins can bypass cooldowns * **XP management** - Add or remove player XP * **Debug mode** - Comprehensive logging for troubleshooting #### Developer Friendly * **LuaDoc annotations** - Full IDE support and autocomplete * **Modular architecture** - Easy to extend and customize * **Proper error handling** - pcall wrappers and validation * **Extensive callbacks** - Rich API for integrations * **Custom framework support** - Adapt to any framework easily * **OX Lib integration** - Uses ox\_lib for base functions * **OxMySQL** - Optimized database queries ### System Requirements #### Required Dependencies * **ox\_lib** - Core library for UI, callbacks, and utilities * **oxmysql** - Database management #### Optional Dependencies * **Interior shell resource** - qb-interior, force-interior, or custom * **Dispatch system** - qs-dispatch, core\_dispatch, or custom * **Target system** - ox\_target, qb-target, or custom * **Progress bar** - ox\_lib, qb-progress, esx\_progressbar, or custom #### Framework Compatibility * ESX (Legacy & Modern) * QBCore * QBox * Custom/Standalone (with minimal configuration) #### Database * MySQL 5.7 or higher * MariaDB 10.2 or higher ### What Makes Force Burglary Unique? #### Immersive Gameplay Unlike simple robbery scripts, Force Burglary creates a complete burglary experience: * **Dynamic NPC behavior** - Tenants have daily schedules, sleep patterns, and realistic reactions * **Stealth mechanics** - Players must manage noise levels to avoid detection * **Risk vs reward** - Higher difficulty houses offer better loot but increased risk * **Progression system** - Players start with easy houses and work their way up #### Performance Focus Designed for servers with high player counts: * **Instanced interiors** - Each robbery is isolated, preventing interference * **Async operations** - No server freezing or lag spikes * **Optimized queries** - Minimal database impact * **Efficient NUI** - Throttled updates and smart rendering #### Complete Economy Integration Creates a full criminal economy loop: * **Market system** - Purchase tools from a black market dealer * **Loot variety** - Hundreds of possible items across rarity tiers * **Pawnshop system** - Fence stolen goods for profit * **Money sinks** - Tools cost money, creating economic balance #### Extensive Customization Configure every aspect of the system: * **1400+ pre-configured houses** - Covers the entire map * **Multiple interior shells** - Compatible with popular shell packs * **Custom loot pools** - Define your own items and spawn chances * **Adjustable difficulty** - Fine-tune every difficulty parameter * **Flexible requirements** - Set item, level, or police requirements per house #### Integration Ready Works seamlessly with your existing systems: * **Multi-dispatch support** - Works with all popular dispatch systems * **Target system support** - ox\_target, qb-target, or custom * **Progress bar support** - Multiple options or use built-in 3D text * **Framework agnostic** - Easy to adapt to any setup ### Support & Documentation #### Documentation Complete documentation is available covering: * Installation and setup * Configuration options * Events and exports * Integration examples * Troubleshooting #### Support * **Discord support** - Join our Discord for help and updates * **Regular updates** - Continuous improvements and bug fixes * **Community feedback** - We listen to our users ### Getting Started Ready to add an immersive burglary system to your server? Check out the Configuration guide to get started, or jump to Usage & Integration to learn how to integrate Force Burglary with your other scripts. --- # 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/introduction.md?ask= ``` 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.