MinecraftForge Documentation

Loot tables are constructed using a hierarchical builder pattern. The hierarchy is as follows:

• LootTable: The root object. Use LootTable#lootTable to get a builder. You add pools via #withPool and apply modifiers via #apply.
• LootPool: A group of operations. Use LootPool#lootPool to get a builder. Pools use #add for entries, #when for conditions, and #apply for functions. Execution frequency is controlled via #setRolls and #setBonusRolls (which factors in luck).
• LootPoolEntryContainer: Defines the actual operations (like generating an item). Use LootPoolEntryContainer$Builder. Entries can be executed simultaneously via #append, sequentially via #then, or as a fallback via #otherwise.
• LootItemCondition: Requirements for an operation to execute. Use LootItemCondition$Builder. Conditions can be combined with #or or inverted with #invert.
• LootItemFunction: Modifies the result of an execution. Use LootItemFunction$Builder.
• NumberProvider: Determines how many times a pool executes. Use LootNumberProviderType implementations. A special type is ScoreboardValue (a ScoreboardNameProvider) which pulls the roll count from a scoreboard name.

The Block State system replaces the legacy metadata system. Instead of using a single integer (metadata) to represent various block configurations, blocks now use a set of named properties.

A BlockState is a unique, immutable combination of a Block and a map of Property<?> objects to their specific values.

Key Concepts:

• Properties: Each property (e.g., DirectionProperty, BooleanProperty) describes a specific aspect of the block.
• Immutability: BlockState objects are immutable. Modifying a state via setValue returns a new state.
• Startup Generation: All possible combinations of a block's properties are generated at game startup. This means you can use reference equality (==) to compare two BlockState objects.

Best Practices:

• Avoid Overuse: Do not put every variation into a BlockState. Excessive properties increase startup time and complexity.
• Rule of Thumb: If a variation has a different name, it should be a separate Block. For example, use properties for the direction of a chair, but use different blocks for different wood types (e.g., oak_chair vs spruce_chair).
• Complex Data: If a block needs to store complex data that doesn't fit into simple properties, use a BlockEntity instead.

Every custom recipe definition in Forge consists of three core components that work together:

1. Recipe: The implementation that holds the recipe data and contains the execution logic (e.g., matching inputs and providing results). It typically implements Recipe<Container> for item-based transformations.
2. RecipeType: Defines the category or context of the recipe (e.g., RecipeType#SMELTING or RecipeType#BLASTING). If your context is unique, you must register a new RecipeType.
3. RecipeSerializer: Handles the decoding of JSON data and manages network communication between the server and client. A serializer must be registered.

To integrate these, your Recipe implementation must return the correct RecipeType via #getType() and the correct RecipeSerializer via #getSerializer().

public record ExampleRecipe(Ingredient input, int data, ItemStack output) implements Recipe<Container> {
  @Override
  public RecipeType<?> getType() {
    return EXAMPLE_TYPE.get();
  }

  @Override
  public RecipeSerializer<?> getSerializer() {
    return EXAMPLE_SERIALIZER.get();
  }
}

Once your top-level package is established, organize your classes into sub-packages using one of two primary methods:

1. Group By Function: Group classes by their technical purpose.
   • Examples: com.example.mymod.block, com.example.mymod.entity, com.example.mymod.item.
2. Group By Logic: Group classes by the feature they belong to.
   • Example: If creating a crafting table feature, put its block, menu, and item under com.example.mymod.feature.crafting_table.

Side Isolation (Client vs. Server)

It is highly recommended to isolate code based on the runtime/side to prevent crashes on dedicated servers:

• client package: Use this for all client-only code. Since dedicated servers do not have access to client-only Minecraft classes, keeping this isolated helps ensure you do not accidentally reference client code on a server.
• server package: Use this for code that only runs on the dedicated server.
• data package: Use this for code related to data generation.

TranslatableContents is a ComponentContents implementation that performs localization and formatting lazily.

This is the recommended way to send messages from a server to players. Because the localization happens lazily, the text is translated using the client's locale settings rather than the server's locale (which is always en_us on dedicated servers).

• Constructor: TranslatableContents(String, Object...) where the first argument is the translation key.
• Formatting: Supports %s, %1$s, %2$s, etc. Formatting arguments can be Component objects, which will preserve their attributes when inserted.
• Creation:
  • Use Component#translatable(String, Object...) to create a MutableComponent directly.
  • Use MutableComponent#create(ComponentContents) to create a component from an existing TranslatableContents instance.

// Creating a translatable component for a player message
MutableComponent message = Component.translatable("chat.example.welcome", playerName);
// The server sends this key; the client localizes it to their language.