Alpha NPC Interaction

A comprehensive FiveM resource that allows players to take NPCs as hostages with realistic animations, looting, and advanced interaction capabilities. Inspired by popular roleplay mechanics.

Features

• Hostage System

  • Realistic take-down and holding animations
  • NPCs can surrender or resist
  • Handcuffing system for subdued NPCs
  • Dynamic NPC reactions to hostage situations

• Looting System

  • Configurable loot tables with weighted chances
  • Money, items, and special drops
  • Blacklist system for restricted items
  • Inventory integration (supports ESX, QBCore, ox_inventory)

• Police Integration

  • Automatic police alerts with blips
  • Configurable response teams
  • Wanted level integration
  • NPC witnesses that can call the police

• Framework Support

  • ESX (Legacy and New Version)
  • QBCore
  • Standalone mode (limited features)
  • ox_lib integration for enhanced UI

• Customization

  • Fully configurable animations
  • Adjustable interaction distances
  • Permission system with job restrictions
  • Multi-language support

Requirements

• OX Lib
• OX Target (Recommended)
• ESX Legacy or QBCore
• ox_inventory or qb-inventory

🚀 Installation

1. Download the latest release
2. Place the Alpha_NpcIntreaction folder in your resources directory
3. Add ensure Alpha_NpcIntreaction to your server.cfg
4. Configure config.lua to match your server's needs
5. Add any required dependencies to your server.cfg
6. Restart your server

Dependencies

• ox_lib (Recommended for best experience)
• ox_target (Optional but recommended)
• ESX or QBCore (Optional, but required for full functionality)

Configuration

Edit the config.lua file to customize the script:

• Change the framework (esx or qb)
• Adjust interaction distances and keybinds
• Configure loot settings and blacklists
• Set up notifications and permissions
• Enable/disable features as needed

🎮 Usage

Taking a Hostage

1. Aim at an NPC with a weapon (or use the interaction key)
2. The NPC will raise their hands in surrender
3. Approach and press the interaction key (default: E) to take them hostage
4. While holding the hostage:
   • E - Release the hostage
   • G - Search the hostage for items
   • H - Execute the hostage (if enabled)
   • F - Handcuff the hostage (requires handcuff item)

Advanced Features

• Surrendering NPCs: NPCs will surrender when aimed at with a weapon
• Witness System: Nearby NPCs may call the police or flee
• Struggle Mechanic: Hostages may try to escape or fight back
• Police Response: Automatic alerts with location blips for law enforcement
• Inventory Integration: Loot goes directly to player's inventory

Looting

• When looting a hostage, you'll receive random items based on the configuration
• Some NPCs may have better loot than others
• Items are added directly to your inventory if there's space

Permissions

• Configure which jobs can take hostages in the config
• Set up admin commands for special permissions

⚙️ Configuration

Edit config.lua to customize:

-- Framework and Menu System
Config.Framework = 'esx' -- 'esx', 'qb', or 'standalone'
Config.Menu = 'ox_lib'   -- 'ox_lib', 'esx_menu_default', or 'qb-menu'

-- Interaction Settings
Config.Distance = 2.0
Config.UseOxTarget = true

-- Loot System
Config.Loot = {
    enabled = true,
    minItems = 1,
    maxItems = 3,
    items = {
        {item = "water", chance = 30, min = 1, max = 2, label = "Water"},
        {item = "money", chance = 50, min = 50, max = 500, label = "Cash"},
        -- Add more items as needed
    }
}

-- Police Integration
Config.Police = {
    enabled = true,
    requiredCops = 1,
    jobs = {'police', 'sheriff'}
}

🛠️ Commands & Permissions

Player Commands

• /releasehostage - Release current hostage (if any)
• /hostagestatus - Check current hostage status

Admin Commands

• /givehostageitem [playerId] [item] [count] - Give items to a player
• /sethostagejob [job] - Set required job for taking hostages
• /toggledebug - Toggle debug mode (admin only)

📡 Exports

Client Exports

-- Check if player is currently holding a hostage
exports['Alpha_NpcIntreaction']:IsHostageTaker()

-- Check if player is currently a hostage
exports['Alpha_NpcIntreaction']:IsHostage()

-- Get current hostage entity
exports['Alpha_NpcIntreaction']:GetCurrentHostage()

-- Force release current hostage
exports['Alpha_NpcIntreaction']:ReleaseHostage()
-- Check if a player is currently a hostage
exports['Alpha_NpcIntreaction']:IsPlayerHostage(playerId)

-- Check if a player is currently taking a hostage
exports['Alpha_NpcIntreaction']:IsPlayerTakingHostage(playerId)

Support

For support, please create an issue on GitHub.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

• [Nithish] - Initial work