# 4 · Blueprints

Install blueprint items, create technical drawings, manage quality/uses and gate recipes through metadata.

# Blueprint System Overview

Blueprints are metadata-rich inventory items used to unlock or authorize recipes.

A blueprint definition is stored in:

```text
nord_crafting_blueprints
```

Each definition can include:

- Stable blueprint ID.
- Label.
- Item/material requirements for drafting.
- Maximum uses.
- Image or image URL.

The physical inventory item is named:

```text
blueprint
```

Each crafted blueprint instance receives its own metadata, allowing different quality and remaining-use values.


# Blueprint Item Installation

The blueprint system requires the inventory item:

```text
blueprint
```

## Nord Inventory

Use Nord Crafting's **automatic installation workflow**. The auto-installer is intended only for `nord_inventory`.

After first boot, verify `blueprint` is present in the Nord Inventory item registry before testing drafting.

## Other inventories

Manual files are included:

```text
install/itens/item.lua
install/itens/item_qs.lua
install/itens/blueprint.png
```

If the item is missing, the blueprint startup check reports that `blueprint` was not found in the active inventory and points to the manual install files.

> For metadata-based uses/quality to work correctly, use a unique/non-stacking blueprint definition where your inventory requires that behavior.


# Drafting & Quality

Blueprint benches can open the drafting interface. The client sends the detected blueprint type and drawing quality to the server.

## Server validation

The server:

1. Normalizes the detected blueprint ID.
2. Confirms the definition exists in the database.
3. Clamps quality to **1–100**.
4. Reads drafting ingredients from the database.
5. Verifies and removes materials.
6. Creates the `blueprint` item with metadata.
7. Refunds materials when adding the final blueprint item fails.

## Quality metadata

The blueprint item label includes its quality percentage, for example:

```text
Pistol Blueprint (85%)
```

Quality is stored in:

```lua
metadata.quality
```


# Blueprint Metadata & Uses

A generated blueprint contains metadata similar to:

```lua
{
    label = 'Pistol Blueprint (85%)',
    description = 'Projeto técnico avançado\nUtilizações: 3/3',
    blueprint = true,
    blueprint_id = 'pistol',
    quality = 85,
    uses = 3,
    max_uses = 3,
    ingredients = { ... },
    createdAt = os.time()
}
```

An optional local image is stored as `metadata.image`; HTTP/HTTPS images are stored as `metadata.imageurl`.

## Use consumption

When a blueprint-required recipe succeeds:

- `uses` decreases by 1.
- The description is updated.
- When uses reach zero, the blueprint item is removed.

If the inventory cannot update metadata directly, Crafting can fall back to removing/re-adding the item with updated metadata where the bridge allows it.


# Blueprint-Gated Recipes

A recipe can require a blueprint type.

Database-backed recipes use:

```text
use_blueprint
blueprint_type
```

The server searches the player's inventory for an item named `blueprint` whose metadata contains the matching `blueprint_id`.

Example concept:

```lua
use_blueprint = 1
blueprint_type = 'pistol'
```

The recipe is rejected if:

- The blueprint type is empty.
- No matching blueprint exists.
- The matching blueprint has no remaining uses.

Blueprint validation occurs before ingredient removal.


# Blueprint Developer API

## Server exports

```lua
exports['nord_crafting']:GetPlayerBlueprintRecipes(source)
exports['nord_crafting']:GetBlueprintDefinition('pistol')
exports['nord_crafting']:BuildBlueprintMetadata(blueprintRow, 85)
exports['nord_crafting']:CreateBlueprintItem(source, 'pistol', 85)
```

Custom uses and metadata can be supplied:

```lua
local ok, metadata = exports['nord_crafting']:CreateBlueprintItem(
    source,
    'pistol',
    85,
    3,
    {
        recipes = { 'weapon_pistol' }
    }
)
```

`GetPlayerBlueprintRecipes` reads `metadata.recipes` from blueprint items and returns the unlocked recipe set.