Description

Composite Materials allow you to build a material by stacking multiple composites, each of which modifies the base material in some way. This enables dynamic, data-driven creation of new materials that combine visual, statistical, and functional traits.

How It Works

A CompositeMaterial consists of: Base Material (starts as DefaultMaterial)

List of Composite Modifiers

• These can change:
• Color & palette
• Name & UI grouping
• Stats (add, multiply, set)
• Ingredient behavior
• Material properties And more

Composites are applied in order, transforming the base material step-by-step into the final result.

{
  "composites": [
    {
      "type": "miapi:material_color",
      "color": "#FF00FF"
    },
    {
      "type": "miapi:material_name",
      "name": "My Fancy Material"
    }
  ]
}

When using Composite Materials, it is technically possible to write every composite directly onto an ItemStack. While this is useful for testing or quick comparisons, it is not recommended for regular gameplay or for large-scale datapack usage, because the full composite data is stored directly on each item and increases NBT size.

For production use, we strongly recommend the Datapack Composite system (miapi:data_composite).
A Datapack Composite allows you to define a complete composite setup inside a datapack and reference it by ID in-game. This significantly reduces the amount of data written to each ItemStack and keeps your content clean and modular.

A Datapack Composite must be placed under: mod-id:miapi/data_composites

Each entry there defines a composite “template” consisting of any number of composite modifiers.

You can study a real example here:
Modular Material Datapack

To use a Datapack Composite in an item, reference it via the composite type: miapi:data_composite

This also enables dynamic material inheritance:
The data Composite has a field for a material, if this is set its in-datapack defined composites to the same materials if they don't specify one.
The Modular Material Datapack makes strong use of this feature.