# Custom Blend Data Pack

Custom blends can be added via datapacks. Each custom blend is defined as a JSON file located at:
```
data/<namespace>/biomeblends/blend_type/<blend_name>.json
```

<Callout variant="info">
  If the blend is used to apply a specific biome, it is generally recommended to set the namespace and the name to match the biome name for consistency.
</Callout>

<Callout variant="warning">
  Changes to blend types will only be visible after restarting the world. The command `/reload` cannot reload the blend types.
</Callout>

## Blend Actions

The `action` field defines what happens when a blend is applied. Only one action may be defined per blend.

<Callout variant="info">
  Each blend **must** contain an `action` to be registered.
</Callout>

### Set Biome Action

Sets a specific biome in the blend area.

```json
{
  "action": {
    "type": "biomeblends:set_biome",
    "target_biome": "minecraft:plains"
  }
}
```

- `target_biome`: ID of the biome to apply.

### Set Namespace Action

Replaces the namespace of each biome in the blend area, attempting to find a matching biome in the new namespace. If there is no matching biome, it will be changed into the fallback biome (if specified).

While this action type doesn't normally have a use, it can be extremely useful for modpack creators. The blend created in the example below will attempt to change any biome, eg. `wasteland:forest` to `minecraft:forest`. Additionally, if there is no matching `minecraft` biome, it will be changed into `minecraft:plains`.

```json
{
  "action": {
    "type": "biomeblends:set_namespace",
    "target_namespace": "minecraft",
    "fallback_biome": "minecraft:plains"
  }
}
```

- `target_namespace`: New namespace to apply to biome IDs.
- `fallback_biome`: If specified, this biome will be created if there is no matching biome in the target namespace (optional).

## Radius

The `horizontal_radius` and `vertical_radius` control the region that is affected by the blend. The area is always centered on the block where the blend is used, but since Minecraft stores biomes in 4x4x4 cubes, it may not always be exact. `vertical_radius` can be set to `-1`, which will cause it to affect the entire vertical column.

By default the `horizontal_radius` and `vertical_radius` is set to 4.

## Conditions

Conditions can be used to stop your blends from interacting with certain mods, dimensions or biomes.

### Dimension Blacklist

Prevents this blend from being applied in specified dimensions. If `negate` is set to true, it will act as a whitelist.

```json
  "dimension_blacklist": {
    "values": ["minecraft:the_nether", "custom:another_dimension"],
    "negate": false
  }
```

### Biome Blacklist

Prevents this blend from being applied inside specified biomes. If `negate` is set to true, it will act as a whitelist. Keep in mind that a blend will still be applied if there is any region that meets this condition.

```json
  "biome_blacklist": {
    "values": ["minecraft:desert", "minecraft:swamp"],
    "negate": false
  }
```

### Namespace Blacklist

Excludes blends from applying to biomes within certain namespaces. If `negate` is set to true, it will act as a whitelist. Keep in mind that a blend will still be applied if there is any region that meets this condition.

```json
  "namespace_blacklist": {
    "values": ["minecraft", "wasteland"],
    "negate": false
  }
```

A practical tool for keeping your blend from interfering with biomes from a specific mod or datapack.

## Blend Color

The `color` field is used to apply a color overlay to the blend's texture. If not set, there is no color applied.

Keep in mind that it only accepts colors in **decimal** format, which means you will need to convert a number from hexadecimal to decimal, eg. `#FF0000` to `16711680`.

## Use Remainder

`use_remainder` is an item that can be given to the player when the blend gets consumed.

```json
  "use_remainder": {
    "id": "minecraft:glass_bottle"
  }
```

## Sound

The default use sound can be changed using the `sound` option.

```json
  "sound": {
    "sound_id": "minecraft:block.anvil.land"
  }
```

## Particles

The default type of particles that is applied on use can be changed with `particle_type`.

```json
  "particle_type": {
    "type": "minecraft:block",
    "block_state": "minecraft:anvil"
  }
```

## Full Example

The following example creates a blend that sets the biome to bamboo jungle, uses anvil sounds and particles and spawns a glass bottle when used. It has a horizontal distance of 10 and an infinite vertical radius, meaning it will affect the entire column.
```json
{
  "action": {
    "type": "biomeblends:set_biome",
    "target_biome": "minecraft:bamboo_jungle"
  },
  "color": 11705,
  "use_remainder": {
    "id": "minecraft:glass_bottle"
  },
  "sound": {
    "sound_id": "minecraft:block.anvil.land"
  },
  "particle_type": {
    "type": "minecraft:block",
    "block_state": "minecraft:anvil"
  },
  "vertical_radius": -1,
  "horizontal_radius": 10
}
```