{"id":27251504,"url":"https://github.com/byloth/micro-ecs","last_synced_at":"2026-01-23T15:43:04.661Z","repository":{"id":286341660,"uuid":"959922267","full_name":"Byloth/micro-ecs","owner":"Byloth","description":"🕹 A simple \u0026 lightweight ECS (Entity Component System) library for JavaScript and TypeScript.","archived":false,"fork":false,"pushed_at":"2026-01-10T20:02:10.000Z","size":565,"stargazers_count":7,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-01-11T05:47:23.783Z","etag":null,"topics":["ecs","entity-component-system","javascript","library","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Byloth.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"Byloth"}},"created_at":"2025-04-03T15:10:17.000Z","updated_at":"2026-01-10T20:02:14.000Z","dependencies_parsed_at":"2025-06-25T09:32:53.662Z","dependency_job_id":"284ef3b8-c611-48af-a7b3-11b84b46c3d5","html_url":"https://github.com/Byloth/micro-ecs","commit_stats":null,"previous_names":["byloth/micro-ecs"],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/Byloth/micro-ecs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Byloth%2Fmicro-ecs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Byloth%2Fmicro-ecs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Byloth%2Fmicro-ecs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Byloth%2Fmicro-ecs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Byloth","download_url":"https://codeload.github.com/Byloth/micro-ecs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Byloth%2Fmicro-ecs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28694830,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-23T14:15:13.573Z","status":"ssl_error","status_checked_at":"2026-01-23T14:09:05.534Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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","library","typescript"],"created_at":"2025-04-11T01:10:09.579Z","updated_at":"2026-01-23T15:43:04.638Z","avatar_url":"https://github.com/Byloth.png","language":"TypeScript","funding_links":["https://github.com/sponsors/Byloth"],"categories":[],"sub_categories":[],"readme":"# μECS 🕹\n\n[![NPM Version](https://img.shields.io/npm/v/%40byloth%2Fmicro-ecs)](https://www.npmjs.com/package/@byloth/micro-ecs)\n[![Codecov](https://codecov.io/gh/Byloth/micro-ecs/graph/badge.svg?token=GU8UM7FQFL)](https://codecov.io/gh/Byloth/micro-ecs)\n[![NPM release](https://github.com/Byloth/micro-ecs/actions/workflows/release-npm.yml/badge.svg)](https://github.com/Byloth/micro-ecs/actions/workflows/release-npm.yml)\n[![GPR release](https://github.com/Byloth/micro-ecs/actions/workflows/release-gpr.yml/badge.svg)](https://github.com/Byloth/micro-ecs/actions/workflows/release-gpr.yml)\n[![NPM Downloads](https://img.shields.io/npm/dt/%40byloth%2Fmicro-ecs)](https://www.npmjs.com/package/@byloth/micro-ecs)\n[![License](https://img.shields.io/github/license/byloth/micro-ecs)](https://www.apache.org/licenses/LICENSE-2.0)\n\nA simple \u0026 lightweight ECS (Entity Component System) library for JavaScript and TypeScript.\n\n---\n\n## Overview\n\nμECS (micro-ecs) is a **headless library**, completely agnostic to any graphics or rendering library.\n\nTraditional ECS architectures excel in low-level contexts with direct memory control (C++, Rust, etc.).  \nJavaScript doesn't offer this level of control, so μECS takes a **pragmatic approach**: it brings only the ECS benefits that translate well to a high-level environment, leaving behind optimizations that would require direct memory management.\n\n### Design Philosophy\n\nThe library is built on three pillars:\n\n- **DX-first**: Developer Experience is prioritized over raw performance.  \nThe library doesn't use TypedArrays which would be faster but significantly hurt ergonomics.  \nA pleasant API is more valuable than squeezing out every microsecond.\n- **Familiarity**: The API should feel natural to any JavaScript developer.  \nThis means using recognizable patterns: ES6 classes, getters/setters, pub/sub events, and typical OOP idioms common in the JS ecosystem.\n- **Speed over Memory**: When trade-offs are necessary, execution speed is preferred over memory consumption.  \nUsing extra memory is acceptable if it yields performance benefits at runtime.\n\n---\n\n## Features\n\n- **World** — Central container managing Entities, Systems, Resources, and Services\n- **Entity** — Container for Components, can be enabled/disabled\n- **Component** — Data attached to Entities, with independent enable/disable\n- **System** — Logic operating on entities/components, with priority-based execution\n- **Resource** — Singleton data shared across the world\n- **Service** — A System that can be used as a Resource dependency\n- **QueryManager** — Efficient component queries with cached views\n- **QueryView** — Cached, auto-updating view of entities matching a query\n- **Contexts** — Dependency injection for Systems (WorldContext) and Components (EntityContext)\n- **Events** — Built-in pub/sub system via `Publisher`\n\n---\n\n## Installation\n\n```bash\n# npm\nnpm install @byloth/micro-ecs @byloth/core\n\n# pnpm\npnpm add @byloth/micro-ecs @byloth/core\n\n# yarn\nyarn add @byloth/micro-ecs @byloth/core\n\n# bun\nbun add @byloth/micro-ecs @byloth/core\n```\n\n\u003e **Note:** This library requires `@byloth/core` as a peer dependency.\n\n---\n\n## Quick Start\n\n```typescript\nimport { World, Entity, Component, System } from \"@byloth/micro-ecs\";\nimport type { ReadonlyQueryView } from \"@byloth/micro-ecs\";\n\n// Define Components\nclass Position extends Component {\n  public x = 0;\n  public y = 0;\n}\nclass Velocity extends Component {\n  public vx = 0;\n  public vy = 0;\n}\n\n// Define a System\nclass MovementSystem extends System {\n  private view?: ReadonlyQueryView\u003c[Position, Velocity]\u003e;\n\n  public override onAttach(world: World): void {\n    this.view = world.getComponentView(Position, Velocity);\n  }\n  public override update(deltaTime: number): void {\n\n    for (const [position, velocity] of this.view!.components) {\n      position.x += velocity.vx * deltaTime;\n      position.y += velocity.vy * deltaTime;\n    }\n  }\n}\n\n// Create the World\nconst world = new World();\n\n// Add Systems and Entities\nworld.addSystem(new MovementSystem());\n\nconst entity = new Entity();\nentity.addComponent(new Position());\nentity.addComponent(new Velocity());\nworld.addEntity(entity);\n\n// Game loop\nfunction gameLoop(deltaTime: number) {\n  world.update(deltaTime);\n}\n```\n\n---\n\n## Architecture\n\n### Core Classes\n\n```\nComponent   — Data attached to Entities (standalone class)\nResource    — Singleton data, attachable to World\n├── Entity  — Container for Components\n└── System  — Logic with update(), priority, enable/disable\n```\n\n### QueryManager\n\nEfficiently queries entities by component types:\n\n```typescript\n// Get first component of type\nworld.getFirstComponent(Position);\n\n// Get first entity with all component types\nworld.getFirstComponents(Position, Velocity);\n\n// Iterate all matching entities\nworld.findAllComponents(Position, Velocity);\n\n// Get cached view that auto-updates\nworld.getComponentView(Position, Velocity);\n```\n\n### Contexts\n\n**WorldContext** — Provided to Systems for:\n- Event subscription (`on`, `once`, `wait`, `off`)\n- Event emission (`emit`)\n- Resource dependency management (`useResource`, `releaseResource`)\n\n**EntityContext** — Provided to Components for:\n- Component dependency management (`useComponent`, `releaseComponent`)\n\n---\n\n## Roadmap\n\n### 🔴 Critical Implementations\n\nEssential features that are currently missing.\n\n*Luckily, none at the moment.*\n\n---\n\n### 🟠 Known Bugs \u0026 Limitations\n\nIssues and constraints that need addressing.\n\n*Inexplicably, none at the moment.*\n\n---\n\n### 🟡 Improvements\n\nOptimizations and refinements that improve quality and performance.\n\n- [ ] **Automatic View garbage collection**\n\n  Implement an automatic clean-up system for `QueryManager` that detects and removes Views no longer referenced or used, avoiding memory accumulation over time.\n\n---\n\n### 🟢 Future Considerations\n\nIdeas and possible evolutions to evaluate based on needs.\n\n- [ ] **Object pooling**\n\n  Implement a pooling system for `Entity` and `Component` to reduce Garbage Collector pressure in scenarios with high creation/destruction frequency (e.g., particle systems, projectiles).\n\n  \u003e ⚠️ Evaluate carefully: could complicate the API and go against the project's \"DX-first\" philosophy.\n\n- [ ] **Archetype-based architecture**\n\n  Implement an Archetype system within the query and component management to group entities by their component composition, improving iteration performance and cache locality.\n\n---\n\n### 🔵 Nice to Have\n\nFeatures that would be beneficial but are not critical.\n\n- [ ] **Advanced Query System**\n\n  Rewrite the query system from scratch to allow users to define queries using, chaining and nesting logical operators: `and`, `or` and `not`.\n\n---\n\n## License\n\n[Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbyloth%2Fmicro-ecs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbyloth%2Fmicro-ecs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbyloth%2Fmicro-ecs/lists"}