Recipe book categories and displays

Use Hooks::recipe_book_categories to supply categories and displays for your custom recipe types. Append RecipeBookCategory values to event.categories. Register the book identity with recipe_book_type during content registration and retain its RecipeBookTypeKey; declaring a category does not register a book, change its settings or unlock recipes.

From Sunrise's modding bookead8a1e

On this page

For Java-compatible saved flag names, use recipe_book_type_with_fields; see Recipe book types and saved flags.

This example assumes book is your registered key and the named menu, items and recipe exist:

rust
use mod_api::{RecipeBookCategory, RecipeBookDisplay, RecipeBookDisplayEntry, RecipeSlotDisplay};

event.categories.push(RecipeBookCategory {
    id: "mymod:crushing".into(),
    recipe_type: "mymod:crusher".into(),
    icon: "mymod:crusher".into(),
    secondary_icon: None,
    target_menu: "mymod:crusher".into(),
    book: book.clone(),
    search_group: "mymod:crusher_search".into(),
    displays: vec![RecipeBookDisplayEntry {
        recipe: "mymod:crushed_stone".into(),
        displays: vec![RecipeBookDisplay::Shapeless {
            ingredients: vec![RecipeSlotDisplay::Item("minecraft:stone".into())],
            result: RecipeSlotDisplay::Item("minecraft:gravel".into()),
            station: RecipeSlotDisplay::Item("mymod:crusher".into()),
        }],
        placement: None,
    }],
});

Declaration rules

FieldRequirement
idUnique namespaced category identifier outside minecraft:.
recipe_typeNamespaced identifier outside minecraft: present in the recipe table. Multiple categories can use one type.
iconRegistered item identifier other than minecraft:air.
secondary_iconNone for a one-icon tab, or a registered item identifier other than minecraft:air drawn beside icon, as vanilla's two-icon tabs do.
target_menuRegistered menu identifier.
bookRegistered RecipeBookTypeKey. All categories in one book name the same menu and search group.
search_groupNamespaced identifier outside minecraft: owned by exactly one book; it cannot also name a category. Search includes exactly that book's categories.
displaysRecipe entries belonging to this type. Each recipe identifier occurs only once across the declaration batch.

Build displays from your type's recipe JSON through Host::recipes_of_type. The hook runs lazily once per recipe table, not per frame. A client reads its own recipe table unless datapack_sync supplies the server's custom type.

host.recipe_book_category(recipe_type) returns a validated declaration or None for an undeclared or invalid type, before resources load, or outside a world. When a type has several categories, it returns the first in category-id order. Implement Hooks::recipe_book_categories to supply your declarations.

Display and placement rules

RecipeBookDisplay provides Shaped, Shapeless, Furnace, Stonecutter and Smithing layouts, and Custom { slots, result, station } for a recipe type whose pictures none of them fit, such as a cooking pot's inputs beside a container. A custom display's slot meaning belongs to the recipe type: the book lists its non-empty slots in order as the recipe's ingredients (all of them count in the craftable filter) and never draws station. The four built-in menu layouts map none of it, so a menu bound to one refuses a category that holds a custom display. Each recipe entry can supply several displays. RecipeSlotDisplay supports items, owned ItemStack values, tags, fuel, empty slots, alternatives through Composite, potion and component filters, dyeing, smithing trims and remainders.

  • Resource references must resolve, and owned stacks must pass stack validation.
  • A shaped display has positive width and height, each at most i32::MAX, and exactly width * height ingredient cells.
  • Furnace duration is at most i32::MAX; experience is finite and nonnegative.
  • Nested slot displays have a maximum depth of 32, with the outer slot at depth 0.
  • When your menu has a registered RecipeBookLayout, its book and recipe type must match the category. Displays must fit the layout.
  • For a recipe type bound to a menu placement layout, supply authoritative ingredient cells in RecipeBookDisplayEntry::placement using PlacementInfo. Display alternatives do not imply placement ingredients. The example's None does not declare a placement plan.

Validation failures

The game validates the complete declaration generation before publishing any category. Invalid identifiers, missing resources, duplicate categories or recipes, conflicting book ownership, invalid layouts and invalid placement refuse the entire generation rather than skipping an entry. The diagnostic begins recipe book declarations refused: and includes the typed error, such as InvalidId, UnknownResource, DuplicateCategory, DuplicateRecipe, ConflictingBook, InvalidLayout or InvalidPlacement.

Both successful and refused generations are cached until the recipe table changes. A recipe-table replacement, new session or server /reload rebuilds declarations. Categories are ordered by category identifier; a book's search group includes only its own categories, not categories from other books sharing a menu.

Placing a recipe yourself

A menu whose inputs are not a crafting grid, a furnace, a stonecutter or a smithing table (a cooking pot with six inputs, a preview slot and a container slot) registers RecipeBookLayout::Mod with menu_recipe_book. The game then maps no display to a slot and answers a recipe click through your MenuPart's recipe_book_place hook. Before the hook runs the game checks what vanilla checks: the player is not a spectator, the window is the open menu of this type, the menu is still valid, the player's book holds the recipe, and its PlacementInfo is not NOT_PLACEABLE. Every recipe of a Mod menu supplies a PlacementInfo; its ingredients are what place_recipe_in_grid moves.

rust
fn recipe_book_place(
    &self,
    host: &mut dyn mod_api::ServerHost,
    event: &mut mod_api::RecipeBookPlaceEvent<'_>,
) {
    // The first five slots take ingredients, as a 3 by 2 grid with a slot to spare.
    let grid: Vec<u16> = (0..5).collect();
    let clear: Vec<u16> = (0..6).collect();
    if let Ok(missing) =
        host.place_recipe_in_grid(event.recipe, 3, 2, grid, clear, event.use_max_items)
    {
        event.ghost = missing;
    }
}

place_recipe_in_grid is vanilla's ServerPlaceRecipe.placeRecipe: the grid's width and height, the menu slot of each cell, the slots to clear first (the grid's slots are cleared too) and whether to place the maximum. It returns whether items were missing: the grid is cleared and ghost asks the client for the recipe's ghosts. A refusal (outside the hook, another recipe, a slot the menu lacks or hides, a repeated slot, a recipe with more cells than slots, a slot whose pickup a part refuses, no room for the cleared items) changes nothing and says why. A recipe never reaches a cell past the last slot given. The whole answer is one action: a write the part makes to the player's inventory, cursor or the menu's storage through the Host, or a change to a block behind the menu, refuses it and undoes the placement. A menu with no part that listens refuses every click.

Drawing the ghosts yourself

When a click finds items missing, the server tells the client and the client draws the recipe's ghosts in the menu's slots. The recipe_book_ghost hook of your MenuPart is asked just before, where vanilla calls the book component's fillGhostRecipe:

rust
fn recipe_book_ghost(
    &self,
    host: &dyn mod_api::ClientHost,
    event: &mut mod_api::RecipeBookGhostEvent<'_>,
) {
    // A pot: the meal preview in slot 6 and the inputs in slots 0 and up.
    if let mod_api::RecipeBookDisplay::Custom { slots, result, .. } = event.display {
        event.ghosts.clear();
        event.ghosts.push(mod_api::GhostSlot { slot: 6, display: result.clone(), result: true });
        for (index, slot) in slots.iter().enumerate() {
            event.ghosts.push(mod_api::GhostSlot { slot: index as u16, display: slot.clone(), result: false });
        }
    }
}

display is the alternative the player clicked. ghosts arrives holding the game's own ghosts for the menu's layout (the crafting, furnace, stonecutter and smithing layouts map the display to their slots; a Mod layout arrives empty); add, change or clear them. A ghost whose display resolves to no stack, or that sits in a slot the menu's screen does not show, is dropped, and at most 256 are kept. The hook fires on the client only, once per answer, for the open menu's book, and only for a menu whose type has a part that listens.

Screen::recipe_book_big_result gives the result ghost vanilla's 24 by 24 frame (isBiggerResultSlot). It is off by default.

Edit this page on GitHub · Spotted something wrong? Open an issue or ask on Discord.