Throwable Items

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

Add the fields to the item entry

Open data/items.lua and add throwable, throwModel, and throwOffset to the item.

data/items.lua

['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),
    },
},

(Optional) Allow throwing several at once

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.

data/items.lua

throwMultiple = true,

Restart the resource

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:

data/items.lua

['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.

Get Started

Awoken Scripts

How throwing works

The item fields

Adding a throwable item

Finding good `throwOffset` values

Worked example - throwable cash pile

Tips

​How throwing works

​The item fields

​Adding a throwable item

​Finding good throwOffset values

​Worked example - throwable cash pile

​Tips

How throwing works

The item fields

Adding a throwable item

Finding good `throwOffset` values

Worked example - throwable cash pile

Tips