> For the complete documentation index, see [llms.txt](https://rp-works-modding.gitbook.io/rp-works-modding-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rp-works-modding.gitbook.io/rp-works-modding-docs/hold-and-throw.md).

# Hold and Throw

### 🧱 How to Install

Follow instructions in [Getting Started](/rp-works-modding-docs/readme.md)

### 🔧 Features

* ✅ `/hand [object]` to spawn a predefined prop in hands
* ✅ `/throw` command or keybind (default `G`) to throw the object
* ✅ Realistic throw physics from hand or vehicle window
* ✅ \[E] Pickup interaction hint when near a thrown object
* ✅ Modular config to enable/disable features
* ✅ Scaleform hints with keybind awareness
* ✅ Full export & event support for other resources
* ✅ Fully client-side and framework-independent

### 📜 Commands

| Command        | Description                                  |
| -------------- | -------------------------------------------- |
| `/hand object` | Spawns a prop from the config into your hand |
| `/hand`        | Cancels current held object or shows usage   |
| `/throw`       | Throws the held object in a random direction |

### 🎮 Keybind

| Action       | Default | Can Rebind In Settings? |
| ------------ | ------- | ----------------------- |
| Throw Object | `G`     | ✅ Yes                   |

To rebind, go to **Settings → Key Bindings → FiveM → Throw Held Object**

### ⚙️ Config (`config.lua`)

#### 🔹 Predefined Objects

```lua
Config.Objects = {
    waterbottle = { label = "Water Bottle", model = "prop_ld_flow_bottle" },
    brick       = { label = "Brick",        model = "prop_brick_01" },
    toolbox     = { label = "Toolbox",      model = "prop_tool_box_04" }
}
```

#### 🔹 Global Settings

```lua
Config.Settings = {
    AllowInVehicle       = true,   -- Allow throwing from vehicles
    ForceUnarmed         = true,   -- Forces player to be unarmed while holding
    BlockMelee           = true,   -- Prevents melee while holding
    BlockAiming          = true,   -- Disables aiming and shooting
    ShowThrowHint        = true,   -- Scaleform hint [G] Throw Object
    ShowAvailableObjects = true    -- Show object list if /hand has no args
}

Config.PickupKey = 38 -- [E] to pick up
```

### 🧩 Exports

#### 🧪 Check if player is holding something

```lua
exports["DH_Throw"]:IsPlayerHoldingObject() then ... end
```

#### 📦 Get current held object

```lua
name = exports["DH_Throw"]:GetHeldObjectName()
local entity = exports["DH_Throw"]:GetHeldObjectEntity()
```

#### ❌ Remove the held object

```lua
exports["DH_Throw"]:RemoveHeldObject()
```

#### 🎁 Set an object via code (same as /hand)

```lua
exports["DH_Throw"]:SetHeldObject("brick")
```

***

### 🪝 Events & Callbacks

#### 🔔 `DH_Throw:ObjectPickedUp`

Triggered when any object is picked up:

```lua
AddEventHandler("DH_Throw:ObjectPickedUp", function(objectName, netId, entity)
    print("Picked up:", objectName)
end)
```

#### 🔁 `RegisterOnObjectPickup(callback)`

Alternative method for pickup detection:

```lua
exports["DH_Throw"]:RegisterOnObjectPickup(function(objectName, netId, entity)
    -- custom logic
end)
```

***

### 💡 Tips

* All objects thrown are synced and visible to all players
* Throw direction is random when on foot, or based on seat position in vehicles
* Melee, aiming, and weapon switching can all be disabled via config
* Fully expandable — drop in new objects, add sounds, integrate with inventory

### ❓ Frequently Asked Questions

<details>

<summary>Can I add my own objects?</summary>

Yes! Just add them to the `Config.Objects` table in `config.lua`:

```lua
brick = { label = "Brick", model = "prop_brick_01" }
```

You’ll need the correct prop model name. Use tools like CodeWalker or [plebmasters ](https://forge.plebmasters.de)to find them.

</details>

<details>

<summary>Can players hold more than one object at a time?</summary>

No — the script is designed so a player can only hold one object at a time. Calling `/hand` again will replace the current one.

</details>

<details>

<summary>Does this work inside vehicles?</summary>

Yes! If `Config.Settings.AllowInVehicle = true`, players can throw objects out of the left or right window based on seat position.

</details>

<details>

<summary>Can I integrate this with my inventory syste, (OX/QS/etc)?</summary>

Absolutely. Use the export:

```lua
exports["DH_Throw"]:SetHeldObject("toolbox")
```

…and combine it with inventory checks or item usage in your own code.

</details>

<details>

<summary>Players are geting a warning: GetNetworkObject: no object by ID - What's up?</summary>

This means a player tried to pick up an object that no longer exists, and it's completely harmless.

</details>