{"id":21807493,"url":"https://github.com/ten3roberts/flax","last_synced_at":"2025-04-04T09:09:36.484Z","repository":{"id":37758472,"uuid":"491645207","full_name":"ten3roberts/flax","owner":"ten3roberts","description":"Batteries included ECS library for rust with entity relations and much more","archived":false,"fork":false,"pushed_at":"2025-02-18T23:18:37.000Z","size":292084,"stargazers_count":84,"open_issues_count":3,"forks_count":5,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-28T08:09:28.534Z","etag":null,"topics":["ecs","game-development","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ten3roberts.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"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":"2022-05-12T19:37:31.000Z","updated_at":"2025-03-27T13:09:07.000Z","dependencies_parsed_at":"2023-10-21T23:29:06.568Z","dependency_job_id":"611c2d61-8097-4eb8-8a81-2daf38179b9f","html_url":"https://github.com/ten3roberts/flax","commit_stats":{"total_commits":437,"total_committers":1,"mean_commits":437.0,"dds":0.0,"last_synced_commit":"8ef50ca9d5477ea18fc29d84d253b50f6675d716"},"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ten3roberts%2Fflax","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ten3roberts%2Fflax/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ten3roberts%2Fflax/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ten3roberts%2Fflax/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ten3roberts","download_url":"https://codeload.github.com/ten3roberts/flax/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247149502,"owners_count":20891954,"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","game-development","rust"],"created_at":"2024-11-27T12:45:20.183Z","updated_at":"2025-04-04T09:09:36.466Z","avatar_url":"https://github.com/ten3roberts.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Flax\n\n[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/ten3roberts/flax/ci.yml?style=for-the-badge)](https://github.com/ten3roberts/flax/actions)\n[![Crates](https://img.shields.io/crates/v/flax?style=for-the-badge)](https://crates.io/crates/flax)\n[![Docs](https://img.shields.io/docsrs/flax?style=for-the-badge)](https://docs.rs/flax)\n[![Codecov](https://img.shields.io/codecov/c/github/ten3roberts/flax?style=for-the-badge)](https://app.codecov.io/gh/ten3roberts/flax)\n[![Guide](https://img.shields.io/badge/guide-Read%20the%20guide-blue?style=for-the-badge)](https://ten3roberts.github.io/flax/guide)\n\n\u003c!-- cargo-sync-readme start --\u003e\n\nFlax is a performant and ergonomic Entity Component System.\n\nThe world is organized by simple identifiers known as an [`Entity`](https://docs.rs/flax/latest/flax/entity/struct.Entity.html), which can have any number of components attached to them.\n\nSystems operate on the world's entities and provide the application logic.\n\nConsider reading the [User Guide](https://ten3roberts.github.io/flax/guide)\n\n## Features\n\n- [Declarative component macro](https://docs.rs/flax/latest/flax/macro.component.html)\n- [Expressive query system](https://docs.rs/flax/latest/flax/query/struct.Query.html)\n- [Change detection](https://docs.rs/flax/latest/flax/component/struct.Component.html#method.modified)\n- [Query filtering](https://docs.rs/flax/latest/flax/filter/index.html)\n- [System execution](https://docs.rs/flax/latest/flax/system/struct.System.html)\n- [Multithreaded system execution](https://docs.rs/flax/latest/flax/schedule/struct.Schedule.html)\n- [Many to many entity relation and graphs](https://docs.rs/flax/latest/flax/macro.component.html#relations)\n- [Reflection through component metadata](https://docs.rs/flax/latest/flax/macro.component.html)\n- [Ergonomic entity builder](https://docs.rs/flax/latest/flax/entity/struct.EntityBuilder.html)\n- [Serialization and deserialization](https://docs.rs/flax/latest/flax/serialize/)\n- [(async) event subscription](https://docs.rs/flax/latest/flax/world/struct.World.html#method.subscribe)\n- [Runtime components](https://docs.rs/flax/latest/flax/world/struct.World.html#method.spawn_component)\n- ...and more\n\n## [Live Demo](https://ten3roberts.github.io/flax/asteroids)\nSee a live demo of asteroids using wasm [here](https://ten3roberts.github.io/flax/asteroids).\n\n[Source](https://github.com/ten3roberts/flax/blob/main/asteroids/src/main.rs)\n\n## Example Usage\n\n```rust\n  // Declare static components\n  use flax::*;\n\n  component! {\n    health: f32,\n    regen: f32,\n    pos: (f32, f32),\n    player: (),\n    items: Vec\u003cString\u003e,\n  }\n\n  let mut world = World::new();\n\n  // Spawn an entity\n  let p = EntityBuilder::new()\n      .set(health(), 50.0)\n      .tag(player())\n      .set(pos(), (0.0, 0.0))\n      .set(regen(), 1.0)\n      .set_default(items())\n      .spawn(\u0026mut world);\n\n  let mut query = Query::new((health().as_mut(), regen()));\n\n  // Apply health regeneration for all matched entites\n  for (health, regen) in \u0026mut query.borrow(\u0026world) {\n      *health = (*health + regen).min(100.0);\n  }\n\n```\n\n## Systems\nQueries with logic can be abstracted into a system, and multiple systems can be\ncollected into a schedule.\n\n```rust\nlet regen_system = System::builder()\n    .with_query(Query::new((health().as_mut(), regen())))\n    .for_each(|(health, regen)| {\n        *health = (*health + regen).min(100.0);\n    })\n    .boxed();\n\nlet despawn_system = System::builder()\n    .with_query(Query::new(entity_ids()).with_filter(health().le(0.0)))\n    .with_cmd_mut()\n    .build(|mut q: QueryBorrow\u003cEntityIds, _\u003e, cmd: \u0026mut CommandBuffer| {\n        for id in \u0026mut q {\n            cmd.despawn(id);\n        }\n    })\n    .boxed();\n\nlet mut schedule = Schedule::from([regen_system, despawn_system]);\n\nschedule.execute_par(\u0026mut world)?;\n\n```\n## Relations\n\nFlax provides first class many-many relations between entities, which is useful for tree scene\nhierarchies, graphs, and physics joints between entities.\n\nRelations can be both state-less or have associated data, like spring or joint strengths.\n\nRelations are cache friendly and querying children of does not require random access. In\naddition, relations are cleaned up on despawns and are stable during serialization, even if the\nentity ids migrate due to collisions.\n\nSee [the guide](https://ten3roberts.github.io/flax/guide/fundamentals/relations.html) for more\ndetails.\n\n```rust\ncomponent! {\n    child_of(parent): () =\u003e [ Debuggable ],\n}\n\nlet mut world = World::new();\n\nlet parent = Entity::builder()\n    .set(name(), \"Parent\".into())\n    .spawn(\u0026mut world);\n\nlet child1 = Entity::builder()\n    .set(name(), \"Child1\".into())\n    .set_default(child_of(parent))\n    .spawn(\u0026mut world);\n\n\n```\n\n\n## Comparison to other ECS\n\nCompared to other ECS implementations, a component is simply another `Entity`\nidentifier to which data is attached. This means the same \"type\" can be added to\nan entity multiple times.\n\nA limitation of existing implementations such as [specs](https://github.com/amethyst/specs), [planck](https://github.com/jojolepro/planck_ecs/), or [hecs](https://github.com/Ralith/hecs) is that newtype wrappers need to be created to allow components of the same inner type to coexist.\n\nThis leads to having to forward all trait implementations trough e.g\n`derive-more` or dereferencing the *newtypes* during usage.\n\nBy making components separate from the type the components can work together without `deref` or\nnewtype construction.\n\n```rust\ncomponent! {\n    velocity: Vec3,\n    position: Vec3,\n}\n\nlet vel = world.get(entity, velocity())?;\nlet mut pos = world.get_mut(entity, position())?;\nlet dt = 0.1;\n\n*pos += *vel * dt;\n```\n\nOn a further note, since the components have to be declared beforehand, it limits the amount of types which can be\ninserted as components. This fixes subtle bugs which come by having the type\ndictate the component, such as using an `Arc\u003cType\u003e` instead of just `Type`,\nwhich leads to subsequent systems not finding the `Type` on the entity.\n\nUsing statically declared components makes the rust type system disallow\nthese cases and catches these bugs earlier.\n\n## Motivation\n\nDuring development of a game in school I used the `hecs` ECS. It is an awesome\nlibrary, and the author [Ralith](https://github.com/Ralith) has been wonderful in accepting\ncontributions and inquiries.\n\nDespite this, I often made subtle bugs with *similar* types. The game engine was\ncluttered with gigantic newtypes for `Velocity`, `Position` with many *deref*\ncoercions in order to coexist.\n\n## Unsafe\nThis library makes use of unsafe for type erasure and the allocation in storage\nof `ComponentBuffer`s and `Archetype`s.\n\n\u003c!-- cargo-sync-readme end --\u003e\n\nLicense: MIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ften3roberts%2Fflax","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ften3roberts%2Fflax","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ften3roberts%2Fflax/lists"}