Throw & Place
Configuration

Configuration

After completing the installation steps, you can fine-tune the script's behavior in the config.lua file. The file is fully commented to explain every option.

General Settings

These settings control the overall functionality and default behaviors of the script.

  • defaultModel:

    • Type: string (model hash or name)
    • Default: `prop_paper_bag_01`
    • Description: The default 3D model used for any item that doesn't have a specific model assigned in the items table. This acts as a fallback to prevent errors with unconfigured items.

  • pickupType:

    • Type: string
    • Default: ox_inventory_drop
    • Options: ox_inventory_drop, ox_target, qb_target, sleepless_interact, interact
    • Description: This crucial setting determines which interaction system the script uses for picking up items. It's essential for ensuring compatibility with your server's framework. Choose the option that matches your server's setup.

  • renderDistance:

    • Type: number
    • Default: 50.0
    • Description: The maximum distance (in game units, usually meters) from which a dropped item will be visible to players. Higher values may slightly impact performance if many items are on the ground.

Item Specific Configurations (items)

This table allows you to define custom properties for individual items. The key for each entry must be the exact item name from your framework (e.g., phone).

If the item is a weapon hash (e.g., WEAPON_PISTOL), you don't need to add a model, as the script automatically fetches the correct weapon model.

items = {
    ["example"] = {
        model = `prop_paper_bag_01`,     -- The 3D prop model for this specific item.
        throwForce = 0.5,                -- A multiplier for the force applied when throwing this item (recommended range: 0.1 - 1.0).
        handPosition = vector3(0, 0, 0), -- A vector3(x, y, z) offset to adjust the item's position in the player's hand.
        handRotation = vector3(0, 0, 0), -- A vector3(x, y, z) rotation to adjust the item's orientation in the player's hand.
        handRotationOrder = 2,           -- Changes the order rotations are applied (XYZ, YZX, etc.) to fix orientation issues.
        disablePlace = true,             -- When is set to true, it prevents the item from being placed in the environment.
    },
    ["money"] = {
        model = `prop_anim_cash_pile_01`,
        handRotation = vector3(0, 90, 0),
    },
    ["phone"] = {
        model = `sf_prop_sf_npc_phone_01a`,
        handRotation = vector3(0, 90, 0),
    },
    ["burger"] = {
        model = `prop_cs_burger_01`,
    },
    ["sprunk"] = {
        model = `prop_ld_can_01`,
        handRotation = vector3(100, 0, 0),
    },
    ["WEAPON_PISTOL"] = {
        throwForce = 0.8,
    },
    ["WEAPON_SMG"] = {
        throwForce = 0.5,
    },
},

Animations

These tables configure the animations that play when players place or pick up items.

  • placeAnimation:

    • enabled
      • Type: boolean
      • Default: true
      • Description: Set to true to enable the animation, false to disable it.
    • dict
      • Type: string
      • Default: anim@narcotics@trash
      • Description: The animation dictionary to be used.
    • name
      • Type: string
      • Default: drop_front
      • Description: The specific animation name within the dictionary.
    • blendInSpeed
      • Type: number
      • Default: 8.0
      • Description: Controls how quickly the animation blends in (higher is faster).
    • blendOutSpeed
      • Type: number
      • Default: 8.0
      • Description: Controls how quickly the animation blends out (higher is faster).
    • duration
      • Type: number (milliseconds)
      • Default: 1500
      • Description: The duration of the animation in milliseconds.
    • flags
      • Type: number
      • Default: 48
      • Description: Animation flags that control behavior (e.g., looping, upper body only).

  • pickupAnimation:

    • enabled
      • Type: boolean
      • Default: true
      • Description: Set to true to enable the animation, false to disable it.
    • low (Animation for picking up items from a low position, e.g., the ground.)
      • dict
      • name
      • blendInSpeed
      • blendOutSpeed
      • duration
      • flags
    • high (Animation for picking up items from a higher position or in a different context.)
      • dict
      • name
      • blendInSpeed
      • blendOutSpeed
      • duration
      • flags

Keybinds (controls)

This table configures all the keybinds used by the script. The numerical values correspond to GTA V's Control Indexes.

You can find a full list of controls here (opens in a new tab) if you want to change them.

  • controls
    • cancelThrow
      • Default: 200 (ESC)
      • Description: Cancels the throw action.
    • startPlace
      • Default: 45 (R)
      • Description: Switches from throw mode to place mode.
    • cancelPlace
      • Default: 200 (ESC)
      • Description: Cancels the placement action.
    • rotateRight
      • Default: 17 (Scroll Wheel Up)
      • Description: Rotates the object to the right in placement mode.
    • rotateLeft
      • Default: 16 (Scroll Wheel Down)
      • Description: Rotates the object to the left in placement mode.
    • smallAjustments
      • Default: 36 (Left Ctrl)
      • Description: Hold this key to make finer, slower adjustments to rotation/position.
    • placeItem
      • Default: 46 (E)
      • Description: Confirms and places the item on the ground.

Localizable Text (locales)

This table holds all the text strings displayed to the user in the UI, allowing for easy localization.

  • locales
    • throwTextUI
      • Default: [R] Place | [ESC] Cancel
      • Description: The help text shown when the player is in the "throw" state.
    • throwOnlyTextUI
      • Default: [ESC] Cancel
      • Description: The help text shown when the player is in the "throw" state but placement is disabled.
    • placeTextUI
      • Default: [E] Place | [Scroll] Rotate | [ESC] Cancel
      • Description: The help text shown when the player is in the "place" state with object rotation.
    • pickupItem
      • Default: Pickup %sx %s
      • Description: The text shown when looking at a pickupable item. The first %s is replaced by the item count, and the second %s by the item name (e.g., "Pickup 3x Phone").
    • tooHeavy
      • Default: Item weight exceeds your carrying capacity.
      • Description: The error message displayed if the player's inventory is too full (by weight)

Advanced Settings (Do Not Modify Unless Understood)

These settings are global defaults for physics and object attachments. Do not modify them unless you fully understand their purpose.

  • defaultThrowForce
    • Default: 1.0
    • Description: The default force applied when an item is thrown if not specified in the items table.
  • defaultRightHandBone
    • Default: 57005 (SKEL_R_Hand)
    • Description: The bone index for the character's right hand.
  • defaultLeftHandBone
    • Default: 18905 (SKEL_L_Hand)
    • Description: The bone index for the character's left hand.
  • defaultHandPosition
    • Default: vector3(0.1, -0.005, -0.05)
    • Description: The default positional offset for an item held in hand.
  • defaultHandRotation
    • Default: vector3(90, 0, 90)
    • Description: The default rotational offset for an item held in hand.
  • defaultHandRotationOrder
    • Default: 2
    • Description: The default rotation order for an item held in hand.
InstallationUsage