yog_entity/
lib.rs

1//! Entity access — a universal handle to *any* entity by UUID.
2//!
3//! In Minecraft most actions are entity-level (Player → LivingEntity → Entity):
4//! teleport, position, health... So Yog exposes them here, by UUID, for any
5//! entity. `Player` (in `yog-player`) is a thin wrapper that adds player-only
6//! things (inventory, networking) on top.
7
8use yog_core::Server;
9
10/// A handle to one entity by UUID, bound to a [`Server`].
11pub struct Entity<'a> {
12    server: &'a dyn Server,
13    uuid: String,
14}
15
16impl<'a> Entity<'a> {
17    /// Bind to the entity with this UUID on `server`.
18    pub fn new(server: &'a dyn Server, uuid: impl Into<String>) -> Self {
19        Self {
20            server,
21            uuid: uuid.into(),
22        }
23    }
24
25    pub fn uuid(&self) -> &str {
26        &self.uuid
27    }
28
29    /// Teleport to `(x, y, z)` within the entity's current world.
30    pub fn teleport(&self, x: f64, y: f64, z: f64) -> bool {
31        self.server.entity_teleport(&self.uuid, x, y, z)
32    }
33
34    /// Current position, or `None` if the entity isn't loaded.
35    /// Yaw and pitch in degrees, or `None` if the entity does not exist.
36    pub fn rotation(&self) -> Option<(f32, f32)> {
37        self.server.entity_rotation(&self.uuid)
38    }
39
40    /// Unit look vector derived from yaw/pitch (Minecraft convention).
41    pub fn look_vector(&self) -> Option<(f64, f64, f64)> {
42        let (yaw, pitch) = self.rotation()?;
43        let (yaw, pitch) = ((yaw as f64).to_radians(), (pitch as f64).to_radians());
44        let cos_p = pitch.cos();
45        Some((-yaw.sin() * cos_p, -pitch.sin(), yaw.cos() * cos_p))
46    }
47
48    pub fn position(&self) -> Option<(f64, f64, f64)> {
49        self.server.entity_position(&self.uuid)
50    }
51
52    /// Health (living entities only), or `None`.
53    pub fn health(&self) -> Option<f32> {
54        self.server.entity_health(&self.uuid)
55    }
56
57    /// Set health (living entities only); returns whether it applied.
58    pub fn set_health(&self, health: f32) -> bool {
59        self.server.entity_set_health(&self.uuid, health)
60    }
61
62    /// Remove/kill the entity.
63    pub fn kill(&self) -> bool {
64        self.server.entity_kill(&self.uuid)
65    }
66
67    // ── status effects ──────────────────────────────────────────────────────
68
69    /// Apply a status effect. `effect_id` is a registry id like
70    /// `"minecraft:speed"`. `amplifier` is 0-based (0 = level I).
71    pub fn add_effect(
72        &self,
73        effect_id: &str,
74        duration_ticks: i32,
75        amplifier: u8,
76        show_particles: bool,
77    ) -> bool {
78        self.server.entity_add_effect(
79            &self.uuid,
80            effect_id,
81            duration_ticks,
82            amplifier,
83            show_particles,
84        )
85    }
86
87    /// Remove a single status effect.
88    pub fn remove_effect(&self, effect_id: &str) -> bool {
89        self.server.entity_remove_effect(&self.uuid, effect_id)
90    }
91
92    /// Clear all active status effects.
93    pub fn clear_effects(&self) -> bool {
94        self.server.entity_clear_effects(&self.uuid)
95    }
96
97    // ── velocity ────────────────────────────────────────────────────────────
98
99    /// Current velocity `(vx, vy, vz)`, or `None` if not loaded.
100    pub fn velocity(&self) -> Option<(f64, f64, f64)> {
101        self.server.entity_velocity(&self.uuid)
102    }
103
104    /// Set velocity directly (replaces current velocity).
105    pub fn set_velocity(&self, vx: f64, vy: f64, vz: f64) -> bool {
106        self.server.entity_set_velocity(&self.uuid, vx, vy, vz)
107    }
108
109    /// Add an impulse to the current velocity (e.g. launch upward: `add_velocity(0, 1, 0)`).
110    pub fn add_velocity(&self, vx: f64, vy: f64, vz: f64) -> bool {
111        self.server.entity_add_velocity(&self.uuid, vx, vy, vz)
112    }
113
114    // ── NBT ─────────────────────────────────────────────────────────────────
115
116    /// SNBT string of the entity's persistent NBT, or `None` if not found.
117    pub fn get_nbt(&self) -> Option<String> {
118        self.server.entity_get_nbt(&self.uuid)
119    }
120
121    /// Merge SNBT data into the entity's persistent NBT. Returns `false` if not found.
122    pub fn set_nbt(&self, snbt: &str) -> bool {
123        self.server.entity_set_nbt(&self.uuid, snbt)
124    }
125
126    // ── attributes ───────────────────────────────────────────────────────────
127
128    /// Base value of an attribute (e.g. `"minecraft:generic.max_health"`), or `None`.
129    pub fn attribute_get(&self, attribute_id: &str) -> Option<f64> {
130        self.server.entity_attribute_get(&self.uuid, attribute_id)
131    }
132
133    /// Set the base value of an attribute. Returns `false` if not found.
134    pub fn attribute_set(&self, attribute_id: &str, value: f64) -> bool {
135        self.server
136            .entity_attribute_set(&self.uuid, attribute_id, value)
137    }
138}
yog_entity/lib.rs

yog_entity/
lib.rs
