diff --git a/README.md b/README.md index e6a611b..1625540 100644 --- a/README.md +++ b/README.md @@ -1,144 +1,91 @@ -

- -

- - -[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge)](LICENSE) [![Wally](https://img.shields.io/github/v/tag/ukendio/jecs?&style=for-the-badge)](https://wally.run/package/ukendio/jecs) +
+ Jecs Logo + # Jecs - ### Just a Stupidly Fast ECS for Roblox - - [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge)](LICENSE) + ### Just a Stupidly Fast Entity Component System + + [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge)](LICENSE) [![Wally](https://img.shields.io/github/v/tag/ukendio/jecs?&style=for-the-badge)](https://wally.run/package/ukendio/jecs) - -# Jecs - Just a Stupidly Fast ECS - A high-performance Entity Component System (ECS) for Roblox games, with first-class support for both Luau and TypeScript.
-A high-performance Entity Component System (ECS) for Roblox games, supporting both Luau and TypeScript. ## ✨ Features -## Features -- 🚀 **Blazing Fast:** Iterate over hundreds of thousands of entities at 60 FPS -- 🔗 **Entity Relationships:** First-class support for entity relationships -- 🏷️ **Component Traits:** Add metadata and behavior to components -- 📝 **Type Safety:** Fully typed API for both Luau and TypeScript +- 🚀 **Blazing Fast:** Iterate over 800,000 entities at 60 FPS +- 🔗 **Entity Relationships:** First-class support for [entity relationships](https://ajmmertens.medium.com/building-games-in-ecs-with-entity-relationships-657275ba2c6c) +- 📝 **Type Safety:** Fully typed [Luau](https://luau-lang.org/) API - 🎯 **Zero Dependencies:** Simple integration with no external dependencies -- ⚡ **Optimized Storage:** Cache-friendly archetype/SoA storage -- ✅ **Battle-tested:** Comprehensive test coverage -- 📚 **Well Documented:** Clear, thorough documentation and examples +- ⚡ **Optimized Storage:** Cache-friendly [archetype/SoA](https://ajmmertens.medium.com/building-an-ecs-2-archetypes-and-vectorization-fe21690805f9) storage +- ✅ **Battle-tested:** [Rigorously tested](https://github.com/Ukendio/jecs/actions/workflows/ci.yaml) for stability -* **Blazing Fast:** Iterate over hundreds of thousands of entities at 60 frames per second. Benchmark results are available in the documentation. -* **Entity Relationships:** First-class support for defining and querying relationships between entities. -* **Type Safety:** Fully typed API for both Luau and TypeScript, enhancing code maintainability and reducing errors. -* **Zero Dependencies:** No external dependencies required, simplifying integration into your project. -* **Optimized Storage:** Cache-friendly archetype/SoA (Structure of Arrays) storage for optimal performance. -* **Battle-tested:** Rigorously unit tested for stability and reliability. -* **Comprehensive Documentation:** Detailed documentation guides you through installation, usage, and advanced concepts. -## 🚀 Quick Start - -### Installation - -## Documentation - -* [Getting Started](docs/learn/overview/get-started.md) -* [API Reference](docs/api/jecs.md) (Note: This link may need updating to reflect the actual location of the API docs if they are generated separately) -* [Concepts](docs/learn/concepts/) - * Entities and Components - * Queries - * Relationships - * Component Traits - * Addons -* [Examples](examples/) -* [FAQ](docs/learn/faq/common-issues.md) -* [Contributing](docs/contributing/) - - -## Quick Example (Luau) +## 🚀 Example Usage ```lua local world = jecs.World.new() -local Position = world:component() :: jecs.Entity -local Velocity = world:component() :: jecs.Entity +local pair = jecs.pair -local entity = world:entity() -world:set(entity, Position, Vector3.new(0, 0, 0)) -world:set(entity, Velocity, Vector3.new(1, 0, 0)) +-- These components and functions are actually already builtin +-- but have been illustrated for demonstration purposes +local ChildOf = world:component() +local Name = world:component() --- Update system (example) -for id, position, velocity in world:query(Position, Velocity) do - world:set(id, Position, position + velocity) +local function parent(entity) + return world:target(entity, ChildOf) end + +local function getName(entity) + return world:get(entity, Name) +end + +local alice = world:entity() +world:set(alice, Name, "alice") + +local bob = world:entity() +world:add(bob, pair(ChildOf, alice)) +world:set(bob, Name, "bob") + +local sara = world:entity() +world:add(sara, pair(ChildOf, alice)) +world:set(sara, Name, "sara") + +print(getName(parent(sara))) +for e in world:query(pair(ChildOf, alice)) do + print(getName(e), "is the child of alice") +end + +-- Output +-- "alice" +-- bob is the child of alice +-- sara is the child of alice ``` -## Quick Example (TypeScript) +## ⚡ Performance -```typescript -import { World } from "@rbxts/jecs"; +### Query Performance +21,000 entities, 125 archetypes, 4 random components queried: +![Queries](assets/image-3.png) +*Benchmark source: /benches/visual/query.luau* -const world = new World(); -const Position = world.component(); -const Velocity = world.component(); +### Insertion Performance +Inserting 8 components to an entity and updating them over 50 times: +![Insertions](assets/image-4.png) +*Benchmark source: /benches/visual/insertions.luau* -const entity = world.entity(); -world.set(entity, Position, new Vector3(0, 0, 0)); -world.set(entity, Velocity, new Vector3(1, 0, 0)); +## 📖 Documentation -// Update system (example) -for (const [id, position, velocity] of world.query(Position, Velocity)) { - world.set(id, Position, position.add(velocity)); -} -``` +- [Getting Started](docs/learn/overview/get-started.md) +- [API Reference](docs/api/jecs.md) +- [Examples](examples/) +- [Common Issues](docs/learn/faq/common-issues.md) -## Performance +## 🤝 Contributing -Benchmark results demonstrating Jecs' performance are available in the documentation. These include query and insertion performance tests. +Please read our [Contributing Guidelines](CONTRIBUTING.md) before submitting pull requests. -## Installation +## 💬 Community -### Using Wally (Luau) +- Join our [Discord](https://discord.gg/h2NV8PqhAD) +- Report issues on [GitHub](https://github.com/ukendio/jecs/issues) -Add Jecs to your `wally.toml`: +## 📄 License -Using Wally (recommended): -```toml -[dependencies] -jecs = "ukendio/jecs@0.2.3" -``` - -Then run: - -```bash -wally install -``` - -### Using npm (Roblox-ts) - -```bash -npm install @rbxts/jecs -``` - -### Standalone Installation - -1. Download `jecs.rbxm` from the [releases page](https://github.com/ukendio/jecs/releases). -2. Import it into your Roblox project. - - -## Contributing - -We welcome contributions! Please see our [contribution guidelines](docs/contributing/guidelines.md) for details. - -## Community & Support - -* [Discord Community](https://discord.gg/h2NV8PqhAD) -* [GitHub Issues](https://github.com/ukendio/jecs/issues) -* [API Documentation](https://ukendio.github.io/jecs/) (Note: This link may need updating) - -## License - -Jecs is [MIT licensed](LICENSE). - -``` - -Jecs = "ukendio/jecs@VERSION" -``` +Jecs is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. \ No newline at end of file