# Metadata

## Shop Metadata Configuration

This script allows you to define **metadata for items sold in shops** in two different ways:

1. **Fixed metadata**, defined directly in the shop configuration file.
2. **Dynamic metadata**, generated in real time on the server using custom logic (player data, context, etc.).

This flexibility allows everything from simple static items to advanced items that depend on player-specific or external data.

***

### 1. Fixed Metadata (config/shops.lua)

Fixed metadata is defined directly inside the shop configuration file: `config/shops.lua`.

This method is ideal when:

* The item should always have the same data.
* It does not depend on the player or any external logic.
* You want a simple and straightforward setup.

#### Example

```lua
items = {
    {
        type = 'other',
        name = 'card',
        price = 10,
        label = 'Pokemon Card',
        metadata = {
            label = 'Charizard',
            type = 'Fire',
        }
    },
}
```

In this case:

* The `card` item will always be sold with the same metadata.
* No additional server-side logic is executed.
* The metadata is assigned directly at the time of purchase.

***

### 2. Dynamic Metadata (server/editable.lua)

When metadata needs to be generated dynamically (for example, based on the player, identity, progress, or any other logic), you must use the following file:

```
server/editable.lua
```

This system allows you to **intercept the item purchase** and assign metadata just before the item is added to the player's inventory.

#### When to Use Dynamic Metadata

This method is recommended when:

* The item requires unique data per player.
* Metadata depends on external or runtime information.
* Advanced logic is required.

Common examples include:

* Phones with unique numbers.
* Personal documents.
* Keys, cards, credentials.
* Items linked to player data.

***

### Using `LV.items:setMetadata`

The `server/editable.lua` file provides a dedicated function to handle this behavior:

```lua
LV.items:setMetadata(itemName, function(source, itemName, amount, shopType, metadata)
    return {
        -- dynamically generated metadata
    }
end)
```

#### Function Parameters

The function receives the following parameters:

* **source**: Player ID who is making the purchase.
* **itemName**: Name of the item.
* **amount**: Quantity purchased.
* **shopType**: Type of shop where the item is bought.
* **metadata**: Base metadata (if any) defined in `shops.lua`.

{% hint style="warning" %}
 **Important:** The function **must return a table** containing the final metadata that will be assigned to the item.
{% endhint %}

***

### Practical Example

```lua
LV.items:setMetadata('phone', function(source, itemName, amount, shopType, metadata)
    return {
        number = "+1 123 45678",
        brand = "Apple",
        model = "16 pro"
    }
end)
```

In this example:

* Every time a `phone` item is purchased.
* The server dynamically generates its metadata.
* The item is added to the inventory with personalized data.

This system can easily be extended to:

* Generate unique serial numbers.
* Read player-specific data.
* Integrate with other scripts.

***

### Metadata Priority

* If an item **does not have dynamic metadata**, the metadata defined in `shops.lua` will be used.
* If a function exists in `server/editable.lua` for that item, **the returned metadata will replace or override** the fixed metadata.

***

### Recommendations

* Use **fixed metadata** for simple and generic items.
* Use **dynamic metadata** for unique items or items tied to server logic.
* Keep complex logic exclusively inside `server/editable.lua`.

***

With this system, shops can easily adapt to any use case without constantly modifying the base configuration.


---

# 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://fivem.lvsoft.com.ar/qb-esx/lvs-shops/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.