Blueprint YAML Reference

ConditionalEquipment fields

Slot resolution

Each slot is resolved to the first entry (in declaration order) whose requirements pass. Unmatched slots are cleared (any existing item removed). This means multiple entries may target the same slot — whichever matches first wins.

All equipped items are forced unbreakable via ItemMeta.setUnbreakable(true), regardless of whether they were defined that way.

Static vs Dynamic Gear

Static entries (no requirements block) are applied once at spawn and never re-evaluated.

Requirement-gated entries (with requirements) are re-evaluated every requirement-update-interval ticks (configurable, default 1 = every tick). A blueprint flagged as dynamic (i.e. has at least one requirement-gated equipment or effect entry) will be touched by the per-tick MobService.tickGear() loop; static-only blueprints are skipped entirely, saving CPU.

Requirements are evaluated against the first online player as the executor, with the %mob_*% placeholder namespace registered for self-state (health, target, etc.). See Mob Actions for placeholder details.

ConditionalEffect fields

Effect resolution

Multiple entries may target the same PotionEffectType: the first entry (in declaration order) whose requirements pass is applied, and the effect is removed if no entry passes. When an effect is already active, it is only re-applied if the amplifier changes (to avoid resetting an infinite effect every tick).

Fields

Spawn behavior

When a mob with passenger set is spawned:

1. The vehicle mob is created and spawned first.

2. The passenger blueprint is looked up by id and spawned at the same location.

3. The passenger is set to ride the vehicle via Entity.startRiding().

4. If passenger-controls-vehicle is true, the passenger's movement goals drive both mobs.

5. Movement control is wrapped in PassengerFollowMoveControl, which gives the passenger steering priority.

The passenger field is a blueprint id, so the same mob can be a passenger, a vehicle, or have its own passenger — you can chain multiple mobs. Cycles are prevented by tracking visited blueprint ids during initialization; a blueprint that references itself (directly or indirectly) will fail to initialize.

Damage & death interaction

redirect-damage: All damage dealt to the vehicle is cancelled and re-applied to the passenger, preserving the original attacker so kill credit and threat remain correct. A vehicle with redirect-damage: true functions as a "meat shield" that passes all harm to its rider.

remove-passenger-on-death: When the vehicle dies, its passengers (if they are tracked custom mobs) have their invulnerability cleared and are force-killed.

kill-vehicle-on-passenger-death: When the passenger dies, the vehicle is also force-killed. A vehicle with kill-vehicle-on-passenger-death: true cannot survive its rider's death.

Mob creation

MobService.summon(blueprint, location):

1. Builds the NMS entity directly: new NMSMob(blueprint.type(), level), then sets its position.

2. Clears the entity's vanilla drops list (if metadata.prevent-other-drops is set) and zeroes expToDrop (if metadata.prevent-experience-drops is set) — before spawning.

3. Sets entity.persist = false — custom mobs are non-persistent and never saved to chunk data or survive a server restart.

4. Runs blueprint.apply(entity) — applies, in order: display name, health, metadata, attributes, move control. (Equipment and effects are not part of apply(); see step 6.)

5. Spawns via level.addFreshEntity(entity, CreatureSpawnEvent.SpawnReason.CUSTOM), then injects the per-instance goal-selector and target-selector copies, and registers the mob in an in-memory UUID map.

6. Applies requirement-gated equipment and effects (blueprint.applyGear(entity)), renders the initial health display, then fires spawn-actions.

7. If the blueprint declares a passenger, spawns and mounts it (see Passenger & Vehicle System).

Damage event handling

MobListener#onDamage:

• Mob-vs-mob projectiles are cancelled: If a projectile is shot by one tracked mob at another, the damage is suppressed. This prevents mobs from harming each other unintentionally.

• Self-damage is cancelled: If a mob damages itself (e.g., its own AoE ability), the damage is suppressed.

MobListener#onEffectAdd:

• WITHER effect on players is cancelled: Players hit by a WITHER effect from an AstralMobs entity have the effect removed. This prevents Wither mobs from inflicting server-killing decay on players.

Death event handling

MobListener#onEntityDeath:

1. Fires death-actions (executor = killer or first online player).

2. Clears EntityDeathEvent#getDrops() if metadata.prevent-other-drops is set (this is the actual drop suppression on the ground).

3. Zeroes setDroppedExp(0) if metadata.prevent-experience-drops is set.

4. Handles passenger cleanup:

   • If this mob is a passenger of a vehicle, removes the passenger reference.

   • If the vehicle has kill-vehicle-on-passenger-death: true, force-kills the vehicle.

5. If remove-passenger-on-death: true, force-kills any tracked-mob passengers.

6. Unregisters the mob from the UUID map and SpoofRegistry.

Health display

Health is not shown as a vanilla name tag. Instead, AstralEntity.updateHealthDisplay() builds a 17-segment health bar from Minecraft font glyphs and sets it as the mob's always-visible custom name. It renders:

• Once on spawn.

• On every EntityDamageEvent for that mob.

• On a configurable schedule (controlled by forceUpdateInterval in config).