@chantey/ecs

Easy ECS

Easy ECS is an Entity Component System architecture putting the Developer Experience first, with intuitive queries and component types.

Overview

The two benefits that have made ECS architecture famous are performance and code simplicity. We are focusing on the latter, allowing access to the query based workflow without constraining components to value types, or requiring explicit type schemas to be declared. This is especially suited to rendering libraries like babylon.js and three.js, where the data to be worked on is usually a predefined object like a Vector3 or Material.

Getting Started

//1. define components
const PlayerComp = defineTagComponent()
const EnemyComp = defineTagComponent()
const HealthComp = defineComponent({value:100})
const PositionComp = defineComponent({x:0})

//2. define queries
const PlayerQuery = defineQuery({
    player:PlayerComp
    health:HealthComp,
    position:PositionComp
})
const EnemyQuery = defineQuery({
    enemy:EnemyComp
    health:HealthComp,
    position:PositionComp
})

//3. define systems
const DamageSystem = defineSystem(world=>{
    
    //4. (optional) create 'tuples' for working on related pairs of entities 
    const playerEnemyTuple = createQueryTuple({playerQuery,enemyQuery})
    
    return {
        update:()=>{
            world.query(PlayerQuery).forEach(({position})=>
                position.x += 0.01    
            )

            playerEnemyTuple.forEach(({playerQuery,enemyQuery})=>{
                if(Math.abs(enemyQuery.position.x - playerQuery.position.x) < 5)
                    playerQuery.health.value -= 10
            })
        }
    }
})

//5. define a small module, to be combined with others in the composition of a sketch
const damageModule = defineModule({
    components:{PlayerComp,EnemyComp,PositionComp,HealthComp},
    queries:{PlayerQuery,EnemyQuery},
    systems:{DamageSystem}
})

//6. create your world and entities
const world = createWorld(damageModule)

world.createEntity()
    .addComponent(PlayerComp)
    .addComponent(HealthComp,{value:100})
    .addComponent(PositionComp,{x:30})

world.createEntity()
    .addComponent(EnemyComp)
    .addComponent(HealthComp,{value:20})
    .addComponent(PositionComp,{x:50})

//7. Begin the render loop!
world.start()
setTimeout(world.update,16)

TODO

• Print Component Table
• Queries
  • Currently query maps are for component instances, shouldnt they be for component definitions?
• Default Values
  • This will not work as expected because reference types, use factories?
  • functions not working - vec = defineComponent(()=>new Vector3())
  • it was 'sorta' overriding when i set the values ie entity.set(vec,myVector3)

Reference

• Overwatch - Singleton Components
  • 40% of components are singletons