-
Notifications
You must be signed in to change notification settings - Fork 3
07. Recipes tool: Blueprints
The Recipes tool (Singleton: NexusForge.Recipes, Class: RecipeCatalog) is designed to define and manage all crafting formulas within your game's economy.
- Role: Defines the item requirements (Inputs) and item results (Outputs) using IDs from the Item Catalog.
- Storage: All recipe data is consolidated into a single file resource known as the Recipe Catalog. This resource uses a custom icon and follows the standard load/create/drag-and-drop workflow.
Warning
The Recipe Catalog is structurally dependent on the Items Tool for synchronization. For the Recipe Catalog to maintain data integrity when item references are modified, it MUST be loaded concurrently with the Item Catalog.
-
Soft Dependency: Recipes store item references purely as
StringNameIDs. - Safe Action: Creating a new item in the Items Tool is harmless to the Recipe Catalog, regardless of whether the Recipe Tool is loaded.
-
Destructive Actions: Actions that modify item identity are destructive if the Recipe Catalog is not loaded:
- Item Deletion: If an item is deleted while the Recipe Catalog is closed.
- Item ID Change: If an item's ID is changed (renamed) while the Recipe Catalog is closed.
- Failure Condition: If either Item Deletion or Item ID Change occurs, the Recipe Catalog will contain broken or incorrect references when loaded later.
Note
It's best practice to always ensure both the Items Catalog and the Recipe Catalog are loaded/created within the Nexus Forge editor before performing any operations in either.
The recipe editor is structured into three main columns, centered around a visual drag-and-drop workflow.
This column controls the file structure and selection of recipes.
- Creation: A text field for searching recipes is at the top. Next to it, a Blueprint with a green '+' icon allows you to create a new recipe. A popup prompts for the recipe's unique ID.
-
Recipe Tree: The tree below lists all defined recipes by their ID.
- Loading: Clicking a recipe loads its data into the Definition Section (2.3).
- Editing ID: The recipe ID can be edited by double-clicking the item in the tree.
- Deletion: A trash bin icon next to each recipe item deletes it permanently.
Note
Recipes in the recipe tree are always sorted alphabetically.
This section serves as the item palette, drawing its data directly from the Item Catalog resource.
- Search: A text field at the top allows users to quickly filter the item list.
- Item Tree: Displays all registered items in two columns: ID (left) and Name (right). This tree is the source for drag-and-drop actions.
Note
The sorting of items in the item tree can be changed by pressing the culumn titles which will sort them alphabetically based on the column you press.
This is the main workspace where the recipe is constructed and customized.
The core crafting formula is defined using two adjacent tree views: Inputs (Left) and Outputs (Right).
Items are added to the recipe by selecting them in the Item Tree (Section 2.2), dragging them, and dropping them onto the desired Input or Output tree.
Note
The physical order of items within both the Input and Output trees is preserved and is significant for crafting logic at runtime. Items can be reordered within a tree or moved between the Input and Output sections via drag-and-drop.
This feature allows for advanced ingredient requirements.
- Controls: Four buttons (Int, Float, Bool, String) are located above the Input/Output trees.
- Enablement Logic: These buttons are disabled by default. They become active only when an item instance (ingredient or output) is selected in the Input or Output tree.
- Function: When active, pressing a button adds the corresponding custom data field to the currently selected item instance. This allows a recipe to require a specific item that also meets custom criteria.
Below the Input/Output trees is a final tree view dedicated to the overall recipe custom data. This is used for defining recipe-level properties (e.g., required crafting station ID, skill check complexity, or success chance).
Tip
You can change the initial default data a recipe contains by changing the constant RECIPE_DEFAULT_DATA on the RecipeCatalog[1].
The API relies heavily on two custom classes: RecipeSheet (the full recipe object) and RecipeItem (the single ingredient/output entry).
| Class | Variable | Type | Purpose |
|---|---|---|---|
RecipeSheet |
id |
StringName |
The unique ID of the recipe. |
input / output
|
Array[RecipeItem] |
The ordered lists of required ingredients and results. | |
data |
Dictionary |
Custom data specific to the overall recipe (e.g., skill required). | |
RecipeItem |
id |
StringName |
The ID of the item (must match an ID in the Item Catalog). |
amount |
int |
The quantity of this item instance required or produced (defaults to 1). | |
data |
Dictionary |
Custom data specific to this item instance within the recipe. |
| Function Signature | Purpose | Return Type | Notes |
|---|---|---|---|
recipes() |
Returns a list containing the IDs of all registered recipes. | Array[StringName] | |
get_recipe(recipe_id) |
Returns an object containing the data of a recipe. | RecipeSheet | Returns null if the recipe is not found. |
| Function Signature | Purpose | Notes |
|---|---|---|
create_recipe(recipe_id) |
Creates a new recipe with the given ID. | Creation fails if the ID already exists. |
set_recipe_inputs(recipe_id, inputs) |
Overwrites the current list of required ingredients. | |
set_recipe_outputs(recipe_id, outputs) |
Overwrites the current list of resulting items. | |
set_recipe_data(recipe_id, data_key, data) |
Sets a key in the recipe's overall custom data. | If data is null, the key is erased. |
set_recipe_input_item_data(recipe_id, ingredient_idx, data_key, data) |
Sets a key in an input ingredient's custom data. | If data is null, the key is erased. |
set_recipe_output_item_data(recipe_id, ingredient_idx, data_key, data) |
Sets a key in an output ingredient's custom data. | If data is null, the key is erased. |
| Function Signature | Purpose | Return Type |
|---|---|---|
has_recipe(recipe_id) |
Used to verify a recipe is registred. | Bool |
| Function Signature | Purpose |
|---|---|
erase_recipe(recipe_id) |
Removes the recipe from the catalog. |
clear_recipe_data(recipe_id) |
Clears the entire custom data dictionary for the recipe. |
clear_recipe_input_item_data(recipe_id, ingredient_idx) |
Clears the custom data dictionary for an input item. |
clear_recipe_output_item_data(recipe_id, ingredient_idx) |
Clears the custom data dictionary for an input item. |
- The default path of the RecipeCatalog is
res://addons/nexus_forge/resources/recipe_catalog.gd.