config.yml

Configuration

This page explains the config.yml file of BetterHorses.

The config controls horse stats, breeding mutations, mount types, horse items, traits, training, trample, cooldowns, and gameplay features.

Stats Display

stats:
  display-mode: RAW

Controls how horse stats are displayed in horse item lore.

Value	Description
`RAW`	Shows internal Minecraft values for speed and jump strength.
`BLOCKS`	Converts speed to blocks per second and jump strength to jump height in blocks.

Command Aliases

command-aliases:
  - bh
  - horses

Adds custom aliases for /horse.

Debug Mode

debug:
  enabled: false

When enabled, BetterHorses writes detailed debug logs to console and enables /horse info.

Mutation Factor

mutation-factor:
  health: 3.0
  speed: 0.05
  jump: 0.05

Controls how much a child mount can mutate when bred.

Example: health: 3.0 means the child can have up to ±3 HP compared to the average health of both parents.

Each supported mount type can also have separate mutation settings:

mutation-factor:
  skeleton-horses:
    health: 3.0
    speed: 0.05
    jump: 0.05
  zombie-horses:
    health: 3.0
    speed: 0.05
    jump: 0.05
  camels:
    health: 3.0
    speed: 0.05
    jump: 0.05
  mules:
    health: 3.0
    speed: 0.05
    jump: 0.05
  donkeys:
    health: 3.0
    speed: 0.05
    jump: 0.05

Max Stats

max-stats:
  health: 300.0
  speed: 0.4
  jump: 1.2

Defines the highest stats mounts can reach.

Each supported mount type can have separate limits.

Horse Item Configuration

Horse items are the items players receive when despawning a mount. They store the mount’s stats, gender, trait, training progress, texture data, and other BetterHorses data.

Horse Item Material

settings:
  horse-item: SADDLE

Controls which Minecraft item is used as the base item for stored horses.

Example:

settings:
  horse-item: LEATHER_HORSE_ARMOR

Use any valid Bukkit material name.

Horse Item Texture / Model Settings

settings:
  texture:
    override-texture-data: false
    custom-model-data: 0
    item-model: ""
    cit-string: ""
    model-string: ""

This section controls custom resource pack integration for horse items.

Option	Description
`custom-model-data`	Applies CustomModelData to the horse item.
`item-model`	Applies a modern item model reference where supported.
`cit-string`	Stores a CIT-compatible texture string.
`model-string`	Stores a custom model string.

CustomModelData

custom-model-data: 1001

Useful for resource packs that use CustomModelData.

If set to 0, no CustomModelData is applied.

Item Model

item-model: "betterhorses:warhorse"

Used for modern item model systems.

Leave empty to disable it:

item-model: ""

CIT String

cit-string: "warhorse"

Can be used by external CIT/resource pack systems.

Leave empty to disable it:

cit-string: ""

Model String

model-string: "betterhorses/warhorse"

Stores a custom model identifier on the horse item.

Leave empty to disable it.

Override Texture Data

override-texture-data: false

Controls whether config-defined texture data should override texture data stored on horse items or provided through the API.

Value	Behavior
`false`	Config acts as a default. API/item texture data can override it.
`true`	Config texture values always override stored/API texture data.

Use true if you want all horse items to always use the same configured appearance.

Horse Item Lore Layout

settings:
  horse-item-lore-layout:
    - stats:
        - gender
        - health
        - speed
        - jump
        - growth
        - blank
    - training:
        - riding
        - brushing
        - feeding
        - blank
    - trait
    - neutered

Controls which lore lines are shown on horse items and in what order.

Entry	Description
`gender`	Shows the mount gender.
`health`	Shows health.
`speed`	Shows speed.
`jump`	Shows jump strength.
`growth`	Shows growth progress.
`training`	Parent section for training lines.
`riding`	Shows riding training.
`brushing`	Shows brushing training.
`feeding`	Shows feeding training.
`trait`	Shows the mount trait.
`neutered`	Shows whether the mount is castrated.
`blank`	Adds an empty lore line.

Custom Literal Lore Lines

You can add custom lore lines using:

- literal:&7Your custom text

Example:

horse-item-lore-layout:
  - literal:&8Special Mount
  - stats:
      - gender
      - health
      - speed
      - jump
  - blank
  - trait

Nested Lore Sections

Nested sections make sure child lines only appear if the parent section resolves to a visible line.

Example:

- training:
    - riding
    - brushing
    - feeding

Mount Types

settings:
  mount-types:
    skeleton-horses: true
    zombie-horses: true
    camels: false
    mules: true
    donkeys: true

Controls which mount types BetterHorses should manage.

Option	Description
`skeleton-horses`	Enables skeleton horse support.
`zombie-horses`	Enables zombie horse support.
`camels`	Enables camel support.
`mules`	Enables mule support.
`donkeys`	Enables donkey support.

Normal horses are always supported.

Chested Mount Despawn

allow-chested-mount-despawn: false

Controls whether chest-capable mounts like donkeys and mules can be despawned while carrying a chest.

When enabled, the chest and its contents are stored in the horse item and restored when spawned again.

This feature is disabled by default to prevent this from being abused as an advanced storage method.

Breeding Settings

allow-same-gender-breeding: false
breeding-cooldown: 300
male-ignore-cooldown: true

Option	Description
`allow-same-gender-breeding`	Allows two mounts of the same gender to breed.
`breeding-cooldown`	Time in seconds before a mount can breed again.
`male-ignore-cooldown`	If true, male mounts ignore the breeding cooldown.

Set cooldown to 0 to disable breeding cooldowns.

Mount Ownership

restrict-mounting-to-owner: false

If enabled, only the owner of a tamed mount can ride it.

Skeleton Horse Mounting

mountable-skeleton-horses: true

Makes skeleton horses mountable like vanilla horses, including skeleton horses spawned from spawn eggs.

Artifica

Right-Click Spawning

allow-rightclick-spawn: true

Allows players to spawn stored horse items by right-clicking them.

Rider Invulnerability

rider-invulnerable: false

If enabled, players riding a mount cannot be damaged.

Step Height Fix

fix-step-height: true

Fixes a vanilla issue where mounted horses cannot smoothly climb from path blocks onto full blocks.

Only applies to mounted horses.

Mounted Damage Boost

mounted-damage-boost:
  enabled: false
  percentage: 25.0

Increases melee damage while riding a mount.

Example: 25.0 means the rider deals 25% more melee damage while mounted.

Sand Slowness

sand-slowness:
  enabled: false

Applies Slowness II to mounted horses while walking on sand.

This affects all supported mount types except camels.

Trait Particle Indicator

trait-particle-indicator: true

Shows particles around traited horses.

Disabling this can slightly improve performance.

Cooldown Display

cooldown-display:
  enabled: true
  show-bossbar-indicator: false
  show-hotbar-indicator: true

Controls how trait cooldowns are displayed.

Option	Description
`enabled`	Enables or disables cooldown display completely.
`show-bossbar-indicator`	Shows cooldown as a bossbar.
`show-hotbar-indicator`	Shows cooldown above the hotbar.

Horse Growth Settings

horse-growth-settings:
  enabled: true
  time-until-adult: 3
  max-size: 1.3

Controls custom horse growth.

This feature only works on Paper 1.20.6+ with Java 21+.

Option	Description
`enabled`	Enables custom growth scaling.
`time-until-adult`	Time in minutes until a mount is fully grown.
`max-size`	Final scale of an adult mount.

Example:

max-size: 1.3

Adult mounts are 30% larger than vanilla size.

Trample

trample:
  enabled: false

Trample allows ridden mounts to damage and knock back entities they run through.

An event check allows for protection plugins like WorldGuard to prevent trampling in certain areas.

Trample Mount Types

trample:
  mount-types:
    horse: true
    skeleton-horses: true
    zombie-horses: true
    camels: false
    mules: false
    donkeys: false

Controls which mount types can use trample.

Trample Settings

damage: 4.0
knockback: 1.5
radius: 1.2
cooldown-ticks: 20
affect-players: true
affect-mobs: true
hit-angle-degrees: 90.0
min-speed: 0.15

Option	Description
`damage`	Damage dealt to trampled entities.
`knockback`	Knockback strength.
`radius`	Detection radius around the mount.
`cooldown-ticks`	Cooldown per target.
`affect-players`	Whether players can be trampled.
`affect-mobs`	Whether mobs can be trampled.
`hit-angle-degrees`	Forward cone angle for detecting targets.
`min-speed`	Minimum movement speed required.

Set min-speed to 0 to disable the speed requirement.

Traits

traits:
  enabled: true

Master toggle for the trait system.

If this is set to false, all traits are disabled.

Common Trait Options

Most traits use these options:

Option	Description
`enabled`	Enables or disables the trait.
`chance`	Chance to receive the trait through breeding.
`particle`	Particle shown for the trait.
`duration`	Duration of the trait effect.
`cooldown`	Cooldown before the trait can be used again.
`radius`	Radius of the trait effect.
`strength`	Strength of the effect.

Trait Chance

Example:

chance: 0.005

Means 0.5%.

Value	Chance
`0.01`	`1%`
`0.005`	`0.5%`
`0.001`	`0.1%`

Available Traits

Trait	Description
`hellmare`	Leaves a trail of fire when activated.
`fireheart`	Is immune to fire.
`dashboost`	Becomes significantly faster when activated.
`featherhooves`	Has permanent slowfalling effect.
`frosthooves`	Turns nearby water into ice.
`kickback`	Knocks nearby enemies away when activated.
`ghosthorse`	Becomes invisible when pressed.
`skyburst`	Knocks nearby enemies in the air when jumping.
`revenantcurse`	Paralyzes attackers when activated.
`undead`	Transforms into a skeleton horse on death.
`heavenhooves`	Can fly like flappy bird.

Undead Trait

undead:
  enabled: true
  chance: 0.01
  particle: SOUL
  transform-back-item: ENCHANTED_GOLDEN_APPLE
  transform-back-animation: true

The Undead trait allows a mount to transform into a skeleton horse on death.

The transformed skeleton horse can be changed back using the configured item.

Training

training:
  enabled: true

Master toggle for the horse training system.

Training allows mounts to improve over time through riding, brushing, and feeding.

Training Lore

training:
  lore:
    enabled: true

Controls whether training progress is shown on horse item lore.

Training Progress Bar

progress-bar:
  length: 15
  hide-on-complete: true
  combine-all-complete: true

Option	Description
`length`	Length of the progress bar.
`hide-on-complete`	Replaces completed bars with “Complete”.
`combine-all-complete`	Combines all finished categories into one complete message.

Riding Training

riding:
  enabled: true
  units-per-percent: 100.0
  bonus-percent-per-progress-percent: 0.2

Riding training increases speed.

Option	Description
`units-per-percent`	Blocks ridden required for 1% progress.
`bonus-percent-per-progress-percent`	Speed bonus gained per 1% progress.

Brushing Training

brushing:
  enabled: true
  item: BRUSH
  cooldown-seconds: 180
  units-per-use: 2.0
  units-per-percent: 1.0
  bonus-percent-per-progress-percent: 0.2

Brushing training increases jump strength.

Option	Description
`item`	Item used for brushing.
`cooldown-seconds`	Cooldown between brushing uses.
`units-per-use`	Training units gained per brush use.
`units-per-percent`	Units required for 1% progress.
`bonus-percent-per-progress-percent`	Jump bonus gained per 1% progress.

Feeding Training

feeding:
  enabled: true
  cooldown-seconds: 180
  units-per-percent: 2.0
  bonus-percent-per-progress-percent: 0.2

Feeding training increases max health.

Food Values

food-values:
  WHEAT: 1.0
  APPLE: 1.0
  CARROT: 1.0
  SUGAR: 1.0
  HAY_BLOCK: 2.0
  GOLDEN_CARROT: 3.0
  GOLDEN_APPLE: 5.0
  ENCHANTED_GOLDEN_APPLE: 8.0

Controls how much training value each food item gives.

Recommended Defaults

For a mostly vanilla-friendly setup:

stats:
  display-mode: BLOCKS

settings:
  restrict-mounting-to-owner: true
  allow-rightclick-spawn: true
  rider-invulnerable: false
  breeding-cooldown: 300

trample:
  enabled: false

training:
  enabled: true

Notes

Always use valid Bukkit material names.
Invalid particle names may cause errors.
Keep backups before changing large config sections.
Restart the server or reload BetterHorses after editing the config.

Home
How it works - Comprehensive guide for server admins & players.
FAQ - Frequently asked questions.
Video Showcase - Watch and learn.
Better Horses API - Guide for plugin developers.
Discord - Get involved with other players using the plugin, seek help or report bugs to the dev.

config.yml

Configuration

Stats Display

Command Aliases

Debug Mode

Mutation Factor

Max Stats

Horse Item Configuration

Horse Item Material

Horse Item Texture / Model Settings

CustomModelData

Item Model

CIT String

Model String

Override Texture Data

Horse Item Lore Layout

Custom Literal Lore Lines

Nested Lore Sections

Mount Types

Chested Mount Despawn

Breeding Settings

Mount Ownership

Skeleton Horse Mounting

Right-Click Spawning

Rider Invulnerability

Step Height Fix

Mounted Damage Boost

Sand Slowness

Trait Particle Indicator

Cooldown Display

Horse Growth Settings

Trample

Trample Mount Types

Trample Settings

Traits

Common Trait Options

Trait Chance

Available Traits

Undead Trait

Training

Training Lore

Training Progress Bar

Riding Training

Brushing Training

Feeding Training

Food Values

Recommended Defaults

Notes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Setup

Features

Commands

Developer API

Clone this wiki locally