# 🎭 unexis_npchostage

> **Advanced NPC Hostage & Compliance System for FiveM** 🚁  

> *Ultimate hostage taking, NPC compliance, and robbery script for QB-Core/Qbox servers*

> *Limited to ONE npc hostage at a time to prevent legacy crashes*

---

## ✨ **Key Features**

### 🎯 **Hostage System**

- 🔫 **Take NPCs Hostage** - Full hostage carrying with realistic animations

- 🎮 **Target Integration** - Works with qb-target and ox_target

- 🚗 **Vehicle Compatibility** - Force NPCs in/out of vehicles seamlessly

- 🎭 **Animation Restoration** - Smart system prevents animation breaking

- 🔊 **Scared States** - Realistic crying, scared voices, and facial expressions

### 💰 **Robbery & Compliance**

- 🙌 **Weapon Pointing** - Aim at NPCs to make them comply (hands up)

- 🧎 **Force Surrender** - Make NPCs kneel in surrender position

- 💵 **Rob System** - Configurable loot with chance-based rewards

- ⏰ **Anti-Exploit** - Individual NPC cooldowns prevent spam

- 🎲 **Random Loot** - Customizable items with min/max quantities

### 🚗 **Advanced Vehicle Integration**

- 🚪 **Smart Exit** - NPCs automatically exit vehicle when you aim at them

- 🚙 **Force Entry** - Push complied NPCs into nearby vehicles

- 🎯 **Seat Detection** - Finds available seats automatically

### 🛠️ **Universal Compatibility**

- 🔧 **Framework Support** - QB-Core & Qbox with auto-detection

- 🎯 **Target Systems** - qb-target, ox_target, or both simultaneously

- 🔫 **Any Weapon** - Works with ALL weapons (custom weapons included)

- 🌐 **Server Ready** - Production-tested with memory management

### 🚗 **SimpleMode - Vehicle Entry Behavior**

```lua

Config.SimpleMode = false  -- Toggle between realistic and instant vehicle entry

```

**SimpleMode = false (Default - Realistic Mode):**

- 🚶 NPCs **walk to the vehicle** naturally

- 🚪 NPCs **open doors and climb in** with full animations

- 🎭 **Immersive experience** - looks natural and realistic

- 🚫 **Driver seat blocked** - NPCs will NEVER enter driver seat

- ⏱️ Takes a few seconds for NPC to reach and enter vehicle

**SimpleMode = true (Instant Mode):**

- ⚡ NPCs are **teleported directly** into vehicle seat

- 🎮 **Instant placement** - no walking or door animations

- 🚫 **Driver seat still blocked** - safety maintained

- ⏰ Perfect for fast-paced gameplay or testing

> **Note:** Regardless of mode, NPCs are prevented from entering the driver seat through multiple safety mechanisms including seat selection filters and config flags.

---

## ⚠️ **Important Limitations**

### 👤 **Single Hostage System**

**You can only take ONE NPC hostage at a time.**

This limitation exists to prevent legacy game engine crashes and memory issues that occur when managing multiple compliant NPCs simultaneously. The system enforces this by:

- 🔒 Blocking new hostage attempts while one is active

- ✅ Automatic release of previous hostage when taking a new one

- 🛡️ Memory protection to prevent server instability

> **Why this matters:** Previous versions allowed multiple hostages which caused:

> - 💥 Game crashes due to excessive entity management

> - 🧠 Memory leaks from tracking too many NPC states

> - ⚠️ Server instability on high-population servers

> **Current behavior:** The single-hostage limit ensures stable, crash-free operation while maintaining full functionality for realistic hostage scenarios.

## 🛡️ **Advanced Features**

### 🧠 **Memory Management**

- ✅ **Auto-Cleanup** - Prevents memory leaks and stuck states

- ✅ **State Recovery** - Script continues running even after errors

- ✅ **Reference Tracking** - Monitors and cleans up NPC states

- ✅ **Timeout Protection** - Auto-resets NPCs stuck too long

### 🎯 **Smart Animation System**

- 🔄 **Auto-Restoration** - Animations restore after door interactions

- 🚫 **Collision Handling** - Handles getting bumped or knocked down

- 🎮 **State Awareness** - Knows when NOT to interfere with animations

- ⚡ **Responsive** - 100ms check interval for instant restoration

### 🚗 **Vehicle Intelligence**

- 🔍 **Auto-Detection** - Finds NPCs in vehicles when aiming

- 🚪 **Forced Exit** - Makes NPCs leave vehicles before complying

- 🎯 **Seat Management** - Intelligent seat finding and assignment

## 🎯 **Compatibility**

### ✅ **Supported Frameworks**

- 🟢 **QB-Core** (All versions)

- 🟢 **Qbox** (All versions)

- 🔄 **Auto-Detection** (Recommended)

### ✅ **Supported Target Systems**

- 🎯 **qb-target** (All versions)

- 🎯 **ox_target** (All versions)

- 🔧 **Dual Setup** (Both simultaneously)

### ✅ **Weapon Compatibility**

- 🔫 **All Default Weapons**

- 🎮 **Custom Weapon Packs**

- 🛠️ **Modded Weapons**

- 🌟 **Any weapon with "weapon_" prefix**

VIDEO : https://youtu.be/Z6ENzwtCWSA