> ## Documentation Index
> Fetch the complete documentation index at: https://docs.awokenlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Throwable Items
> Make any item physically throwable with a custom prop model and hand offset.
The Awoken rework adds a full throwing system to ox\_inventory. Right-clicking any item flagged as throwable reveals a **Throw** option in the context menu, after which the player aims with RMB and throws with LMB. Landed items sync to all clients and can be picked back up.
This page covers how to **make any item throwable** by adding a small set of fields to its entry in `data/items.lua`.
Weapons in `data/weapons.lua` (grenades, snowballs, BZ gas, etc.) throw via the engine's native weapon system. The `throwable` tag on those entries is purely for the filter chip and stack behaviour. The throwing system documented here is for **regular items** in `data/items.lua`.
## How throwing works
* A throwable item gets a **Throw** entry added to its right-click context menu.
* When the player triggers Throw, the configured prop model is attached to their right hand.
* Hold **RMB** to enter the aiming pose, release LMB to throw, or press **X** to cancel.
* The projectile arcs through the air, can smash any of the 6 vehicle windows on direct hit, and ragdolls nearby NPCs on impact.
* Once it stops moving, the item is registered server-side and any nearby player can pick it up (via ox\_target if present, otherwise a fallback marker prompt).
* Landed pickups auto-despawn after 5 minutes if untouched.
## The item fields
Add the following fields to any item definition in `data/items.lua`.
| Field | Type | Required | Description |
| --------------- | ---------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `throwable` | `boolean` | yes | Enables the **Throw** option in the right-click context menu. |
| `throwModel` | `hash` *(prop)* | optional | GTA prop model used as the held and thrown object. If omitted, the resource falls back to the item's `client.prop` model, and finally to `prop_paper_bag_small`. |
| `throwOffset` | `{ pos = vec3, rot = vec3 }` | optional | Position and rotation used when attaching the prop to the player's right hand bone. Tune so the prop sits naturally. |
| `throwMultiple` | `boolean` | optional | Prompts the player for an amount before throwing. Use for stackables like cash piles. |
The `'throwable'` entry in an item's `tags` array is **optional**. It only controls whether the item appears under the **Throwable** filter chip in the inventory toolbar. The throw mechanic itself runs purely off the `throwable` boolean.
## Adding a throwable item
Open `data/items.lua` and add `throwable`, `throwModel`, and `throwOffset` to the item.
```lua data/items.lua theme={"dark"}
['molotov_bottle'] = {
label = 'Molotov Cocktail',
description = 'A petrol-soaked rag in a glass bottle. Light, throw, run.',
weight = 600,
tags = { 'throwable' },
throwable = true,
throwModel = `prop_ld_flow_bottle`,
throwOffset = {
pos = vec3(0.143, 0.028, -0.018),
rot = vec3(-70.73, -29.69, -9.82),
},
},
```
For stackable items where it makes sense to throw a handful in one go (cash piles, marbles, food scraps), add `throwMultiple = true`. The player gets a small input dialog asking how many to throw.
```lua data/items.lua theme={"dark"}
throwMultiple = true,
```
`ensure ox_inventory`. The new item is now throwable. Spawn one with `/giveitem 1 molotov_bottle 1` to test.
## Finding good `throwOffset` values
The offset determines how the prop sits in the player's right hand. A bad offset means the prop clips into the wrist or floats away from the hand.
Two quick ways to find usable values:
* **Reuse an existing offset.** If your prop model is already used by another throwable item (or any item's `client.prop`), copy that entry's `pos` and `rot` vectors.
* **Use a prop-attachment tool.** Tools like Codewalker or in-game attachment editors let you drag the prop on a ped bone in real time. Pick the **right-hand** bone, position the prop, then copy the resulting position and rotation vectors into `throwOffset`.
If you skip `throwOffset` entirely, the system uses a sensible generic right-hand offset that works tolerably for most small props. It's not perfect, but it's enough to test whether the rest of your setup is wired correctly before you fine-tune.
## Worked example - throwable cash pile
A dirty-money stack that lets the player throw any amount in one motion:
```lua data/items.lua theme={"dark"}
['black_money'] = {
label = 'Dirty Money',
description = 'Cash that cannot be traced back to a legitimate source.',
tags = { 'currency', 'throwable' },
throwable = true,
throwMultiple = true,
throwModel = `prop_anim_cash_pile_01`,
throwOffset = {
pos = vec3(0.130, 0.013, -0.034),
rot = vec3(43.36, 39.05, -1.57),
},
},
```
When the player right-clicks the stack and chooses Throw, a small input asks **Amount**. Whatever they type is removed from inventory in a single throw motion, and the cash-pile prop arcs forward.
## Tips
* **Match the prop to the item.** A bandage throwing as a paper bag is jarring. The closer the prop model is to the item's actual look, the more believable the throw.
* **Tag it `'throwable'`.** It costs nothing and lets players filter their inventory down to throwables at a glance.
* **Use `throwMultiple` sparingly.** It adds an input prompt, so reserve it for items where throwing several at once is genuinely useful (cash, marbles, food fights). For most items, single-throw is cleaner.
* **Test the impact behaviour.** Throwables smash any vehicle window on direct hit and ragdoll the nearest NPC within 2m of the landing spot. That can be exactly what you want, or unwanted - keep it in mind when tagging items as throwable.