Derive Macro for MapEntites

[jonathandw743]

What problem does this solve or what need does it fill?

Would remove boilerplate like

impl MapEntities for Foo {
    fn map_entities<M: EntityMapper>(&mut self, entity_mapper: &mut M) {
        self.a.map_entities(entity_mapper);
        self.b.map_entities(entity_mapper);
    }
}

What solution would you like?

A derive macro which can implement MapEntities for any struct where all its attributes implement MapEntities (like Debug and Default do).

What alternative(s) have you considered?

Just implementing it.

[Liam19]

I've been running my own derive macro in my project for a while now. It's got some rough edges but I may as well share it here if someone wants to modify it for a PR. It has definitely saved me a LOT of time.

use proc_macro::TokenStream;
use quote::quote;
use syn::{parse_macro_input, parse_quote, Data, DeriveInput, Fields, Path, Type};

/// A derive macro that implements the `AutoMapEntities` trait for structs and enums.
///
/// # Features
///
/// - **Automatic implementation**: Adds `AutoMapEntities` trait support to any* struct or enum by
///   simply using `#[derive(AutoMapEntities)]`, no manual implementation required.
/// - **Deep nesting support**: Recursively traverses nested structs, enums, and supported
///   collection types (`Vec`, `Option`, `HashMap`, etc.) to find and update `Entity` values, even within complex hierarchies.
/// - **Support for foreign types**: Unlike Bevy's built-in `MapEntities`, this custom
///   version allows for implementation on types from external crates.
/// - **Auto detection for Component implementations**: AutoMapEntities will implement bevy's MapEntities trait for
///   serialisation and deserialisation on [Component] types
///
/// # Usage
///
/// To use this macro, annotate your struct or enum with `#[derive(AutoMapEntities)]`. The macro will then
/// generate the appropriate implementation of the `auto_map_entities` method, which can be used to update
/// the `Entity` values based on a provided mapping.
///
/// # Limitations
///
/// - While this custom version supports a wider range of types, including primitives, you may still
///   need to manually implement `AutoMapEntities` for generic/foreign types that require special handling.
pub fn derive_auto_map_entities(input: TokenStream) -> TokenStream {
    let input = parse_macro_input!(input as DeriveInput);
    let name = input.ident.clone();

    let ty = &input.ident;
    let component_trait: Path = parse_quote!(::bevy_ecs::component::Component);

    let component_tokens = if implements_trait(
        &syn::Type::Path(syn::TypePath {
            qself: None,
            path: syn::Path::from(ty.clone()),
        }),
        &component_trait,
    ) {
        quote! {
            impl bevy::ecs::entity::MapEntities for #name {
                fn map_entities<M: bevy::ecs::entity::EntityMapper>(&mut self, entity_mapper: &mut M) {
                    self.auto_map_entities(entity_mapper);
                }
            }
        }
    } else {
        quote! {}
    };

    // Generate code to map entities for each field
    let map_entities_impl = match input.data {
        Data::Struct(data_struct) => {
            let map_entities = map_struct_fields(&data_struct.fields);

            quote! {
                #component_tokens

                impl AutoMapEntities for #name {
                    fn auto_map_entities<M: bevy::ecs::entity::EntityMapper>(&mut self, entity_mapper: &mut M) {
                        #map_entities
                    }
                }
            }
        }
        Data::Enum(data_enum) => {
            let map_entities_variants = data_enum.variants.iter().map(|variant| {
                let variant_name = &variant.ident;
                let pattern = get_enum_variant_pattern(&variant.fields);
                let map_entities = map_enum_variant(&variant.fields);

                quote! {
                    #name::#variant_name #pattern => {
                        #map_entities
                    }
                }
            });

            quote! {
                #component_tokens

                impl AutoMapEntities for #name {
                    fn auto_map_entities<M: bevy::ecs::entity::EntityMapper>(&mut self, entity_mapper: &mut M) {
                        match self {
                            #(#map_entities_variants),*
                        }
                    }
                }
            }
        }
        _ => unimplemented!(),
    };

    map_entities_impl.into()
}

/// Checks if a given type implements a specific trait
///
/// Returns true if the type implements the trait, false otherwise
fn implements_trait(ty: &Type, trait_path: &Path) -> bool {
    // Create a type implementation check using std::marker::PhantomData
    let check = quote! {
        {
            fn assert_impl<T: ?Sized + #trait_path>() {}
            assert_impl::<#ty>();
        }
    };

    // Try to parse the implementation check
    // If it parses successfully, the type implements the trait
    syn::parse2::<proc_macro2::TokenStream>(check).is_ok()
}

// Function to generate code to map fields for a struct
fn map_struct_fields(fields: &Fields) -> proc_macro2::TokenStream {
    let mut map_entities = vec![];

    for (i, field) in fields.iter().enumerate() {
        let map_field = if is_primitive(&field.ty) {
            quote! {}
        } else if let Some(field_name) = &field.ident {
            // Named field (struct)
            quote! {
                self.#field_name.auto_map_entities(entity_mapper);
            }
        } else {
            // Unnamed field (tuple-like struct or enum variant)
            let idx = syn::Index::from(i);
            quote! {
                self.#idx.auto_map_entities(entity_mapper);
            }
        };

        map_entities.push(map_field);
    }

    quote! {
        #(#map_entities)*
    }
}

// Function to generate code to map fields for an enum variant
fn map_enum_variant(fields: &Fields) -> proc_macro2::TokenStream {
    let mut map_entities = vec![];

    for (i, field) in fields.iter().enumerate() {
        let map_field = if is_primitive(&field.ty) {
            quote! {}
        } else if let Some(field_name) = &field.ident {
            // Named field
            quote! {
                #field_name.auto_map_entities(entity_mapper);
            }
        } else {
            // Unnamed field
            let var_name = syn::Ident::new(&format!("field_{}", i), proc_macro2::Span::call_site());
            quote! {
                #var_name.auto_map_entities(entity_mapper);
            }
        };

        map_entities.push(map_field);
    }

    quote! {
        #(#map_entities)*
    }
}

/// Generates the match pattern for unnamed fields (e.g., `(field_0, field_1)`)
///
/// Or named fields (e.g., `(item, quantity)`)
fn get_enum_variant_pattern(fields: &Fields) -> proc_macro2::TokenStream {
    match fields {
        Fields::Named(named_fields) => {
            let field_vars = named_fields.named.iter().map(|field| {
                let var_name = field.ident.as_ref().unwrap();
                quote! { #var_name }
            });
            quote! { {#(#field_vars),*} }
        }
        Fields::Unnamed(unnamed_fields) => {
            let field_vars = (0..unnamed_fields.unnamed.len()).map(|i| {
                let var_name =
                    syn::Ident::new(&format!("field_{}", i), proc_macro2::Span::call_site());
                quote! { #var_name }
            });
            quote! { ( #(#field_vars),* ) }
        }
        Fields::Unit => quote! {},
    }
}

fn is_primitive(ty: &syn::Type) -> bool {
    match ty {
        syn::Type::Path(type_path) => {
            if let Some(ident) = type_path.path.get_ident() {
                matches!(
                    ident.to_string().as_str(),
                    "usize"
                        | "u8"
                        | "u16"
                        | "u32"
                        | "u64"
                        | "u128"
                        | "isize"
                        | "i8"
                        | "i16"
                        | "i32"
                        | "i64"
                        | "i128"
                        | "f32"
                        | "f64"
                        | "f128"
                        | "bool"
                        | "char"
                        | "str"
                        | "String"
                )
            } else {
                false
            }
        }
        _ => false,
    }
}

Then in my game crate i have an entity_mapping.rs file that includes:

My custom trait:

/// Custom trait for MappingEntities
pub trait AutoMapEntities {
    /// Map entities using [`bevy::ecs::entity::map_entities`]
    fn auto_map_entities<M: EntityMapper>(&mut self, entity_mapper: &mut M);
}

Implementations:

impl AutoMapEntities for Entity {
    fn auto_map_entities<M: EntityMapper>(&mut self, entity_mapper: &mut M) {
        *self = entity_mapper.map_entity(*self);
    }
}

impl<T: AutoMapEntities> AutoMapEntities for Option<T> {
    fn auto_map_entities<M: EntityMapper>(&mut self, entity_mapper: &mut M) {
        if let Some(ref mut value) = self {
            value.auto_map_entities(entity_mapper);
        }
    }
}

impl<T: AutoMapEntities> AutoMapEntities for Vec<T> {
    fn auto_map_entities<M: EntityMapper>(&mut self, entity_mapper: &mut M) {
        for item in self {
            item.auto_map_entities(entity_mapper);
        }
    }
}

impl AutoMapEntities for Record {
    fn auto_map_entities<M: EntityMapper>(&mut self, entity_mapper: &mut M) {
        // Record only contains primitives, so do nothing
    }
}

impl AutoMapEntities for f32 {
    fn auto_map_entities<M: EntityMapper>(&mut self, _: &mut M) {
        // f32 is a primitive, so do nothing
    }
}

// and so on...

[cBournhonesque]

This would definitely be useful. The macro is probably enough for at least 80% of cases