> For the complete documentation index, see [llms.txt](https://tgiann.gitbook.io/tgiann/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tgiann.gitbook.io/tgiann/scripts/tgiann-inventory/guides/creating-items.md).

# Creating Items

All of the items are defined in the items.lua file with key, value pairs. Key is the name (not the label) of an item and the value is a table containing the options for the item.

{% hint style="warning" %}
You can edit items in the <mark style="color:yellow;">tgiann-inventory/items</mark> folder
{% endhint %}

{% hint style="success" %}
Many features work exactly the same as in [ox\_inventory](https://overextended.dev/ox_inventory/Guides/creatingItems), the most popular free inventory system.
{% endhint %}

{% hint style="info" %}
question(?) marks are not mandatory.
{% endhint %}

{% hint style="info" %}
Most per-item settings (`propModel`, `prop`, `carry`, `block`, `decayTime`, `editable`, `maxStack`, `maxUseAmount`, `roleplay`, `brokenInWater`, `rareName`, `size` and the consumable `client` block) can also be edited in game with the admin panel (`/invadmin > Items`). The admin panel saves them to `data/items.json` and **wins over items.lua**: admin panel value > preset > items.lua. The only per-item config list left is `config.itemStash` (`configItemStash.lua`), which wins over the `itemStash` field here.
{% endhint %}

* Item Options
  * label: `string` | `Record<string, string>`
  * weight: `number`
  * type: `item` | `weapon`
  * image?: `string` ([docs](https://docs.tgiann.com/scripts/tgiann-inventory/guides/item-images))
  * shouldClose?: `boolean`
  * hasMetadata?: `boolean` (If an item has a metadata/info value, it should be set to true, If the config.checkItemHasMetadata setting is true, this parameter must be correctly configured for each item.)
  * description: `string` | `Record<string, string>`
  * useable?: `boolean`
  * unique?: `boolean` (Each stack of the item keeps its own metadata/id instead of sharing one, use for non-stackable items like keys or lockpicks)
  * clothe?: `boolean` (Marks the item as a wearable clothing item for the clothing system)
  * size?: `table` (Cells the item takes in the inventory grid, `1x1` when missing. Weapons in `weapons.lua` take the same field)
    * width?: `number` (default `1`)
    * height?: `number` (default `1`, at most `config.grid.maxItemHeight`)
    * rotatable?: `boolean` (Players can turn the item with the rotate key, `R` by default)
  * rareName?: `string` (Rarity key, the rarities themselves are set in the admin panel under Rarities. A rare item gets a colored strip/background and a label in the UI)
  * maxStack?: `number` (Max stack amount for this item, `0` = no limit)
  * maxUseAmount?: `table` (Limits how many times the item can be used before it's removed. The item needs `hasMetadata` or `unique`)
    * amount: `number` (Number of uses before the item is removed)
    * autoDecreases: `boolean` (If true, the use count decreases automatically each time the item is used. If false, you need to trigger `TriggerServerEvent("tgiann-inventory:decreaseMaxUseAmount", itemSlot)` manually after using the item)
  * brokenInWater?: `string` (Item name given in place of this one when the player swims, e.g. `"broken_phone"`)
  * editable?: `table` (Allows players to rename the item and/or change its image by right-clicking it)
    * label?: `boolean`
    * img?: `boolean`
  * decayTime?: `number` (Seconds after creation before the item can no longer be used)
  * block?: `table` (Restricts what can be done with the item)
    * drop?: `boolean` (Player can't drop the item)
    * glovebox?: `boolean` (Player can't put the item in the glovebox)
    * trunk?: `boolean` (Player can't put the item in the trunk)
    * stash?: `boolean` (Player can't put the item in any stash)
    * give?: `boolean` (Player can't give the item to someone else)
    * player?: `boolean` (Player can't take or give this item from/to another player)
    * throw?: `boolean` (Player can't throw the item)
    * place?: `boolean` (Player can't place the item in the world)
  * propModel?: `string` or `hash` (Prop model of the item, defined once and used everywhere the item shows up in the world: dropped on the ground, thrown, placed, dropped on death and carried in the hands. Items without it use the `defaultObject` of the feature in `configDrop.lua`, `configThrowableItems.lua` and `configPlaceableItems.lua`)
  * prop?: `table` (Placement of that prop. `throwObject` and `dropObject` are the old names of this field and still work)
    * groundRotation?: `table` (x, y, z) fixed rotation on the ground, missing = automatic ground placement
    * handRotation?: `table` ({x, y, z} position, {x, y, z} rotation) offsets while held in hand (throw)
    * handRotationOrder?: `number` (rotation order of `handRotation`, default `1`)
    * zOffset?: `number` height offset when the prop lands on the ground
  * carry?: `table` (Makes the item carried in both hands while it is in the inventory, like a TV or a box. The prop is the item's `propModel`)
    * bone: `number`
    * offset: `vector3`
    * rot: `vector3`
    * rotationOrder?: `number` (default `1`)
    * anim: `table`
      * dict: `string`
      * name: `string`
    * disableKeys?: `table` ([control ids](https://docs.fivem.net/docs/game-references/controls/) to disable while carrying the item)
    * moveRate?: `number` (Player movement speed multiplier while carrying the item)
  * itemStash?: `table` (Turns the item into a container that opens a secondary stash inventory when used, same as `config.itemStash` in `configItemStash.lua`, the config file wins when both exist)
    * maxweight: `number` (`0` = no limit)
    * slots: `number`
    * label: `string`
    * whitelist?: `table` (List of item names allowed inside the stash, omit to allow any item)
    * weightMultiplier?: `number` (Fraction of the stash contents' weight that is added to the item's own weight, default `1`. `0.5` means 100kg of contents add 50kg to the item)
  * roleplay?: `table` (Small roleplay action when the item is used. A roleplay item skips the normal use flow: no framework usable item callback, no `client.export`/`client.event`)
    * remove?: `boolean` (One item is removed after use)
    * anim?: `table` (Played while using. `duration` in ms only matters when there is no progress bar)
      * dict: `string`
      * clip: `string`
      * flag?: `number` (default `49`)
      * duration?: `number`
    * prop?: `table` (Prop shown in hand during the progress bar)
      * model: `string` or `hash`
      * bone: `number`
      * pos: `vector3`
      * rot: `vector3`
    * progressbar?: `table`
      * time?: `number` (ms, default `3000`)
      * label?: `string` | `Record<string, string>` (item label when omitted)
      * cancel?: `boolean` (default `true`)
      * disableMove?: `boolean`
    * emote?: `string` | `Record<string, string>` (`/me` text sent after the action)
    * doEmote?: `string` | `Record<string, string>` (`/do` text sent after the action)
    * hand?: `table` (Keeps a prop in the player's hand until the put away key from `config.roleplayItemKeys` is pressed. Using the item again also puts it away, and the prop is removed when the item leaves the inventory)
      * model: `string` or `hash` (single prop)
      * bone: `number`
      * offset?: `vector3`
      * rot?: `vector3`
      * props?: `table` (Several props at once: list of `{ model, bone, offset, rot }`, used instead of the single prop fields)
      * anim?: `table` (Looped while holding)
        * dict: `string`
        * name: `string`
      * give?: `boolean` (The give key hands the item to the closest player, who then holds it)
      * emote?: `string` | `Record<string, string>` (`/me` text when the item is taken in hand)
  * server?: `table`
    * export?: `string`
  * consume?: `number` (Amount of the item removed each time it's used)
  * client?: `table`
    * export?: `string` (Export to be triggered after item use)
    * event?: `string` (Client event to be triggered after item use)
    * status?: `table` (Adjust esx\_status/qb values after use)
    * anim?: `table` (Animation that will be played during the progress bar)
      * dict: `string`
      * clip: `string`
    * prop?: `table` (Attached prop that will be displayed during the progress bar)
      * model: `string` or `hash`
      * pos: `table` (x, y, z)
      * rot: `table` (x, y, z)
      * bone?: `number`
      * rotOrder?: `number`
    * disable?: `table` (Actions to be disabled during the progress bar)
      * move?: `boolean`
      * car?: `boolean`
      * combat?: `boolean`
      * mouse?: `boolean`
    * usetime?: `number` (Progress bar duration)
    * cancel?: `boolean` (If set to true the player can cancel item use)
    * notification?: `string` (Notification to be sent when the item is used)
    * add?: `function`(total: `number`)
      * Function that triggers when receiving an item
      * Returns total item count as `total`
    * remove?: `function`(total: `number`)
      * Function that triggers when removing an item
      * Returns total item count as `total`
  * buttons?: `table`
    * label: `string` | `Record<string, string>`
    * action: `function`(slot: `number`)
      * Callback function when button is clicked in context menu, returns item slot.

```lua
testburger = {
    label = 'Test Burger',
    weight = 220,
    type = "item", 
    image = "testburger.png",
    hasMetadata = false,
    useable = true,
    shouldClose = false, 
    description = "It's a Burger",
    client = {
        image = 'burger_chicken.png',
        status = { hunger = 200000, thirst = 10000 },
        anim = { dict = 'missheistdockssetup1clipboard@idle_a', clip = 'idle_a', flag = 49 },
        prop = { model = `prop_rolled_sock_02`, pos = vec3(-0.14, -0.14, -0.08), rot = vec3(-50.0, -50.0, 0.0) },
        usetime = 2500,
        notification = 'You used the burger',
        event = "tgiann-food-job:useBurger",
        export = 'tgiann-food-job.testburger' -- Script Name . Function name
    },
    server = {
        export = 'tgiann-food-job.testburger', -- Script Name . Function name
    },
}
```

Example Grid Size, Prop and Carry

```lua
goldbar = {
    label = 'Gold Bar',
    weight = 1000,
    type = 'item',
    description = '',
    size = { width = 2, height = 1, rotatable = true }, -- takes 2 cells, players can turn it with R
    propModel = "hei_prop_heist_gold_bar",             -- used on the ground, when thrown, placed and carried
    prop = { groundRotation = { 0.0, 0.0, 0.0 }, zOffset = 0.02 },
},
television = {
    label = 'Television',
    weight = 15000,
    type = 'item',
    description = '',
    size = { width = 3, height = 3 },
    propModel = "xs_prop_arena_screen_tv_01",
    carry = {
        bone = 28252,
        offset = vector3(0.26, 0.11, -0.14),
        rot = vector3(96.16, 168.9, 84.24),
        anim = { dict = "anim@heists@box_carry@", name = "idle" },
        disableKeys = { 21, 22 },
        moveRate = 0.5,
    },
},
phone = {
    label = 'Phone',
    weight = 190,
    type = 'item',
    description = '',
    brokenInWater = "broken_phone", -- turns into broken_phone when the player swims
},
```

Example Multi Language Labels

```lua
test_item = {
        label = {
            tr = 'Örnek Çok Dilli Etiket',
            en = 'Example Multi Language Label',
        },
        weight = 100,
        type = 'item',
        description = {
            tr = 'Bu bir örnek çok dilli etiket içeren bir öğedir.',
            en = 'This is an item with an example multi language label.',
        },
        buttons = {
            {
                label = {
                    tr = 'Özel Buton',
                    en = 'Custom Button',
                },
                action = function(slot)
                    print('Custom Button', slot)
                end
            }
        },
    },
```

Example Roleplay Items

```lua
condom = {
    label = 'Condom',
    weight = 10,
    type = 'item',
    useable = true,
    shouldClose = true,
    description = '',
    roleplay = {
        remove = true,
        anim = { dict = "missheistdockssetup1clipboard@idle_a", clip = "idle_a", flag = 49 },
        progressbar = { time = 3000, label = { en = "Opening the condom", tr = "Kondomu açıyorsun" } },
        emote = { en = "tears the condom pack open and puts it on", tr = "kondom paketini yırtıp taktı" },
    },
},
bouquet = {
    label = 'Bouquet',
    weight = 200,
    type = 'item',
    useable = true,
    shouldClose = true,
    description = '',
    roleplay = {
        hand = { -- stays in hand until the put away key (X) is pressed, G gives it to the closest player
            model = joaat("prop_snow_flower_02"),
            bone = 24817,
            offset = vector3(-0.29, 0.40, -0.02),
            rot = vector3(-90.0, -90.0, 0.0),
            anim = { dict = "impexp_int-0", name = "mp_m_waremech_01_dual-0" },
            give = true,
            emote = { en = "holds a bouquet of flowers", tr = "elinde bir buket çiçek tutuyor" },
        },
    },
},
```

{% hint style="success" %}
more examples are in the items/items.lua file
{% endhint %}