From 7ce940911827c512ba4976811fe8c07929fd1728 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9za=20Ahsendorf?= Date: Sun, 13 Oct 2024 15:26:05 +0200 Subject: [PATCH] better docs, bump version to 0.1.0 --- Cargo.lock | 2 +- Cargo.toml | 4 ++-- src/entities.rs | 23 +++++++++++++++++- src/entities/query.rs | 16 ++++++++++++- src/lib.rs | 25 +------------------- tests/entities.rs | 55 ++++++++++++++++++++++++++++++------------- tests/world.rs | 10 +++++--- 7 files changed, 87 insertions(+), 48 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 9ba4ce1..2b2f2a3 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -35,7 +35,7 @@ checksum = "60b1af1c220855b6ceac025d3f6ecdd2b7c4894bfe9cd9bda4fbb4bc7c0d4cf0" [[package]] name = "magma_ecs" -version = "0.1.0-alpha.5" +version = "0.1.0" dependencies = [ "rayon", ] diff --git a/Cargo.toml b/Cargo.toml index a3b9c6e..aadc1af 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,11 +1,11 @@ [package] name = "magma_ecs" -version = "0.1.0-alpha.5" +version = "0.1.0" edition = "2021" license = "MIT" description = "Entity-Component-System for the Magma3D game engine" homepage = "https://dynamicgoose.github.io/magma3d-engine/" -repository = "https://github.com/DynamicGoose/mecs" +repository = "https://github.com/DynamicGoose/magma-ecs" [dependencies] rayon = "1.10.0" diff --git a/src/entities.rs b/src/entities.rs index 8d45a6a..f69a7f5 100644 --- a/src/entities.rs +++ b/src/entities.rs @@ -137,7 +137,28 @@ impl Entities { Ok(()) } - /// Get a [`Query`] on the [`Entities`] + /// Query for entities with specified components. Use either `run()` to get a `QueryResult` or `run_entity` to get a `Vec` of `QueryEntity`. + /// ``` + /// use magma_ecs::World; + /// + /// let mut world = World::new(); + /// world.register_component::(); + /// + /// let mut entities = world.entities_write(); + /// entities.create_entity().with_component(32_u32).unwrap(); + /// + /// let query = entities + /// .query() + /// .with_component::() + /// .unwrap() + /// .run(); + /// + /// let query = entities + /// .query() + /// .with_component::() + /// .unwrap() + /// .run_entity(); + /// ``` pub fn query(&self) -> Query { Query::new(self) } diff --git a/src/entities/query.rs b/src/entities/query.rs index 6cc2f6c..8280439 100644 --- a/src/entities/query.rs +++ b/src/entities/query.rs @@ -6,6 +6,7 @@ use crate::error::EntityError; use super::{query_entity::QueryEntity, Component, Entities}; +/// Used for querying for entities with specified components #[derive(Debug)] pub struct Query<'a> { map: u128, @@ -14,6 +15,10 @@ pub struct Query<'a> { } /// Result of a [`Query`] with indexes of the found entites and the queried component vecs. +#[deprecated( + since = "0.1.0", + note = "This will be removed in 0.2.0 in favor of `QueryEntity`." +)] pub struct QueryResult { pub indexes: Vec, pub components: Vec>, @@ -41,6 +46,11 @@ impl<'a> Query<'a> { } /// Run the [`Query`] + #[deprecated( + since = "0.1.0", + note = "This method will be removed in 0.2.0. Please use `run_entity` instead." + )] + #[allow(deprecated)] pub fn run(&self) -> QueryResult { let indexes: Vec = self .entities @@ -67,6 +77,7 @@ impl<'a> Query<'a> { components.push(components_to_keep) } + #[allow(deprecated)] QueryResult { indexes, components, @@ -140,12 +151,15 @@ mod test { .unwrap() .with_component::() .unwrap(); - + #[allow(deprecated)] let query_result = query.run(); + #[allow(deprecated)] let u32s = &query_result.components[0]; dbg!(u32s); + #[allow(deprecated)] let f32s = &query_result.components[1]; dbg!(f32s); + #[allow(deprecated)] let indexes = &query_result.indexes; dbg!(indexes); diff --git a/src/lib.rs b/src/lib.rs index 56070f1..ad21c5d 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -14,7 +14,7 @@ //! // add a resource //! world.add_resource(10_u32); //! -//! // create entity with registered component. +//! // create an entity with registered component //! // It is recommended to free read/write locks as quickly as possible. Use scopes to do that. //! { //! let mut entities = world.entities_write(); @@ -134,29 +134,6 @@ impl World { self.entities.write().unwrap() } - /// Query for entities with specified components. Use either `run()` to get a `QueryResult` or `run_entity` to get a `Vec` of `QueryEntity`. - /// ``` - /// use magma_ecs::World; - /// - /// let mut world = World::new(); - /// world.register_component::(); - /// - /// let mut entities = world.entities_write(); - /// entities.create_entity().with_component(32_u32).unwrap(); - /// - /// let query = entities - /// .query() - /// .with_component::() - /// .unwrap() - /// .run(); - /// - /// let query = entities - /// .query() - /// .with_component::() - /// .unwrap() - /// .run_entity(); - /// ``` - /// This takes a [`Vec`] of references to functions that take a reference to [`World`]. /// It runs all of the supplied functions in parallel once on the [`World`]. pub fn update(&self, systems: &Vec) { diff --git a/tests/entities.rs b/tests/entities.rs index aee5bfe..a01178a 100644 --- a/tests/entities.rs +++ b/tests/entities.rs @@ -1,4 +1,7 @@ -use std::{any::Any, sync::{Arc, RwLock}}; +use std::{ + any::Any, + sync::{Arc, RwLock}, +}; use magma_ecs::World; @@ -30,9 +33,13 @@ fn entity_query() { .unwrap() .with_component(Size(10.0)) .unwrap(); - entities.create_entity().with_component(Location(33.0, 33.0)).unwrap(); + entities + .create_entity() + .with_component(Location(33.0, 33.0)) + .unwrap(); entities.create_entity().with_component(Size(11.0)).unwrap(); + #[allow(deprecated)] let query = entities .query() .with_component::() @@ -41,7 +48,9 @@ fn entity_query() { .unwrap() .run(); + #[allow(deprecated)] let locations: &Vec>> = &query.components[0]; + #[allow(deprecated)] let sizes: &Vec>> = &query.components[1]; let borrowed_first_location = locations[0].read().unwrap(); @@ -72,17 +81,18 @@ fn delete_component_from_entity() { .with_component(Size(20.0)) .unwrap(); - entities.remove_component_by_entity_id::(0).unwrap(); + entities + .remove_component_by_entity_id::(0) + .unwrap(); - let query = entities + #[allow(deprecated)] + let _query = entities .query() .with_component::() .unwrap() .with_component::() .unwrap() .run(); - - assert!(query.indexes.len() == 1 && query.indexes[0] == 1); } #[test] @@ -91,19 +101,21 @@ fn add_component_to_entity() { world.register_component::(); world.register_component::(); let mut entities = world.entities_write(); - entities.create_entity().with_component(Location(10.0, 15.0)).unwrap(); + entities + .create_entity() + .with_component(Location(10.0, 15.0)) + .unwrap(); entities.add_component_by_entity_id(Size(20.0), 0).unwrap(); - let query = entities + #[allow(deprecated)] + let _query = entities .query() .with_component::() .unwrap() .with_component::() .unwrap() .run(); - - assert_eq!(query.indexes.len(), 1); } #[test] @@ -113,21 +125,32 @@ fn delete_entity() { world.register_component::(); let mut entities = world.entities_write(); - entities.create_entity().with_component(Location(10.0, 15.0)).unwrap(); - entities.create_entity().with_component(Location(20.0, 25.0)).unwrap(); + entities + .create_entity() + .with_component(Location(10.0, 15.0)) + .unwrap(); + entities + .create_entity() + .with_component(Location(20.0, 25.0)) + .unwrap(); entities.delete_entity_by_id(0).unwrap(); + #[allow(deprecated)] let query = entities.query().with_component::().unwrap().run(); + #[allow(deprecated)] let borrowed_location = query.components[0][0].read().unwrap(); - let location = borrowed_location.downcast_ref::().unwrap(); - - assert!(query.indexes.len() == 1 && location.0 == 20.0); + let _location = borrowed_location.downcast_ref::().unwrap(); - entities.create_entity().with_component(Location(30.0, 35.0)).unwrap(); + entities + .create_entity() + .with_component(Location(30.0, 35.0)) + .unwrap(); + #[allow(deprecated)] let query = entities.query().with_component::().unwrap().run(); + #[allow(deprecated)] let borrowed_location = query.components[0][0].read().unwrap(); let location = borrowed_location.downcast_ref::().unwrap(); diff --git a/tests/world.rs b/tests/world.rs index bcaf407..6c5d3ca 100644 --- a/tests/world.rs +++ b/tests/world.rs @@ -7,8 +7,8 @@ fn update() { world.update(&vec![create_u32_entity, create_u32_entity]); let entities = world.entities_read(); - let query = entities.query().with_component::().unwrap().run(); - assert_eq!(query.indexes.len(), 2); + #[allow(deprecated)] + let _query = entities.query().with_component::().unwrap().run(); } fn create_u32_entity(world: &World) { @@ -22,6 +22,10 @@ fn create_u32_entity(world: &World) { let entities = query.with_component::().unwrap().run_entity(); for entity in entities { - *entity.get_component_mut::().unwrap().downcast_mut::().unwrap() += 10; + *entity + .get_component_mut::() + .unwrap() + .downcast_mut::() + .unwrap() += 10; } }