# 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>


---

# 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://rp-works-modding.gitbook.io/rp-works-modding-docs/hold-and-throw.md?ask=<question>
```

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.