ThrowPhone

The ThrowPhone & ThrowBall Negotiation Script introduces a realistic law-enforcement tool for hostage and crisis negotiations in FiveM. Inspired by real-world tactical equipment, it allows police negotiators to establish secure communication without physically exposing themselves too long or at all.

The ThrowPhone system allows law enforcement to deploy specialized communication devices into a building or area occupied by suspects. Criminals can retrieve the device and communicate directly with negotiators, while police maintain distance, control, and oversight.

Showcase: https://youtu.be/HgORbMqlxSs

Features

• Local-Object Optimization: Uses non-networked (local) objects for the phone while keeping state synced across clients, reducing network overhead.
• Optimised: In game 0.00ms idle and 0.01-0.02ms client/server with deployed phones.
• Control Box Management: Issue, manage, and listen to deployed phones from a dedicated control box.
• Live Camera & GPS Tracking: View the throw phone camera and track the handset location when enabled.
• Automatic Cleanup: Phones, prompts, and voice channels clear themselves when the scene wraps up, keeping your server tidy.
• Permissions: Gate access by job/role (ESX, QBCore, QBox, Ox).

Perfect For

• Hostage negotiations where SWAT tosses in a phone and monitors from cover.
• Undercover stings that need a disposable, hard-to-trace comms line.
• Event control or heist scenarios that benefit from isolated, object-based voice channels.

---

Getting Started

1. Download the latest version from Cfx.re Portal

2. Download Dependencies

   • ox_lib: Must be version v3.30.0 or higher.
   • Voice (one of)
     • pma-voice
     • pma-voice (Konflict fork)
   • Target (one of)
     • ox_target
     • sleepless_interact
     • qb-target
   • Inventory (one of)
     • ox_inventory
     • codem-inventory
     • qb-inventory
     • qs-inventory
     • qs-inventory-pro
     • origen_inventory
     • tgiann-inventory

3. Install

   Move the dependencies and the folders kf-throw-phone & kf-throw-phone-assets into your server’s resources directory.

4. Add to server.cfg

   server.cfg

   ensure ox_lib
   ensure pma-voice
   
   ensure ox_target
   ensure ox_inventory
   
   ensure kf-throw-phone
   ensure kf-throw-phone-assets

5. The following is for ox_inventory only. Please refer to the documentation for other supported inventory resources.

6. Add the control box to the inventory item config file.

   Add to the ox_inventory items config file. Default location: resources/[ox]/ox_inventory/data/items.lua

   ['kf_throwphone_control'] = {
     label = 'Throw Phone Control',
     weight = 8000,
     stack = false,
     close = true,
     client = {
       export = 'kf-throw-phone.deployControl'
     }
   },

7. Add the throwables to the inventory weapon config file.

   Add to the ox_inventory weapons config file. Default location: resources/[ox]/ox_inventory/data/weapons.lua

   ['WEAPON_KFTHROWPHONE'] = {
         label = 'Throw Phone Case',
         weight = 1000,
         throwable = true,
   },
   
   ['WEAPON_KFTHROWPHONE_BALL'] = {
         label = 'Throw Phone Ball',
         weight = 300,
         throwable = true,
   },
   
   ['WEAPON_KFTHROWPHONE_HANDSET'] = {
         label = 'Throw Phone',
         weight = 190,
         throwable = true,
   },

8. Add the images to the inventory images folder

   Add all the images files from kf-throw-phone/inventory-images/ingame OR kf-throw-phone/inventory-images/stylized into the ox_inventory images folder. Default location: resources/[ox]/ox_inventory/web/images

---

Configuration

The main configuration is located in config.lua.

config.lua

Config = {
  debug = false,
  notifications = true,
  textUiEnabled = true,
  -- The notification resource to use, one of: 'ox_lib', 'esx_notify', 'qb-core', 'qbx_core', 'okokNotify', 'wasabi_notify',
  notify = 'ox_lib',
  -- The inventory resource to use
  -- one of: 'ox_inventory', 'codem-inventory', 'qb-inventory', 'qs-inventory', 'qs-inventory-pro', 'origen_inventory', 'tgiann-inventory'
  inventory = 'ox_inventory',
  -- The target resource to use, one of: 'ox_target', 'sleepless_interact', or 'qb-target'
  target = 'ox_target',

  -- Control box
  -- Allowed groups to use the control box - leave empty to allow all groups
  -- List format (no grade requirement):
  -- { 'police', 'sheriff', 'fbi' }
  -- Grade format (minimum grade):
  -- { police = 2, sheriff = 1 }
  -- ESX also supports grade_name aliases:
  -- { police = 'boss' }
  controlBoxAllowedJobs = {
    -- Example:
    -- police = 2,
  },
  controlBoxMaxDeployed = 1,
  controlBoxMaxPhones = 5,
  controlBoxAllowBallRetrieve = true,
  -- When true, only the player who deployed the control box can interact with it.
  controlBoxRequireOwnership = false,
  ballJoinRadius = 3.0,

  -- Throw phone camera
  cameraEnabled = true,
  cameraEnabledByType = {
    case = false,
    phone = true,
    ball = true,
  },
  cameraNightVisionToggleEnabled = true,
  cameraThermalVisionToggleEnabled = true,
  cameraFOV = 100.0,
  cameraRequireApproval = true, -- require nearby players to approve camera access
  cameraApprovalMethod = 'target', -- 'dialog', 'target', or 'both'
  cameraApprovalTimeout = 300000, -- milliseconds camera approval timeout (0 to disable)
  cameraViewTimeout = 300000, -- milliseconds active camera view timeout (0 to disable)
  cameraApprovalRange = 20.0,
  cameraMouseRotationEnabled = true,
  cameraKeyboardPitchYawEnabled = true,

  -- GPS tracker
  gpsTrackerEnabled = true,
  gpsTrackerUpdateInterval = 5000, -- milliseconds between GPS coordinate refreshes
  gpsTrackerBlipSprite = 459, -- blip sprite
  gpsTrackerBlipColour = 38, -- blip colour
  gpsTrackerBlipScale = 0.8, -- blip scale
  gpsTrackerBlipShortRange = true, -- blip short range on minimap
}