mirror of
https://github.com/Ukendio/jecs.git
synced 2025-04-24 17:10:03 +00:00
Update README.md
This commit is contained in:
Raghav Arora
parent
88e6836017
commit
8e9c1e808b
1 changed files with 65 additions and 118 deletions
183
README.md
183
README.md
|
|
@ -1,144 +1,91 @@
|
|||
<p align="center">
|
||||
<img src="assets/image-5.png" width=35%/>
|
||||
</p>
|
||||
<!-- <div align="center">
|
||||
<img src="assets/image-5.png" width="240" alt="Jecs Logo"/> -->
|
||||
|
||||
[](LICENSE) [](https://wally.run/package/ukendio/jecs)
|
||||
<div align="center">
|
||||
<img src="assets/image-5.png" width="240" alt="Jecs Logo"/>
|
||||
|
||||
# Jecs
|
||||
### Just a Stupidly Fast ECS for Roblox
|
||||
|
||||
[](LICENSE)
|
||||
### Just a Stupidly Fast Entity Component System
|
||||
|
||||
[](LICENSE)
|
||||
[](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.
|
||||
</div>
|
||||
|
||||
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<Vector3>
|
||||
local Velocity = world:component() :: jecs.Entity<Vector3>
|
||||
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:
|
||||
|
||||
*Benchmark source: /benches/visual/query.luau*
|
||||
|
||||
const world = new World();
|
||||
const Position = world.component<Vector3>();
|
||||
const Velocity = world.component<Vector3>();
|
||||
### Insertion Performance
|
||||
Inserting 8 components to an entity and updating them over 50 times:
|
||||
|
||||
*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.
|
||||
Loading…
Reference in a new issue