# qb-crafting: recipes, workbenches and XP

The [`qb-crafting` repository](https://github.com/qbcore-fivem/qb-crafting/tree/c54be24cbc1b54ec7a34ae2c7e23c7411d45dacc) contains item and attachment crafting benches, ingredient requirements, crafting reputation and an optional minigame. The [README](https://github.com/qbcore-fivem/qb-crafting/blob/c54be24cbc1b54ec7a34ae2c7e23c7411d45dacc/README.md) is short; the actual integration contract is in the Lua source.

**Important:** The reviewed server has security and transaction-integrity limitations. Read [the security section](#server-side-validation-and-known-limits) before enabling this resource for real players.

## Requirements and installation

The [manifest](https://github.com/qbcore-fivem/qb-crafting/blob/c54be24cbc1b54ec7a34ae2c7e23c7411d45dacc/fxmanifest.lua) loads QBCore locale helpers, `config.lua`, `client.lua` and `server.lua`. It does not itself enumerate all runtime dependencies.

The source calls these resources:

- `qb-core` — shared item definitions, callbacks and player reputation
- `qb-inventory` — ingredients, crafted items and workbench items
- `qb-input` — amount selection
- `qb-menu` — available recipes
- `qb-target` — interactions with spawned crafting benches
- `qb-minigames` — `Skillbar` when `Config.EnableSkillCheck` is enabled
- QBCore `progressbar` integration — progress UI

After downloading the official repository, start those dependencies before `qb-crafting`. Ensure `item_bench`, `attachment_bench` and **every recipe item** exist in the installed shared item definitions and inventory images. The resource ships no dedicated SQL file; it relies on player metadata/inventory persistence.

## Recipe structure

The [official config](https://github.com/qbcore-fivem/qb-crafting/blob/c54be24cbc1b54ec7a34ae2c7e23c7411d45dacc/config.lua) defines `Config.item_bench` and `Config.attachment_bench`. Each has an object model, `xpType` and `recipes` array. `Config.EnableSkillCheck` selects the optional skill check.

~~~lua filename="config.lua"
-- Example to add INSIDE Config.item_bench.recipes.
-- Ensure both item names exist in your installed shared item table.
{
    item = 'lockpick',
    xpRequired = 0,
    xpGain = 1,
    requiredItems = {
        { item = 'metalscrap', amount = 22 },
        { item = 'plastic', amount = 32 },
    },
},
~~~

Fields:

| Field | Meaning |
| --- | --- |
| `item` | Output item name from QBCore shared items |
| `xpRequired` | Minimum reputation to show/unlock the recipe |
| `xpGain` | Reputation gained per craft amount |
| `requiredItems` | Array of material `item` and `amount` pairs |
| `xpType` on bench | Metadata reputation key, e.g. `craftingrep` |
| `object` on bench | GTA object model spawned for the bench |

Only add the recipe **inside** the existing table; do not duplicate `Config.item_bench` or assume the example is a complete `config.lua`.

## What happens when a player crafts?

1. A player uses a bench item; the client creates the bench object and adds `qb-target` interactions.
2. The menu reads the player's metadata reputation and inventory using `crafting:getPlayerInventory`.
3. The player chooses an amount via `qb-input`. An enabled minigame runs `exports['qb-minigames']:Skillbar('easy', '12345')`.
4. After progress completion, the client calls `qb-crafting:server:receiveItem` with bench type, recipe output and quantity.
5. The server looks up the configured recipe, checks reputation, attempts ingredient removals and calls `qb-inventory:AddItem` for the result.

The menu/skill-check is a **client experience**, not independent authorization.

## Relevant events and callbacks

| Side | Name | What it does |
| --- | --- | --- |
| Client event | `qb-crafting:client:useCraftingTable` | Places the specified bench item |
| Server callback | `crafting:getPlayerInventory` | Supplies the current player's inventory to the menu |
| Server event | `qb-crafting:server:receiveItem` | Attempts to craft a configured recipe |
| Server event | `qb-crafting:server:removeMaterials` | Removes materials after a failed skill check |
| Server event | `qb-crafting:server:removeCraftingTable` | Consumes a bench item |
| Server event | `qb-crafting:server:addCraftingTable` | Returns a bench item on pickup |

These names are **internal** to the bundled resource. Avoid exposing them as generic publicly callable integrations.

## Server-side validation and known limits

The reviewed [`server.lua`](https://github.com/qbcore-fivem/qb-crafting/blob/c54be24cbc1b54ec7a34ae2c7e23c7411d45dacc/server.lua) validates that a requested recipe exists and that reputation is high enough. However, it does **not** establish all of the following:

- The numeric craft amount is a bounded positive **integer** (the handler converts with `tonumber` and checks `> 0`, but not an integer or maximum).
- The player is actually near and entitled to use the specified bench.
- Ingredient removal and output grant are **atomic**. If a later removal or output grant fails, earlier deductions are not rolled back.
- The `removeMaterials` event validates its caller-supplied item name and amount against a failed server-verified skill check.
- The separate bench return/consume events are linked to an authoritative placed bench entity.

A public server should close these gaps in a maintained fork before enabling crafting. At minimum, keep requests server-authorized, validate integer quantity and available capacity, enforce location/bench ownership, verify ingredient amounts and complete the inventory transaction with recoverable failure handling. A menu-side materials check does **not** protect the server.

See [safe server events](/docs/security/safe-server-events) and the [inventory API reference](/docs/resources/qb-inventory) for related patterns.

## Troubleshooting

| Symptom | Check |
| --- | --- |
| Crafting menu does not appear | `qb-target`, spawned bench entity, item registration and console |
| Blank item name or image | Correct `QBCore.Shared.Items` entry and `Config.ImageBasePath` |
| Crafting never completes | Progressbar, `qb-minigames` dependency and installed callback names |
| No materials recognized | `crafting:getPlayerInventory` response and item names |
| Recipe locked | `metadata.craftingrep` (or the configured `xpType`) and `xpRequired` |
| Ingredients disappear on failure | Partial non-atomic removal behavior in `server.lua`; investigate before reattempting |

## Update checklist

1. Pin the resource commit and compare upstream `config.lua` to local recipes.
2. Verify every ingredient/output/workbench item exists in your actual inventory.
3. Exercise success, failure, repeated, malformed, very large and disconnected-player crafting requests **on a disposable staging server**.
4. Do not deploy until server-side authorization and transaction boundaries are proven for your fork.

## Sources

[Repository](https://github.com/qbcore-fivem/qb-crafting/tree/c54be24cbc1b54ec7a34ae2c7e23c7411d45dacc) · [Recipe config](https://github.com/qbcore-fivem/qb-crafting/blob/c54be24cbc1b54ec7a34ae2c7e23c7411d45dacc/config.lua) · [Client UI/workbench flow](https://github.com/qbcore-fivem/qb-crafting/blob/c54be24cbc1b54ec7a34ae2c7e23c7411d45dacc/client.lua) · [Server events and security boundary](https://github.com/qbcore-fivem/qb-crafting/blob/c54be24cbc1b54ec7a34ae2c7e23c7411d45dacc/server.lua)
