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)]
97pub enum Event {
98    /// A new entity (or a replacement for an existing id).
99    Spawned(i32),
100    /// An entity was removed (destroy, pickup, world change).
101    Removed {
102        /// Id.
103        id: i32,
104        /// Its type.
105        ty: EntityType,
106    },
107    /// Server position or rotation changed (movement, teleport).
108    Moved(i32),
109    /// Velocity changed.
110    Velocity(i32),
111    /// `entity_status` (e.g. 2 hurt, 3 death).
112    Status {
113        /// Id.
114        id: i32,
115        /// Status byte.
116        status: i8,
117    },
118    /// Metadata changed.
119    Metadata(i32),
120    /// Equipment changed.
121    Equipment(i32),
122    /// Effects changed.
123    Effects(i32),
124    /// Riding changed: `id` now rides `vehicle`.
125    Mounted {
126        /// Rider.
127        id: i32,
128        /// Vehicle (`None` = dismounted).
129        vehicle: Option<i32>,
130    },
131    /// An item / orb / arrow was picked up (`collector` may be the bot).
132    Collected {
133        /// Picked-up entity.
134        collected: i32,
135        /// Collector.
136        collector: i32,
137    },
138    /// The tab list changed.
139    PlayerList,
140}
141
142/// A tab-list entry (`#[non_exhaustive]`: read-only for callers, fields may be added).
143#[derive(Clone, Debug, PartialEq, Eq)]
144#[non_exhaustive]
145pub struct PlayerInfo {
146    /// Profile name.
147    pub name: Box<str>,
148    /// Game mode.
149    pub game_mode: i32,
150    /// Latency in ms.
151    pub ping: i32,
152    /// Display name (raw chat JSON), if set.
153    pub display_name: Option<Box<str>>,
154    /// The base64 `"textures"` profile property as sent (only with [`Config::skins`]; its
155    /// signature is not kept). Decoded it is JSON with the skin and cape URLs.
156    pub textures: Option<Box<str>>,
157}
158
159#[derive(Default, Clone, Copy)]
160pub(crate) struct IdHasher(u64);
161
162impl Hasher for IdHasher {
163    #[inline]
164    fn finish(&self) -> u64 {
165        let h = self.0.wrapping_mul(0x9E37_79B9_7F4A_7C15);
166        h ^ (h >> 29)
167    }
168
169    #[inline]
170    fn write(&mut self, bytes: &[u8]) {
171        for &b in bytes {
172            self.0 = (self.0 << 8) | u64::from(b);
173        }
174    }
175
176    #[inline]
177    fn write_i32(&mut self, v: i32) {
178        self.0 = u64::from(v as u32);
179    }
180
181    #[inline]
182    fn write_u128(&mut self, v: u128) {
183        self.0 = (v as u64) ^ ((v >> 64) as u64);
184    }
185}
186
187type Fast<K, V> = HashMap<K, V, BuildHasherDefault<IdHasher>>;
188
189/// The tracked entities and tab list (queries are the same for every version).
190#[derive(Clone, Debug, Default)]
191pub struct Entities {
192    pub(crate) map: Fast<i32, Entity>,
193    pub(crate) self_id: Option<i32>,
194    pub(crate) config: Config,
195    pub(crate) events: Vec<Event>,
196    pub(crate) players: Fast<Uuid, PlayerInfo>,
197    pub(crate) scratch: Vec<(u8, MetaValue)>,
198    /// Set once any leash link exists (skips the leash scan on removal otherwise).
199    pub(crate) any_leash: bool,
200    /// 1.16 tracker (selects the vanilla size table).
201    pub(crate) modern: bool,
202}
203
204impl Entities {
205    pub(crate) fn new(config: Config) -> Self {
206        Entities {
207            config,
208            ..Default::default()
209        }
210    }
211
212    /// The entity with this id (including the bot's own entry, see [`Entities::self_id`]).
213    #[inline]
214    #[must_use]
215    pub fn get(&self, id: i32) -> Option<&Entity> {
216        self.map.get(&id)
217    }
218
219    /// Number of tracked entities (including the bot's own entry).
220    #[must_use]
221    pub fn len(&self) -> usize {
222        self.map.len()
223    }
224
225    /// `true` when nothing is tracked.
226    #[must_use]
227    pub fn is_empty(&self) -> bool {
228        self.map.is_empty()
229    }
230
231    /// Other entities (the bot's own entry is skipped), arbitrary order.
232    pub fn iter(&self) -> impl Iterator<Item = &Entity> {
233        let me = self.self_id;
234        self.map.values().filter(move |e| Some(e.id) != me)
235    }
236
237    /// The bot's own entity id (from `login`). Its entry carries metadata, effects, equipment
238    /// and riding state, but **no position**: the client owns its own position.
239    #[must_use]
240    pub fn self_id(&self) -> Option<i32> {
241        self.self_id
242    }
243
244    /// The bot's own entry.
245    #[must_use]
246    pub fn me(&self) -> Option<&Entity> {
247        self.map.get(&self.self_id?)
248    }
249
250    /// Entities whose server position is within `radius` of `p` (linear scan).
251    pub fn within(&self, p: [f64; 3], radius: f64) -> impl Iterator<Item = &Entity> {
252        let r2 = radius * radius;
253        self.iter().filter(move |e| {
254            let d = [e.pos[0] - p[0], e.pos[1] - p[1], e.pos[2] - p[2]];
255            d[0] * d[0] + d[1] * d[1] + d[2] * d[2] <= r2
256        })
257    }
258
259    /// Alias of [`Entities::within`].
260    pub fn near(&self, p: [f64; 3], radius: f64) -> impl Iterator<Item = &Entity> {
261        self.within(p, radius)
262    }
263
264    /// The tab list.
265    #[must_use]
266    pub fn player_info(&self, uuid: &Uuid) -> Option<&PlayerInfo> {
267        self.players.get(uuid)
268    }
269
270    /// All tab-list entries.
271    pub fn players(&self) -> impl Iterator<Item = (&Uuid, &PlayerInfo)> {
272        self.players.iter()
273    }
274
275    /// Name of a player entity (from the tab list).
276    #[must_use]
277    pub fn player_name(&self, id: i32) -> Option<&str> {
278        let e = self.map.get(&id)?;
279        e.is_player()
280            .then(|| self.players.get(&e.uuid).map(|p| &*p.name))
281            .flatten()
282    }
283
284    /// The configuration.
285    #[must_use]
286    pub fn config(&self) -> Config {
287        self.config
288    }
289
290    /// Takes the queued events (keeps the buffer's capacity).
291    pub fn drain_events(&mut self) -> std::vec::Drain<'_, Event> {
292        self.events.drain(..)
293    }
294
295    /// Removes every entity (keeps the tab list and the bot's id).
296    pub fn clear(&mut self) {
297        if self.config.events {
298            let me = self.self_id;
299            self.events.extend(
300                self.map
301                    .values()
302                    .filter(|e| Some(e.id) != me)
303                    .map(|e| Event::Removed { id: e.id, ty: e.ty }),
304            );
305        }
306        let me = self.self_id.and_then(|id| self.map.remove(&id));
307        self.map.clear();
308        if let Some(mut me) = me {
309            me.vehicle = None;
310            me.passengers.clear();
311            me.leash_holder = None;
312            self.map.insert(me.id, me);
313        }
314    }
315
316    #[inline]
317    pub(crate) fn event(&mut self, e: Event) {
318        if self.config.events {
319            self.events.push(e);
320        }
321    }
322
323    pub(crate) fn set_self(&mut self, id: i32) {
324        if let Some(old) = self.self_id {
325            self.map.remove(&old);
326        }
327        self.self_id = Some(id);
328        let mut me = Entity::new(id, EntityType::Player);
329        me.sizer = if self.modern {
330            crate::v1_16_5::vanilla_size(&me).map(|v| (v, true))
331        } else {
332            crate::v1_8::vanilla_size(&me).map(|v| (v, false))
333        };
334        self.map.insert(id, me);
335    }
336
337    /// Adds an entity, replacing (and unlinking) any entity with the same id, as vanilla does.
338    pub(crate) fn spawn(&mut self, mut e: Entity) {
339        let id = e.id;
340        e.sizer = if self.modern {
341            crate::v1_16_5::vanilla_size(&e).map(|v| (v, true))
342        } else {
343            crate::v1_8::vanilla_size(&e).map(|v| (v, false))
344        };
345        if Some(id) == self.self_id {
346            return;
347        }
348        if self.map.contains_key(&id) {
349            self.unlink(id);
350        }
351        self.map.insert(id, e);
352        self.event(Event::Spawned(id));
353    }
354
355    pub(crate) fn remove(&mut self, id: i32) -> bool {
356        if Some(id) == self.self_id || !self.map.contains_key(&id) {
357            return false;
358        }
359        self.unlink(id);
360        if let Some(e) = self.map.remove(&id) {
361            self.event(Event::Removed { id, ty: e.ty });
362        }
363        true
364    }
365
366    /// Detaches `id` from its vehicle, passengers and leash links.
367    fn unlink(&mut self, id: i32) {
368        let Some(e) = self.map.get_mut(&id) else {
369            return;
370        };
371        let vehicle = e.vehicle.take();
372        let passengers = std::mem::take(&mut e.passengers);
373        if let Some(v) = vehicle
374            && let Some(v) = self.map.get_mut(&v)
375        {
376            v.passengers.retain(|&p| p != id);
377        }
378        for p in passengers {
379            if let Some(p) = self.map.get_mut(&p)
380                && p.vehicle == Some(id)
381            {
382                p.vehicle = None;
383            }
384        }
385        if self.any_leash {
386            for other in self.map.values_mut() {
387                if other.leash_holder == Some(id) {
388                    other.leash_holder = None;
389                }
390            }
391        }
392    }
393
394    /// `true` when `vehicle` is `rider` or (indirectly) rides `rider`.
395    fn rides(&self, vehicle: i32, rider: i32) -> bool {
396        let mut cur = Some(vehicle);
397        let mut guard = 0;
398        while let Some(c) = cur {
399            if c == rider {
400                return true;
401            }
402            guard += 1;
403            if guard > 64 {
404                return true;
405            }
406            cur = self.map.get(&c).and_then(|e| e.vehicle);
407        }
408        false
409    }
410
411    /// Makes `rider` ride `vehicle` (or dismount with `None`). `single` = 1.8 semantics (one
412    /// rider per vehicle: a previous rider is dismounted). Returns `false` when ignored.
413    pub(crate) fn mount(&mut self, rider: i32, vehicle: Option<i32>, single: bool) -> bool {
414        if !self.map.contains_key(&rider) {
415            return false;
416        }
417        if let Some(v) = vehicle
418            && (!self.map.contains_key(&v) || self.rides(v, rider))
419        {
420            return false;
421        }
422        // Leave the old vehicle.
423        let old = self.map.get_mut(&rider).and_then(|e| e.vehicle.take());
424        if let Some(o) = old
425            && let Some(o) = self.map.get_mut(&o)
426        {
427            o.passengers.retain(|&p| p != rider);
428        }
429        if let Some(v) = vehicle {
430            let prev: Vec<i32> = if single {
431                self.map
432                    .get_mut(&v)
433                    .map(|e| std::mem::take(&mut e.passengers))
434                    .unwrap_or_default()
435            } else {
436                Vec::new()
437            };
438            for p in prev {
439                if let Some(p) = self.map.get_mut(&p) {
440                    p.vehicle = None;
441                }
442            }
443            if let Some(ve) = self.map.get_mut(&v) {
444                ve.passengers.push(rider);
445            }
446            if let Some(r) = self.map.get_mut(&rider) {
447                r.vehicle = Some(v);
448            }
449        }
450        self.event(Event::Mounted { id: rider, vehicle });
451        true
452    }
453
454    /// 1.16 `set_passengers`: ejects every current passenger of `vehicle`, then mounts `ids`.
455    pub(crate) fn set_passengers(&mut self, vehicle: i32, ids: impl Iterator<Item = i32>) -> bool {
456        let Some(v) = self.map.get_mut(&vehicle) else {
457            return false;
458        };
459        let old = std::mem::take(&mut v.passengers);
460        for p in &old {
461            if let Some(p) = self.map.get_mut(p)
462                && p.vehicle == Some(vehicle)
463            {
464                p.vehicle = None;
465            }
466        }
467        // Reuse the old buffer for the new list (no allocation in steady state).
468        let mut old = old;
469        old.clear();
470        if let Some(v) = self.map.get_mut(&vehicle) {
471            v.passengers = old;
472        }
473        for id in ids {
474            self.mount(id, Some(vehicle), false);
475        }
476        true
477    }
478
479    pub(crate) fn leash(&mut self, id: i32, holder: Option<i32>) -> bool {
480        match self.map.get_mut(&id) {
481            Some(e) => {
482                e.leash_holder = holder;
483                self.any_leash |= holder.is_some();
484                true
485            }
486            None => false,
487        }
488    }
489}
490
491#[cfg(test)]
492mod tests {
493    use super::*;
494
495    fn store() -> Entities {
496        let mut s = Entities::new(Config {
497            events: true,
498            ..Config::default()
499        });
500        for id in 1..=4 {
501            s.spawn(Entity::new(id, EntityType::Registry(6)));
502        }
503        s
504    }
505
506    #[test]
507    fn mount_single_and_multi() {
508        let mut s = store();
509        assert!(s.mount(1, Some(2), true));
510        assert!(s.mount(3, Some(2), true)); // 1.8: replaces rider 1
511        assert_eq!(s.get(2).unwrap().passengers(), &[3]);
512        assert_eq!(s.get(1).unwrap().vehicle(), None);
513        assert!(!s.mount(2, Some(3), true), "cycle");
514        assert!(s.set_passengers(4, [1, 3].into_iter()));
515        assert_eq!(s.get(4).unwrap().passengers(), &[1, 3]);
516        assert_eq!(s.get(2).unwrap().passengers(), &[] as &[i32]);
517        assert_eq!(s.get(3).unwrap().vehicle(), Some(4));
518        s.remove(4);
519        assert_eq!(s.get(1).unwrap().vehicle(), None);
520        assert_eq!(s.get(3).unwrap().vehicle(), None);
521    }
522
523    #[test]
524    fn self_entry_survives_clear() {
525        let mut s = store();
526        s.set_self(9);
527        s.spawn(Entity::new(9, EntityType::Registry(1))); // ignored: own id
528        assert_eq!(s.get(9).unwrap().entity_type(), EntityType::Player);
529        assert!(!s.remove(9));
530        s.drain_events().for_each(drop);
531        s.clear();
532        assert_eq!(s.len(), 1);
533        assert!(s.me().is_some());
534        assert_eq!(s.drain_events().count(), 4);
535        assert_eq!(s.iter().count(), 0);
536    }
537}