Unlocks

A crafter can only craft recipes it knows. Every recipe has an Unlock setting that decides how a crafter gets to know it:

Unlock	A crafter knows the recipe when
Always Known (default)	It is in one of the crafter’s Recipe Books.
Learned	It was taught with Learn Recipe: a scroll, a trainer, a quest reward, or crafting another recipe with the Learn Recipes effect.
Discovered	It is in one of the crafter’s recipe books, and the crafter carries at least one item for each of its ingredients. Craftwright learns it automatically.

Get Available Recipes returns known recipes only. Get Locked Recipes returns the others that are in the crafter’s books, so a menu can show them locked with how to unlock them; see Unlock hints in the menu. Requesting an unknown recipe fails with Unknown Recipe (“You do not know this recipe yet.”).

Known recipes

The crafter keeps a list of the recipes it has learned (Learned and Discovered recipes, and any recipe taught with Learn Recipe), each with its uses left. Always Known recipes in its books are known without being in the list.

Function	Returns or does
Is Recipe Known (Recipe)	True when the crafter knows the recipe
Get Recipe Uses (Recipe)	-1 for unlimited, 0 when not known, or the crafts left
Get Known Recipes	The learned list: each entry has Recipe and Uses Left (-1 = unlimited)
Learn Recipe (Recipe, Uses = -1)	Server only. Teaches the recipe; returns true when something changed
Forget Recipe (Recipe)	Server only. Removes the recipe from the learned list; returns true when it was there

Learn Recipe can teach any recipe, also one that is in none of the crafter’s books; it then shows up in Get Available Recipes too. Forget Recipe only removes learned entries: an Always Known recipe in the crafter’s books stays known.

The learned list replicates to the owning client only, and it is part of the crafter’s save data.

Learned recipes

Call Learn Recipe on the server when the player reads a scroll, talks to a trainer or finishes a quest. In the example, the Iron Sword is a Learned recipe, taught by crafting a Pickaxe.

Limited uses

Pass a positive Uses to Learn Recipe for one-shot blueprints and schematics:

• Uses are spent when a craft is accepted, one per unit: a batch of 3 spends 3 uses.
• When the uses reach 0, the recipe is forgotten.
• A request for more units than uses left fails with Not Enough Uses (“Not enough uses left on this blueprint.”), and Max Count in Check Craft is at most the uses left.
• Uses spent on a job don’t come back when the job is cancelled.

Learning a recipe the crafter already knows:

Already known with	Learn Recipe with	Result
Limited uses	A positive number	The uses are added: 2 left + 3 = 5
Limited uses	-1	Unlimited from now on
Unlimited uses	Anything	Nothing changes; returns false

Uses of 0 or below -1 are invalid; Learn Recipe returns false.

The Learn Recipes effect

Add a Learn Recipes effect to a recipe’s Effects to teach recipes by crafting:

Property	Default	Meaning
Recipes	Empty	The recipes to teach (unlimited uses).
Only On Success	On	Teach only when the crafted unit succeeded.

It runs on the server after each unit and teaches the recipes the crafter doesn’t know yet. In the example, the Pickaxe recipe’s Learn Recipes effect teaches the Iron Sword, which is then crafted at the Forge.

Discovered recipes

A Discovered recipe is learned automatically, on the server, when the crafter carries at least one item that matches each of its ingredients (tools included). The amounts don’t matter: a recipe that needs 3 Plant Fiber is discovered with 1 Plant Fiber in the bag.

What counts as carried: the crafter’s own inventories and its extra sources (Add Inventory Source). Shared containers nearby and station storage don’t count.

Craftwright checks for discoveries:

• when the crafter begins play on the server;
• whenever one of those inventories changes, if it is a built-in Craftwright Inventory;
• when a new built-in Craftwright Inventory shows up on the crafter’s owner, pawn, controller or player state (it looks once a second, for example for a pawn that spawns later);
• when you call Notify Inventory Changed on the crafter (server). Call it after your own inventory changes; see Inventories.

A Discovered recipe must be in one of the crafter’s recipe books, and it must have at least one ingredient; the editor reports one without ingredients as Cannot be discovered.

In the example, Rope (3 Plant Fiber) is Discovered. The player starts with 9 Plant Fiber, so Rope is known from the first moment of play; without fiber it would be discovered the first time you gather from the Fiber Bush.

Unlock hints in the menu

The crafting menu’s Locked Recipes setting decides what players see of recipes they don’t know yet:

Locked Recipes	The menu
Hide (default)	Lists only known recipes
Show	Lists them locked, after the known ones: name, ingredients and a lock
Show As Unknown	Lists them as “???” with a dark icon; they are not found by search and not tracked

A locked recipe’s details show how to unlock it: the recipe’s Unlock Hint, or the menu’s text for its unlock type.

Unlock	Text when the recipe has no Unlock Hint	Menu property
Learned	“Learn this recipe to craft it.”	Learned Hint Text
Discovered	“Carry every ingredient once to discover it.”	Discovered Hint Text

Get Unlock Hint on the menu returns the same text. The craft button stays locked, and the status says “You do not know this recipe yet.”.

The example menu uses Show. Its hints are “Forge your first pickaxe to learn it.” on the Iron Sword and “Carry plant fiber to discover it.” on Rope. See Locked recipes in the Crafting UI.

The Iron Sword at the Forge before a Pickaxe was crafted.

Events

Event	Fires on	When
On Recipe Learned (Crafter, Recipe)	Server	A recipe was added to the learned list: Learn Recipe, Learn Recipes, or a discovery.
On Recipes Changed (Crafter)	Server and owning client	The learned list or its uses changed, including after loading a save.

Tip

On Recipe Learned fires only on the server. In single player and for the host of a listen server that is the local player; on remote clients, bind On Recipes Changed and compare the known recipes to show “New recipe” messages.

Checks in the editor

Two checks help with unlocks. See Editor tools:

• Not taught by a recipe (Suggestion): a Learned recipe that no Learn Recipes effect teaches. Fine when your game code teaches it.
• Cannot be discovered (Error): a Discovered recipe without ingredients.