steel_core/entity/living_base/

mod.rs

//! Shared fields for all living entities.
//!
//! Mirrors the runtime fields that vanilla defines on `LivingEntity` (and
//! `Entity` for `invulnerableTime`). Entities that implement `LivingEntity`
//! embed this struct and expose it via `LivingEntity::living_base()`, just like
//! `EntityBase` is used for core `Entity` fields.

use std::{array, mem, sync::Arc};

use glam::DVec3;
use rustc_hash::FxHashMap;
use simdnbt::owned::{NbtCompound, NbtTag};
use steel_protocol::packets::game::{CRemoveMobEffect, CUpdateMobEffect, MobEffectPacketFlags};
use steel_registry::RegistryEntry;
use steel_registry::attribute::AttributeRef;
use steel_registry::data_components::vanilla_components::SwingAnimation;
use steel_registry::entity_data::ParticleList;
use steel_registry::entity_type::EntityTypeRef;
use steel_registry::item_stack::ItemStack;
use steel_registry::items::ItemRef;
use steel_registry::mob_effect::MobEffectRef;
use steel_registry::mob_effect_instance::INFINITE_EFFECT_DURATION;
use steel_registry::vanilla_attributes;
use steel_registry::vanilla_entity_data::VanillaLivingEntityData;
use steel_registry::vanilla_mob_effects;
use steel_utils::locks::{IntoShared, Shared, SyncMutex};
use steel_utils::types::InteractionHand;
use steel_utils::{BlockPos, Identifier};
use uuid::Uuid;

use crate::behavior::MOB_EFFECT_BEHAVIORS;
use crate::entity::attribute::{AttributeMap, AttributeModifier, AttributeModifierOperation};
use crate::entity::synced_data::EntitySyncedData;
use crate::entity::{LivingEntity, SharedEntity, WeakEntity};
use crate::inventory::equipment::{EntityEquipment, EquipmentSlot, OwnedEntityEquipment};
use crate::world::World;

/// Duration in ticks of the death animation before entity removal.
pub const DEATH_DURATION: i32 = 20;
/// Duration in ticks of the vanilla hurt animation.
pub const HURT_DURATION_TICKS: i32 = 10;
/// Vanilla default `SwingAnimation` duration in ticks.
pub const DEFAULT_SWING_DURATION: i32 = 6;
const MIN_EFFECT_AMPLIFIER: i32 = 0;
const MAX_EFFECT_AMPLIFIER: i32 = 255;
const SPRINT_SPEED_MODIFIER_AMOUNT: f64 = 0.3;
const POST_IMPULSE_GRACE_TICKS: i32 = 40;

/// Runtime mob-effect state.
///
/// Mirrors vanilla `MobEffectInstance` state that affects server-side living
/// physics and client synchronization.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct MobEffectInstance {
    effect: MobEffectRef,
    duration: i32,
    amplifier: i32,
    ambient: bool,
    visible: bool,
    show_icon: bool,
    hidden_effect: Option<Box<MobEffectInstance>>,
}

/// Active mob-effect state stored on a living entity.
pub type ActiveMobEffect = MobEffectInstance;

impl MobEffectInstance {
    /// Creates infinite active mob-effect state for internal physics tests and hooks.
    #[must_use]
    pub const fn new(effect: MobEffectRef, amplifier: i32) -> Self {
        Self::with_duration(effect, INFINITE_EFFECT_DURATION, amplifier)
    }

    /// Creates active mob-effect state with vanilla default visibility flags.
    #[must_use]
    pub const fn with_duration(effect: MobEffectRef, duration: i32, amplifier: i32) -> Self {
        Self {
            effect,
            duration,
            amplifier: clamp_effect_amplifier(amplifier),
            ambient: false,
            visible: true,
            show_icon: true,
            hidden_effect: None,
        }
    }

    /// Sets whether this effect is ambient.
    #[must_use]
    pub const fn with_ambient(mut self, ambient: bool) -> Self {
        self.ambient = ambient;
        self
    }

    /// Sets whether this effect should show particles.
    #[must_use]
    pub const fn with_visible(mut self, visible: bool) -> Self {
        self.visible = visible;
        self
    }

    /// Sets whether this effect should show its inventory icon.
    #[must_use]
    pub const fn with_show_icon(mut self, show_icon: bool) -> Self {
        self.show_icon = show_icon;
        self
    }

    /// Returns the mob effect.
    #[must_use]
    pub const fn effect(&self) -> MobEffectRef {
        self.effect
    }

    /// Returns the effect's duration in ticks.
    #[must_use]
    pub const fn duration(&self) -> i32 {
        self.duration
    }

    /// Returns the effect's amplifier (potency level above the base).
    #[must_use]
    pub const fn amplifier(&self) -> i32 {
        self.amplifier
    }

    /// Returns whether this effect came from an ambient source (e.g. a
    /// beacon), reducing particle visibility.
    #[must_use]
    pub const fn is_ambient(&self) -> bool {
        self.ambient
    }

    /// Returns whether this effect shows particles.
    #[must_use]
    pub const fn is_visible(&self) -> bool {
        self.visible
    }

    /// Returns whether this effect shows its HUD icon.
    #[must_use]
    pub const fn show_icon(&self) -> bool {
        self.show_icon
    }

    /// Returns whether this effect uses vanilla's infinite-duration sentinel.
    #[must_use]
    pub const fn is_infinite_duration(&self) -> bool {
        self.duration == INFINITE_EFFECT_DURATION
    }

    /// Checks whether the duration is at most `ticks` infinite effects never qualify
    #[must_use]
    pub const fn ends_within(&self, ticks: i32) -> bool {
        !self.is_infinite_duration() && self.duration <= ticks
    }

    /// Maps the duration leaving zero and infinite durations unchanged
    #[must_use]
    fn map_duration(&self, mapper: impl FnOnce(i32) -> i32) -> i32 {
        if self.is_infinite_duration() || self.duration == 0 {
            self.duration
        } else {
            mapper(self.duration)
        }
    }

    /// Serializes this effect with vanilla's `MobEffectInstance.CODEC` shape.
    #[must_use]
    pub(crate) fn to_vanilla_nbt(&self) -> NbtCompound {
        let mut nbt = self.details_to_vanilla_nbt();
        nbt.insert("id", self.effect.key.to_string());
        nbt
    }

    fn details_to_vanilla_nbt(&self) -> NbtCompound {
        let mut nbt = NbtCompound::new();
        if self.amplifier != 0 {
            nbt.insert("amplifier", NbtTag::Byte(self.amplifier as i8));
        }
        if self.duration != 0 {
            nbt.insert("duration", self.duration);
        }
        if self.ambient {
            nbt.insert("ambient", NbtTag::Byte(1));
        }
        if !self.visible {
            nbt.insert("show_particles", NbtTag::Byte(0));
        }
        nbt.insert("show_icon", NbtTag::Byte(i8::from(self.show_icon)));
        if let Some(hidden_effect) = self.hidden_effect.as_deref() {
            nbt.insert(
                "hidden_effect",
                NbtTag::Compound(hidden_effect.details_to_vanilla_nbt()),
            );
        }
        nbt
    }

    #[must_use]
    pub(crate) const fn has_remaining_duration(&self) -> bool {
        self.is_infinite_duration() || self.duration > 0
    }

    #[must_use]
    pub(crate) fn should_apply_effect_tick_this_tick(&self, entity_tick_count: i32) -> bool {
        let tick_count = if self.is_infinite_duration() {
            entity_tick_count
        } else {
            self.duration
        };

        MOB_EFFECT_BEHAVIORS
            .get_behavior(self.effect)
            .should_apply_effect_tick_this_tick(tick_count, self.amplifier)
    }

    pub(crate) fn apply_effect_tick(&self, world: &World, entity: &dyn LivingEntity) -> bool {
        MOB_EFFECT_BEHAVIORS
            .get_behavior(self.effect)
            .apply_effect_tick(world, entity, self.amplifier)
    }

    #[must_use]
    const fn is_shorter_duration_than(&self, other: &Self) -> bool {
        !self.is_infinite_duration()
            && (self.duration < other.duration || other.is_infinite_duration())
    }

    /// Merges another instance of the same effect into this instance.
    pub fn update(&mut self, take_over: Self) -> bool {
        let mut changed = false;
        let take_over_ambient = take_over.ambient;
        let take_over_visible = take_over.visible;
        let take_over_show_icon = take_over.show_icon;
        if take_over.amplifier > self.amplifier {
            if take_over.is_shorter_duration_than(self) {
                let previous_hidden_effect = self.hidden_effect.take();
                let mut hidden = self.clone();
                hidden.hidden_effect = previous_hidden_effect;
                self.hidden_effect = Some(Box::new(hidden));
            }

            self.amplifier = take_over.amplifier;
            self.duration = take_over.duration;
            changed = true;
        } else if self.is_shorter_duration_than(&take_over) {
            if take_over.amplifier == self.amplifier {
                self.duration = take_over.duration;
                changed = true;
            } else if let Some(hidden_effect) = &mut self.hidden_effect {
                hidden_effect.update(take_over);
            } else {
                self.hidden_effect = Some(Box::new(take_over));
            }
        }

        if (!take_over_ambient && self.ambient) || changed {
            self.ambient = take_over_ambient;
            changed = true;
        }

        if take_over_visible != self.visible {
            self.visible = take_over_visible;
            changed = true;
        }

        if take_over_show_icon != self.show_icon {
            self.show_icon = take_over_show_icon;
            changed = true;
        }

        changed
    }

    fn tick_duration(&mut self) -> MobEffectTickResult {
        if !self.has_remaining_duration() {
            return MobEffectTickResult::Expired;
        }

        self.tick_down_duration();
        if self.downgrade_to_hidden_effect() {
            return MobEffectTickResult::Active { downgraded: true };
        }
        if self.has_remaining_duration() {
            MobEffectTickResult::Active { downgraded: false }
        } else {
            MobEffectTickResult::Expired
        }
    }

    fn tick_down_duration(&mut self) {
        if let Some(hidden_effect) = &mut self.hidden_effect {
            hidden_effect.tick_down_duration();
        }

        self.duration = self.map_duration(|duration| duration - 1);
    }

    fn downgrade_to_hidden_effect(&mut self) -> bool {
        if self.duration != 0 {
            return false;
        }

        let Some(hidden_effect) = self.hidden_effect.take() else {
            return false;
        };
        let MobEffectInstance {
            duration,
            amplifier,
            ambient,
            visible,
            show_icon,
            hidden_effect,
            ..
        } = *hidden_effect;
        self.duration = duration;
        self.amplifier = amplifier;
        self.ambient = ambient;
        self.visible = visible;
        self.show_icon = show_icon;
        self.hidden_effect = hidden_effect;
        true
    }
}

const fn clamp_effect_amplifier(amplifier: i32) -> i32 {
    if amplifier < MIN_EFFECT_AMPLIFIER {
        MIN_EFFECT_AMPLIFIER
    } else if amplifier > MAX_EFFECT_AMPLIFIER {
        MAX_EFFECT_AMPLIFIER
    } else {
        amplifier
    }
}

enum MobEffectTickResult {
    Active { downgraded: bool },
    Expired,
}

/// A queued mob-effect packet change produced by living effect state.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum MobEffectSyncChange {
    /// Add or update a mob effect.
    Update {
        /// The active effect instance to encode.
        effect: MobEffectInstance,
        /// Whether the owner-client packet should use vanilla's blend flag.
        blend_for_self: bool,
    },
    /// Remove a mob effect.
    Remove {
        /// The effect type to remove.
        effect: MobEffectRef,
    },
}

impl MobEffectSyncChange {
    /// Builds the clientbound packet for a concrete recipient.
    #[must_use]
    pub fn packet(&self, entity_id: i32, is_self_recipient: bool) -> MobEffectSyncPacket {
        match self {
            Self::Update {
                effect,
                blend_for_self,
            } => MobEffectSyncPacket::Update(CUpdateMobEffect::new(
                entity_id,
                effect.effect,
                effect.amplifier,
                effect.duration,
                MobEffectPacketFlags {
                    ambient: effect.ambient,
                    visible: effect.visible,
                    show_icon: effect.show_icon,
                    blend: *blend_for_self && is_self_recipient,
                },
            )),
            Self::Remove { effect } => {
                MobEffectSyncPacket::Remove(CRemoveMobEffect::new(entity_id, effect))
            }
        }
    }
}

/// Concrete mob-effect packet ready to send to a player connection.
#[derive(Debug, Clone)]
pub enum MobEffectSyncPacket {
    /// Add/update mob-effect packet.
    Update(CUpdateMobEffect),
    /// Remove mob-effect packet.
    Remove(CRemoveMobEffect),
}

/// Synchronized living entity-data values derived from active mob effects.
#[derive(Debug, Clone, PartialEq)]
pub struct MobEffectDisplayState {
    /// Visible effect particles for `LivingEntity.DATA_EFFECT_PARTICLES`.
    pub particles: ParticleList,
    /// Whether all active effects are ambient.
    pub ambient: bool,
    /// Whether the shared invisible flag should be set by active effects.
    pub invisible: bool,
    /// Whether the shared glowing flag should be set by active effects.
    pub glowing: bool,
}

/// Movement input stored on vanilla `LivingEntity`.
///
/// Vanilla names these fields `xxa`, `yya`, and `zza`; Steel uses axis names
/// so AI/pathfinding code can set intent without carrying obfuscated names.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct LivingTravelInput {
    sideways: f32,
    vertical: f32,
    forward: f32,
}

impl LivingTravelInput {
    /// No travel input.
    pub const ZERO: Self = Self::new(0.0, 0.0, 0.0);

    /// Creates living travel input.
    #[must_use]
    pub const fn new(sideways: f32, vertical: f32, forward: f32) -> Self {
        Self {
            sideways,
            vertical,
            forward,
        }
    }

    /// Returns sideways movement input.
    #[must_use]
    pub const fn sideways(self) -> f32 {
        self.sideways
    }

    /// Returns vertical movement input.
    #[must_use]
    pub const fn vertical(self) -> f32 {
        self.vertical
    }

    /// Returns forward movement input.
    #[must_use]
    pub const fn forward(self) -> f32 {
        self.forward
    }

    /// Returns this input with horizontal (sideways/forward) components
    /// reduced by 2%, leaving vertical unchanged.
    #[must_use]
    pub const fn dampened(self) -> Self {
        Self {
            sideways: self.sideways * 0.98,
            vertical: self.vertical,
            forward: self.forward * 0.98,
        }
    }
}

/// Vanilla living-entity body/head rotation state.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct LivingRotationState {
    y_body_rot: f32,
    y_body_rot_o: f32,
    y_head_rot: f32,
    y_head_rot_o: f32,
}

impl LivingRotationState {
    /// Creates default living rotation state.
    #[must_use]
    pub const fn new() -> Self {
        Self {
            y_body_rot: 0.0,
            y_body_rot_o: 0.0,
            y_head_rot: 0.0,
            y_head_rot_o: 0.0,
        }
    }

    /// Returns the entity's body yaw, used for turning smoothing separate from head yaw.
    #[must_use]
    pub const fn y_body_rot(self) -> f32 {
        self.y_body_rot
    }

    /// Returns the entity's previous-tick body yaw, used for render interpolation.
    #[must_use]
    pub const fn y_body_rot_o(self) -> f32 {
        self.y_body_rot_o
    }

    /// Returns the entity's head yaw.
    #[must_use]
    pub const fn y_head_rot(self) -> f32 {
        self.y_head_rot
    }

    /// Returns the entity's previous-tick head yaw, used for render interpolation.
    #[must_use]
    pub const fn y_head_rot_o(self) -> f32 {
        self.y_head_rot_o
    }
}

impl Default for LivingRotationState {
    fn default() -> Self {
        Self::new()
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
struct SwingDescription {
    hand: InteractionHand,
    animation: SwingAnimation,
    duration_ticks: i32,
}

/// Arm-swing animation state stored on a living entity.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct LivingSwingState {
    current_swing: Option<SwingDescription>,
    swing_time: i32,
    old_attack_anim: f32,
    attack_anim: f32,
}

impl LivingSwingState {
    /// Creates empty vanilla swing animation state.
    #[must_use]
    pub const fn new() -> Self {
        Self {
            current_swing: None,
            swing_time: 0,
            old_attack_anim: 0.0,
            attack_anim: 0.0,
        }
    }

    /// Returns whether an arm-swing animation is currently playing.
    #[must_use]
    pub const fn swinging(self) -> bool {
        self.current_swing.is_some()
    }

    /// Returns which hand is currently swinging, if any.
    #[must_use]
    pub const fn swinging_arm(self) -> Option<InteractionHand> {
        match self.current_swing {
            Some(swing) => Some(swing.hand),
            None => None,
        }
    }

    /// Returns ticks elapsed in the current arm-swing animation.
    #[must_use]
    pub const fn swing_time(self) -> i32 {
        self.swing_time
    }

    /// Returns the previous-tick animation progress for interpolation.
    #[must_use]
    pub const fn old_attack_anim(self) -> f32 {
        self.old_attack_anim
    }

    /// Returns the current attack animation progress.
    #[must_use]
    pub const fn attack_anim(self) -> f32 {
        self.attack_anim
    }
}

impl Default for LivingSwingState {
    fn default() -> Self {
        Self::new()
    }
}

/// Vanilla active item-use state stored on `LivingEntity`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ActiveItemUseState {
    hand: InteractionHand,
    item: ItemRef,
    duration: i32,
    remaining_ticks: i32,
}

impl ActiveItemUseState {
    /// Creates active item-use state from the hand, stack snapshot, and duration.
    #[must_use]
    pub const fn new(hand: InteractionHand, item: ItemRef, duration: i32) -> Self {
        Self {
            hand,
            item,
            duration,
            remaining_ticks: duration,
        }
    }

    /// Returns the hand being used.
    #[must_use]
    pub const fn hand(&self) -> InteractionHand {
        self.hand
    }

    /// Returns the item snapshot captured when use started.
    #[must_use]
    pub const fn item(&self) -> ItemRef {
        self.item
    }

    /// Returns the original use duration.
    #[must_use]
    pub const fn duration(&self) -> i32 {
        self.duration
    }

    /// Returns the remaining active-use ticks.
    #[must_use]
    pub const fn remaining_ticks(&self) -> i32 {
        self.remaining_ticks
    }
}

#[derive(Debug, Clone)]
struct LivingEntityState {
    effects_dirty: bool,
    death_processed: bool,
    invulnerable_time: i32,
    hurt_time: i32,
    hurt_duration: i32,
    last_hurt: f32,
    last_hurt_by_player: Option<Uuid>,
    last_hurt_by_player_entity: Option<WeakEntity>,
    last_hurt_by_player_memory_time: i32,
    last_hurt_by_mob: Option<WeakEntity>,
    last_hurt_by_mob_timestamp: i32,
    last_hurt_mob: Option<WeakEntity>,
    last_hurt_mob_timestamp: i32,
    absorption_amount: f32,
    skip_drop_experience: bool,
    death_time: i32,
    speed: f32,
    current_impulse_impact_pos: Option<DVec3>,
    current_impulse_context_reset_grace_time: i32,
    fall_flying: bool,
    fall_flying_ticks: i32,
    sprinting: bool,
    sleeping_pos: Option<BlockPos>,
    last_climbable_pos: Option<BlockPos>,
    discard_friction: bool,
    jumping: bool,
    travel_input: LivingTravelInput,
    rotation: LivingRotationState,
    swing: LivingSwingState,
    active_item_use: Option<ActiveItemUseState>,
    no_jump_delay: i32,
    no_action_time: i32,
}

impl LivingEntityState {
    const fn new(speed: f32) -> Self {
        Self {
            effects_dirty: false,
            death_processed: false,
            invulnerable_time: 0,
            hurt_time: 0,
            hurt_duration: 0,
            last_hurt: 0.0,
            last_hurt_by_player: None,
            last_hurt_by_player_entity: None,
            last_hurt_by_player_memory_time: 0,
            last_hurt_by_mob: None,
            last_hurt_by_mob_timestamp: 0,
            last_hurt_mob: None,
            last_hurt_mob_timestamp: 0,
            absorption_amount: 0.0,
            skip_drop_experience: false,
            death_time: 0,
            speed,
            current_impulse_impact_pos: None,
            current_impulse_context_reset_grace_time: 0,
            fall_flying: false,
            fall_flying_ticks: 0,
            sprinting: false,
            sleeping_pos: None,
            last_climbable_pos: None,
            discard_friction: false,
            jumping: false,
            travel_input: LivingTravelInput::ZERO,
            rotation: LivingRotationState::new(),
            swing: LivingSwingState::new(),
            active_item_use: None,
            no_jump_delay: 0,
            no_action_time: 0,
        }
    }

    const fn reset_death_state(&mut self) {
        self.death_processed = false;
        self.death_time = 0;
        self.invulnerable_time = 0;
        self.last_hurt = 0.0;
        self.absorption_amount = 0.0;
        self.skip_drop_experience = false;
    }
}

/// Common runtime fields shared by all living entities.
///
/// **Deviation from vanilla:** Vanilla calls this guard `LivingEntity.dead`,
/// but it means death side effects have been processed, not health is zero.
/// `ServerPlayer.die()` does NOT call `super.die()` and never sets that field.
/// Steel uses this guard for players too so repeated callbacks cannot duplicate
/// death side effects. Health remains the source of truth for dead-or-dying
/// checks such as client respawn requests.
pub struct LivingEntityBase {
    state: SyncMutex<LivingEntityState>,
    attributes: SyncMutex<AttributeMap>,
    active_mob_effects: SyncMutex<FxHashMap<MobEffectRef, ActiveMobEffect>>,
    dirty_mob_effects: SyncMutex<Vec<MobEffectSyncChange>>,
    equipment: Shared<dyn EntityEquipment>,
    last_equipment_items: SyncMutex<[ItemStack; EquipmentSlot::ALL.len()]>,
    pending_equipment_changes: SyncMutex<[Option<ItemStack>; EquipmentSlot::ALL.len()]>,
    equipment_attribute_modifiers:
        SyncMutex<[Vec<EquipmentAttributeModifierKey>; EquipmentSlot::ALL.len()]>,
}

#[derive(Debug)]
struct EquipmentAttributeModifierKey {
    attribute: AttributeRef,
    id: Identifier,
}

impl LivingEntityBase {
    /// Creates living runtime state from an entity type's default attributes.
    #[must_use]
    pub fn new(entity_type: EntityTypeRef) -> Self {
        Self::with_attributes(AttributeMap::new_for_entity(entity_type))
    }

    /// Creates living runtime state from an explicit attribute map.
    #[must_use]
    pub fn with_attributes(attributes: AttributeMap) -> Self {
        let equipment: Shared<dyn EntityEquipment> = OwnedEntityEquipment::new().into_shared();
        Self::with_attributes_and_equipment(attributes, equipment)
    }

    /// Creates living runtime state with an explicit canonical equipment backing.
    #[must_use]
    pub fn with_equipment(
        entity_type: EntityTypeRef,
        equipment: Shared<dyn EntityEquipment>,
    ) -> Self {
        Self::with_attributes_and_equipment(AttributeMap::new_for_entity(entity_type), equipment)
    }

    fn with_attributes_and_equipment(
        attributes: AttributeMap,
        equipment: Shared<dyn EntityEquipment>,
    ) -> Self {
        let speed = attributes.required_value(vanilla_attributes::MOVEMENT_SPEED) as f32;

        Self {
            state: SyncMutex::new(LivingEntityState::new(speed)),
            attributes: SyncMutex::new(attributes),
            active_mob_effects: SyncMutex::new(FxHashMap::default()),
            dirty_mob_effects: SyncMutex::new(Vec::new()),
            equipment,
            last_equipment_items: SyncMutex::new(array::from_fn(|_| ItemStack::empty())),
            pending_equipment_changes: SyncMutex::new(array::from_fn(|_| None)),
            equipment_attribute_modifiers: SyncMutex::new(array::from_fn(|_| Vec::new())),
        }
    }

    /// Returns this entity's attribute map.
    #[inline]
    pub const fn attributes(&self) -> &SyncMutex<AttributeMap> {
        &self.attributes
    }

    /// Applies vanilla constructor-time synced-data mutations for living entities.
    ///
    /// Vanilla defines `DATA_HEALTH_ID` as `1.0F`, then `LivingEntity` constructs
    /// its attribute map and calls `setHealth(getMaxHealth())`.
    pub fn initialize_synced_data<T: VanillaLivingEntityData>(&self, entity_data: &mut T) {
        let max_health = self
            .attributes
            .lock()
            .required_value(vanilla_attributes::MAX_HEALTH) as f32;
        entity_data.living_entity_mut().health.set(max_health);
    }

    /// Returns this entity's equipped-item storage.
    #[inline]
    pub const fn equipment(&self) -> &Shared<dyn EntityEquipment> {
        &self.equipment
    }

    /// Collects equipment changes against Vanilla's previous-tick snapshots.
    pub fn collect_equipment_changes(&self) -> Vec<(EquipmentSlot, ItemStack, ItemStack)> {
        let current_items = self.equipment.lock().snapshot();
        let mut last_items = self.last_equipment_items.lock();
        let mut changes = Vec::new();

        for slot in EquipmentSlot::ALL {
            let index = slot.index();
            if ItemStack::matches(&last_items[index], &current_items[index]) {
                continue;
            }
            let previous = mem::replace(&mut last_items[index], current_items[index].clone());
            changes.push((slot, previous, current_items[index].clone()));
        }
        changes
    }

    /// Coalesces detected equipment changes until entity tracking sends them.
    pub fn queue_equipment_changes(
        &self,
        changes: impl IntoIterator<Item = (EquipmentSlot, ItemStack)>,
    ) {
        let mut pending = self.pending_equipment_changes.lock();
        for (slot, item_stack) in changes {
            pending[slot.index()] = Some(item_stack);
        }
    }

    /// Drains equipment changes detected by the living tick.
    pub fn drain_equipment_changes(&self) -> Vec<(EquipmentSlot, ItemStack)> {
        let mut pending = self.pending_equipment_changes.lock();
        EquipmentSlot::ALL
            .into_iter()
            .filter_map(|slot| pending[slot.index()].take().map(|item| (slot, item)))
            .collect()
    }

    /// Returns vanilla living body/head rotation state.
    #[must_use]
    pub fn rotation_state(&self) -> LivingRotationState {
        self.state.lock().rotation
    }

    /// Returns vanilla arm-swing animation state.
    #[must_use]
    pub fn swing_state(&self) -> LivingSwingState {
        self.state.lock().swing
    }

    /// Returns a snapshot of vanilla active item-use state.
    #[must_use]
    pub fn active_item_use(&self) -> Option<ActiveItemUseState> {
        self.state.lock().active_item_use
    }

    /// Returns whether this living entity is actively using an item.
    #[must_use]
    pub fn is_using_item(&self) -> bool {
        self.state.lock().active_item_use.is_some()
    }

    /// Starts vanilla active item use.
    pub fn start_using_item(&self, hand: InteractionHand, item: &ItemStack, duration: i32) -> bool {
        if item.is_empty() || duration <= 0 {
            return false;
        }

        let mut state = self.state.lock();
        if state.active_item_use.is_some() {
            return false;
        }
        state.active_item_use = Some(ActiveItemUseState::new(hand, item.item(), duration));
        true
    }

    /// Stops vanilla active item use without calling item hooks.
    pub fn stop_using_item(&self) -> Option<ActiveItemUseState> {
        self.state.lock().active_item_use.take()
    }

    /// Decrements active-use remaining ticks and returns the updated state.
    pub fn decrement_active_item_use(&self) -> Option<ActiveItemUseState> {
        let mut state = self.state.lock();
        let active = state.active_item_use.as_mut()?;
        active.remaining_ticks -= 1;
        Some(*active)
    }

    /// Returns the entity's body yaw, used for turning smoothing separate from head yaw.
    #[must_use]
    pub fn y_body_rot(&self) -> f32 {
        self.state.lock().rotation.y_body_rot
    }

    /// Sets the entity's body yaw.
    pub fn set_y_body_rot(&self, y_body_rot: f32) {
        self.state.lock().rotation.y_body_rot = y_body_rot;
    }

    /// Returns the entity's head yaw.
    #[must_use]
    pub fn y_head_rot(&self) -> f32 {
        self.state.lock().rotation.y_head_rot
    }

    /// Sets the entity's head yaw.
    pub fn set_y_head_rot(&self, y_head_rot: f32) {
        self.state.lock().rotation.y_head_rot = y_head_rot;
    }

    /// Copies current living head/body rotations to their old-rotation fields.
    pub fn advance_rotation_for_base_tick(&self) {
        let mut state = self.state.lock();
        state.rotation.y_head_rot_o = state.rotation.y_head_rot;
        state.rotation.y_body_rot_o = state.rotation.y_body_rot;
    }

    /// Starts a swing when the active animation's restart gate allows it.
    pub fn start_swing(
        &self,
        hand: InteractionHand,
        animation: SwingAnimation,
        duration_ticks: i32,
    ) -> bool {
        let mut state = self.state.lock();
        let swing = &mut state.swing;
        if let Some(current) = swing.current_swing
            && swing.swing_time <= current.duration_ticks / 2
            && swing.swing_time > 0
        {
            return false;
        }

        let description = SwingDescription {
            hand,
            animation,
            duration_ticks,
        };
        if swing.current_swing != Some(description) {
            swing.old_attack_anim = 0.0;
            swing.attack_anim = 0.0;
        }
        swing.current_swing = Some(description);
        swing.swing_time = 0;
        true
    }

    /// Advances the swing animation at the start of the living entity's base tick.
    pub fn tick_swing_state(&self) {
        let mut state = self.state.lock();
        let swing = &mut state.swing;
        swing.old_attack_anim = swing.attack_anim;
        let Some(current) = swing.current_swing else {
            swing.attack_anim = 0.0;
            return;
        };
        if current.duration_ticks > 0 {
            swing.attack_anim = (swing.swing_time as f32 / current.duration_ticks as f32).min(1.0);
        }
        let finished = swing.swing_time > current.duration_ticks;
        swing.swing_time += 1;
        if finished {
            swing.current_swing = None;
            swing.attack_anim = 0.0;
        }
    }

    /// Returns vanilla `LivingEntity.absorptionAmount` for non-player living entities.
    #[must_use]
    pub fn absorption_amount(&self) -> f32 {
        self.state.lock().absorption_amount
    }

    /// Sets vanilla `LivingEntity.absorptionAmount` for non-player living entities.
    pub fn set_absorption_amount(&self, amount: f32) {
        let max_absorption = self
            .attributes
            .lock()
            .required_value(vanilla_attributes::MAX_ABSORPTION) as f32;
        self.state.lock().absorption_amount = amount.clamp(0.0, max_absorption);
    }

    /// Marks this entity to skip dropping experience on death.
    pub fn skip_drop_experience(&self) {
        self.state.lock().skip_drop_experience = true;
    }

    /// Returns whether this entity has been marked to skip dropping experience.
    #[must_use]
    pub fn was_experience_consumed(&self) -> bool {
        self.state.lock().skip_drop_experience
    }

    /// Returns ticks this entity has gone without taking a noteworthy action.
    #[must_use]
    pub fn no_action_time(&self) -> i32 {
        self.state.lock().no_action_time
    }

    /// Sets ticks this entity has gone without taking a noteworthy action.
    pub fn set_no_action_time(&self, no_action_time: i32) {
        self.state.lock().no_action_time = no_action_time;
    }

    /// Increments the no-action-time counter by one tick.
    pub fn increment_no_action_time(&self) {
        self.state.lock().no_action_time += 1;
    }

    /// Refreshes transient item attribute modifiers for an equipment slot.
    pub fn refresh_equipment_attribute_modifiers(
        &self,
        slot: EquipmentSlot,
        item_stack: &ItemStack,
    ) {
        let slot_index = slot.index();
        let mut attributes = self.attributes.lock();
        let mut installed_modifiers = self.equipment_attribute_modifiers.lock();

        #[expect(
            clippy::iter_with_drain,
            reason = "keeps the slot's allocation for the modifiers installed below"
        )]
        for key in installed_modifiers[slot_index].drain(..) {
            attributes.remove_modifier(key.attribute, &key.id);
        }

        if item_stack.is_empty() || item_stack.is_broken() {
            return;
        }

        let Some(modifiers) = item_stack.get_attribute_modifiers() else {
            return;
        };

        for entry in modifiers.for_slot(slot) {
            for (index, keys) in installed_modifiers.iter_mut().enumerate() {
                if index == slot_index {
                    continue;
                }
                keys.retain(|key| key.attribute.key != entry.attribute.key || key.id != entry.id);
            }

            attributes.remove_modifier(entry.attribute, &entry.id);
            if attributes.add_modifier(
                entry.attribute,
                AttributeModifier {
                    id: entry.id.clone(),
                    amount: entry.amount,
                    operation: entry.operation,
                },
                false,
            ) {
                installed_modifiers[slot_index].push(EquipmentAttributeModifierKey {
                    attribute: entry.attribute,
                    id: entry.id.clone(),
                });
            }
        }
    }

    /// Returns whether this living entity has an active vanilla mob effect.
    #[must_use]
    pub fn has_mob_effect(&self, effect: MobEffectRef) -> bool {
        self.active_mob_effects.lock().contains_key(&effect)
    }

    /// Returns active vanilla mob-effect state.
    #[must_use]
    pub fn mob_effect(&self, effect: MobEffectRef) -> Option<ActiveMobEffect> {
        self.active_mob_effects.lock().get(&effect).cloned()
    }

    /// Returns all active vanilla mob effects.
    #[must_use]
    pub fn active_mob_effects(&self) -> Vec<ActiveMobEffect> {
        self.active_mob_effects.lock().values().cloned().collect()
    }

    /// Adds or updates active vanilla mob-effect state.
    pub fn add_mob_effect(&self, effect: MobEffectInstance) -> bool {
        let effect_key = effect.effect;
        let mut existing_effect = None;
        let mut changed_effect = None;
        {
            let mut effects = self.active_mob_effects.lock();
            if let Some(current) = effects.get_mut(&effect_key) {
                if current.update(effect) {
                    changed_effect = Some(current.clone());
                }
            } else {
                effects.insert(effect_key, effect.clone());
                existing_effect = Some(effect);
            }
        }

        if let Some(effect) = existing_effect {
            self.add_effect_attribute_modifiers(&effect);
            self.mark_effects_dirty();
            self.queue_mob_effect_sync(MobEffectSyncChange::Update {
                effect,
                blend_for_self: true,
            });
            return true;
        }

        if let Some(effect) = changed_effect {
            self.refresh_effect_attribute_modifiers(&effect);
            self.mark_effects_dirty();
            self.queue_mob_effect_sync(MobEffectSyncChange::Update {
                effect,
                blend_for_self: false,
            });
            return true;
        }

        false
    }

    /// Sets active vanilla mob-effect state.
    pub fn set_mob_effect(&self, effect: MobEffectRef, amplifier: i32) {
        self.add_mob_effect(MobEffectInstance::new(effect, amplifier));
    }

    /// Sets the presence of a vanilla mob effect.
    pub fn set_mob_effect_active(&self, effect: MobEffectRef, active: bool) {
        if active {
            self.set_mob_effect(effect, 0);
        } else {
            self.remove_mob_effect(effect);
        }
    }

    /// Removes active vanilla mob-effect state.
    pub fn remove_mob_effect(&self, effect: MobEffectRef) -> bool {
        let removed = self.active_mob_effects.lock().remove(&effect);
        let Some(removed) = removed else {
            return false;
        };

        self.remove_effect_attribute_modifiers(removed.effect);
        self.mark_effects_dirty();
        self.queue_mob_effect_sync(MobEffectSyncChange::Remove { effect });
        true
    }

    /// Ticks one active mob-effect duration after its server behavior has run.
    pub(super) fn tick_mob_effect_duration(&self, effect_key: MobEffectRef) {
        let (updated, removed) = {
            let mut effects = self.active_mob_effects.lock();
            let Some(effect) = effects.get_mut(&effect_key) else {
                return;
            };
            match effect.tick_duration() {
                MobEffectTickResult::Active { downgraded } => {
                    let updated =
                        (downgraded || effect.duration() % 600 == 0).then(|| effect.clone());
                    (updated, None)
                }
                MobEffectTickResult::Expired => (None, effects.remove(&effect_key)),
            }
        };

        if let Some(effect) = updated {
            self.refresh_effect_attribute_modifiers(&effect);
            self.mark_effects_dirty();
            self.queue_mob_effect_sync(MobEffectSyncChange::Update {
                effect,
                blend_for_self: false,
            });
        }

        if let Some(effect) = removed {
            self.remove_effect_attribute_modifiers(effect.effect);
            self.mark_effects_dirty();
            self.queue_mob_effect_sync(MobEffectSyncChange::Remove {
                effect: effect.effect,
            });
        }
    }

    /// Drains pending mob-effect packet changes.
    pub fn drain_dirty_mob_effects(&self) -> Vec<MobEffectSyncChange> {
        self.dirty_mob_effects.lock().drain(..).collect()
    }

    /// Returns whether synchronized effect entity data should be recomputed.
    pub fn take_effects_dirty(&self) -> bool {
        let mut state = self.state.lock();
        let dirty = state.effects_dirty;
        state.effects_dirty = false;
        dirty
    }

    /// Builds the synchronized living effect particle/glow/invisibility state.
    pub fn mob_effect_display_state(&self) -> MobEffectDisplayState {
        let mut effects = self
            .active_mob_effects
            .lock()
            .values()
            .cloned()
            .collect::<Vec<_>>();
        effects.sort_by_key(|effect| effect.effect.try_id().unwrap_or(usize::MAX));

        let particles = effects
            .iter()
            .filter(|effect| effect.is_visible())
            .map(|effect| effect.effect.create_particle_options(effect.ambient))
            .collect();

        MobEffectDisplayState {
            particles: ParticleList { particles },
            ambient: !effects.is_empty() && effects.iter().all(MobEffectInstance::is_ambient),
            invisible: effects
                .iter()
                .any(|effect| effect.effect == vanilla_mob_effects::INVISIBILITY),
            glowing: effects
                .iter()
                .any(|effect| effect.effect == vanilla_mob_effects::GLOWING),
        }
    }

    fn add_effect_attribute_modifiers(&self, effect: &MobEffectInstance) {
        let mut attributes = self.attributes.lock();
        for modifier in effect.effect.attribute_modifiers {
            attributes.remove_modifier(modifier.attribute, &modifier.id);
            attributes.add_modifier(
                modifier.attribute,
                AttributeModifier {
                    id: modifier.id.clone(),
                    amount: modifier.amount * f64::from(effect.amplifier + 1),
                    operation: modifier.operation,
                },
                false,
            );
        }
    }

    fn refresh_effect_attribute_modifiers(&self, effect: &MobEffectInstance) {
        self.remove_effect_attribute_modifiers(effect.effect);
        self.add_effect_attribute_modifiers(effect);
    }

    fn remove_effect_attribute_modifiers(&self, effect: MobEffectRef) {
        let mut attributes = self.attributes.lock();
        for modifier in effect.attribute_modifiers {
            attributes.remove_modifier(modifier.attribute, &modifier.id);
        }
    }

    fn queue_mob_effect_sync(&self, change: MobEffectSyncChange) {
        self.dirty_mob_effects.lock().push(change);
    }

    /// Marks synchronized effect visibility data for recomputation.
    pub(crate) fn mark_effects_dirty(&self) {
        self.state.lock().effects_dirty = true;
    }

    /// Gets the cached movement speed used by living movement code.
    #[inline]
    pub fn speed(&self) -> f32 {
        self.state.lock().speed
    }

    /// Sets the cached movement speed used by living movement code.
    #[inline]
    pub fn set_speed(&self, speed: f32) {
        self.state.lock().speed = speed;
    }

    /// Refreshes the cached movement speed from the `MOVEMENT_SPEED` attribute.
    pub fn refresh_speed_from_attributes(&self) {
        let speed = self
            .attributes
            .lock()
            .get_value(vanilla_attributes::MOVEMENT_SPEED);
        if let Some(speed) = speed {
            self.state.lock().speed = speed as f32;
        }
    }

    /// Applies vanilla post-impulse movement validation grace.
    pub fn apply_post_impulse_grace_time(&self, ticks: i32) {
        let mut state = self.state.lock();
        state.current_impulse_context_reset_grace_time =
            state.current_impulse_context_reset_grace_time.max(ticks);
    }

    /// Sets whether fall damage from the current knockback/impulse impact should be ignored.
    pub fn set_ignore_fall_damage_from_current_impulse(
        &self,
        ignore_fall_damage: bool,
        new_impulse_impact_pos: DVec3,
    ) {
        let mut state = self.state.lock();
        if ignore_fall_damage {
            state.current_impulse_context_reset_grace_time = state
                .current_impulse_context_reset_grace_time
                .max(POST_IMPULSE_GRACE_TICKS);
            state.current_impulse_impact_pos = Some(new_impulse_impact_pos);
        } else {
            state.current_impulse_context_reset_grace_time = 0;
        }
    }

    /// Returns the position of the most recent knockback/impulse impact, if still active.
    #[must_use]
    pub fn current_impulse_impact_pos(&self) -> Option<DVec3> {
        self.state.lock().current_impulse_impact_pos
    }

    /// Returns ticks remaining before the current impulse context can be reset.
    #[must_use]
    pub fn current_impulse_context_reset_grace_time(&self) -> i32 {
        self.state.lock().current_impulse_context_reset_grace_time
    }

    /// Returns whether fall damage should be ignored due to a recent
    /// knockback/impulse impact.
    #[must_use]
    pub fn is_ignoring_fall_damage_from_current_impulse(&self) -> bool {
        self.state.lock().current_impulse_impact_pos.is_some()
    }

    /// Clears the current impulse impact position once its grace time has expired.
    pub fn try_reset_current_impulse_context(&self) {
        let mut state = self.state.lock();
        if state.current_impulse_context_reset_grace_time == 0 {
            state.current_impulse_impact_pos = None;
        }
    }

    /// Immediately clears the current impulse impact position and its grace time.
    pub fn reset_current_impulse_context(&self) {
        let mut state = self.state.lock();
        state.current_impulse_context_reset_grace_time = 0;
        state.current_impulse_impact_pos = None;
    }

    /// Returns whether movement validation is inside post-impulse grace.
    #[must_use]
    pub fn is_in_post_impulse_grace_time(&self) -> bool {
        self.state.lock().current_impulse_context_reset_grace_time > 0
    }

    /// Decrements post-impulse grace once per living-entity tick.
    pub fn tick_post_impulse_grace_time(&self) {
        let mut state = self.state.lock();
        if state.current_impulse_context_reset_grace_time > 0 {
            state.current_impulse_context_reset_grace_time -= 1;
        }
    }

    /// Returns whether this living entity is currently fall flying.
    #[must_use]
    pub fn is_fall_flying(&self) -> bool {
        self.state.lock().fall_flying
    }

    /// Sets the vanilla living-entity fall-flying state.
    pub fn set_fall_flying(&self, fall_flying: bool) {
        self.state.lock().fall_flying = fall_flying;
    }

    /// Returns ticks this entity has been fall-flying (elytra gliding).
    #[must_use]
    pub fn fall_flying_ticks(&self) -> i32 {
        self.state.lock().fall_flying_ticks
    }

    /// Advances (or resets) the fall-flying tick counter based on whether
    /// the entity is currently fall-flying.
    pub fn tick_fall_flying_state(&self, fall_flying: bool) {
        let mut state = self.state.lock();
        if fall_flying {
            state.fall_flying_ticks = state.fall_flying_ticks.wrapping_add(1);
        } else {
            state.fall_flying_ticks = 0;
        }
    }

    /// Returns whether this living entity is sprinting.
    #[must_use]
    pub fn is_sprinting(&self) -> bool {
        self.state.lock().sprinting
    }

    /// Sets the vanilla living-entity sprinting state and movement-speed modifier.
    pub fn set_sprinting(&self, sprinting: bool) {
        self.state.lock().sprinting = sprinting;

        let mut attributes = self.attributes.lock();
        if sprinting {
            attributes.add_modifier(
                vanilla_attributes::MOVEMENT_SPEED,
                AttributeModifier {
                    id: Identifier::vanilla_static("sprinting"),
                    amount: SPRINT_SPEED_MODIFIER_AMOUNT,
                    operation: AttributeModifierOperation::AddMultipliedTotal,
                },
                false,
            );
        } else {
            attributes.remove_modifier(
                vanilla_attributes::MOVEMENT_SPEED,
                &Identifier::vanilla_static("sprinting"),
            );
        }
    }

    /// Returns the bed position that makes this living entity sleeping.
    #[must_use]
    pub fn sleeping_pos(&self) -> Option<BlockPos> {
        self.state.lock().sleeping_pos
    }

    /// Sets the vanilla living-entity sleeping position.
    pub fn set_sleeping_pos(&self, bed_position: BlockPos) {
        self.state.lock().sleeping_pos = Some(bed_position);
    }

    /// Clears the vanilla living-entity sleeping position.
    pub fn clear_sleeping_pos(&self) {
        self.state.lock().sleeping_pos = None;
    }

    /// Returns whether this living entity has a sleeping position.
    #[must_use]
    pub fn is_sleeping(&self) -> bool {
        self.sleeping_pos().is_some()
    }

    /// Returns the last climbable block position this living entity touched.
    #[must_use]
    pub fn last_climbable_pos(&self) -> Option<BlockPos> {
        self.state.lock().last_climbable_pos
    }

    /// Records the last climbable block position this living entity touched.
    pub fn set_last_climbable_pos(&self, pos: BlockPos) {
        self.state.lock().last_climbable_pos = Some(pos);
    }

    /// Returns whether vanilla living travel should skip friction damping.
    #[must_use]
    pub fn should_discard_friction(&self) -> bool {
        self.state.lock().discard_friction
    }

    /// Sets whether vanilla living travel should skip friction damping.
    pub fn set_discard_friction(&self, discard_friction: bool) {
        self.state.lock().discard_friction = discard_friction;
    }

    /// Returns whether this living entity is applying jump input.
    #[must_use]
    pub fn is_jumping(&self) -> bool {
        self.state.lock().jumping
    }

    /// Sets whether this living entity is applying jump input.
    pub fn set_jumping(&self, jumping: bool) {
        self.state.lock().jumping = jumping;
    }

    /// Returns vanilla living travel input.
    #[must_use]
    pub fn travel_input(&self) -> LivingTravelInput {
        self.state.lock().travel_input
    }

    /// Sets vanilla living travel input.
    pub fn set_travel_input(&self, input: LivingTravelInput) {
        self.state.lock().travel_input = input;
    }

    /// Applies horizontal damping to the stored travel input.
    pub fn dampen_travel_input(&self) {
        let mut state = self.state.lock();
        state.travel_input = state.travel_input.dampened();
    }

    /// Returns vanilla jump cooldown ticks.
    #[must_use]
    pub fn no_jump_delay(&self) -> i32 {
        self.state.lock().no_jump_delay
    }

    /// Sets vanilla jump cooldown ticks.
    pub fn set_no_jump_delay(&self, ticks: i32) {
        self.state.lock().no_jump_delay = ticks;
    }

    /// Decrements vanilla jump cooldown once per living AI step.
    pub fn tick_no_jump_delay(&self) {
        let mut state = self.state.lock();
        if state.no_jump_delay > 0 {
            state.no_jump_delay -= 1;
        }
    }

    /// Calculates vanilla living-entity fall damage.
    #[must_use]
    pub fn calculate_fall_damage(
        fall_distance: f64,
        damage_modifier: f32,
        safe_fall_distance: f64,
        fall_damage_multiplier: f64,
    ) -> i32 {
        ((fall_distance + 1.0e-6 - safe_fall_distance)
            * f64::from(damage_modifier)
            * fall_damage_multiplier)
            .floor() as i32
    }

    /// Returns the remaining hurt-cooldown ticks.
    pub fn invulnerable_time(&self) -> i32 {
        self.state.lock().invulnerable_time
    }

    /// Sets the remaining hurt-cooldown ticks.
    pub fn set_invulnerable_time(&self, invulnerable_time: i32) {
        self.state.lock().invulnerable_time = invulnerable_time;
    }

    /// Decrements remaining invulnerability ticks by one if any are active.
    pub fn decrement_invulnerable_time(&self) {
        let mut state = self.state.lock();
        if state.invulnerable_time > 0 {
            state.invulnerable_time -= 1;
        }
    }

    /// Starts the vanilla hurt animation.
    pub fn begin_hurt_animation(&self) {
        let mut state = self.state.lock();
        state.hurt_duration = HURT_DURATION_TICKS;
        state.hurt_time = state.hurt_duration;
    }

    /// Decrements the vanilla hurt animation timer.
    pub fn decrement_hurt_time(&self) {
        let mut state = self.state.lock();
        if state.hurt_time > 0 {
            state.hurt_time -= 1;
        }
    }

    /// Returns the current hurt time
    #[must_use]
    pub fn hurt_time(&self) -> i32 {
        self.state.lock().hurt_time
    }

    /// Returns the current hurt duration
    #[must_use]
    pub fn hurt_duration(&self) -> i32 {
        self.state.lock().hurt_duration
    }

    /// Applies vanilla hurt cooldown bookkeeping.
    ///
    /// Returns `None` when damage should be ignored because death was already
    /// processed or the amount did not exceed the active invulnerability frame.
    pub fn apply_damage_cooldown(
        &self,
        amount: f32,
        bypasses_cooldown: bool,
    ) -> Option<(bool, f32)> {
        let mut state = self.state.lock();
        if state.death_processed {
            return None;
        }

        if state.invulnerable_time > 10 && !bypasses_cooldown {
            if amount <= state.last_hurt {
                return None;
            }
            let effective = amount - state.last_hurt;
            state.last_hurt = amount;
            Some((false, effective))
        } else {
            state.last_hurt = amount;
            state.invulnerable_time = 20;
            Some((true, amount))
        }
    }

    /// Records the player that last hurt this entity, remembered for
    /// `time_to_remember` ticks.
    pub fn set_last_hurt_by_player(&self, player_uuid: Uuid, time_to_remember: i32) {
        let mut state = self.state.lock();
        state.last_hurt_by_player = Some(player_uuid);
        state.last_hurt_by_player_entity = None;
        state.last_hurt_by_player_memory_time = time_to_remember;
    }

    /// Sets the remaining memory time without touching the remembered player.
    pub fn set_last_hurt_by_player_memory_time(&self, time_to_remember: i32) {
        self.state.lock().last_hurt_by_player_memory_time = time_to_remember;
    }

    /// Remembers the live player independently of which world it occupies.
    pub(crate) fn set_last_hurt_by_player_entity(
        &self,
        player: &SharedEntity,
        time_to_remember: i32,
    ) {
        let uuid = player.uuid();
        let mut state = self.state.lock();
        state.last_hurt_by_player = Some(uuid);
        state.last_hurt_by_player_entity = Some(Arc::downgrade(player));
        state.last_hurt_by_player_memory_time = time_to_remember;
    }

    /// Resolves cached kill credit before falling back to the saved UUID.
    #[must_use]
    pub(crate) fn last_hurt_by_player(&self, world: &World) -> Option<SharedEntity> {
        let (uuid, cached) = {
            let state = self.state.lock();
            (
                state.last_hurt_by_player?,
                state.last_hurt_by_player_entity.clone(),
            )
        };
        if let Some(player) = cached.and_then(|player| player.upgrade())
            && !player.is_removed()
        {
            return Some(player);
        }
        world
            .get_entity_by_uuid(&uuid)
            .filter(|entity| entity.as_player().is_some())
    }

    /// Returns ticks remaining that this entity will remember the player who last hurt it.
    #[must_use]
    pub fn last_hurt_by_player_memory_time(&self) -> i32 {
        self.state.lock().last_hurt_by_player_memory_time
    }

    /// Returns the remembered player UUID, if present.
    #[must_use]
    pub fn last_hurt_by_player_uuid(&self) -> Option<Uuid> {
        self.state.lock().last_hurt_by_player
    }

    /// Returns vanilla `LivingEntity.lastHurtByMob`, if still resolvable.
    #[must_use]
    pub fn last_hurt_by_mob(&self) -> Option<SharedEntity> {
        let mut state = self.state.lock();
        living_entity_from_weak(&mut state.last_hurt_by_mob)
    }

    /// Returns the tick timestamp this entity was last hurt by a mob.
    #[must_use]
    pub fn last_hurt_by_mob_timestamp(&self) -> i32 {
        self.state.lock().last_hurt_by_mob_timestamp
    }

    /// Records the mob that last hurt this entity and the tick it happened.
    pub fn set_last_hurt_by_mob(&self, target: Option<&SharedEntity>, tick_count: i32) {
        let mut state = self.state.lock();
        state.last_hurt_by_mob = weak_living_entity(target);
        state.last_hurt_by_mob_timestamp = tick_count;
    }

    /// Returns vanilla `LivingEntity.lastHurtMob`, if still resolvable.
    #[must_use]
    pub fn last_hurt_mob(&self) -> Option<SharedEntity> {
        let mut state = self.state.lock();
        living_entity_from_weak(&mut state.last_hurt_mob)
    }

    /// Returns the tick timestamp this entity last hurt a mob.
    #[must_use]
    pub fn last_hurt_mob_timestamp(&self) -> i32 {
        self.state.lock().last_hurt_mob_timestamp
    }

    /// Records the mob this entity last hurt and the tick it happened.
    pub fn set_last_hurt_mob(&self, target: Option<&SharedEntity>, tick_count: i32) {
        let mut state = self.state.lock();
        state.last_hurt_mob = weak_living_entity(target);
        state.last_hurt_mob_timestamp = tick_count;
    }

    /// Ticks vanilla last-hurt-by-player memory.
    pub fn tick_last_hurt_by_player_memory(&self) {
        let mut state = self.state.lock();
        if state.last_hurt_by_player_memory_time > 0 {
            state.last_hurt_by_player_memory_time -= 1;
        } else {
            state.last_hurt_by_player = None;
            state.last_hurt_by_player_entity = None;
        }
    }

    /// Ticks vanilla living combat-memory cleanup.
    pub fn tick_living_combat_memory(&self, tick_count: i32) {
        if self
            .last_hurt_mob()
            .is_some_and(|target| living_is_dead(&target))
        {
            self.set_last_hurt_mob(None, tick_count);
        }

        let Some(hurt_by) = self.last_hurt_by_mob() else {
            return;
        };
        if living_is_dead(&hurt_by) || tick_count - self.last_hurt_by_mob_timestamp() > 100 {
            self.set_last_hurt_by_mob(None, tick_count);
        }
    }

    /// Returns whether death side effects have already run.
    ///
    /// Close to vanilla `LivingEntity.dead`, which guards `die`, but not identical:
    /// Steel also gates [`Self::apply_damage_cooldown`] on it, and players set it
    /// through their own death path. Treat it as "this entity has already died",
    /// not as a faithful mirror of the vanilla field.
    #[must_use]
    pub fn is_death_processed(&self) -> bool {
        self.state.lock().death_processed
    }

    /// Marks death side effects as processed.
    ///
    /// Returns `false` if they were already processed.
    pub fn mark_death_processed(&self) -> bool {
        let mut state = self.state.lock();
        if state.death_processed {
            return false;
        }
        state.death_processed = true;
        true
    }

    /// Increments death animation time by 1 and returns the new value.
    #[inline]
    pub fn increment_death_time(&self) -> i32 {
        let mut state = self.state.lock();
        state.death_time += 1;
        state.death_time
    }

    /// Returns ticks elapsed since this entity started dying (its death animation).
    #[must_use]
    pub fn death_time(&self) -> i32 {
        self.state.lock().death_time
    }

    /// Resets all death-related state back to alive defaults.
    #[inline]
    pub fn reset_death_state(&self) {
        self.state.lock().reset_death_state();
    }
}

fn weak_living_entity(target: Option<&SharedEntity>) -> Option<WeakEntity> {
    let target = target?;
    target.is_living_entity().then(|| Arc::downgrade(target))
}

fn living_entity_from_weak(entity: &mut Option<WeakEntity>) -> Option<SharedEntity> {
    let Some(upgraded) = entity.as_ref().and_then(WeakEntity::upgrade) else {
        *entity = None;
        return None;
    };
    if !upgraded.is_living_entity() {
        *entity = None;
        return None;
    }
    Some(upgraded)
}

fn living_is_dead(entity: &SharedEntity) -> bool {
    entity
        .as_living_entity()
        .is_none_or(|living| !LivingEntity::is_alive(living))
}

#[cfg(test)]
mod tests;

/// Pushes newly dirty mob-effect state into a living entity's synced data.
///
/// Every mob does this before its data is sent, so it lives here rather than being
/// restated per species. Returns the resolved display state when something was dirty,
/// so a caller that syncs further flags from it need not repeat the dirty check, and
/// `None` when there was nothing to publish.
pub fn sync_dirty_mob_effects<T>(
    living_base: &LivingEntityBase,
    entity_data: &SyncMutex<T>,
) -> Option<MobEffectDisplayState>
where
    T: VanillaLivingEntityData + Send + Sync,
    SyncMutex<T>: EntitySyncedData,
{
    if !living_base.take_effects_dirty() {
        return None;
    }

    let display = living_base.mob_effect_display_state();
    {
        let mut entity_data = entity_data.lock();
        let living = entity_data.living_entity_mut();
        living.effect_particles.set(display.particles.clone());
        living.effect_ambience.set(display.ambient);
    }
    entity_data.set_base_invisible_flag(display.invisible);
    Some(display)
}