{"id":18103162,"url":"https://github.com/gastonmorixe/ecs-animation-engine","last_synced_at":"2026-05-04T05:39:49.215Z","repository":{"id":259135851,"uuid":"876406325","full_name":"gastonmorixe/ecs-animation-engine","owner":"gastonmorixe","description":"🏂 Entity Component System (ECS) physics animation engine with damped harmonic oscillator (springs, and friction)","archived":false,"fork":false,"pushed_at":"2024-10-24T15:08:04.000Z","size":90,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-06T05:43:15.178Z","etag":null,"topics":["animation","animation-engine","ecs","enitity-component-system","harmonic-oscillator","physics","spring"],"latest_commit_sha":null,"homepage":"https://gastonmorixe.github.io/ecs-animation-engine/","language":"TypeScript","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/gastonmorixe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-21T23:12:54.000Z","updated_at":"2024-10-24T15:08:08.000Z","dependencies_parsed_at":"2024-12-19T13:26:49.139Z","dependency_job_id":"508e0eb1-3df7-4993-a0ea-e36db49ef75d","html_url":"https://github.com/gastonmorixe/ecs-animation-engine","commit_stats":null,"previous_names":["gastonmorixe/ecs-animation-engine"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/gastonmorixe/ecs-animation-engine","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gastonmorixe%2Fecs-animation-engine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gastonmorixe%2Fecs-animation-engine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gastonmorixe%2Fecs-animation-engine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gastonmorixe%2Fecs-animation-engine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gastonmorixe","download_url":"https://codeload.github.com/gastonmorixe/ecs-animation-engine/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gastonmorixe%2Fecs-animation-engine/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32596533,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T22:12:39.696Z","status":"online","status_checked_at":"2026-05-04T02:00:06.625Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["animation","animation-engine","ecs","enitity-component-system","harmonic-oscillator","physics","spring"],"created_at":"2024-10-31T22:10:43.118Z","updated_at":"2026-05-04T05:39:49.199Z","avatar_url":"https://github.com/gastonmorixe.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Entity Component System (ECS) Physics Animation Engine\n\n![CleanShot 2024-10-21 at 19 21 00](https://github.com/user-attachments/assets/93241f1c-50c1-4c76-bdbe-3b4e958aa734)\n\n\n### Description\n\n**Entity Component System (ECS) physics animation engine with damped harmonic oscillator (springs, and friction)**\n\nThis project is a physics animation engine built using the Entity Component System (ECS) architectural pattern. The engine simulates the motion of entities affected by forces such as springs and friction, incorporating physical concepts like damped harmonic oscillators to create realistic interactions.\n\nThe engine provides an efficient way to simulate and visualize complex systems with multiple entities, leveraging ECS for high performance and modularity.\n\n### Features\n\n- **ECS Architecture**: Modular design using an Entity Component System for a flexible, scalable physics simulation.\n- **Spring System**: Damped harmonic oscillators for realistic spring-based motion.\n- **Friction System**: Implemented friction that opposes velocity, creating natural deceleration.\n- **Mouse Interaction**: Drag and release entities with realistic forces applied, such as spring pullback and friction.\n- **Chart Visualization**: Real-time visualization of entity properties (position, velocity, and force) using Chart.js, allowing you to observe the effect of forces over time.\n\n### Usage \n\nCheck `src/main.ts` \n\n```ts\n// Engine\nimport { AnimationEngine } from \"./engine\";\n\n// ECS - Core\nimport { MovementSystem, FrictionSystem } from \"./systems\";\nimport { BoxEntity, AnchorEntity } from \"./entities\";\n\n// Specialized Systems and Entities\nimport { MouseForceSystem, DOMUpdateSystem } from \"./dom\";\nimport { SpringEntity, SpringPhysicsSystem } from \"./spring\";\n\n//\n// -- Entities --\n//\n\n// Create the box entity\nconst boxElement = document.getElementById(\"box1\") as HTMLElement;\nconst boxEntity = new BoxEntity(boxElement, { x: 100, y: 100 }, \"box1\");\n\n// Creating a fixed anchor\nconst anchorEntity = new AnchorEntity({ x: 100, y: 100 }, \"anchor\");\n\n// Create a spring entity that connects box1 and anchor\nconst springEntity = new SpringEntity(boxEntity, anchorEntity, 0.2, 0.05, 1.0);\n\n// Create second box entity\nconst boxElement2 = document.getElementById(\"box2\") as HTMLElement;\nconst boxEntity2 = new BoxEntity(boxElement2, { x: 250, y: 100 }, \"box2\");\n\n// Creating the spring force connecting box and box2\nconst springEntity2 = new SpringEntity(boxEntity, boxEntity2, 0.2, 0.05, 2.0);\n\n// Create third box entity\nconst boxElement3 = document.getElementById(\"box3\") as HTMLElement;\nconst boxEntity3 = new BoxEntity(boxElement3, { x: 400, y: 100 }, \"box3\");\n\n// Creating the spring force connecting box2 and box3\nconst springEntity3 = new SpringEntity(boxEntity2, boxEntity3, 0.1, 0.05, 1.0);\n\n//\n// --- Systems ---\n//\n\n// Set up the movement system (handles physics and movement)\nconst movementSystem = new MovementSystem();\n\n// Creating the friction component and system\nconst frictionSystem = new FrictionSystem();\n\n// Spring physics system\nconst springPhysicsSystem = new SpringPhysicsSystem();\n\n// Set up the mouse force system (handles the spring-like dragging effect)\nconst mouseForceSystem = new MouseForceSystem(0.2, 0.1); // Drag strength and damping\n\n// Set up the DOM update system (handles syncing the DOM with the entity position)\nconst domUpdateSystem = new DOMUpdateSystem();\n\n//\n// -- Engine --\n//\n\n// Create the ECS engine\nconst engine = new AnimationEngine();\n\n// Add Entities to the engine\nengine.addEntity(anchorEntity);\nengine.addEntity(boxEntity);\nengine.addEntity(boxEntity2);\nengine.addEntity(boxEntity3);\nengine.addEntity(springEntity);\nengine.addEntity(springEntity2);\nengine.addEntity(springEntity3);\n\n// Add systems to the engine\nengine.addSystem(springPhysicsSystem);\nengine.addSystem(frictionSystem);\nengine.addSystem(mouseForceSystem);\nengine.addSystem(movementSystem);\nengine.addSystem(domUpdateSystem);\n\n// Start the engine\nengine.start();\n```\n\n### Getting Started\n\n#### Prerequisites\n\n- **Bun**\n\n#### Installation\n\n1. **Clone the Repository**:\n   ```sh\n   git clone https://github.com/gastonmorixe/ecs-animation-engine.git\n   cd ecs-animation-engine\n   ```\n\n2. **Install Dependencies**:\n   ```sh\n   bun install\n   ```\n\n#### Running the Engine\n\n1. **Start the Development Server**:\n   ```sh\n   bun run dev\n   ```\n   This command will start a local development server, and you can view the engine in your browser at `http://localhost:5173`.\n\n2. **Interact with the Simulation**:\n   - **Click and drag** the blue box to move it around.\n   - **Release the mouse** to see the effects of spring forces and friction as the entity moves back towards its anchor.\n\n### Code Overview\n\n#### ECS Pattern\n- **Entities**: Represent the objects in the simulation (e.g., `box`, `anchor`).\n- **Components**: Contain the data needed to describe various aspects of an entity, such as `PositionComponent`, `VelocityComponent`, `ForceComponent`, and `FrictionComponent`.\n- **Systems**: Implement the logic that operates on entities with specific components (e.g., `MovementSystem`, `SpringForceSystem`, `FrictionSystem`).\n\n#### Key Systems\n- **Movement System**: Calculates the new positions of entities based on the forces acting on them.\n- **Spring Force System**: Applies spring forces between entities, creating the effect of a damped harmonic oscillator.\n- **Mouse Force System**: Handles user interactions for dragging entities with the mouse.\n- **Friction System**: Simulates the force of friction opposing entity movement, providing a realistic deceleration.\n- **Chart System**: Visualizes key properties such as position, velocity, and forces over time using Chart.js.\n\n### File Structure\n\n```\n├── bun.lockb\n├── index.html\n├── package.json\n├── public\n├── src\n│   ├── main.ts\n│   ├── style.css\n│   └── vite-env.d.ts\n└── tsconfig.json\n```\n\n### How It Works\n- **Mouse Interaction**: Users can interact with the `box` entity by clicking and dragging it. Upon releasing the mouse, the box is affected by spring and friction forces, resulting in realistic motion and smooth oscillation back towards the anchor point.\n- **Rolling Window for Charts**: To keep the real-time chart visualization readable, a rolling window is used to limit the number of data points shown, preventing performance issues and ensuring clarity.\n\n### Contributing\n\n1. **Fork the Project**\n2. **Create a Branch** (`git checkout -b feature/YourFeature`)\n3. **Commit Your Changes** (`git commit -m 'Add some feature'`)\n4. **Push to the Branch** (`git push origin feature/YourFeature`)\n5. **Open a Pull Request**\n\n### License\n\nThis project is licensed under the MIT License. See `LICENSE` for more information.\n\n### Contact\n\n**Gaston Morixe** - [@gastonmorixe](https://x.com/gastonmorixe) - gaston@gastonmorixe.com\n\nProject Link: [https://github.com/gastonmorixe/ecs-animation-engine](https://github.com/gastonmorixe/ecs-animation-engine)\n\n### Acknowledgements\n- **Chart.js** for real-time data visualization\n- **ECS Pattern** inspiration for flexible game development\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgastonmorixe%2Fecs-animation-engine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgastonmorixe%2Fecs-animation-engine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgastonmorixe%2Fecs-animation-engine/lists"}