simplecs/lib.rs
1//! # simplecs
2//!
3//! [](https://crates.io/crates/simplecs)
4//! [](https://docs.rs/simplecs)
5//! [](https://opensource.org/licenses/MIT)
6//!
7//! **`simplecs`** is a lightweight, zero-dependency Entity-Component System (ECS) for Rust.
8//! It emphasizes **simplicity**, **type-safety**, and **ergonomic querying**.
9//!
10//! ---
11//!
12//! ## ✨ Features
13//!
14//! - ✅ Simple API — no macro-heavy boilerplate
15//! - 🧠 Type-based querying with `With<T>` / `Without<T>`
16//! - 🧩 Dynamic component registration via `ComponentStorageBuilder`
17//! - 🔄 Uses `TypeId` + `Any` internally for type-erased buckets
18//! - 🦀 Pure safe Rust — great for learning ECS
19//!
20//! ---
21//!
22//! ## 🚀 Example
23//!
24//! ```rust
25//! use simplecs::*;
26//!W
27//! struct Position(f32, f32);
28//! impl Component for Position {}
29//!
30//! struct Velocity(f32, f32);
31//! impl Component for Velocity {}
32//!
33//! // For now, you should manually inform
34//! // how many combinations you can use in
35//! // your queries
36//! component_list!(A, B, C, D, E);
37//!
38//! fn main() {
39//! let mut storage = ComponentStorageBuilder::<u32>::new()
40//! .with::<Position>()
41//! .with::<Velocity>()
42//! .build();
43//!
44//! storage.add_component(1, Position(1.0, 2.0));
45//! storage.add_component(1, Velocity(0.1, 0.1));
46//! storage.add_component(2, Position(5.0, 5.0));
47//!
48//! let moving = storage.query::<With<(Position, Velocity)>>();
49//! assert_eq!(moving, vec![1]);
50//!
51//! let static_entities = storage.query::<(With<Position>, Without<Velocity>)>();
52//! assert_eq!(static_entities, vec![2]);
53//! }
54//! ```
55//!
56//! ---
57//!
58//! ## 📐 Query API
59//!
60//! `simplecs` uses type-safe static dispatch to query entities:
61//!
62//! - `With<T>` – selects entities with components `T`
63//! - `Without<T>` – selects entities that lack `T`
64//! - Combinations like `(With<A>, Without<B>)` work too
65//!
66//! Define component groups with a macro:
67//!
68//! ```rust
69//! component_list!(A, B, C, D, E, F);
70//! ```
71//!
72//! Then use in queries:
73//!
74//! ```rust
75//! let ids = storage.query::<(With<(Position, Velocity)>, Without<Health>)>();
76//! ```
77//!
78//! ---
79//!
80//! ## 🧱 Architecture
81//!
82//! - Each component type has a separate `Storage<E, T>`
83//! - All storages are type-erased into `dyn ComponentBucket<E>`
84//! - ECS queries are resolved using sets and intersections
85//! - Entities can be any `Copy + Eq + Hash` type (e.g. `u32`)
86//!
87//! ---
88//!
89//! ## 🛠 License
90//!
91//! Licensed under either of:
92//!
93//! - MIT license <https://opensource.org/licenses/MIT>
94//! - Apache License, Version 2.0 <https://www.apache.org/licenses/LICENSE-2.0>
95//!
96//! ---
97//!
98//! ## 🦀 Created by Buzzac
99//!
100//! For questions, ideas, or contributions, feel free to open an issue or PR.
101//!
102//! Want to regenerate this README from your docs?
103//!
104//! ```sh
105//! cargo install cargo-readme
106//! cargo readme > README.md
107//! ```
108
109
110mod components;
111mod storage;
112mod query;
113
114pub use crate::components::{Component, ComponentBucket, ComponentList};
115pub use crate::query::{Query, With, Without};
116pub use crate::storage::{ComponentStorage, Storage};
117pub use simplecs_derive::Component;