{"id":22025746,"url":"https://github.com/dmarkh/easyecs","last_synced_at":"2025-07-25T03:11:28.854Z","repository":{"id":57218847,"uuid":"259173374","full_name":"dmarkh/easyecs","owner":"dmarkh","description":"EasyECS - Entity-Component-System library for Javascript-ES6","archived":false,"fork":false,"pushed_at":"2021-08-12T13:41:51.000Z","size":15,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-01T01:37:56.811Z","etag":null,"topics":["ecs","entity-component-system","javascript-es6","javascript-library"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dmarkh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-04-27T01:30:11.000Z","updated_at":"2021-08-12T13:41:54.000Z","dependencies_parsed_at":"2022-08-29T02:11:47.166Z","dependency_job_id":null,"html_url":"https://github.com/dmarkh/easyecs","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmarkh%2Feasyecs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmarkh%2Feasyecs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmarkh%2Feasyecs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmarkh%2Feasyecs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dmarkh","download_url":"https://codeload.github.com/dmarkh/easyecs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245090876,"owners_count":20559298,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ecs","entity-component-system","javascript-es6","javascript-library"],"created_at":"2024-11-30T07:19:28.050Z","updated_at":"2025-03-23T11:12:45.111Z","avatar_url":"https://github.com/dmarkh.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# EasyECS - Entity-Component-System for Javascript ES6+\n\n## Intro\n\nEasyECS is the Entity-Component-System package, that implements all features of the modern [Entity–component–system](https://en.wikipedia.org/wiki/Entity_component_system).\n\nECS is the architectural pattern that follows the \"composition over inheritance\" principle.\nIt allows much greater readability, extensibility and loose module coupling compared to the inheritance-based object designs.\n\n * Entity - a collection of components that has unique id;\n * Component - plain data structure;\n * Assemblage - helper: a predefined group of components forming pseudo-entity;\n * Query - a rule that describess a selection of entities satisfying some criteria - similar to SQL query;\n * System - code logic module that runs over a set of entities selected by Query(-ies). Systems may add/remove components, or modify component data of a specific entity. Also, Systems may add entities to or remove entities from ECS.\n\nImplementation details:\n\n * Written using JavaScript ES6;\n * Unlike many Javascript ECS systems, this one does not apply updates immediately, but queues them for 'after-tick' batch processing. This allows to apply Systems in parallel;\n * Implements shared Queues for efficient Entity grouping/processing;\n * Components, Assemblages, Entities, Queries are all simple structures, no classes =\u003e store in any format!\n * Implements easy serialization / deserialization of ECS state;\n * Tested to work well with older browsers if transpiled by Babel;\n * Includes basic logging library (see src/Log.js) for easier debugging;\n\n## Core concepts\n\n### ECS initialization\n\n        import { EasyECS, System } from 'easyecs';\n        let ecs = new EasyECS();\n\n### Component definitions\n\n        let components = [\n          [ 'position', { x: 0, y: 0 } ],\n          [ 'speed',  { vx: 0, vy: 0 } ],\n        ];\n        ecs.registerComponents( components );\n\n### Assemblage definitions\n\nNOTE: all components referred to by Assemblage must be registered with ECS first!\n\n        let assemblages = [\n          {\n            name: 'moving_object',\n            components: {\n              position: { x: 0, y: 0 },\n              speed: { vx: 0, vy: 0 },\n            }\n          }\n        ];\n        ecs.registerComponentAssemblages( assemblages );\n\n### Entity definitions\n\n        let circle = {\n          position: { x: 1, y: 1 },\n          speed: { vx: 1.5, vy: 0.5 }\n        };\n        // ...or...\n        let circle = ecs.getComponentAssemblage( \"moving_object\" );\n        // ...or, assemblage with defaults...\n        let circle = ecs.getComponentAssemblage( \"moving_object\", { speed: { vx: 1.5, vy: 0.5 } } );\n        ecs.addEntities([ circle ]);\n\n### Query definitions\n\nQuery definition: ( name, list of component names that MUST present, list of component names that MUST NOT present, is query reactive? ); \n[ '\u003cname\u003e', [ '\u003ccomponent1\u003e'...'\u003ccomponentN\u003e\" ], [ '\u003ccomponent1\u003e' ... '\u003ccomponentN\u003e' ], true/false ]\n\n        let queries = [\n          [ 'query_movable', ['position','speed'], [] ],\n          [ 'query_static', ['position'], ['speed'] ],\n          [ 'query_display', [ 'position', 'display' ], [], true ]\n        ];\n        ecs.registerQueries( queries );\n\n### System definitions\nNOTE: each System must request one or more Queries, that will provide Entity lists!\n\n        // simple system:\n        let SystemMove = new System('SystemMove')\n          .on_queries(['query_movable'])\n          .on_tick( function( entityManager, componentManager ) {\n            this.queries.query_movable.get().forEach( entity =\u003e {\n              let dx = entity.speed.x, dy = entity.speed.y;\n              entityManager.update( entity, 'position', { x: dx, y: dy } );\n            });\n          });\n\n        // a system that uses reactive query:\n        let SystemDisplay = new System('SystemDisplay')\n          .on_queries(['query_display'])\n          .on_tick( function( entityManager, componentManager ) {\n            // a system that intercepts insert/delete/move of entities, and acts accordingly\n            if ( this.queries.query_display.is_changed() ) {\n              // new entries added or old ones removed\n              this.queries.query_display.entities_inserted.forEach( entity =\u003e {\n                // new entity just inserted, let's add a sprite to screen here\n              });\n              this.queries.query_display.entities_deleted.forEach( entity =\u003e {\n                // entity scheduled for removal, remove sprite from screen\n              });\n            }\n            if ( this.queries.query_display.is_updated() ) {\n              this.queries.query_display.entities_updated.forEach( ( components, entity, map ) =\u003e {\n                // some entity component was updated, let's move sprite\n              });\n            }\n          });\n        ecs.registerSystems([ SystemMove, SystemDisplay ]);\n\n### Basic ECS loop\n\n        while( 1 ) {\n          await ecs.tick();\n        }\n\n### ECS state save / load\n\n        // save ECS state to JSON-encoded string:\n        let json_string = ecs.serialize();\n        \n        // then, sometime later, restore ECS state:\n        ecs.clear();\n        ecs.deserialize( json_string );\n\n## How-To\n\n### Installation\n\nEasyECS package could be installed via NPM:\n        \n        $\u003e npm install easyecs\n        \n### Usage \n\n Please see \"examples\" directory for a tutorial(s) on EasyECS\n\n## License\n\nEasyECS is covered under the terms of [MIT License](https://en.wikipedia.org/wiki/MIT_License)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdmarkh%2Feasyecs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdmarkh%2Feasyecs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdmarkh%2Feasyecs/lists"}