# Ingredient-based Items

## Ingredient-based Items

Ingredient-based items let you create consumables that are built from individual ingredients. Instead of a burger with fixed stats, you start with a clean slate and the final result depends entirely on what ingredients go in. This is great for restaurant RP where players prepare food with real input.

To be clear, this is unrelated to the "pouring" functionality, which is more geared towards bartender RP.

***

### Table of Contents

* [How It Works](#how-it-works)
* [Step 1: Configure Your Ingredients](#step-1-configure-your-ingredients)
* [Step 2: Create the Base Item](#step-2-create-the-base-item)
* [Step 3: Craft the Item](#step-3-craft-the-item)
* [Quality](#quality)
* [Requiring Ingredients from Inventory](#requiring-ingredients-from-inventory)
* [Giving Ingredients to Players](#giving-ingredients-to-players)
* [Supported Resources](#supported-resources)
* [FAQ](#faq)

***

### How It Works

1. **Ingredients are configured** in the Ingredient Configurator. Each ingredient defines what it provides when consumed (ex. how much food it gives).
2. **A base item is created** in the Item Creator with its reward type set to `ingredients`. You can optionally add default ingredients that are always included.
3. **The item is crafted** using the `CraftItem` export, which combines the base item with a list of ingredients to produce the final consumable.

When a player consumes the finished item, the rewards are calculated from the combined ingredients. Better quality ingredients give better rewards.

***

### Step 1: Configure Your Ingredients

Open the **Ingredient Configurator** menu. This is where you define what each ingredient does when it is part of a consumable item.

Each ingredient has the following fields:

| Field                   | Description                                                                            |
| ----------------------- | -------------------------------------------------------------------------------------- |
| **Name**                | The inventory item name for this ingredient (ex. `burger_patty`, `lettuce`)            |
| **Amount**              | How much this ingredient contributes to the item's total amount (total servings/bites) |
| **Decay**               | How quickly this ingredient decays over time                                           |
| **Consumption Rewards** | What the ingredient gives when consumed (ex. food, thirst, health)                     |

If an ingredient that gets put into an item is **not** configured here, it will simply be ignored. It won't cause any errors, but it also won't contribute any rewards.

***

### Step 2: Create the Base Item

Go into the **Item Creator** and create the item that players will receive after crafting (ex. `burger`, `pizza`, `sandwich`).

Fill in the item information as you normally would (name, label, type, props, animations, etc.), but pay attention to these key points:

#### Reward Type

Set the reward type to `ingredients`. This tells the system that this item's rewards come from its ingredients rather than from fixed consumption rewards.

#### Base Ingredients

In the **Ingredients** section of the item, you can optionally add default ingredients. These are ingredients that are always included in every crafted version of this item, regardless of what the player adds during crafting.

* If you want a completely clean slate, leave this empty
* If you want every burger to always have buns, add `burger_bun_top` and `burger_bun_bottom` as base ingredients

#### Consumption Rewards

For ingredient-based items, leave the **Consumption Rewards** section empty. The rewards will be calculated from the ingredients instead. If you do add consumption rewards here, they will act as base rewards that exist on top of whatever ingredients are added.

***

### Step 3: Craft the Item

To actually create an ingredient-based item for a player, use the `CraftItem` server export:

```lua
exports["zyke_consumables"]:CraftItem(playerId, itemName, ingredients, requireIngredients)
```

| Parameter            | Type      | Description                                                                   |
| -------------------- | --------- | ----------------------------------------------------------------------------- |
| `playerId`           | `number`  | Server ID of the player receiving the item                                    |
| `itemName`           | `string`  | Name of the base item (ex. `"burger"`)                                        |
| `ingredients`        | `table`   | Array of ingredients to add (see below)                                       |
| `requireIngredients` | `boolean` | If `true`, checks the player's inventory for the ingredients and removes them |

#### Ingredients Format

Each entry in the ingredients array needs a `name` and a `quality`:

```lua
local ingredients = {
    { name = "burger_patty", quality = 85.0 },
    { name = "cheese",       quality = 100.0 },
    { name = "lettuce",      quality = 72.5 },
    { name = "ketchup",      quality = 100.0 },
}

exports["zyke_consumables"]:CraftItem(playerId, "burger", ingredients, true)
```

You can also pass ingredient metadata directly if you already have it:

```lua
{ name = "burger_patty", metadata = { quality = 85.0 } }
```

If no quality is provided for an ingredient, it defaults to `100.0`.

***

### Quality

Each ingredient carries a quality value (0 to 100). Quality affects the rewards the player receives when consuming the item.

* Higher quality ingredients give better rewards
* Ingredients with quality above the `qualityThreshold` (configured per reward) provide the full reward multiplier
* Ingredients below the threshold provide reduced rewards

Ingredient quality can decay over time based on the ingredient's `decay` setting. Fresh ingredients are better ingredients.

***

### Requiring Ingredients from Inventory

When `requireIngredients` is set to `true` in the `CraftItem` export:

1. The system checks if the player has all the specified ingredients in their inventory
2. For each ingredient, it finds the closest quality match in the player's inventory
3. If all ingredients are found, they are removed from the player's inventory
4. The actual quality from the inventory items is used (not the quality you passed in)
5. If any ingredients are missing, the craft fails and the player is notified of what they're missing

When set to `false`, the ingredients are not checked or removed from inventory. The item is simply created with whatever ingredients you provide. This is useful for scripted scenarios where you handle ingredient removal yourself.

***

### Giving Ingredients to Players

Do note that you can just give someone the basic item, it doesn't have to go via this export, this is just a convenience wrapper that lets you easily set the quality. Our `ensureMetadata` lib method already handles all of the missing metadata when you spawn in the item.

Use the `GiveIngredient` server export to add ingredient items to a player's inventory:

```lua
exports["zyke_consumables"]:GiveIngredient(playerId, ingredientName, amount, quality)
```

| Parameter        | Type      | Description                                            |
| ---------------- | --------- | ------------------------------------------------------ |
| `playerId`       | `number`  | Server ID of the player                                |
| `ingredientName` | `string`  | Name of the ingredient (ex. `"burger_patty"`)          |
| `amount`         | `number?` | How many to give (defaults to `1`)                     |
| `quality`        | `number?` | Quality of the ingredient, 0-100 (defaults to `100.0`) |

***

### Supported Resources

The `CraftItem` export can be integrated with any restaurant, cooking, or crafting script. The following resources have built-in support:

* *<mark style="color:$info;">None yet</mark>*

If you would like support for a specific resource, please reach out in our [**Discord**](https://discord.gg/zykeresources) and we will work on adding it.

***

### FAQ

**Q: What happens if I put an unconfigured ingredient into an item?** Nothing bad. It gets ignored silently. It won't provide any rewards, but it won't cause errors either. This will be printed as a warning in the server console.

**Q: Can I mix ingredient-based and fixed rewards on the same item?** Yes. If you add consumption rewards to an ingredient-based item, they act as base rewards. The ingredient rewards are added on top.

**Q: Do base ingredients count towards the craft requirement?** Yes. When `requireIngredients` is `true`, the player needs both the base ingredients and the additional ingredients in their inventory.

**Q: How is the item's total amount (servings) calculated?** The total amount is the sum of each ingredient's configured `amount` value. Adding more ingredients means more servings.

**Q: Can players see what ingredients are in their item?** Yes. The ingredient list and their qualities are stored in the item's metadata and displayed in the item description.