Skip to main content

ghast_entity/
store.rs

1//! Version-independent entity store shared by the per-version trackers.
2
3use std::collections::HashMap;
4use std::hash::{BuildHasherDefault, Hasher};
5
6use uuid::Uuid;
7
8use crate::entity::{Entity, EntityType, MetaValue};
9
10/// What the tracker keeps. Everything off costs nothing beyond position tracking; packets for a
11/// disabled part are not parsed (and the client should not even decode them, see the version
12/// modules' packet id lists).
13///
14/// `#[non_exhaustive]`: build it from [`Config::default`] with the `with_*` methods:
15///
16/// ```
17/// let c = ghast_entity::Config::default().with_equipment(false).with_skins(true);
18/// assert!(c.metadata && !c.equipment && c.skins);
19/// ```
20#[derive(Clone, Copy, Debug, PartialEq, Eq)]
21#[non_exhaustive]
22pub struct Config {
23    /// Entity metadata (flags, health, item of item entities, names, ...). Default `true`.
24    pub metadata: bool,
25    /// Equipment. Default `true`.
26    pub equipment: bool,
27    /// Status effects. Default `true`.
28    pub effects: bool,
29    /// Tab list (`player_info`). Default `true`.
30    pub player_list: bool,
31    /// Queue [`Event`]s for [`Entities::drain_events`]. Default `false`.
32    pub events: bool,
33    /// Keep the base64 `"textures"` profile property (skin / cape URLs) of tab-list entries in
34    /// [`PlayerInfo::textures`]. Default `false`: properties are skipped without allocating.
35    pub skins: bool,
36}
37
38impl Config {
39    /// Sets [`Config::metadata`].
40    #[must_use]
41    pub const fn with_metadata(mut self, on: bool) -> Self {
42        self.metadata = on;
43        self
44    }
45
46    /// Sets [`Config::equipment`].
47    #[must_use]
48    pub const fn with_equipment(mut self, on: bool) -> Self {
49        self.equipment = on;
50        self
51    }
52
53    /// Sets [`Config::effects`].
54    #[must_use]
55    pub const fn with_effects(mut self, on: bool) -> Self {
56        self.effects = on;
57        self
58    }
59
60    /// Sets [`Config::player_list`].
61    #[must_use]
62    pub const fn with_player_list(mut self, on: bool) -> Self {
63        self.player_list = on;
64        self
65    }
66
67    /// Sets [`Config::events`].
68    #[must_use]
69    pub const fn with_events(mut self, on: bool) -> Self {
70        self.events = on;
71        self
72    }
73
74    /// Sets [`Config::skins`].
75    #[must_use]
76    pub const fn with_skins(mut self, on: bool) -> Self {
77        self.skins = on;
78        self
79    }
80}
81
82impl Default for Config {
83    fn default() -> Self {
84        Config {
85            metadata: true,
86            equipment: true,
87            effects: true,
88            player_list: true,
89            events: false,
90            skins: false,
91        }
92    }
93}
94
95/// A change notification (only queued with [`Config::events`]).
96#[derive(Clone, Copy, Debug, PartialEq, Eq)]
97#[non_exhaustive]
98pub enum Event {
99    /// A new entity (or a replacement for an existing id).
100    Spawned(i32),
101    /// An entity was removed (destroy, pickup, world change).
102    Removed {
103        /// Id.
104        id: i32,
105        /// Its type.
106        ty: EntityType,
107    },
108    /// Server position or rotation changed (movement, teleport).
109    Moved(i32),
110    /// Velocity changed.
111    Velocity(i32),
112    /// `entity_status` (e.g. 2 hurt, 3 death).
113    Status {
114        /// Id.
115        id: i32,
116        /// Status byte.
117        status: i8,
118    },
119    /// Metadata changed.
120    Metadata(i32),
121    /// Equipment changed.
122    Equipment(i32),
123    /// Effects changed.
124    Effects(i32),
125    /// Riding changed: `id` now rides `vehicle`.
126    Mounted {
127        /// Rider.
128        id: i32,
129        /// Vehicle (`None` = dismounted).
130        vehicle: Option<i32>,
131    },
132    /// An item / orb / arrow was picked up (`collector` may be the bot).
133    Collected {
134        /// Picked-up entity.
135        collected: i32,
136        /// Collector.
137        collector: i32,
138    },
139    /// The tab list changed.
140    PlayerList,
141}
142
143/// A tab-list entry (`#[non_exhaustive]`: read-only for callers, fields may be added).
144#[derive(Clone, Debug, PartialEq, Eq)]
145#[non_exhaustive]
146pub struct PlayerInfo {
147    /// Profile name.
148    pub name: Box<str>,
149    /// Game mode.
150    pub game_mode: i32,
151    /// Latency in ms.
152    pub ping: i32,
153    /// Display name (raw chat JSON), if set (1.8 – 1.16; see
154    /// [`PlayerInfo::display_name_nbt`] for 26.1).
155    pub display_name: Option<Box<str>>,
156    /// The base64 `"textures"` profile property as sent (only with [`Config::skins`]; its
157    /// signature is not kept). Decoded it is JSON with the skin and cape URLs.
158    pub textures: Option<Box<str>>,
159    /// 26.1: the display name as its raw network NBT text component, if set.
160    pub display_name_nbt: Option<bytes::Bytes>,
161    /// Shown in the tab list (26.1 `UPDATE_LISTED`; always `true` before 26.1).
162    pub listed: bool,
163    /// 26.1 tab list order (`UPDATE_LIST_ORDER`; 0 before).
164    pub list_order: i32,
165    /// Which tab list object this is (26.1 player entities keep the one they first saw).
166    pub(crate) generation: u32,
167}
168
169#[derive(Default, Clone, Copy)]
170pub(crate) struct IdHasher(u64);
171
172impl Hasher for IdHasher {
173    #[inline]
174    fn finish(&self) -> u64 {
175        let h = self.0.wrapping_mul(0x9E37_79B9_7F4A_7C15);
176        h ^ (h >> 29)
177    }
178
179    #[inline]
180    fn write(&mut self, bytes: &[u8]) {
181        for &b in bytes {
182            self.0 = (self.0 << 8) | u64::from(b);
183        }
184    }
185
186    #[inline]
187    fn write_i32(&mut self, v: i32) {
188        self.0 = u64::from(v as u32);
189    }
190
191    #[inline]
192    fn write_u64(&mut self, v: u64) {
193        self.0 = v;
194    }
195
196    #[inline]
197    fn write_u128(&mut self, v: u128) {
198        self.0 = (v as u64) ^ ((v >> 64) as u64);
199    }
200}
201
202pub(crate) type Fast<K, V> = HashMap<K, V, BuildHasherDefault<IdHasher>>;
203
204/// The tracked entities and tab list (queries are the same for every version).
205#[derive(Clone, Debug, Default)]
206pub struct Entities {
207    pub(crate) map: Fast<i32, Entity>,
208    pub(crate) self_id: Option<i32>,
209    pub(crate) config: Config,
210    pub(crate) events: Vec<Event>,
211    pub(crate) players: Fast<Uuid, PlayerInfo>,
212    pub(crate) scratch: Vec<(u8, MetaValue)>,
213    /// Set once any leash link exists (skips the leash scan on removal otherwise).
214    pub(crate) any_leash: bool,
215    /// The tracker's protocol family (selects the vanilla size table).
216    pub(crate) era: crate::entity::Era,
217    /// Last tab list object generation handed out.
218    pub(crate) generations: u32,
219}
220
221impl Entities {
222    pub(crate) fn new(config: Config) -> Self {
223        Entities {
224            config,
225            ..Default::default()
226        }
227    }
228
229    /// The entity with this id (including the bot's own entry, see [`Entities::self_id`]).
230    #[inline]
231    #[must_use]
232    pub fn get(&self, id: i32) -> Option<&Entity> {
233        self.map.get(&id)
234    }
235
236    /// Number of tracked entities (including the bot's own entry).
237    #[must_use]
238    pub fn len(&self) -> usize {
239        self.map.len()
240    }
241
242    /// `true` when nothing is tracked.
243    #[must_use]
244    pub fn is_empty(&self) -> bool {
245        self.map.is_empty()
246    }
247
248    /// Other entities (the bot's own entry is skipped), arbitrary order.
249    pub fn iter(&self) -> impl Iterator<Item = &Entity> {
250        let me = self.self_id;
251        self.map.values().filter(move |e| Some(e.id) != me)
252    }
253
254    /// The bot's own entity id (from `login`). Its entry carries metadata, effects, equipment
255    /// and riding state, but **no position**: the client owns its own position.
256    #[must_use]
257    pub fn self_id(&self) -> Option<i32> {
258        self.self_id
259    }
260
261    /// The bot's own entry.
262    #[must_use]
263    pub fn me(&self) -> Option<&Entity> {
264        self.map.get(&self.self_id?)
265    }
266
267    /// Entities whose server position is within `radius` of `p` (linear scan).
268    pub fn within(&self, p: [f64; 3], radius: f64) -> impl Iterator<Item = &Entity> {
269        let r2 = radius * radius;
270        self.iter().filter(move |e| {
271            let d = [e.pos[0] - p[0], e.pos[1] - p[1], e.pos[2] - p[2]];
272            d[0] * d[0] + d[1] * d[1] + d[2] * d[2] <= r2
273        })
274    }
275
276    /// Alias of [`Entities::within`].
277    pub fn near(&self, p: [f64; 3], radius: f64) -> impl Iterator<Item = &Entity> {
278        self.within(p, radius)
279    }
280
281    /// The tab list.
282    #[must_use]
283    pub fn player_info(&self, uuid: &Uuid) -> Option<&PlayerInfo> {
284        self.players.get(uuid)
285    }
286
287    /// All tab-list entries.
288    pub fn players(&self) -> impl Iterator<Item = (&Uuid, &PlayerInfo)> {
289        self.players.iter()
290    }
291
292    /// Name of a player entity (from the tab list).
293    #[must_use]
294    pub fn player_name(&self, id: i32) -> Option<&str> {
295        let e = self.map.get(&id)?;
296        e.is_player()
297            .then(|| self.players.get(&e.uuid).map(|p| &*p.name))
298            .flatten()
299    }
300
301    /// The configuration.
302    #[must_use]
303    pub fn config(&self) -> Config {
304        self.config
305    }
306
307    /// Takes the queued events (keeps the buffer's capacity).
308    pub fn drain_events(&mut self) -> std::vec::Drain<'_, Event> {
309        self.events.drain(..)
310    }
311
312    /// Removes every entity (keeps the tab list and the bot's id).
313    pub fn clear(&mut self) {
314        if self.config.events {
315            let me = self.self_id;
316            self.events.extend(
317                self.map
318                    .values()
319                    .filter(|e| Some(e.id) != me)
320                    .map(|e| Event::Removed { id: e.id, ty: e.ty }),
321            );
322        }
323        let me = self.self_id.and_then(|id| self.map.remove(&id));
324        self.map.clear();
325        if let Some(mut me) = me {
326            me.vehicle = None;
327            me.passengers.clear();
328            me.leash_holder = None;
329            self.map.insert(me.id, me);
330        }
331    }
332
333    #[inline]
334    pub(crate) fn event(&mut self, e: Event) {
335        if self.config.events {
336            self.events.push(e);
337        }
338    }
339
340    pub(crate) fn set_self(&mut self, id: i32) {
341        if let Some(old) = self.self_id {
342            self.map.remove(&old);
343        }
344        self.self_id = Some(id);
345        let mut me = Entity::new(id, EntityType::Player);
346        self.resolve(&mut me);
347        self.map.insert(id, me);
348    }
349
350    /// Stamps the protocol family and resolves the vanilla size entry.
351    fn resolve(&self, e: &mut Entity) {
352        use crate::entity::Era;
353        e.era = self.era;
354        e.sizer = match self.era {
355            #[cfg(feature = "v1_8")]
356            Era::V1_8 => crate::v1_8::vanilla_size(e),
357            #[cfg(feature = "v1_12")]
358            Era::V1_12 => crate::v1_12::vanilla_size(e),
359            #[cfg(feature = "v1_16_5")]
360            Era::V1_16 => crate::v1_16_5::vanilla_size(e),
361            #[cfg(feature = "v26_1")]
362            Era::V26 => crate::v26_1::vanilla_size(e),
363            #[cfg(feature = "v26_2")]
364            Era::V26_2 => crate::v26_2::vanilla_size(e),
365            #[allow(unreachable_patterns)]
366            _ => None,
367        };
368    }
369
370    /// Adds an entity, replacing (and unlinking) any entity with the same id, as vanilla does.
371    pub(crate) fn spawn(&mut self, mut e: Entity) {
372        let id = e.id;
373        self.resolve(&mut e);
374        if Some(id) == self.self_id {
375            return;
376        }
377        if self.map.contains_key(&id) {
378            self.unlink(id);
379        }
380        self.map.insert(id, e);
381        self.event(Event::Spawned(id));
382    }
383
384    pub(crate) fn remove(&mut self, id: i32) -> bool {
385        if Some(id) == self.self_id || !self.map.contains_key(&id) {
386            return false;
387        }
388        self.unlink(id);
389        if let Some(e) = self.map.remove(&id) {
390            self.event(Event::Removed { id, ty: e.ty });
391        }
392        true
393    }
394
395    /// Detaches `id` from its vehicle, passengers and leash links.
396    fn unlink(&mut self, id: i32) {
397        let Some(e) = self.map.get_mut(&id) else {
398            return;
399        };
400        let vehicle = e.vehicle.take();
401        let passengers = std::mem::take(&mut e.passengers);
402        if let Some(v) = vehicle
403            && let Some(v) = self.map.get_mut(&v)
404        {
405            v.passengers.retain(|&p| p != id);
406        }
407        for p in passengers {
408            if let Some(p) = self.map.get_mut(&p)
409                && p.vehicle == Some(id)
410            {
411                p.vehicle = None;
412            }
413        }
414        if self.any_leash {
415            for other in self.map.values_mut() {
416                if other.leash_holder == Some(id) {
417                    other.leash_holder = None;
418                }
419            }
420        }
421    }
422
423    /// `true` when `vehicle` is `rider` or (indirectly) rides `rider`.
424    fn rides(&self, vehicle: i32, rider: i32) -> bool {
425        let mut cur = Some(vehicle);
426        let mut guard = 0;
427        while let Some(c) = cur {
428            if c == rider {
429                return true;
430            }
431            guard += 1;
432            if guard > 64 {
433                return true;
434            }
435            cur = self.map.get(&c).and_then(|e| e.vehicle);
436        }
437        false
438    }
439
440    /// Makes `rider` ride `vehicle` (or dismount with `None`). `single` = 1.8 semantics (one
441    /// rider per vehicle: a previous rider is dismounted). Returns `false` when ignored.
442    pub(crate) fn mount(&mut self, rider: i32, vehicle: Option<i32>, single: bool) -> bool {
443        if !self.map.contains_key(&rider) {
444            return false;
445        }
446        if let Some(v) = vehicle
447            && (!self.map.contains_key(&v) || self.rides(v, rider))
448        {
449            return false;
450        }
451        // Leave the old vehicle.
452        let old = self.map.get_mut(&rider).and_then(|e| e.vehicle.take());
453        if let Some(o) = old
454            && let Some(o) = self.map.get_mut(&o)
455        {
456            o.passengers.retain(|&p| p != rider);
457        }
458        if let Some(v) = vehicle {
459            let prev: Vec<i32> = if single {
460                self.map
461                    .get_mut(&v)
462                    .map(|e| std::mem::take(&mut e.passengers))
463                    .unwrap_or_default()
464            } else {
465                Vec::new()
466            };
467            for p in prev {
468                if let Some(p) = self.map.get_mut(&p) {
469                    p.vehicle = None;
470                }
471            }
472            if let Some(ve) = self.map.get_mut(&v) {
473                ve.passengers.push(rider);
474            }
475            if let Some(r) = self.map.get_mut(&rider) {
476                r.vehicle = Some(v);
477            }
478        }
479        self.event(Event::Mounted { id: rider, vehicle });
480        true
481    }
482
483    /// 1.16 `set_passengers`: ejects every current passenger of `vehicle`, then mounts `ids`.
484    pub(crate) fn set_passengers(&mut self, vehicle: i32, ids: impl Iterator<Item = i32>) -> bool {
485        let Some(v) = self.map.get_mut(&vehicle) else {
486            return false;
487        };
488        let old = std::mem::take(&mut v.passengers);
489        for p in &old {
490            if let Some(p) = self.map.get_mut(p)
491                && p.vehicle == Some(vehicle)
492            {
493                p.vehicle = None;
494            }
495        }
496        // Reuse the old buffer for the new list (no allocation in steady state).
497        let mut old = old;
498        old.clear();
499        if let Some(v) = self.map.get_mut(&vehicle) {
500            v.passengers = old;
501        }
502        for id in ids {
503            self.mount(id, Some(vehicle), false);
504        }
505        true
506    }
507
508    pub(crate) fn leash(&mut self, id: i32, holder: Option<i32>) -> bool {
509        match self.map.get_mut(&id) {
510            Some(e) => {
511                e.leash_holder = holder;
512                self.any_leash |= holder.is_some();
513                true
514            }
515            None => false,
516        }
517    }
518}
519
520#[cfg(test)]
521mod tests {
522    use super::*;
523
524    fn store() -> Entities {
525        let mut s = Entities::new(Config {
526            events: true,
527            ..Config::default()
528        });
529        for id in 1..=4 {
530            s.spawn(Entity::new(id, EntityType::Registry(6)));
531        }
532        s
533    }
534
535    /// Bytes per tracked entity (the map slot adds the 4-byte key, padded).
536    #[test]
537    fn entity_size() {
538        let n = std::mem::size_of::<Entity>();
539        eprintln!("size_of::<Entity>() = {n}");
540        // 0.3.0: 232 bytes. The 26.1 state is boxed: one pointer in the entity.
541        let modern = cfg!(any(feature = "v26_1", feature = "v26_2"));
542        assert!(n <= if modern { 232 } else { 224 }, "{n}");
543        #[cfg(any(feature = "v26_1", feature = "v26_2"))]
544        {
545            let b = std::mem::size_of::<crate::modern_state::State>();
546            eprintln!("size_of::<modern_state::State>() = {b} (heap, 26.x entities only)");
547            assert!(b <= 120, "{b}");
548        }
549    }
550
551    #[test]
552    fn mount_single_and_multi() {
553        let mut s = store();
554        assert!(s.mount(1, Some(2), true));
555        assert!(s.mount(3, Some(2), true)); // 1.8: replaces rider 1
556        assert_eq!(s.get(2).unwrap().passengers(), &[3]);
557        assert_eq!(s.get(1).unwrap().vehicle(), None);
558        assert!(!s.mount(2, Some(3), true), "cycle");
559        assert!(s.set_passengers(4, [1, 3].into_iter()));
560        assert_eq!(s.get(4).unwrap().passengers(), &[1, 3]);
561        assert_eq!(s.get(2).unwrap().passengers(), &[] as &[i32]);
562        assert_eq!(s.get(3).unwrap().vehicle(), Some(4));
563        s.remove(4);
564        assert_eq!(s.get(1).unwrap().vehicle(), None);
565        assert_eq!(s.get(3).unwrap().vehicle(), None);
566    }
567
568    #[test]
569    fn self_entry_survives_clear() {
570        let mut s = store();
571        s.set_self(9);
572        s.spawn(Entity::new(9, EntityType::Registry(1))); // ignored: own id
573        assert_eq!(s.get(9).unwrap().entity_type(), EntityType::Player);
574        assert!(!s.remove(9));
575        s.drain_events().for_each(drop);
576        s.clear();
577        assert_eq!(s.len(), 1);
578        assert!(s.me().is_some());
579        assert_eq!(s.drain_events().count(), 4);
580        assert_eq!(s.iter().count(), 0);
581    }
582}