Companions

Companions provide persistent, collectible boosts to one configured mob-kill currency. The complete catalogue and presentation are controlled by content/companions.yml.

Enablement and bound item

enabled: true
hotbar-slot: 1
prevent-drop: true
prevent-storage: true
keep-on-death: true
storage-item-material: TURTLE_EGG
storage-capacity: 300
equipped-slots: 3
maximum-equipped-slots: 6

The hotbar slot is zero-based. Players use the bound storage item to open storage and manage equipped companions. Transferable unlock scrolls can open additional slots up to the configured maximum:

/dga give <player> companion-scroll [amount]

Companion Blocks

Each zone can have one protected Companion Block inside its arena. Place it with the setup tool or:

/dga setup <zone> companionblock
/dga setup <zone> clearcompanionblock

The block-material, hologram, and particle sections control the physical block and its presentation. Hologram lines support zone, price, currency, reward-currency, and block-material placeholders documented directly in the YAML.

Price and boost scaling

egg price = base price
          × zone-price-multiplier ^ (zone order - 1)
          × stage-price-multiplier ^ (stage number - 1)

reward boost = base reward boost
             × zone-boost-multiplier ^ (zone order - 1)
             × stage-boost-multiplier ^ (stage number - 1)

price.currency pays for eggs. reward-boost.currency selects the one mob-kill wallet affected by equipped companions. Those currencies may be different.

Companion boosts are additive on top of the neutral 1x. Three equipped companions worth +0.5x, +0.75x, and +1x produce 3.25x of the configured reward.

Rarities, qualities, and definitions

The rarities section controls display names, colors, and bulk-delete banner materials. The stable quality IDs are normal, shiny, rainbow, and void; admins can customize their names, colors, badges, and multipliers.

companions:
  chicken:
    display-name: Chicken Companion
    rarity: basic
    icon: PLAYER_HEAD
    head-texture: 'http://textures.minecraft.net/texture/...'
    weight: 55.0
    base-reward-boost: '0.5'

Weights are relative across the enabled catalogue. The persistent variant key includes companion ID, zone, stage, quality, and fusion level. Renaming a stable ID creates a different variant.

Progression and automation

progression configures upgrade currency, cost growth, rarity luck, quality chances, fusion limits and chance, fusion-level boost, and auto-open interval. Egg purchases are checked before charging, and automatic opening stops when payment or storage fails.

Players can set exact zone/stage auto-delete preferences. Rolled companions are still charged and resolved, then matching variants are deleted before entering storage.

Follower display and performance

display.enabled is false by default. Enabling it creates protected real Armor Stand and Text Display entities behind each player—up to two entities per equipped slot. Load-test peak player counts before enabling this presentation. Storage, equipment, and reward boosts work while display is disabled.

Use maximum-rebuilds-per-pass, movement intervals, and structural reconciliation intervals to control burst cost.

Menus

Companions use dedicated egg, storage, fusion, upgrade, single-delete, and bulk-delete menu files. Keep all required item IDs when redesigning those menus.