# 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.