# Metadata

## How to show metadata to players

Showing specific metadata to players is easy. First of all, you'll need to know what is the metadata key you want to show, to do so, you can enable "Debug mode" in the `/inventory` settings menu, then hover the item you want to see the metadata of

| ![Item debug settings screenshot](/files/zo4T5o9kTadKRNUZZ6HV) | ![Item debug metadata screenshot](/files/8E15dfLuba9hhbHmsvO3) |
| -------------------------------------------------------------- | -------------------------------------------------------------- |

### Adding it to a single item

To show to players the metadata of a single item, you can add and adapt this code in the single item definition, in `jaksam_inventory/_data/items.lua` file:

```lua
displayFields = {
    { field = 'YOUR_METADATA_KEY_HERE', label = 'TEXT YOU WANT HERE: ${value}'}, -- Random example
    { field = 'ammo', label = 'Ammo: ${value}'}, -- Useful on weapons (already built in by default)
    { field = 'plate', label = 'Plate: ${value}'}, -- Useful on carkeys
},

```

![Single item display fields example](/files/0ffOYZmkx3tNS8wt3uGh)

### Adding it to all item type

To show to players the metadata of an entire item type, it's 100% the same method, but place it in the `Script.defaultsByType` table, in `jaksam_inventory/_data/defaults.lua` file

### Optional: Making metadata values look nicer

Sometimes you want to show metadata in a prettier way to players. For example, instead of showing "weapon\_pistol", you want to show "Pistol". This is where formatters come in!

A formatter is like a translator:

* It takes the original value (e.g. "weapon\_pistol")
* Converts it to something nicer (e.g. "Pistol")

You can use built-in formatters or create your own custom ones in `jaksam_inventory/_data/formatter.lua`. Here's how to use them:

```lua
displayFields = {
    { field = 'item', label = 'Label: ${value}', formatterId = "itemNameToLabel"}, -- An example with built in formatter
},
```

## How to set default metadata for items

Want items to have certain metadata values when they're first created? For example, maybe you want new weapons to start with 50% durability. Here's how to do it:

1. Type `/inventory` in-game to open the admin menu
2. Find and click on the item you want to edit
3. Click on the "metadata" tab
4. Set the metadata values you want

### Advanced - Using templates for dynamic metadata

Sometimes you want metadata that changes based on certain conditions. For this, you can use templates:

1. Go to the same metadata tab in the item editor
2. Change the metadata type to `template`
3. Either:
   * Select an existing template, or
   * Create your own template in `jaksam_inventory/_data/metadata_templates.lua`

Templates let you create metadata that updates automatically based on rules you define!

#### Example

Some examples of what you can do with dynamic metadata templates:

* Assign to a player Identification Card, his name, birth date, height, etc.
* Assign a random durability to a weapon
* Assign the creation date to an item (the first time the item is created)


---

# 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://documentation.jaksam-scripts.com/jaksam-inventory/guides/metadata.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.