[Tutorial]Complete Tutorial for DST's New Craft Menu

[LongFeiaot]

Introduction

The crafting menu  underwent a major overhaul in recent update. The sidebar TAB format was replaced by filters, which greatly increased the flexibility and richness of the crafting menu's design. In the new version of the crafting menu, items can belong to any filter, and players can even customize their own filters, greatly broadening the game's playability.

To adapt to this change, Klei released a group of ModAPIs for the crafting menu's modifications. To help everyone better understand and master these new features, I have written this article. In this tutorial, I will explain how to add recipes, add custom filters, manage filters, add character-specific recipes, add decomposition recipes, add prototypes, and modify recipes.

At the same time, I have also provided a sample mod code for everyone to reference and learn from. You can find it here: lesson_add_new_recipe

Finally, I have attached a quick reference manual for the relevant ModAPI at the end of this article, allowing you to quickly set the necessary parameters.

I hope this article can help you quickly become familiar with the related operations of the new version of the crafting menu and make better mods.

Adding a Recipe

With the ModAPI: AddRecipe2, we can add new crafting recipes. AddRecipe2 is derived from AddRecipe, and just like AddRecipe, it shares the same function parameter list as the Recipe2 class.

Let's take a look at the basic usage of the AddRecipe2 function. Below is an example code for creating a new recipe:

-- modmain.lua
local recipe_name = "lotus_umbrella" -- Unique name of the recipe, cannot be duplicated, usually using the prefab name.
local ingredients = {Ingredient("cutgrass", 1), Ingredient("twigs", 1)} -- Ingredient table
local tech = TECH.NONE -- Required technology, must use the value in the constants table TECH.
local config = {
    atlas = "images/inventoryimages/lotus_umbrella.xml",
}
AddRecipe2(recipe_name, ingredients, tech, config)
STRINGS.RECIPE_DESC.LOTUS_UMBRELLA = "荷叶做的雨伞" -- Description in the crafting menu.

In this example, we create a new recipe named "lotus_umbrella". This recipe requires 1 grass and 1 twig, with a TECH.NONE unlock requirement, which means no technology is needed. Then, we set some extra configuration information through the config parameter table. Once added, you can find it in the "Mod Items" section of the crafting tab.

AddRecipe2 Parameter Explanation:

• name (string): The name of the recipe, usually the prefab name.
• ingredients (table): A table of ingredients required for the recipe.
• tech (string): The technology required to unlock the recipe.
• (Optional) config (table): An optional configuration table containing the optional fields of the Recipe2 class constructor.
• (Optional) filters (table): An optional list of filters containing the names of the filters to add the recipe to.

The config table keys are as follows:

• (Optional)placer (string): The placeable prefab used to display a temporary placement of a building that disappears once the building is placed.
• (Optional) min_spacing (num): The minimum spacing between buildings.
• (Optional)nounlock (bool): If false, the recipe can only be crafted near the corresponding technology building. Otherwise, it can be crafted anywhere after the initial unlock.
• (Optional)numtogive (num): The number of items the player receives upon successfully crafting the recipe.
• (Optional)builder_tag (string): The required builder tag. A character without this tag cannot craft the item and it can be used for character-specific items.
• (Required)atlas (string): The path of the atlas file where the item icon is located, used to display the image in the crafting tab. It can be left blank, but the icon will be empty.
• (Optional)image (string): The filename of the item icon, which is already included in the atlas and does not need to be filled in.
• (Optional)testfn (function): The placement test function, which can be used to check building requirements, such as terrain specifications.
• (Optional)product (string): The product of the recipe, which represents the item created upon a successful craft. Default
• (Optional)build_mode (string): The build mode, which must use the BUILDMODE constant table, such as BUILDMODE.LAND, with specific values being NONE, LAND, and WATER.
• (Optional)build_distance (num): The maximum distance between the player and the building when constructing it.

 

Recipe Filter

The recipe filter can be understood as a recipe classification, which makes it easy to quickly filter out what we need to make. We can use the official filter or create our own. A recipe can belong to multiple categories, making it easy to choose in different scenarios.

Creating a Custom Filter

Creating a custom filter requires the use of ModAPI AddRecipeFilter, the process is as follows.

First, define a filter (filter_def), which is a table that contains the following keys:

• name (string): The ID of the filter, which needs to be added to STRINGS.UI.CRAFTING_FILTERS[name].
• atlas (string or function): The atlas of the icon, which can be a string or a function.
• image (string or function): The icon displayed in the crafting menu, which can be a string or a function.
• (Optional) image_size (num): Custom image size, default is 64.
• (Optional) custom_pos (bool): Custom filter position, default is false. If true, the filter icon will not be added to the grid, but all items under this category will be placed under the mod item category.
• recipes (table): Do not use ! Please create the filter and pass it to the AddRecipe2() or AddRecipeToFilter() function.

Then, call AddRecipeFilter and pass in the filter:

AddRecipeFilter(filter_def, index)

Finally, when creating a recipe, use the AddRecipe2 or AddCharacterRecipe function to add the recipe to the corresponding filter, using the filters parameter, which is a list of filter names. The recipe will be added to these filters. For example: AddRecipe2(name, ingredients, tech, config, filters).

Here is an example of creating a custom filter:

-- Load Resources
Assets = {
    Asset("ATLAS", "images/craft_samansha_icon.xml"),
}

-- Define a new filter object
local filter_samansha_def = {
    name = "SAMANSHA",
    atlas = "images/craft_samansha_icon.xml",
    image = "craft_samansha_icon.tex"
}

-- Adding custom filters
AddRecipeFilter(filter_samansha_def, 1)
STRINGS.UI.CRAFTING_FILTERS.SAMANSHA =”Custom filters” -- Name displayed in the production column

-- Create a recipe and add it to a custom filter
AddRecipe2("my_custom_recipe", ingredients, tech, config, {"SAMANSHA"})

In this example, we created a filter named "SAMANSHA" and added it to the filter while creating the recipe. This way, when the player opens the crafting interface, they can see and use this custom filter to quickly find custom items.

Adding or Removing Recipes in a Filter

You can use AddRecipeToFilter and RemoveRecipeFromFilter to add or remove recipes in a filter. Here is a specific example:

-- Put the lotus_umbrella under the "Rain" category.
AddRecipeToFilter("lotus_umbrella","RAIN")

-- Remove the axe from the "Tools" category.
RemoveRecipeFromFilter("axe", "TOOLS")

The parameters is the same for both functions:

• recipe_name (string): The name of the recipe to add/remove.
• filter_name (string): The filter name to add/remove the recipe from.

Add character recipes

In the game, some characters (official or modded) may have unique abilities or items, which requires creating character-specific recipes. To achieve this functionality, we can use the AddCharacterRecipe function.

The AddCharacterRecipe function can be used to create character-specific recipes:

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

Here, name is the recipe name, ingredients are the required ingredients, tech is the technology requirement, config is the additional configuration information, and extra_filters (optional) is the list of filters to add to, which is similar to AddRecipe2. The character-specific aspect is reflected in the config parameter, where the builder_tag property is set to specify the character-specific tag. Only characters with this tag can make this recipe. For example, to create a specific recipe for the character "Wilson", set the builder_tag to "wilson".

If you need to add the character-specific recipe to a character-specific filter, you can create a character-specific filter first, and then add the recipe to this filter, as mentioned earlier.

Here is an example of creating a character-specific recipe and adding it to a custom filter. In this example, instead of using a custom mod character, we limit the tag to "reader", which corresponds to an official character with the ability to read, such as the librarian.

-- Create a character-specific recipe that can only be used by those who can read book.
local config2 = {
    atlas = "images/inventoryimages/lotus_umbrella.xml",
    builder_tag = "reader",
    product = "lotus_umbrella", -- When the recipe name is not the same as the prefab name, it needs to be explicitly specified.
}
AddCharacterRecipe("lotus_umbrella_few", {Ingredient("cutgrass", 1)}, TECH.NONE, config2, {"SAMANSHA"})

Modifications and Others

Adding a Deconstruction Recipe

In the game, sometimes we need to break down certain items to obtain raw materials, which requires the creation of a deconstruction recipe. This recipe will not appear in any filters and is mainly used for "Deconstruction Staves" or breaking down uncraftable items. To implement this functionality, we can use the AddDeconstructRecipe function to create a deconstruction recipe:

AddDeconstructRecipe(name, return_ingredients)

Here, name is the name of the prefab to which the recipe is added, and return_ingredients are the materials returned after deconstruction.

The following is an example of creating a deconstruction recipe, where an axe is deconstructed to obtain one flint

-- Deconstructing an axe to obtain one flint.
AddDeconstructRecipe("axe", {Ingredient("flint", 1)})

 

Adding a Custom Prototype Machine

Sometimes we need to customize the display of prototype machines (research or crafting stations) in the crafting menu. Prototype machines refer to devices such as Science Machines, Alchemy Engines, Ancient Pseudoscience Stations, and similar devices, such as the Shrine of the Year event. The character can stand next to the machine to craft corresponding items. To implement this functionality, we can use the AddPrototyperDef function to customize the display of the prototype machine

AddPrototyperDef(prototyper_prefab, prototyper_def)

Among them, prototyper_prefab is the name of the prefab used for the prototype machine, and prototyper_def is a table containing the following properties:

• icon_atlas (string): Icon document
• icon_image (string): Icon image
• action_str (string): The string displayed on the "build" button, such as "Offering" displayed on the shrine
• is_crafting_station (bool): Whether it is a crafting station, that is, whether it can only make corresponding items when it is near a stop
• filter_text (string): Name on the filter

Here is an example of creating a custom prototype machine definition

local prototyper_prefab = "moon_altar"
prototyper_def = {
    icon_atlas = "images/xxxx.xml",
    icon_image = "moon_altar.tex",
    is_crafting_station = true,
    action_str = "Produce",
    filter_text = "Moon Products"
},

AddPrototyperDef(prototyper_prefab, prototyper_def)

Modify Recipe

Sometimes we need to modify the existing recipe in the game. To achieve this, we can use AddRecipePostInit

AddRecipePostInit(recipe, fn)

Here, recipe is the name of the recipe to be modified, and fn is a modification function that takes the recipe object as its parameter.

The following is an example of modifying a specific recipe

local function fn(recipe)-- Modify the crafting tab description
    recipe.description = "Suitable for chopping trees"
end
AddRecipePostInit("axe", fn)

Modify Any Recipe

If we need to modify all recipes, we can use AddRecipePostInitAny

AddRecipePostInitAny(fn)

Here, fn is a modification function that takes the recipe object as its parameter. This modification will affect all recipes.

The following is an example of modifying any recipe

local function fn(recipe)-- Modify the crafting tab description uniformly
    local old_str = recipe.description
    recipe.description = "Description: " .. old_str
end

AddRecipePostInitAny(fn)

Summary

In this tutorial, we explored the new features added to the Don't Starve Together crafting tab and how to use the new ModAPI to perform corresponding operations. We reviewed the following contents:

1. Adding regular recipes: Use the AddRecipe2 function to create a new recipe and set relevant parameters.
2. Creating custom filters: Use the AddRecipeFilter function to create custom filters and set filter parameters.
3. Managing filters: Use the AddRecipeToFilter and RemoveRecipeFromFilter functions to add and remove recipes from filters.
4. Adding character-specific recipes: Use the AddCharacterRecipe function to create character-specific recipes and add them to custom filters.
5. Modifications and other content: Including decomposing recipes, custom prototypes, and modifying recipes.

Through these functions and operations, we can customize the crafting tab of Don't Starve Together more flexibly and achieve a richer gaming experience. I hope this tutorial can provide practical help to your Mod development work and help you master the relevant operations of the new crafting tab faster.

 

Official Filter Complete List

From the CRAFTING_FILTER_DEFS constant in recipe_filter.lua

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

Quick Reference Related APIs

To keep this page concise, a list of the mods is not provided here. Please visit Don't Starve Mod Development Quick Reference-modutil for the list. Currently, only the Chinese version is available, and an English version will be added after Q3 2023. For now, please use Google Translate to view the page. If you are interested in collaborating, you can contact me through email, which is listed on my GitHub page.

Reference

• [Documentation] New Recipe System Functions & Other Info

Edited April 19, 2023 by LongFeiaot