Attributes & Metadata

Attributes and metadata are the low-level tuning knobs for mob entity behavior and appearance. Attributes control numeric properties like walk speed, detection range, and hitbox size; metadata controls boolean flags like whether the mob makes sounds, displays a health bar, or drops loot.

Attributes

The attributes block maps Bukkit attribute names (in snake_case) to their base values. When a mob is spawned, each attribute is registered on the entity (if missing) and its base value is set.

attributes:
  follow_range: 100
  movement_speed: 0.25
  step_height: 1.5
  scale: 1.0
  knockback_resistance: 0.5
  explosion_knockback_resistance: 0.2

Attribute	Description	Common Range
`follow_range`	Detection range used when no target selector `range` is set; see Target Selector Fallback below.	`10`–`350`
`movement_speed`	Walk/run speed multiplier. Must be set in `attributes`, not `metadata` (see Critical Gotcha below).	`0.1`–`1.0`
`step_height`	How high the mob can step up blocks without jumping.	`0.5`–`3.0`
`scale`	Model and eye-height scale (used by flying move control for collision). Must be set in `attributes`, not `metadata`.	`0.5`–`2.0`
`knockback_resistance`	Resistance to knockback force from attacks.	`0.0`–`1.0`
`explosion_knockback_resistance`	Resistance to knockback from explosions.	`0.0`–`9999`
`flying_speed`	(Auto-set by flying move control) Speed while airborne when using `move-control: flying`.	`0.1`–`1.0`

Critical Gotcha

movement_speed and scale MUST be declared under attributes, not under metadata. The metadata keys movement-speed and scale are not recognized by the blueprint loader and will be silently ignored.

Incorrect:

metadata:
  movement-speed: 0.3    # IGNORED — this key does not exist in MobMetadata
  scale: 1.2             # IGNORED — this key does not exist in MobMetadata

Correct:

attributes:
  movement_speed: 0.3
  scale: 1.2

Several example blueprints in the network contain the incorrect metadata form for backwards compatibility reasons, but new blueprints should use attributes.

Target Selector Fallback

If a target selector's range is omitted or set to <= 0, it falls back to the follow_range attribute. This allows you to tune detection range globally without repeating it across every selector.

target-selectors:
  player:
    range: 100    # use this range explicitly
    interval: 10

  # OR (range <= 0 or omitted):
  player:
    must-see: false
    interval: 10
    # range omitted; will fall back to attributes.follow_range

Metadata

The metadata block controls behavioral flags via kebab-case keys. All fields are optional and default to the values shown below.

metadata:
  always-show-name: false
  prevent-other-drops: true
  prevent-mob-kill-drops: true
  prevent-experience-drops: true
  silent: false
  visible-by-default: true
  invisible: false
  collidable: true
  remove-physics: false
  no-gravity: false
  invulnerable: false
  baby: false
  boss: false
  hide-health-bar: false

Field	Type	Default	Description
`always-show-name`	boolean	`false`	When `true`, the mob's custom name is always visible (via `setCustomNameVisible`). When `false`, the name only shows when looking at the mob or aiming.
`silent`	boolean	`false`	When `true`, the mob plays no sounds (footsteps, ambient, attack, death, etc.). Useful for scripted mobs with custom sound actions.
`visible-by-default`	boolean	`true`	Internal flag used during rendering setup; usually left `true`.
`invisible`	boolean	`false`	When `true`, the mob is rendered invisible to players (no geometry, but collision/AI still work).
`collidable`	boolean	`true`	When `true`, the mob has collision and blocks movement. When `false`, entities and players pass through it.
`remove-physics`	boolean	`false`	When `true`, the mob has no block collision (phasing through terrain). Often paired with flying move control or `no-gravity`.
`no-gravity`	boolean	`false`	When `true`, the mob is not affected by gravity and does not fall. Do not use with walking move control — use `flying` move control instead.
`invulnerable`	boolean	`false`	When `true`, the mob cannot take damage (no amount or damage type will hurt it).
`baby`	boolean	`false`	When `true` (on mobs that support it), the entity is rendered as a baby variant (smaller, higher-pitched sounds).
`boss`	boolean	`false`	When `true`, a boss bar health display is created. When `false` but health is displayed, an overhead text label is used instead.
`hide-health-bar`	boolean	`false`	When `true`, no health display (boss bar or text) is created or updated for the mob, hiding its health entirely.
`prevent-other-drops`	boolean	`true`	When `true`, vanilla loot drops are cleared when the mob spawns and when it dies. Does not affect custom drops from actions.
`prevent-mob-kill-drops`	boolean	`true`	Deserialized by `MobMetadata` and defaults to `true`, but is not currently read anywhere in the plugin — setting it has no observable effect. Reserved/unimplemented; use `prevent-other-drops` for actual drop suppression.
`prevent-experience-drops`	boolean	`true`	When `true`, the mob drops no experience when killed. When `false`, normal experience is awarded.

Drop Control

The three prevent-* flags work together to control what happens when the mob dies:

prevent-other-drops: Clears all vanilla loot drops (armor, weapons, equipment, mob-specific items). Runs on both spawn and death.
prevent-experience-drops: Sets the death event's experience drop to 0, awarding no XP.
prevent-mob-kill-drops: Present in MobMetadata and defaults true, but currently has no wired behavior — it is not read by MobListener or anywhere else in the plugin.

Most boss mobs set prevent-other-drops and prevent-experience-drops to true to prevent unintended loot cascades.

Note: `prevent-sunburn`

Some example blueprints contain a prevent-sunburn metadata field in comments. This field is not recognized by AstralMobs and has no effect. It appears to be legacy documentation. Do not use it; rely instead on skeletons and other sun-sensitive mobs working correctly without it (the Pig-based spoofing handles sun-damage immunity naturally for most types).

Examples

Normal Mob: Skeleton

id: skeleton
type: SKELETON
health: 150.0

attributes:
  follow_range: 100
  movement_speed: 0.25
  step_height: 1.5

metadata:
  always-show-name: false
  prevent-other-drops: true
  prevent-mob-kill-drops: true
  prevent-experience-drops: true
  silent: true
  visible-by-default: true
  invisible: false
  collidable: true
  invulnerable: false

Boss Mob: Warden

id: warden
type: WARDEN
health: 5000.0

attributes:
  follow_range: 300
  movement_speed: 0.4
  step_height: 3.0

metadata:
  boss: true
  prevent-other-drops: true
  prevent-mob-kill-drops: true
  prevent-experience-drops: true
  silent: true
  visible-by-default: true
  invisible: false
  collidable: true
  invulnerable: false

The Warden example sets boss: true, which creates a boss bar health display instead of overhead text. The silent: true suppresses the default warden sounds in favor of custom sound actions.

Last modified: 25 July 2026