veloren_common/terrain/sprite/
magic.rs

1#[macro_export]
2macro_rules! sprites {
3    (
4        $($category_name:ident = $category_disc:literal $(has $($attr:ident),* $(,)?)? {
5            $($sprite_name:ident = $sprite_id:literal),* $(,)?
6        }),* $(,)?
7    ) => {
8        make_case_elim!(
9            category,
10            #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq, Serialize, Deserialize, EnumIter, FromPrimitive)]
11            #[repr(u32)]
12            pub enum Category {
13                $($category_name = $category_disc,)*
14            }
15        );
16
17        impl Category {
18            #[inline] pub const fn all() -> &'static [Self] {
19                &[$(Self::$category_name,)*]
20            }
21
22            #[cfg(test)]
23            #[inline] const fn all_sprites(&self) -> &'static [SpriteKind] {
24                match self {
25                    $(Self::$category_name => &[$(SpriteKind::$sprite_name,)*],)*
26                }
27            }
28
29            // Size, in bits, of the sprite ID
30            #[inline] pub const fn sprite_id_mask(&self) -> u32 {
31                match self {
32                    $(Self::$category_name => ((0u32 $(| $sprite_id)*) + 1).next_power_of_two() - 1,)*
33                }
34            }
35
36            // Size, in bits, of the sprite ID
37            #[inline] pub const fn sprite_id_size(&self) -> u32 { self.sprite_id_mask().count_ones() }
38
39            // The mask that, when applied to the block data, yields the sprite kind
40            #[inline(always)] pub const fn sprite_kind_mask(&self) -> u32 { 0x00FF0000 | self.sprite_id_mask() }
41
42            /// Note that this function assumes that the `BlockKind` of `block` permits sprite inhabitants
43            /// (i.e: is unfilled).
44            #[expect(non_upper_case_globals)]
45            #[inline] pub(super) const fn from_block(block: Block) -> Option<Self> {
46                $(const $category_name: u8 = Category::$category_name as u8;)*
47                match block.sprite_category_byte() {
48                    $($category_name => Some(Self::$category_name),)*
49                    _ => None,
50                }
51            }
52
53            // TODO: It would be nice to use `NonZeroU8` here for the space saving, but `0` is a valid
54            // offset for categories with only one SpriteKind (i.e: the sprite ID is zero-length and so
55            // attributes can go right up to the end of the block data). However, we could decide that an
56            // offset of, say, 0xFF (which would obviously be far out of bounds anyway) represents 'this
57            // attribute has no presence in this category'.
58            #[inline] pub const fn attr_offsets(&self) -> &[Option<u8>; Attributes::all().len()] {
59                match self {
60                    $(Self::$category_name => {
61                        #[allow(unused_mut, unused_variables, unused_assignments)]
62                        const fn gen_attr_offsets() -> [Option<u8>; Attributes::all().len()] {
63                            let mut lut = [None; Attributes::all().len()];
64                            // Don't take up space used by the sprite ID
65                            let mut offset = Category::$category_name.sprite_id_size();
66                            $($({
67                                // Perform basic checks
68                                if offset + $attr::BITS as u32 > 16 {
69                                    panic!("Sprite category has an attribute set that will not fit in the block data");
70                                } else if lut[$attr::INDEX].is_some() {
71                                    panic!("Sprite category cannot have more than one instance of an attribute");
72                                } else if offset > (!0u8) as u32 {
73                                    panic!("Uhhh");
74                                }
75                                lut[$attr::INDEX] = Some(offset as u8);
76                                offset += $attr::BITS as u32;
77                            })*)*
78                            lut
79                        }
80                        const ATTR_OFFSETS: [Option<u8>; Attributes::all().len()] = gen_attr_offsets();
81                        &ATTR_OFFSETS
82                    },)*
83                }
84            }
85
86            /// Returns `true` if this category of sprite has the given attribute.
87            #[inline] pub fn has_attr<A: Attribute>(&self) -> bool {
88                self.attr_offsets()[A::INDEX].is_some()
89            }
90
91            /// Read an attribute from the given block.
92            ///
93            /// Note that this function assumes that the category of `self` matches that of the block, but does
94            /// not validate this.
95            #[inline] pub(super) fn read_attr<A: Attribute>(&self, block: Block) -> Result<A, AttributeError<A::Error>> {
96                let offset = match self.attr_offsets()[A::INDEX] {
97                    Some(offset) => offset,
98                    None => return Err(AttributeError::NotPresent),
99                };
100                let bits = (block.to_be_u32() >> offset as u32) & ((1 << A::BITS as u32) - 1);
101                A::from_bits(bits as u16).map_err(AttributeError::Attribute)
102            }
103
104            /// Write an attribute to the given block.
105            ///
106            /// Note that this function assumes that the category of `self` matches that of the block, but does
107            /// not validate this.
108            #[inline] pub(super) fn write_attr<A: Attribute>(&self, block: &mut Block, attr: A) -> Result<(), AttributeError<core::convert::Infallible>> {
109                let offset = match self.attr_offsets()[A::INDEX] {
110                    Some(offset) => offset,
111                    None => return Err(AttributeError::NotPresent),
112                };
113                let bits = attr.into_bits() as u32;
114                #[cfg(debug_assertions)]
115                assert!(bits < (1 << A::BITS as u32), "The bit representation of the attribute {} must fit within {} bits, but the representation was {:0b}", core::any::type_name::<A>(), A::BITS, bits);
116                let data = ((block.to_be_u32() & (!(((1 << A::BITS as u32) - 1) << offset as u32))) | (bits << offset as u32)).to_be_bytes();
117                *block = block.with_data([data[1], data[2], data[3]]);
118                Ok(())
119            }
120        }
121
122        #[inline] const fn gen_discriminant(category: Category, id: u16) -> u32 {
123            (category as u32) << 16 | id as u32
124        }
125
126        make_case_elim!(
127            sprite_kind,
128            #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq, Serialize, Deserialize, EnumIter, FromPrimitive)]
129            #[repr(u32)]
130            pub enum SpriteKind {
131                $($($sprite_name = $crate::terrain::sprite::gen_discriminant($crate::terrain::sprite::Category::$category_name, $sprite_id),)*)*
132            }
133        );
134
135        #[doc(hidden)]
136        mod categories {
137            use super::*;
138            $(
139                /// Struct used to deserialize attributes for a specific category of sprites.
140                #[doc(hidden)]
141                #[derive(Default, Copy, Clone, Debug, Eq, PartialEq)]
142                pub struct $category_name $(($($attr),*))?;
143
144                const _: () = {
145
146                    #[doc(hidden)]
147                    pub struct Visitor<'a, 'de, O, F> {
148                        f: F,
149                        expecting: &'a str,
150                        _marker: std::marker::PhantomData<O>,
151                        _lifetime: std::marker::PhantomData<&'de ()>,
152                    }
153
154                    #[automatically_derived]
155                    impl<'a, 'de, O, F: FnOnce($category_name) -> O> serde::de::Visitor<'de> for Visitor<'a, 'de, O, F> {
156                        type Value = O;
157
158                        fn expecting(&self, formatter: &mut std::fmt::Formatter) -> std::fmt::Result {
159                            formatter.write_str(&format!("Variant SpriteKind::{}", self.expecting))
160                        }
161
162                        #[inline]
163                        fn visit_seq<A>(self, mut _seq: A) -> Result<Self::Value, <A as serde::de::SeqAccess<'de>>::Error>
164                        where
165                            A: serde::de::SeqAccess<'de>,
166                        {
167                            let res = $category_name $(($(
168                                serde::de::SeqAccess::next_element::<$attr>(&mut _seq)?.unwrap_or_default()
169                            ),*))?;
170
171                            Ok((self.f)(res))
172                        }
173                    }
174
175                    impl $category_name {
176                        pub const LEN: usize = ${count($attr)};
177
178                        pub fn apply_to_block(self, _block: &mut Block) -> Result<(), AttributeError<core::convert::Infallible>> {
179                            $($(
180                                _block.set_attr(self.${index()} ${ignore($attr)})?;
181                            )*)?
182
183                            Ok(())
184                        }
185
186                        pub fn visitor<'de, O, F: FnOnce($category_name) -> O>(f: F, expecting: &str) -> Visitor<'_, 'de, O, F> {
187                            Visitor {
188                                f,
189                                expecting,
190                                _marker: std::marker::PhantomData,
191                                _lifetime: std::marker::PhantomData,
192                            }
193                        }
194                    }
195                };
196
197            )*
198        }
199        #[doc(hidden)]
200        #[derive(Copy, Clone, Debug, Eq, PartialEq)]
201        #[repr(u32)]
202        enum StructureSpriteKind {
203            $($($sprite_name(categories::$category_name) = SpriteKind::$sprite_name as u32,)*)*
204        }
205
206        impl StructureSpriteKind {
207            /// Assigns this structure sprite to a block.
208            ///
209            /// Returns error if [`Block::try_with_sprite`] fails.
210            fn apply_to_block(self, block: Block) -> Result<Block, Block> {
211                match self {
212                    $($(Self::$sprite_name(c) => block.try_with_sprite(SpriteKind::$sprite_name)
213                        .map(|mut block| {
214                            c.apply_to_block(&mut block).expect("We just added sprite to block");
215                            block
216                        }),
217                    )*)*
218                }
219            }
220        }
221
222        const _: () = {
223            mod __priv {
224                use super::{SpriteKind, StructureSpriteKind, categories};
225                use std::{
226                    fmt::{self, Formatter},
227                    marker::PhantomData,
228                };
229                use serde::{de, Deserialize, Deserializer};
230
231                impl<'de> Deserialize<'de> for StructureSpriteKind {
232                    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
233                    where
234                        D: Deserializer<'de>
235                    {
236                        #[doc(hidden)]
237                        struct Visitor<'de> {
238                            lifetime: PhantomData<&'de ()>,
239                        }
240
241                        impl<'de> de::Visitor<'de> for Visitor<'de> {
242                            type Value = StructureSpriteKind;
243
244                            fn expecting(&self, formatter: &mut Formatter) -> fmt::Result {
245                                formatter.write_str("enum SpriteKind")
246                            }
247
248                            fn visit_enum<A>(self, data: A) -> Result<Self::Value, A::Error>
249                            where
250                                A: de::EnumAccess<'de>
251                            {
252                                match de::EnumAccess::variant(data)? {
253                                    $($(
254                                        (SpriteKind::$sprite_name, variant) => {
255                                            let visitor = categories::$category_name::visitor(StructureSpriteKind::$sprite_name, stringify!($sprite_name));
256                                            de::VariantAccess::tuple_variant(
257                                                variant,
258                                                categories::$category_name::LEN,
259                                                visitor,
260                                            )
261                                        },
262                                    )*)*
263                                }
264                            }
265                        }
266
267                        #[doc(hidden)]
268                        const VARIANTS: &[&str] = &[
269                            $($(stringify!($sprite_name),)*)*
270                        ];
271
272                        Deserializer::deserialize_enum(
273                            deserializer,
274                            "SpriteKind",
275                            VARIANTS,
276                            Visitor {
277                                lifetime: PhantomData,
278                            },
279                        )
280                    }
281                }
282            }
283        };
284
285        impl SpriteKind {
286            #[inline] pub const fn all() -> &'static [Self] {
287                &[$($(Self::$sprite_name,)*)*]
288            }
289
290            #[inline] pub const fn category(&self) -> Category {
291                match self {
292                    $($(Self::$sprite_name => Category::$category_name,)*)*
293                }
294            }
295
296            /// Note that this function assumes that the category of `self` matches that of the block data, but does
297            /// not validate this.
298            #[expect(non_upper_case_globals)]
299            #[inline] pub(super) const fn from_block(block: Block) -> Option<Self> {
300                match block.sprite_category() {
301                    None => None,
302                    $(Some(category @ Category::$category_name) => {
303                        $(const $sprite_name: u32 = SpriteKind::$sprite_name as u32;)*
304                        match block.to_be_u32() & category.sprite_kind_mask() {
305                            $($sprite_name => Some(Self::$sprite_name),)*
306                            _ => None,
307                        }
308                    },)*
309                }
310            }
311
312            #[inline] pub(super) fn to_initial_bytes(self) -> [u8; 3] {
313                let sprite_bytes = (self as u32).to_be_bytes();
314                let block = Block::from_raw(super::BlockKind::Air, [sprite_bytes[1], sprite_bytes[2], sprite_bytes[3]]);
315                match self.category() {
316                    $(Category::$category_name => block$($(.with_attr($attr::default()).unwrap())*)?,)*
317                }
318                    .data()
319            }
320        }
321    };
322}
323
324#[derive(Debug)]
325pub enum AttributeError<E> {
326    /// The attribute was not present for the given block data's category.
327    NotPresent,
328    /// An attribute-specific error occurred when performing extraction.
329    Attribute(E),
330}
331
332pub trait Attribute: Default + Sized {
333    /// The unique index assigned to this attribute, used to index offset
334    /// arrays.
335    const INDEX: usize;
336    /// The number of bits required to represent this attribute.
337    const BITS: u8;
338    /// The error that might occur when decoding the attribute from bits.
339    type Error: core::fmt::Debug;
340    fn from_bits(bits: u16) -> Result<Self, Self::Error>;
341    fn into_bits(self) -> u16;
342}
343
344#[macro_export]
345macro_rules! attributes {
346    ($(
347        $name:ident { bits: $bits:literal, err: $err:path, from: $from_bits:expr, into: $into_bits:expr $(,)? }
348    ),* $(,)?) => {
349        #[derive(Copy, Clone, Debug)]
350        #[repr(u16)]
351        pub enum Attributes {
352            $($name,)*
353        }
354
355        impl Attributes {
356            #[inline] pub const fn all() -> &'static [Self] {
357                &[$(Self::$name,)*]
358            }
359        }
360
361        $(
362            impl Attribute for $name {
363                const INDEX: usize = Attributes::$name as usize;
364                const BITS: u8 = $bits;
365                type Error = $err;
366                #[inline(always)] fn from_bits(bits: u16) -> Result<Self, Self::Error> { $from_bits(bits) }
367                #[inline(always)] fn into_bits(self) -> u16 { $into_bits(self) }
368            }
369        )*
370    };
371}