diff --git a/README.md b/README.md index c7e9adc..6157bfc 100644 --- a/README.md +++ b/README.md @@ -20,30 +20,28 @@ Pico Entity System for JavaScript (ES6+). Read up on what an ECS is here: [https://en.wikipedia.org/wiki/Entity_component_system](https://en.wikipedia.org/wiki/Entity_component_system) -This entity system is designed to be as simple as possible, while still having useful features. - ### Features - **Simple query syntax** - `world.each('a', 'b', ({a, b}) => { a.foo = b.bar })` - See the examples below for more advanced usage, or the [reference docs](https://ayebear.com/picoes/class/src/world.js~World.html#instance-method-each) -- **No formal declarations required** - - Can create **unlimited** (within memory limits) components and entities in a world and query on them, without needing to define structured systems and components -- **Strings as component keys** - - No need to manually define component keys, or manually include component classes to use them -- **Automatic dependency injection for systems** +- **Optional registration of systems and components** + - Once a `World` instance is made, you can arbitrarily set components on entities and query them + - This is possible due to the use of strings as component keys +- **Automatic dependency injection** - No need to pass state to each system, can have a single context that gets injected into all systems automatically + - Registered components also get their parent entity injected - **Balanced performance** - See [ECS benchmark comparison](https://github.com/noctjs/ecs-benchmark) - - Entity/Component adding/removing performance is decent with PicoES, which is important for many games. - - Active research and work is being done to significantly improve PicoES performance as much as possible without making it harder to use. + - Entity/Component adding/removing performance is good with PicoES, which is important for many games. + - Continued research is being done to find new ways to make PicoES faster. There are many things such as pools, bit arrays, better indexing structures, and more that could be done to achieve this. ### Terminology - **Component:** Holds some related data - Example: Position, Velocity, Health - **Entity:** Refers to a collection of components - - Example: Position + Health could represent a player + - Example: Position and Health could represent a player - **System:** Logic loop that processes entities - Example: Movement system which handles positions and velocities - **World:** The entry point of all PicoES features. Can register components/systems and create/query entities in a self-contained object - which avoids the use of singletons. @@ -60,7 +58,7 @@ Eric Hebert ### Setup -You'll normally want to install PicoES as a dev dependency, and have it transpiled into the build of your application. +You'll normally want to install PicoES as a dev dependency, and have it transpiled into the build of your application. PicoES uses features such as import/export syntax, so you may need updated tools to use it. It has been used successfully with node 14+ and parcel 2+. #### Yarn @@ -82,7 +80,7 @@ The full reference documentation can be found here: ### Examples -#### Shorthand anonymous components and systems +#### Unregistered components and queries ```javascript import { World } from 'picoes' @@ -106,4 +104,44 @@ world.each('damages', ({ damages }) => { console.assert(player.get('health').value === 60) ``` -More complete examples coming with final 1.0.0 release! For now, refer to the [full documentation](https://ayebear.com/picoes). +#### System and component registration + +```javascript +import { World } from 'picoes' + +// Create a reusable vector component +class Vec2 { + constructor(x = 0, y = 0) { + this.x = x + this.y = y + } +} + +// Define a system for handling movement +class Movement { + run(dt) { + this.world.each('position', 'velocity', ({ position, velocity }) => { + position.x += velocity.x * dt + position.y += velocity.y * dt + }) + } +} + +// Create a world, register components and systems +const world = new World({ + components: { position: Vec2, velocity: Vec2 }, + systems: [Movement], +}) + +// Create an entity at (0,0) with a velocity +const entity = world.entity().set('position').set('velocity', 10, 10) + +// Run the systems (typically would use a ticker and pass dt) +world.run(16) + +// See that the entity has moved +const { x, y } = entity.get('position') +console.log(x, y) // 160 160 +``` + +For more information, refer to the [full documentation](https://ayebear.com/picoes).