ghast_entity/lib.rs
1//! Entity tracking for the ghast Minecraft Java Edition client library (1.8.9, 1.12.2, 1.16.5
2//! 26.1 and 26.2).
3//!
4//! [`v1_8::Tracker`] / [`v1_12::Tracker`] / [`v1_16_5::Tracker`] / `v26_1::Tracker` take raw
5//! clientbound play packets
6//! ([`ghast_protocol::RawPacket`]) and keep every entity the server announced, keyed by id:
7//! type, UUID, **server position** (exactly as the vanilla client tracks it from the packets,
8//! with each version's fixed-point rules), rotation, last velocity, on-ground, riding / leash
9//! links, and optionally metadata, equipment, effects and the tab list.
10//!
11//! - **Cheap.** Packets are parsed by hand straight from the packet body; movement, look,
12//! teleport, velocity, head-rotation and destroy packets do not allocate. Lookups are one hash
13//! of the id. Parts nobody needs are switched off in [`Config`], and `Tracker::wants(id)` /
14//! `packet_ids()` tell the client which packets it can drop before decoding.
15//! - **Vanilla semantics.** Spawns replace an existing id, unknown types spawn nothing, moves
16//! for unknown ids are ignored, `login` and world changes clear everything, pickups remove
17//! the item (1.16: when its stack runs out), riding follows each version's rules.
18//! - **Never panics on server data**: malformed bodies return a [`ghast_protocol::DecodeError`].
19//!
20//! ```
21//! use ghast_entity::{Config, v1_8::Tracker};
22//! let tracker = Tracker::new(Config::default());
23//! assert!(tracker.get(42).is_none());
24//! ```
25
26#![forbid(unsafe_code)]
27#![warn(missing_docs, unnameable_types)]
28// A build with only some versions leaves helpers of the others unused.
29#![cfg_attr(
30 not(all(
31 feature = "v1_8",
32 feature = "v1_12",
33 feature = "v1_16_5",
34 feature = "v26_1",
35 feature = "v26_2"
36 )),
37 allow(dead_code)
38)]
39// A build with no version at all keeps only the shared store.
40#![cfg_attr(
41 not(any(
42 feature = "v1_8",
43 feature = "v1_12",
44 feature = "v1_16_5",
45 feature = "v26_1",
46 feature = "v26_2"
47 )),
48 allow(unused_imports, unused_variables)
49)]
50
51#[cfg(feature = "v1_16_5")]
52mod client16;
53mod common;
54mod entity;
55#[cfg(any(feature = "v26_1", feature = "v26_2"))]
56mod modern_state;
57mod store;
58#[cfg(feature = "v1_12")]
59pub mod v1_12;
60#[cfg(feature = "v1_16_5")]
61pub mod v1_16_5;
62#[cfg(feature = "v1_8")]
63pub mod v1_8;
64
65/// The modern tracker source (`src/v26_1.rs`) compiled for protocol 775: `data` and `proto`
66/// name that protocol's `ghast-data` and `ghast-protocol` modules.
67#[cfg(feature = "v26_1")]
68#[path = "."]
69mod modern_775 {
70 pub(crate) use ghast_data::v26_1 as data;
71 use ghast_protocol::types::slot::v775::ItemStack;
72 pub(crate) use ghast_protocol::v26_1 as proto;
73
74 /// The entity era this instance stamps.
75 pub(crate) const ERA: crate::entity::Era = crate::entity::Era::V26;
76 /// Registry id of `minecraft:scale` in 26.1.
77 pub(crate) const SCALE_ATTRIBUTE_ID: i32 = 25;
78
79 /// A slot with 26.1's component codec.
80 #[inline]
81 pub(crate) fn read_stack(
82 r: &mut ghast_protocol::Reader<'_>,
83 ) -> crate::common::R<Option<ItemStack>> {
84 ItemStack::read(r)
85 }
86
87 #[path = "v26_1.rs"]
88 pub mod tracker;
89}
90#[cfg(feature = "v26_1")]
91#[doc(inline)]
92pub use modern_775::tracker as v26_1;
93
94/// The same tracker source for protocol 776 (26.2): ids, sizes and the slot codec come from
95/// `ghast_data::v26_2` / `ghast_protocol::v26_2`; the entity data serializers are unchanged.
96#[cfg(feature = "v26_2")]
97#[path = "."]
98mod modern_776 {
99 pub(crate) use ghast_data::v26_2 as data;
100 use ghast_protocol::types::slot::v775::ItemStack;
101 pub(crate) use ghast_protocol::v26_2 as proto;
102
103 /// The entity era this instance stamps.
104 pub(crate) const ERA: crate::entity::Era = crate::entity::Era::V26_2;
105 /// Registry id of `minecraft:scale` in 26.2 (`minecraft:attribute` gained entries before it).
106 pub(crate) const SCALE_ATTRIBUTE_ID: i32 = 30;
107
108 /// A slot with 26.2's component codec.
109 #[inline]
110 pub(crate) fn read_stack(
111 r: &mut ghast_protocol::Reader<'_>,
112 ) -> crate::common::R<Option<ItemStack>> {
113 ItemStack::read_776(r)
114 }
115
116 #[allow(clippy::duplicate_mod)]
117 #[path = "v26_1.rs"]
118 pub mod tracker;
119}
120#[cfg(feature = "v26_2")]
121#[doc(inline)]
122pub use modern_776::tracker as v26_2;
123
124pub use entity::{
125 EQUIPMENT_SLOTS, Effect, Entity, EntityClass, EntityType, Item, MetaValue, Metadata,
126};
127pub use store::{Config, Entities, Event, PlayerInfo};
128
129/// What applying a packet did.
130#[derive(Clone, Copy, Debug, PartialEq, Eq)]
131pub enum Applied {
132 /// Tracked state changed.
133 Changed,
134 /// Valid, but nothing changed (unknown entity id, unknown type, the bot's own position, ...).
135 Ignored,
136 /// Not a packet this tracker handles (or one its configuration does not want).
137 NotEntityPacket,
138}