Require manual Component implementation

Author: Ralith

CHANGELOG.md

@@ -1,3 +1,13 @@
+# Unreleased
+
+### Changed
+
+- `Component` is no longer automatically implemented for all `Send + Sync + 'static` types. Types
+  must now implement it explicitly, either by hand (`impl Component for Position {}`) or with the
+  new `#[derive(Component)]` macro from the `hecs-macros` crate (enabled by the `macros` feature).
+  This rules out accidental use of third-party types as components and leaves the door open for
+  future trait extensions.
+
 # 0.11.1
 
 ### Added

README.md

@@ -13,16 +13,24 @@ your application however you like!
 
 ```rust
 let mut world = hecs::World::new();
-// Nearly any type can be used as a component with zero boilerplate
-let a = world.spawn((123, true, "abc"));
-let b = world.spawn((42, false));
+
+// Component types can be defined with minimal boilerplate
+struct Name(&'static str);
+impl hecs::Component for Name {}
+struct Weight(u32);
+impl hecs::Component for Weight {}
+struct Price(u32);
+impl hecs::Component for Price {}
+
+let a = world.spawn((Name("abc"), Weight(12), Price(123)));
+let b = world.spawn((Weight(38), Price(42)));
 // Systems can be simple for loops
-for (number, &flag) in world.query_mut::<(&mut i32, &bool)>() {
-  if flag { *number *= 2; }
+for (price, weight) in world.query_mut::<(&mut Price, &Weight)>() {
+  if weight.0 < 20 { price.0 *= 2; }
 }
 // Random access is simple and safe
-assert_eq!(*world.get::<&i32>(a).unwrap(), 246);
-assert_eq!(*world.get::<&i32>(b).unwrap(), 42);
+assert_eq!(world.get::<&Price>(a).unwrap().0, 246);
+assert_eq!(world.get::<&Price>(b).unwrap().0, 42);
 ```
 
 ### Why ECS?

benches/bench.rs

@@ -7,8 +7,14 @@ use hecs::*;
 
 #[derive(Clone)]
 struct Position(f32);
+impl Component for Position {}
 #[derive(Clone)]
 struct Velocity(f32);
+impl Component for Velocity {}
+
+/// Stand-in component used to populate worlds with interesting archetype shapes
+struct Extra<const N: usize>;
+impl<const N: usize> Component for Extra<N> {}
 
 fn spawn_tuple(c: &mut Criterion) {
     let mut world = World::new();
@@ -108,8 +114,8 @@ fn insert_remove(c: &mut Criterion) {
         b.iter(|| {
             let e = *entities.next().unwrap();
             world.remove_one::<Velocity>(e).unwrap();
-            world.insert_one(e, true).unwrap();
-            world.remove_one::<bool>(e).unwrap();
+            world.insert_one(e, Extra::<0>).unwrap();
+            world.remove_one::<Extra<0>>(e).unwrap();
             world.insert_one(e, Velocity(0.0)).unwrap();
         })
     });
@@ -124,8 +130,8 @@ fn exchange(c: &mut Criterion) {
     c.bench_function("exchange", |b| {
         b.iter(|| {
             let e = *entities.next().unwrap();
-            world.exchange_one::<Velocity, _>(e, true).unwrap();
-            world.exchange_one::<bool, _>(e, Velocity(0.0)).unwrap();
+            world.exchange_one::<Velocity, _>(e, Extra::<0>).unwrap();
+            world.exchange_one::<Extra<0>, _>(e, Velocity(0.0)).unwrap();
         })
     });
 }
@@ -212,8 +218,8 @@ fn for_each_batched_100k(c: &mut Criterion) {
 
 fn spawn_100_by_50(world: &mut World) {
     fn spawn_two<const N: usize>(world: &mut World, i: i32) {
-        world.spawn((Position(-(i as f32)), Velocity(i as f32), [(); N]));
-        world.spawn((Position(-(i as f32)), [(); N]));
+        world.spawn((Position(-(i as f32)), Velocity(i as f32), Extra::<N>));
+        world.spawn((Position(-(i as f32)), Extra::<N>));
     }
 
     for i in 0..2 {
@@ -264,7 +270,7 @@ fn iterate_uncached_1_of_100_by_50(c: &mut Criterion) {
         b.iter(|| {
             for (pos, vel) in world
                 .query::<(&mut Position, &Velocity)>()
-                .with::<&[(); 0]>()
+                .with::<&Extra<0>>()
                 .iter()
             {
                 pos.0 += vel.0;
@@ -339,9 +345,9 @@ fn build_cloneable(c: &mut Criterion) {
 fn access_view(c: &mut Criterion) {
     let mut world = World::new();
     let _enta = world.spawn((Position(0.0), Velocity(0.0)));
-    let _entb = world.spawn((true, 12));
+    let _entb = world.spawn((Extra::<0>, Extra::<1>));
     let entc = world.spawn((Position(3.0),));
-    let _entd = world.spawn((13, true, 4.0));
+    let _entd = world.spawn((Extra::<1>, Extra::<2>, Extra::<3>));
     let mut query = PreparedQuery::<&Position>::new();
     let mut query = query.query(&world);
     let view = query.view();

examples/cloning.rs

@@ -10,6 +10,19 @@ use std::any::TypeId;
 
 use hecs::{Archetype, ColumnBatchBuilder, ColumnBatchType, Component, TypeIdMap, TypeInfo, World};
 
+#[derive(Clone, Debug, PartialEq)]
+struct Count(i32);
+impl Component for Count {}
+
+#[derive(Clone, Debug, PartialEq)]
+struct Name(String);
+impl Component for Name {}
+
+/// A component that will not be registered with the [`WorldCloner`]
+#[derive(Clone, Debug, PartialEq)]
+struct Marker(u8);
+impl Component for Marker {}
+
 struct ComponentCloneMetadata {
     type_info: TypeInfo,
     insert_into_batch_func: &'static dyn Fn(&Archetype, &mut ColumnBatchBuilder),
@@ -75,21 +88,15 @@ impl WorldCloner {
 }
 
 pub fn main() {
-    let int0 = 0;
-    let int1 = 1;
-    let str0 = "Ada".to_owned();
-    let str1 = "Bob".to_owned();
-    let str2 = "Cal".to_owned();
-
     let mut world0 = World::new();
-    let entity0 = world0.spawn((int0, str0));
-    let entity1 = world0.spawn((int1, str1));
-    let entity2 = world0.spawn((str2,));
-    let entity3 = world0.spawn((0u8,)); // unregistered component
+    let entity0 = world0.spawn((Count(0), Name("Ada".to_owned())));
+    let entity1 = world0.spawn((Count(1), Name("Bob".to_owned())));
+    let entity2 = world0.spawn((Name("Cal".to_owned()),));
+    let entity3 = world0.spawn((Marker(0),)); // unregistered component
 
     let mut cloner = WorldCloner::default();
-    cloner.register::<i32>();
-    cloner.register::<String>();
+    cloner.register::<Count>();
+    cloner.register::<Name>();
 
     let world1 = cloner.clone_world(&world0);
 
@@ -104,18 +111,18 @@ pub fn main() {
         world0
             .entity(entity3)
             .expect("w0 entity3 should exist")
-            .has::<u8>(),
-        "original world entity has u8 component"
+            .has::<Marker>(),
+        "original world entity has Marker component"
     );
     assert!(
         !world1
             .entity(entity3)
             .expect("w1 entity3 should exist")
-            .has::<u8>(),
-        "cloned world entity does not have u8 component because it was not registered"
+            .has::<Marker>(),
+        "cloned world entity does not have Marker component because it was not registered"
     );
 
-    type AllRegisteredComponentsQuery = (&'static i32, &'static String);
+    type AllRegisteredComponentsQuery = (&'static Count, &'static Name);
     for entity in [entity0, entity1] {
         let w0_e = world0.entity(entity).expect("w0 entity should exist");
         let w1_e = world1.entity(entity).expect("w1 entity should exist");
@@ -128,7 +135,7 @@ pub fn main() {
         );
     }
 
-    type SomeRegisteredComponentsQuery = (&'static String,);
+    type SomeRegisteredComponentsQuery = (&'static Name,);
     let w0_e = world0.entity(entity2).expect("w0 entity2 should exist");
     let w1_e = world1.entity(entity2).expect("w1 entity2 should exist");
     assert!(w0_e.satisfies::<SomeRegisteredComponentsQuery>());

examples/ffa_simulation.rs

@@ -19,18 +19,23 @@ struct Position {
     x: i32,
     y: i32,
 }
+impl Component for Position {}
 
 #[derive(Debug)]
 struct Health(i32);
+impl Component for Health {}
 
 #[derive(Debug)]
 struct Speed(i32);
+impl Component for Speed {}
 
 #[derive(Debug)]
 struct Damage(i32);
+impl Component for Damage {}
 
 #[derive(Debug)]
 struct KillCount(i32);
+impl Component for KillCount {}
 
 fn manhattan_dist(x0: i32, x1: i32, y0: i32, y1: i32) -> i32 {
     let dx = (x0 - x1).abs();

examples/format.rs

@@ -3,12 +3,36 @@
 
 type FormattingFunction = &'static dyn Fn(hecs::EntityRef<'_>) -> Option<String>;
 
+struct Number(i32);
+impl hecs::Component for Number {}
+impl std::fmt::Display for Number {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        self.0.fmt(f)
+    }
+}
+
+struct Flag(bool);
+impl hecs::Component for Flag {}
+impl std::fmt::Display for Flag {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        self.0.fmt(f)
+    }
+}
+
+struct Ratio(f64);
+impl hecs::Component for Ratio {}
+impl std::fmt::Display for Ratio {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        self.0.fmt(f)
+    }
+}
+
 fn format_entity(entity: hecs::EntityRef<'_>) -> String {
     fn fmt<T: hecs::Component + std::fmt::Display>(entity: hecs::EntityRef<'_>) -> Option<String> {
         Some(entity.get::<&T>()?.to_string())
     }
 
-    const FUNCTIONS: &[FormattingFunction] = &[&fmt::<i32>, &fmt::<bool>, &fmt::<f64>];
+    const FUNCTIONS: &[FormattingFunction] = &[&fmt::<Number>, &fmt::<Flag>, &fmt::<Ratio>];
 
     let mut out = String::new();
     for f in FUNCTIONS {
@@ -31,6 +55,6 @@ fn format_entity(entity: hecs::EntityRef<'_>) -> String {
 
 fn main() {
     let mut world = hecs::World::new();
-    let e = world.spawn((42, true));
+    let e = world.spawn((Number(42), Flag(true)));
     println!("{}", format_entity(world.entity(e).unwrap()));
 }

examples/serialize_to_disk.rs

@@ -35,16 +35,19 @@ struct SaveContextDeserialize {
 }
 
 // Components of our world.
-// Only Serialize and Deserialize derives are necessary.
+// In addition to implementing `Component`, types need Serialize and Deserialize derives to be
+// included in the serialization process.
 #[derive(Serialize, Deserialize, Eq, PartialEq, Debug, Clone)]
 struct ComponentA {
     data: usize,
 }
+impl hecs::Component for ComponentA {}
 
 #[derive(Serialize, Deserialize, Eq, PartialEq, Debug, Clone)]
 struct ComponentB {
     some_other_data: String,
 }
+impl hecs::Component for ComponentB {}
 
 impl DeserializeContext for SaveContextDeserialize {
     fn deserialize_component_ids<'de, A>(&mut self, mut seq: A) -> Result<ColumnBatchType, A::Error>

examples/transform_hierarchy.rs

@@ -12,6 +12,7 @@ struct Parent {
     /// Converts child-relative coordinates to parent-relative coordinates
     from_child: Transform,
 }
+impl Component for Parent {}
 
 fn main() {
     let mut world = World::new();
@@ -100,6 +101,7 @@ fn evaluate_relative_transforms(world: &mut World) {
 // In practice this would usually also include rotation, or even be a general homogeneous matrix
 #[derive(Debug, Copy, Clone, Default, Eq, PartialEq)]
 struct Transform(i32, i32);
+impl Component for Transform {}
 
 impl std::ops::Mul for Transform {
     type Output = Transform;

macros/src/lib.rs

@@ -7,6 +7,7 @@ mod query;
 pub(crate) mod common;
 
 use proc_macro::TokenStream;
+use quote::quote;
 use syn::{parse_macro_input, DeriveInput};
 
 /// Implement `Bundle` for a struct
@@ -17,15 +18,23 @@ use syn::{parse_macro_input, DeriveInput};
 /// # Example
 /// ```
 /// # use hecs::*;
+/// #[derive(Debug, PartialEq)]
+/// struct X(i32);
+/// impl Component for X {}
+///
+/// #[derive(Debug, PartialEq)]
+/// struct Y(char);
+/// impl Component for Y {}
+///
 /// #[derive(Bundle)]
 /// struct Foo {
-///     x: i32,
-///     y: char,
+///     x: X,
+///     y: Y,
 /// }
 ///
 /// let mut world = World::new();
-/// let e = world.spawn(Foo { x: 42, y: 'a' });
-/// assert_eq!(*world.get::<&i32>(e).unwrap(), 42);
+/// let e = world.spawn(Foo { x: X(42), y: Y('a') });
+/// assert_eq!(*world.get::<&X>(e).unwrap(), X(42));
 /// ```
 #[proc_macro_derive(Bundle)]
 pub fn derive_bundle(input: TokenStream) -> TokenStream {
@@ -68,19 +77,27 @@ pub fn derive_dynamic_bundle_clone(input: TokenStream) -> TokenStream {
 /// # Example
 /// ```
 /// # use hecs::*;
+/// #[derive(Debug, PartialEq)]
+/// struct X(i32);
+/// impl Component for X {}
+///
+/// #[derive(Debug, PartialEq)]
+/// struct Y(bool);
+/// impl Component for Y {}
+///
 /// #[derive(Query, Debug, PartialEq)]
 /// struct Foo<'a> {
-///     x: &'a i32,
-///     y: &'a mut bool,
+///     x: &'a X,
+///     y: &'a mut Y,
 /// }
 ///
 /// let mut world = World::new();
-/// let e = world.spawn((42, false));
+/// let e = world.spawn((X(42), Y(false)));
 /// assert_eq!(
 ///     world.query_one_mut::<Foo>(e).unwrap(),
 ///     Foo {
-///         x: &42,
-///         y: &mut false
+///         x: &X(42),
+///         y: &mut Y(false)
 ///     }
 /// );
 /// ```
@@ -93,3 +110,24 @@ pub fn derive_query(input: TokenStream) -> TokenStream {
     }
     .into()
 }
+
+/// Implement `Component` for some type.
+///
+/// Convenience short-hand for `impl Component for T {}`.
+///
+/// Generic type parameters automatically receive the `Send + Sync + 'static` bounds required by the
+/// trait's supertraits. When this is inappropriate, use a manual implementation instead.
+#[proc_macro_derive(Component)]
+pub fn derive_component(input: TokenStream) -> TokenStream {
+    let input = parse_macro_input!(input as DeriveInput);
+    let ident = input.ident;
+    let mut generics = input.generics;
+    for param in generics.type_params_mut() {
+        param.bounds.push(syn::parse_quote!(::core::marker::Send));
+        param.bounds.push(syn::parse_quote!(::core::marker::Sync));
+        param.bounds.push(syn::parse_quote!('static));
+    }
+    let (impl_generics, ty_generics, where_clause) = generics.split_for_impl();
+
+    quote! { impl #impl_generics ::hecs::Component for #ident #ty_generics #where_clause {} }.into()
+}