steel_core/entity/entities/objects/projectiles/

ender_pearl.rs

//! Thrown ender pearl projectile entity (`ThrownEnderpearl`).
//!
//! Mirrors vanilla `ThrownEnderpearl` (yarn `EnderPearlEntity`) on the Steel
//! `Projectile → ThrowableProjectile → ThrowableItemProjectile` trait stack.
//! On collision it teleports its owning player to the pearl's pre-move position,
//! deals 5.0 `ender_pearl` damage, plays the teleport sound, and discards itself.
//!
//! The pearl refreshes a timeout chunk ticket (`TicketType.ENDER_PEARL`) each tick
//! so it keeps flying across the simulation border, and is registered on its owning
//! player so it persists with them and re-spawns on login (vanilla
//! `ServerPlayer.enderPearls`).

use std::sync::{Arc, Weak};

use glam::DVec3;
use simdnbt::borrow::NbtCompound as BorrowedNbtCompoundView;
use simdnbt::owned::NbtCompound;
use steel_macros::entity_behavior;
use steel_protocol::packets::game::{RelativeMovement, SoundSource};
use steel_registry::entity_type::EntityTypeRef;
use steel_registry::item_stack::ItemStack;
use steel_registry::items::ItemRef;
use steel_registry::vanilla_entity_data::EnderPearlEntityData;
use steel_registry::vanilla_game_rules::{ENDER_PEARLS_VANISH_ON_DEATH, SPAWN_MOBS};
use steel_registry::{sound_events, vanilla_damage_types, vanilla_entities, vanilla_items};
use steel_utils::ChunkPos;
use steel_utils::locks::SyncMutex;
use steel_utils::{BlockPos, Downcast as _, DowncastType, DowncastTypeKey};

use crate::chunk::chunk_map::ENDER_PEARL_TICKET_TIMEOUT;
use crate::entity::damage::DamageSource;
use crate::entity::entities::EndermiteEntity;
use crate::entity::{
    ENTITIES, Entity, EntityBase, EntityBaseLoad, EntitySyncedData, LivingEntity, Projectile,
    ProjectileBase, ProjectileHit, RemovalReason, SharedEntity, ThrowableItemProjectile,
    ThrowableProjectile, change_entity_world, next_entity_id,
};
use crate::player::Player;
use crate::portal::{TeleportPostTransition, TeleportTransition};
use crate::world::World;

/// Fall-style damage dealt to the teleporting owner (vanilla `enderPearl()`, 5.0).
const TELEPORT_DAMAGE: f32 = 5.0;

/// Spawn chance for an endermite on impact (5% in vanilla `ThrownEnderpearl`).
const ENDERMITE_SPAWN_CHANCE: f32 = 0.05;

/// A thrown ender pearl.
#[entity_behavior(class = "ThrownEnderpearl")]
pub struct EnderPearlEntity {
    /// Common entity fields (id, uuid, position, etc.).
    base: EntityBase,
    /// Vanilla entity type registered for this implementation.
    entity_type: EntityTypeRef,
    /// Synced data carrying the rendered item stack.
    entity_data: SyncMutex<EnderPearlEntityData>,
    /// Shared `Projectile` state (owner / left-owner / has-been-shot).
    projectile_base: ProjectileBase,
    /// Countdown until the chunk-loading ticket is refreshed (vanilla `ticketTimer`).
    ticket_timer: SyncMutex<i64>,
}

// SAFETY: This key is owned by Steel and uniquely identifies `EnderPearlEntity`.
unsafe impl DowncastType for EnderPearlEntity {
    const TYPE_KEY: DowncastTypeKey = DowncastTypeKey::new("steel:entity/ender_pearl");
}

impl EnderPearlEntity {
    /// Creates a new ender pearl with no owner and the default rendered item.
    #[must_use]
    pub fn new(entity_type: EntityTypeRef, id: i32, position: DVec3, world: Weak<World>) -> Self {
        Self {
            base: EntityBase::new(id, position, entity_type.dimensions, world),
            entity_type,
            entity_data: SyncMutex::new(EnderPearlEntityData::new()),
            projectile_base: ProjectileBase::new(),
            ticket_timer: SyncMutex::new(0),
        }
    }

    /// Creates an ender pearl from saved base data.
    #[must_use]
    pub fn from_saved(entity_type: EntityTypeRef, load: EntityBaseLoad) -> Self {
        Self {
            base: EntityBase::from_load(load, entity_type.dimensions),
            entity_type,
            entity_data: SyncMutex::new(EnderPearlEntityData::new()),
            projectile_base: ProjectileBase::new(),
            ticket_timer: SyncMutex::new(0),
        }
    }

    /// Resolves the owner as an online player, including cached cross-world refs.
    fn owner_player(&self) -> Option<SharedEntity> {
        let owner = self.get_owner()?;
        owner.as_player()?;
        Some(owner)
    }

    /// Removes this pearl from its owner's persistence set when it hits or is
    /// discarded (vanilla `ThrownEnderpearl.onRemoval` deregistration).
    fn deregister_from_owner(&self) {
        if let Some(owner) = self.owner_player()
            && let Some(player) = owner.as_player()
        {
            player.deregister_ender_pearl(self.uuid());
        }
    }

    /// Refreshes the chunk-loading ticket so the pearl keeps flying across the
    /// simulation border (vanilla `ThrownEnderpearl.tick` →
    /// `registerAndUpdateEnderPearlTicket`).
    ///
    /// Re-places the ticket when the countdown lapses or the pearl crosses a chunk
    /// border, but only while owned by an online player.
    fn update_ender_pearl_ticket(&self, world: &Arc<World>) {
        let current_chunk = ChunkPos::from_entity_pos(self.position());
        let crossed_border = ChunkPos::from_entity_pos(self.old_position()) != current_chunk;

        let mut timer = self.ticket_timer.lock();
        *timer -= 1;
        if *timer > 0 && !crossed_border {
            return;
        }

        let Some(owner) = self.owner_player() else {
            return;
        };
        let Some(player) = owner.as_player() else {
            return;
        };
        let Some(pearl) = world.get_entity_by_uuid(&self.uuid()) else {
            return;
        };
        if pearl.generation() != self.generation() {
            return;
        }

        player.register_ender_pearl(&pearl);
        world.chunk_map.place_ender_pearl_ticket(current_chunk);
        // Vanilla `registerAndUpdateEnderPearlTicket` returns `timeout - 1`.
        *timer = ENDER_PEARL_TICKET_TIMEOUT - 1;
    }

    /// Vanilla `ThrownEnderpearl.tick` owner-death short-circuit: a pearl whose
    /// owner is a dead player vanishes when the gamerule is set.
    fn should_vanish_on_owner_death(&self, world: &Arc<World>) -> bool {
        let Some(owner) = self.owner_player() else {
            return false;
        };
        let Some(player) = owner.as_player() else {
            return false;
        };
        // Vanilla checks `!owner.isAlive()` for a dead (but still connected) player.
        // `LivingEntity::is_alive` is the health-based override vanilla dispatches to.
        Self::should_vanish_for_owner_state(
            LivingEntity::is_alive(player),
            player.has_won_game(),
            world.get_game_rule(&ENDER_PEARLS_VANISH_ON_DEATH),
        )
    }

    const fn should_vanish_for_owner_state(
        owner_alive: bool,
        owner_won_game: bool,
        vanish_on_death_rule: bool,
    ) -> bool {
        !owner_alive && !owner_won_game && vanish_on_death_rule
    }

    /// Returns whether the owner may be teleported to: if still in the
    /// pearl's world they must be alive and not sleeping, otherwise a
    /// cross-dimension teleport requires portal permission.
    fn is_allowed_to_teleport_owner(world: &Arc<World>, player: &Player) -> bool {
        let player_world = player.get_world();
        if Arc::ptr_eq(&player_world, world) {
            return LivingEntity::is_alive(player) && !player.is_sleeping();
        }

        player.can_use_portal(true)
    }

    /// Teleports the owning player and applies the pearl's effects.
    fn teleport_owner(
        &self,
        world: &Arc<World>,
        owner: &SharedEntity,
        player: &Player,
        teleport_pos: DVec3,
    ) {
        if world.get_game_rule(&SPAWN_MOBS) && rand::random::<f32>() < ENDERMITE_SPAWN_CHANCE {
            let endermite = ENTITIES.create(
                &vanilla_entities::ENDERMITE,
                next_entity_id(),
                teleport_pos,
                Arc::downgrade(world),
            );
            if let Some(endermite) = endermite {
                if let Some(endermite_entity) = endermite.as_ref().downcast_ref::<EndermiteEntity>()
                {
                    endermite_entity.set_player_spawned(true);
                }
                let _ = world.try_add_entity(endermite);
            }
        }
        if self.is_on_portal_cooldown() {
            player.reset_portal_cooldown();
        }

        let transition = TeleportTransition {
            target_world: Arc::clone(world),
            position: teleport_pos,
            rotation: (0.0, 0.0),
            velocity: DVec3::ZERO,
            relatives: RelativeMovement::ROTATION.union(RelativeMovement::DELTA),
            portal_cooldown: player.portal_cooldown(),
            as_passenger: false,
            post_transition: TeleportPostTransition::do_nothing(),
        };
        let Some(new_owner) = change_entity_world(Arc::clone(owner), &transition) else {
            log::debug!("failed to teleport ender pearl owner {}", self.id());
            return;
        };
        let Some(new_player) = new_owner.as_player() else {
            return;
        };

        new_player.reset_fall_distance();
        new_player.reset_current_impulse_context();

        let damage = DamageSource::environment(&vanilla_damage_types::ENDER_PEARL);
        new_player.hurt(world, &damage, TELEPORT_DAMAGE);

        world.play_sound_at(
            &sound_events::ENTITY_PLAYER_TELEPORT,
            SoundSource::Players,
            teleport_pos,
            1.0,
            1.0,
            None,
        );
    }
}

impl Entity for EnderPearlEntity {
    fn base(&self) -> &EntityBase {
        &self.base
    }

    fn entity_type(&self) -> EntityTypeRef {
        self.entity_type
    }

    fn tick(self: Arc<Self>) {
        // Vanilla `ThrownEnderpearl.tick`: vanish if the owner died (gamerule),
        // otherwise run the throwable projectile movement/collision loop and keep
        // the pearl's chunk loaded via the ENDER_PEARL ticket.
        let Some(world) = self.level() else {
            self.throwable_projectile_tick();
            return;
        };

        if self.should_vanish_on_owner_death(&world) {
            self.deregister_from_owner();
            self.set_removed(RemovalReason::Discarded);
            return;
        }

        Arc::clone(&self).throwable_projectile_tick();

        if self.is_alive() {
            self.update_ender_pearl_ticket(&world);
        }
    }

    fn get_default_gravity(&self) -> f64 {
        self.throwable_default_gravity()
    }

    fn on_above_bubble_column(&self, drag_down: bool, pos: BlockPos) {
        self.default_on_above_bubble_column(drag_down, pos);
    }

    fn on_inside_bubble_column(&self, drag_down: bool) {
        self.default_on_inside_bubble_column(drag_down);
    }

    fn sound_source(&self) -> SoundSource {
        SoundSource::Neutral
    }

    fn spawn_data(&self) -> i32 {
        self.get_owner().map_or(0, |owner| owner.id())
    }

    fn restore_owner_reference(&self, owner: &SharedEntity) {
        self.cache_owner_entity(owner);
    }

    fn projectile_owner_uuid(&self) -> Option<uuid::Uuid> {
        self.owner_uuid()
    }

    fn projectile_owner(&self) -> Option<SharedEntity> {
        self.get_owner()
    }

    fn synced_data(&self) -> Option<&dyn EntitySyncedData> {
        Some(&self.entity_data)
    }

    fn save_additional(&self, nbt: &mut NbtCompound) {
        self.save_projectile(nbt);
        self.save_throwable_item(nbt);
    }

    fn load_additional(&self, nbt: BorrowedNbtCompoundView<'_, '_>) {
        self.load_projectile(nbt);
        self.load_throwable_item(nbt);
    }
}

impl Projectile for EnderPearlEntity {
    fn projectile_base(&self) -> &ProjectileBase {
        &self.projectile_base
    }

    fn on_hit_entity(self: Arc<Self>, entity: &SharedEntity, _location: DVec3) {
        // Vanilla `ThrownEnderpearl.onHitEntity`: deal 0 damage with a `thrown`
        // source so the hit entity registers the impact without being hurt.
        let mut damage = DamageSource::environment(&vanilla_damage_types::THROWN)
            .with_direct_entity(Arc::<Self>::clone(&self));
        if let Some(owner) = self.get_owner() {
            damage = damage.with_causing_entity(owner);
        }
        if let Some(world) = entity.level() {
            entity.hurt(&world, &damage, 0.0);
        }
    }

    fn on_hit(self: Arc<Self>, hit: &ProjectileHit) {
        // Vanilla `ThrownEnderpearl.onHit`: super.onHit() then teleport the owner.
        Arc::clone(&self).projectile_on_hit(hit);

        // VANILLA CLIENT-LOCAL: `ThrownEnderpearl.onHit` creates the 32 portal particles.
        let Some(world) = self.level() else {
            return;
        };
        if self.is_removed() {
            return;
        }

        let teleport_pos = self.old_position();
        if let Some(owner) = self.owner_player()
            && let Some(player) = owner.as_player()
            && Self::is_allowed_to_teleport_owner(&world, player)
        {
            self.teleport_owner(&world, &owner, player, teleport_pos);
        }
        self.deregister_from_owner();
        self.set_removed(RemovalReason::Discarded);
    }
}

impl ThrowableProjectile for EnderPearlEntity {}

impl ThrowableItemProjectile for EnderPearlEntity {
    fn get_default_item(&self) -> ItemRef {
        &vanilla_items::ENDER_PEARL
    }

    fn set_item(&self, item: ItemStack) {
        self.entity_data
            .lock()
            .throwable_item_projectile
            .item_stack
            .set(item);
    }

    fn get_item(&self) -> ItemStack {
        self.entity_data
            .lock()
            .throwable_item_projectile
            .item_stack
            .get()
            .clone()
    }
}

#[cfg(test)]
mod tests {
    use std::sync::{Arc, Weak};

    use glam::DVec3;
    use steel_registry::{init_vanilla_registry, vanilla_entities, vanilla_items};
    use steel_utils::{BlockPos, ChunkPos};

    use crate::entity::{Entity, Projectile, SharedEntity, ThrowableItemProjectile};
    use crate::player::Player;
    use crate::test_support::{TestPlayerBuilder, fresh_test_world, insert_ready_full_chunk};
    use crate::world::World;

    use super::EnderPearlEntity;

    #[test]
    fn shoot_aligns_velocity_with_direction() {
        init_vanilla_registry();

        let pearl = EnderPearlEntity::new(
            &vanilla_entities::ENDER_PEARL,
            1,
            DVec3::ZERO,
            Weak::<World>::new(),
        );
        pearl.shoot(DVec3::new(0.0, 0.0, 1.0), 1.5, 1.0);

        let velocity = pearl.velocity();
        assert!(velocity.z > 0.0);
        assert!((velocity.length() - 1.5).abs() < 0.1);
        assert!(velocity.x.abs() < 0.1 && velocity.y.abs() < 0.1);
    }

    #[test]
    fn owner_round_trips() {
        init_vanilla_registry();

        let pearl = EnderPearlEntity::new(
            &vanilla_entities::ENDER_PEARL,
            1,
            DVec3::ZERO,
            Weak::<World>::new(),
        );
        assert!(pearl.owner_uuid().is_none());

        let uuid = uuid::Uuid::from_u128(0x1234_5678_9abc_def0);
        pearl.set_owner_uuid(Some(uuid));
        assert_eq!(pearl.owner_uuid(), Some(uuid));
        assert_eq!(pearl.projectile_owner_uuid(), Some(uuid));
    }

    #[test]
    fn default_item_is_ender_pearl() {
        init_vanilla_registry();

        let pearl = EnderPearlEntity::new(
            &vanilla_entities::ENDER_PEARL,
            1,
            DVec3::ZERO,
            Weak::<World>::new(),
        );
        assert_eq!(pearl.get_default_item().key, vanilla_items::ENDER_PEARL.key);
    }

    #[test]
    fn owner_death_vanish_predicate_respects_won_game() {
        assert!(EnderPearlEntity::should_vanish_for_owner_state(
            false, false, true
        ));
        assert!(!EnderPearlEntity::should_vanish_for_owner_state(
            false, true, true
        ));
        assert!(!EnderPearlEntity::should_vanish_for_owner_state(
            true, false, true
        ));
        assert!(!EnderPearlEntity::should_vanish_for_owner_state(
            false, false, false
        ));
    }

    #[test]
    fn ticket_renewal_registers_with_the_resolved_owner() {
        init_vanilla_registry();

        let world_fixture = fresh_test_world("ender_pearl_ticket_owner");
        let world = &world_fixture.world;
        insert_ready_full_chunk(world, ChunkPos::new(0, 0));
        let player = TestPlayerBuilder::new(Arc::clone(world), "Owner", 1).build();
        let owner: SharedEntity = Arc::<Player>::clone(&player);
        let pearl = Arc::new(EnderPearlEntity::new(
            &vanilla_entities::ENDER_PEARL,
            2,
            DVec3::new(0.5, 64.0, 0.5),
            Arc::downgrade(world),
        ));
        pearl.set_owner_entity(Some(&owner));
        let shared_pearl: SharedEntity = Arc::<EnderPearlEntity>::clone(&pearl);
        if let Err(error) = world.try_add_entity(shared_pearl) {
            panic!("test pearl should be added: {error}");
        }

        assert!(player.ender_pearls().is_empty());
        pearl.update_ender_pearl_ticket(world);

        let registered = player.ender_pearls();
        assert_eq!(registered.len(), 1);
        assert_eq!(registered[0].generation(), pearl.generation());
    }

    #[test]
    fn bubble_column_uses_clamped_entity_behavior() {
        init_vanilla_registry();

        let pearl = EnderPearlEntity::new(
            &vanilla_entities::ENDER_PEARL,
            1,
            DVec3::ZERO,
            Weak::<World>::new(),
        );
        let entity: &dyn Entity = &pearl;

        for (above_column, drag_down, initial_y, expected_y) in [
            (true, false, 2.0, 1.8),
            (true, true, -2.0, -0.9),
            (false, false, 2.0, 0.7),
            (false, true, -2.0, -0.3),
        ] {
            entity.set_velocity(DVec3::new(0.25, initial_y, -0.25));
            entity.set_fall_distance(5.0);

            if above_column {
                entity.on_above_bubble_column(drag_down, BlockPos::new(0, 0, 0));
            } else {
                entity.on_inside_bubble_column(drag_down);
            }

            let expected = DVec3::new(0.25, expected_y, -0.25);
            let actual = entity.velocity();

            assert!(
                (actual - expected).abs().max_element() < 1.0e-12,
                "above_column={above_column}, drag_down={drag_down}: \
                 expected {expected:?}, got {actual:?}"
            );

            let expected_fall_distance = if above_column { 5.0 } else { 0.0 };
            assert!(
                (entity.fall_distance() - expected_fall_distance).abs() < 1.0e-12,
                "above_column={above_column}, drag_down={drag_down}: \
                 unexpected fall distance"
            );
        }
    }
}