[Documentation] New Recipe System Functions & Other Info

[Wonderlarr]

This is some documentation about the new recipe system. This doesn't have everything, but should be a solid starting point. I included GLOBAL before every global function, as I assume these will all be used in modmain.

New Recipe Functions

The examples are a bit ridiculous on purpose to get the point across.

AddRecipe2

Spoiler

AddRecipe2(name, ingredients, tech, config, filters)

The AddRecipe2 function is intended for adding custom recipes to the game.

Parameters:
Parameters in bold are required.

• name - A string, sets the internal name for your recipe. Will also be product of the craft unless otherwise set in the config. Multiple recipes for the same product MUST be named differently, or the last one called will take precedent.
• ingredients - A table of ingredients used for the recipe. Identically formatted to old AddRecipe ingredient tables.
• tech - A GLOBAL.TECH variable. The tech level, aka crafting station, that is required to craft the item. See constants.lua's TECH table for a list of possible tech levels.
• config - A table of configuration settings that can be set for the recipe.
• filters - A table of crafting filters this recipe will show up in. AddRecipe2 automatically adds your item to the "MODS" filter, unless you remove it manually.

Examples:

Spoiler

Item:

AddRecipe2("awesome_beardhair", -- name
	{ -- ingredients
		GLOBAL.Ingredient("cutgrass", 1),
		GLOBAL.Ingredient("twigs", 1),
	},
	GLOBAL.TECH.SCIENCE_ONE, -- tech
	{ -- config
		product = "beardhair",
		builder_tag = "bearded",
		numtogive = 3,
	}, 
	{ -- filters
		"WEAPONS",
		"RAIN",
		"SUMMER",
	}
)

Structure:

AddRecipe2("awesome_researchlab", -- name
	{ -- ingredients
		GLOBAL.Ingredient("cutgrass", 1),
		GLOBAL.Ingredient("goldnugget", 1),
		GLOBAL.Ingredient("beardhair", 1),
	},
	GLOBAL.TECH.SCIENCE_ONE, -- tech
	{ -- config
		product = "researchlab",
		placer = "researchlab_placer",
		nounlock = true,
	}, 
	{ -- filters
		"MAGIC",
		"DECOR",
	}
)

 

Possible Config Variables:

Spoiler

min_spacing
* A number
* How far away structures must be from obstacles in order to be built.
* Defaults to 1
nounlock
* A boolean
* Determines if the crafter must be near a recipe's crafting structure (ex. Alchemy Engine) in order to craft it.
* Defaults to false
numtogive
* A number
* How many items the recipe makes when crafted.
* Defaults to 1
builder_tag
* A string
* A tag the crafter must have in order to craft the recipe.
* Defaults to nil
atlas
* A string
* The path to the atlas containing the image you'd like to use for the recipe. Will use the recipe product's icon image if it's valid.
* Defaults to nil
image
* A string
* The name of the image inside the atlas you'd like to use for the recipe. Will use the recipe product's icon image if it's valid.
* Defaults to nil
testfn
* A function
* A function that must return true in order to place a structure. Does nothing for item recipes.
* Defaults to nil
product
* A string
* The name/id of the recipe's intended product. I believe this is intended for items, but it might work for structures too. Will use the recipe name as the product if this value is left nil.
* Defaults to nil.
build_mode
* A string
* Determines what type of terrain a structure can be built on.
* Defaults to BUILDMODE.LAND
build_distance
* A number
* Determines how far away you can build a structure from.
* Defaults to 1

There are additional config options leftover from the old recipe system, I haven't done a whole ton of research on them, but they still seem to work at the time of writing.

placer
* A string
* Points to the prefab you want to use as your placer for a structure.
imagefn
* A function
* Allows you to return different images based on different conditions using a function.
* Doesn't seem to be used in vanilla anymore.
* Defaults to nil
fxover
* A table
* Seems to take a bank, build, and anim, and spawns an effect based on them once the crafting is finished.
* Defaults to nil
canbuild
* A function
* Must return true in order to craft the recipe.
* Seems to be ran using canbuild(recipe, inst, pt, rotation)
sg_state
* A string
* A stategraph state to be used while crafting the recipe.
* Defaults to nil
no_deconstruction
* A boolean
* Whether or not the item/structure can be deconstructed using the Deconstruction Staff.
* Defaults to false
dropitem
* A boolean
* Drops the product prefab into the world on top of the player.
* Defaults to false
actionstr
* A string
* Can't figure out what this actually does. Seems like it's supposed to cause a talker line when you craft the recipe, but doesn't.
manufactured
* A boolean
* Prevents the builder component from actually building the product, leaving it up to the crafting station prefab to do something on its own.
is_deconstruction_recipe
* A boolean
* Prevents the recipe from actually being craftable by any players, while still allowing the item to be deconstructed using the deconstruction staff.
hint_msg
* A string
* Seems to cause a talker line when the recipe can't be crafted. Is only used for seasonal items in the modern game.
require_special_event
* I don't know what this is for what it does. Might be a boolean.
* It may not be used anymore, and might be an old way to limit items to special events like Winter's Feast.
station_tag
* A string
* Not sure what this does, or why you would use it over a TECH level. Maybe for crafting stations that aren't always active?
rpc_id
* A number
* I don't know what this does for sure, but I presume it's something to do with networking recipes and assigning recipes to mods.

The below config options are deprecated and should not be used in any new mods for the modern game.

sortkey (deprecated)
* A number
* Sorted your recipe among other recipes when using the old recipe system. This does nothing now.
tab (deprecated)
* A string
* The tab your recipe would have gone in using the old recipe system. This does very little now, and it is highly recommended you use filters instead.

Possible Filters:

Spoiler

"FAVORITES"
"CRAFTING_STATION"
"SPECIAL_EVENT"
"MODS"
"CHARACTER"
"TOOLS"
"LIGHT"
"PROTOTYPERS"
"REFINE"
"WEAPONS"
"ARMOUR"
"CLOTHING"
"RESTORATION"
"MAGIC"
"DECOR"
"STRUCTURES"
"CONTAINERS"
"COOKING"
"GARDENING"
"FISHING"
"SEAFARING"
"RIDING"
"WINTER"
"SUMMER"
"RAIN"
"EVERYTHING"

 

 

AddCharacterRecipe

Spoiler

AddCharacterRecipe(name, ingredients, tech, config, filters)

The AddCharacterRecipe function is intended for adding custom character recipes to the game, based on the builder_tag set. They will show up in the "Survivor Items" section of the crafting menu.

Parameters:
Parameters in bold are required.

• name - A string, sets the internal name for your recipe. Will also be product of the craft unless otherwise set in the config. Multiple recipes for the same product MUST be named differently, or the last one called will take precedent.
• ingredients - A table of ingredients used for the recipe. Identically formatted to old AddRecipe ingredient tables.
• tech - A GLOBAL.TECH variable. The tech level, aka crafting station, that is required to craft the item. See constants.lua's TECH table for a list of possible tech levels.
• config - A table of configuration settings that can be set for the recipe. builder_tag is required for AddCharacterRecipe.
• filters - A table of crafting filters names this recipe will show up in. The recipe is automatically added to the character recipes filter by AddCharacterRecipe, but is not added to the "MODS" filter.

Example:

Spoiler

AddCharacterRecipe("awesome_beardhair", -- name
	{ -- ingredients
		GLOBAL.Ingredient("cutgrass", 1),
		GLOBAL.Ingredient("twigs", 1),
	},
	GLOBAL.TECH.NONE, -- tech
	{ -- config
		product = "beardhair",
		builder_tag = "bearded",
		numtogive = 3,
	}, 
	{ -- filters
		"WEAPONS",
	}
)

 

Possible config variables and filter names can be found in the AddRecipe2 section.

 

AddRecipeFilter

Spoiler

AddRecipeFilter(filter_def, index)

The AddRecipeFilter function is intended for adding custom recipe filters to the game. If you're making a custom character filter, it's recommended you  use AddCharacterRecipe in combination with the new built in character recipe filter.

Parameters:
Parameters in bold are required.

• filter_def - A table of variables required to set up a custom recipe filter.
• index - A number, sets a filter's priority among other filters.

Example:

Spoiler

-- This string must be set somewhere for the display name of the filter. "EXAMPLE" should match your filter's internal name.
GLOBAL.STRINGS.UI.CRAFTING_FILTERS["EXAMPLE"] = "Example Filter"

AddRecipeFilter(
	{ -- filter_def
		name = "EXAMPLE", -- internal name.
		atlas = "images/crafting_menu_icons.xml",
		image = "filter_modded.tex",
		image_size = 64, -- 64 is default
		custom_pos = false, -- setting to true hides this filter from the normal filter grid.
	},
	5 -- index
)

 

 

 

AddRecipeToFilter

Spoiler

AddRecipeToFilter(recipe_name, filter_name)

The AddRecipeToFilter function is intended for adding a given recipe to a given filter.

Parameters:
Parameters in bold are required.

• recipe_name - A string, the internal name of a recipe you'd like to effect.
• filter_name - A string, the name of a filter you'd like to effect.

Example:

Spoiler

AddRecipeToFilter("spear", "DECOR")

 

 

 

RemoveRecipeFromFilter

Spoiler

RemoveRecipeFromFilter(recipe_name, filter_name)

The RemoveRecipeFromFilter function is intended for removing a given recipe from a given filter.

Parameters:
Parameters in bold are required.

• recipe_name - A string, the internal name of a recipe you'd like to effect.
• filter_name - A string, the name of a filter you'd like to effect.

Example:

Spoiler

RemoveRecipeFromFilter("spear", "WEAPONS")

 

 

 

Other Info

Custom characters can have a unique icon for their crafting filter by putting an image in images/crafting_menu_avatars/avatar_esctemplate.xml and .tex. Otherwise, the game will automatically use the image in images/avatars/avatar_esctemplate.xml and .tex. Of course, esctemplate should be replaced with your character's prefab name.

If your item's recipe icon is invisible, you likely need to register it's inventory icon with the game properly. See the RegisterInventoryItemAtlas section from Hornete's Modutil Documentation.

 

And that's all I have for you, for now anyway. Have fun!

Edited June 19 by Wonderlarr

[Leonidas IV]

Beautiful work! The only thing I would add is the parameter type (you wrote it for the tables), typing in documentation is essential.

[Wonderlarr]

2 hours ago, Leonidas IV said:

Beautiful work! The only thing I would add is the parameter type (you wrote it for the tables), typing in documentation is essential.

Good point! I'll get on that pretty soon here.

[Wonderlarr]

On 6/15/2022 at 10:30 PM, Leonidas IV said:

Beautiful work! The only thing I would add is the parameter type (you wrote it for the tables), typing in documentation is essential.

Finally got around to updating it lol. It's only been, oh, over a year.