Blueprints

Blueprints are physical inventory items that gate access to certain crafting recipes. A player must carry the matching blueprint in their inventory to craft the recipe. Without it, the recipe appears locked. Because blueprints are real items, players can trade, store, and sell them just like any other item.

#Table of Contents

• How Blueprints Work
• Blueprint Uses (Durability)
• Marking a Recipe as Blueprint-Required
• Registering the Blueprint Item in Your Inventory
• Giving Blueprints to Players
• Admin Commands
• Configuration Reference
• Blueprint Metadata Reference
• Troubleshooting
• FAQ

#How Blueprints Work

1. A craft in Config.Crafts is marked with blueprint = true.
2. When a player opens a crafting bench, the system scans their inventory for blueprint items and reads each one's metadata.recipe field.
3. If no matching blueprint is found, the craft is greyed out with a "Missing Blueprint" message.
4. If the player has the blueprint, the craft is available (assuming level and material requirements are also met).
5. After a successful craft, if the blueprint has finite uses, one use is deducted. When uses reach 0 the blueprint item is removed from inventory.
6. If the player's inventory changes while they have the crafting menu open (e.g. they lose a blueprint in a trade), the menu refreshes automatically.

Blueprints use a generic item pattern. A single inventory item name (blueprint) is reused for all recipes. Differentiation happens entirely through metadata, the same way packs work in zyke_consumables. This means the inventory shows a custom label and image per blueprint (e.g. "Blueprint: SNS Pistol" with the pistol's icon) if the inventory supports it.

#Blueprint Uses (Durability)

Each blueprint has a uses value that determines how many times it can be used for crafting:

Uses are configured per recipe in Config.Settings.blueprintUses. A wildcard (["*"]) sets the default for all recipes not explicitly listed.

When giving a blueprint via the export or admin command, you can also pass a custom uses value that overrides the config. The priority is:

1. Custom value: passed directly via export or command
2. Specific config value: Config.Settings.blueprintUses["weapon_snspistol"]
3. Wildcard config value: Config.Settings.blueprintUses["*"]
4. Fallback: -1 (infinite)

Config.Settings.blueprintUses = {
    ["*"] = -1,                      -- Default: infinite uses
    ["weapon_snspistol"] = 3,        -- SNS Pistol blueprints expire after 3 crafts
    ["armor"] = 5,                   -- Armor blueprints expire after 5 crafts
}

When a blueprint has finite uses, its inventory description updates after each craft to show the remaining count (e.g. "Uses: 2"). When infinite, it shows "Uses: Infinite".

#Marking a Recipe as Blueprint-Required

In Config.Crafts, add blueprint = true to any craft entry:

{
    item = "weapon_snspistol",
    label = "SNS Pistol",
    level = 3,
    timeToCraft = 5,
    amount = 1,
    experienceToGive = 50,
    blueprint = true,                 -- Requires a blueprint item
    items = {
        { label = "Iron", item = "iron", amount = 3 },
    },
},

Recipes without blueprint = true (or with it set to false) are always available as long as level and material requirements are met.

#Registering the Blueprint Item in Your Inventory

You need to register a single blueprint item in your inventory resource. This is required. Blueprints will not work without it.

#ox_inventory

["blueprint"] = {
    label = "Blueprint",
    weight = 50,
    stack = false,
    close = true,
},

#qb-core

["blueprint"] = {
    ["name"] = "blueprint",
    ["label"] = "Blueprint",
    ["weight"] = 50,
    ["type"] = "item",
    ["image"] = "blueprint.png",
    ["unique"] = true,
    ["useable"] = false,
    ["shouldClose"] = false,
    ["combinable"] = nil,
    ["description"] = "A crafting blueprint",
},

A blueprint.png image is included in extras/items/images/ that you can copy to your inventory's images folder. However, each blueprint item will display the craft's own image via metadata.imageurl, so this image is only used as a fallback since some inventories don't support dynamic image changes.

#Giving Blueprints to Players

For the export reference (AddBlueprint) and usage examples, see Exports & Events.

#Admin Commands

All commands are defined in server/unlocked.lua and configurable in Config.Settings.commands. Each command supports multiple aliases (pass an array of strings) and permission gating.

#/craft:addbp

Gives you a blueprint item in your inventory.

/craft:addbp <item> [uses]
/craft:addbp random [uses]

Examples:

/craft:addbp weapon_snspistol           -- Gives you a blueprint for the SNS Pistol (uses from config)
/craft:addbp weapon_snspistol 10        -- Gives you a blueprint for the SNS Pistol with 10 uses
/craft:addbp weapon_snspistol -1        -- Gives you a blueprint for the SNS Pistol with infinite uses
/craft:addbp random                     -- Gives you a blueprint for a random blueprint-required recipe
/craft:addbp random 1                   -- Gives you a random blueprint with 1 use

If the blueprint item is not registered in your inventory, you will see a console warning and an in-game error. See Troubleshooting.

#/craft:removebp

Removes a blueprint from your inventory matching the specified recipe.

/craft:removebp <item>

Example:

/craft:removebp weapon_snspistol    -- Removes your SNS Pistol blueprint

#/craft:checkbp

Prints all blueprints in your inventory to the server console. Useful for debugging.

/craft:checkbp

Output example:

[zyke_crafting] Blueprints in inventory:
  - Blueprint: SNS Pistol (recipe: weapon_snspistol, uses: Infinite, slot: 3)
  - Blueprint: Armor (recipe: armor, uses: 5, slot: 7)

#/craft:addxp

Gives you crafting XP.

/craft:addxp <amount>

Example:

/craft:addxp 500    -- Gives you 500 crafting XP

#Customizing Commands

All command names and permissions are configured in Config.Settings.commands:

Config.Settings.commands = {
    addBlueprint = {
        commands = {"craft:addbp"},       -- Array for multiple aliases: {"craft:addbp", "addbp"}
        permission = "command",            -- ACE permission required
    },
    removeBlueprint = {
        commands = {"craft:removebp"},
        permission = "command",
    },
    checkBlueprints = {
        commands = {"craft:checkbp"},
        permission = "command",
    },
    addXp = {
        commands = {"craft:addxp"},
        permission = "command",
    },
},

To change a command name, just update the string. To add aliases, add more strings to the array. To change the permission, update the permission field (uses Z.hasPermission under the hood; server console always has access).

#Configuration Reference

#Config.Settings

Config.Settings = {
    debug = false,
    blueprintItem = "blueprint",         -- Inventory item name for blueprints
    blueprintUses = {
        ["*"] = -1,                       -- Default uses for all recipes (-1 = infinite)
        -- ["weapon_snspistol"] = 3,      -- Override per recipe
    },
    Levels = {
        baseXp = 100,
        xpMultiplier = 1.5,
    },
}

#Config.Crafts (blueprint-related fields only)

{
    item = "weapon_snspistol",
    label = "SNS Pistol",
    blueprint = true,       -- Set to true to require a blueprint
    img = "https://...",    -- Used as the blueprint's inventory image
    -- ... other craft fields
}

#Blueprint Metadata Reference

Each blueprint inventory item carries the following metadata:

#Troubleshooting

#"Blueprint item is not registered in your inventory"

You tried to give a blueprint but the blueprint item doesn't exist in your inventory resource. Make sure you've added the item definition to your inventory:

• ox_inventory: Add the entry to ox_inventory/data/items.lua
• qb-core: Add the entry to qb-core/shared/items.lua

See Registering the Blueprint Item for the exact code to copy.

#"No blueprint-required recipe found for that item"

You ran /craft:addbp <item> but the item you specified doesn't have blueprint = true in Config.Crafts. Either the item name is wrong, or the recipe isn't configured to require a blueprint.

#"Failed to add blueprint, check inventory space"

The blueprint item is registered but addItem returned false. The player's inventory is most likely full.

#Blueprint shows in inventory but recipe is still locked

The blueprint's metadata.recipe must exactly match the craft's item field. If you gave the blueprint before the config was updated, the metadata may be stale. Remove the old blueprint and give a new one.

#FAQ

Q: Do I need a separate inventory item for each blueprint? No. A single blueprint item is used for all recipes. The metadata differentiates them.

Q: Can players trade blueprints? Yes. Since blueprints are regular inventory items, players can drop, trade, or store them like any other item.

Q: What happens when a blueprint runs out of uses? The blueprint item is removed from the player's inventory. They'll need to obtain a new one to continue crafting that recipe.

Q: Can a blueprint be used at multiple crafting locations? Yes. As long as the recipe is available at that location and the player has the blueprint, it works anywhere.

Q: What if multiple recipes share the same item but only some require a blueprint? The blueprint check only applies to recipes where blueprint = true. Other recipes for the same item are unaffected.

Q: Does the crafting menu update in real-time when my inventory changes? Yes. When your inventory changes (items added, removed, or moved), the crafting menu automatically refreshes to reflect your current blueprint ownership and materials.

Q: Can I change the inventory item name from blueprint to something else? Yes. Change Config.Settings.blueprintItem and register that item name in your inventory resource instead. All blueprint logic uses this config value.

Q: How do I change how many uses a blueprint has? There are three ways:

1. Per-blueprint: Pass a custom uses value when giving the blueprint via export or command
2. Per-recipe: Set Config.Settings.blueprintUses["weapon_snspistol"] = 3 for a specific recipe
3. Global default: Set Config.Settings.blueprintUses["*"] = -1 for all recipes without a specific override

Note: changing the config only affects newly created blueprints. Existing ones in player inventories keep their original uses count.