{"id":13712300,"url":"https://github.com/Avokadoen/ecez","last_synced_at":"2025-05-06T21:33:49.869Z","repository":{"id":41653884,"uuid":"510328790","full_name":"Avokadoen/ecez","owner":"Avokadoen","description":"An ECS API for Zig!","archived":false,"fork":false,"pushed_at":"2025-04-29T17:57:49.000Z","size":1601,"stargazers_count":31,"open_issues_count":21,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-03T21:30:03.115Z","etag":null,"topics":["data-oriented-programming","ecs","zig"],"latest_commit_sha":null,"homepage":"","language":"Zig","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/Avokadoen.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":"2022-07-04T11:19:39.000Z","updated_at":"2025-04-29T17:57:52.000Z","dependencies_parsed_at":"2023-11-24T20:27:15.918Z","dependency_job_id":"da5913ae-dc45-48a6-a928-e3645641a555","html_url":"https://github.com/Avokadoen/ecez","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Avokadoen%2Fecez","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Avokadoen%2Fecez/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Avokadoen%2Fecez/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Avokadoen%2Fecez/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Avokadoen","download_url":"https://codeload.github.com/Avokadoen/ecez/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252772556,"owners_count":21801941,"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":["data-oriented-programming","ecs","zig"],"created_at":"2024-08-02T23:01:16.893Z","updated_at":"2025-05-06T21:33:49.862Z","avatar_url":"https://github.com/Avokadoen.png","language":"Zig","funding_links":[],"categories":["Multimedia \u0026 Graphics"],"sub_categories":["Game Development"],"readme":"![Test](https://github.com/Avokadoen/ecez/actions/workflows/test.yaml/badge.svg)\r\n\r\n# ECEZ - An ECS API\r\n\r\nThis is a ECS (Entity Component System) API for Zig.\r\n\r\n## Try it yourself!\r\n\r\n### Requirements\r\n\r\nThe [zig compiler 0.14.0](https://ziglang.org)\r\n\r\nYou can use zigup to easily get this specific version\r\n\r\n### Steps\r\nRun the following commands\r\n```bash\r\n# Clone the repo\r\ngit clone https://github.com/Avokadoen/ecez.git\r\n# Run tests\r\nzig build test\r\n# Run GOL example, use '-Denable-tracy=true' at the end to add tracy functionality\r\nzig build run-game-of-life \r\n\r\n```\r\n\r\nYou should also checkout [src/root.zig](https://github.com/Avokadoen/ecez/blob/main/src/root.zig) which has the public API. From there you can follow the deifinition to get more details.\r\n\r\n### Include ecez and optionally tracy in your project\r\n\r\nAdd ecez to build.zig.zon, example in terminal:\r\n```\r\nzig fetch --save git+https://github.com/Avokadoen/ecez.git/#HEAD\r\n```\r\n\r\n#### Basic ecez build\r\n\r\nbuild.zig\r\n```zig\r\nconst ecez = b.dependency(\"ecez\", .{});\r\nconst ecez_module = ecez.module(\"ecez\");\r\nexe.addImport(\"ecez\", ecez_module);\r\n```\r\n\r\n#### Using ztracy with ecez:\r\nbuild.zig:\r\n```zig\r\nconst options = .{\r\n   .enable_ztracy = b.option(\r\n      bool,\r\n      \"enable_ztracy\",\r\n      \"Enable Tracy profile markers\",\r\n   ) orelse false,\r\n   .enable_fibers = b.option(\r\n      bool,\r\n      \"enable_fibers\",\r\n      \"Enable Tracy fiber support\",\r\n   ) orelse false,\r\n   .on_demand = b.option(\r\n      bool,\r\n      \"on_demand\",\r\n      \"Build tracy with TRACY_ON_DEMAND\",\r\n   ) orelse false,\r\n};\r\n\r\n// link ecez and ztracy\r\n{\r\n   const ecez = b.dependency(\"ecez\", .{\r\n      .enable_ztracy = options.enable_ztracy,\r\n      .enable_fibers = options.enable_fibers,\r\n      .on_demand = options.on_demand,\r\n   });\r\n   const ecez_module = ecez.module(\"ecez\");\r\n\r\n   exe.root_module.addImport(\"ecez\", ecez_module);\r\n   exe_unit_tests.root_module.addImport(\"ecez\", ecez_module);\r\n\r\n   const ztracy_dep = ecez.builder.dependency(\"ztracy\", .{\r\n      .enable_ztracy = options.enable_ztracy,\r\n      .enable_fibers = options.enable_fibers,\r\n      .on_demand = options.on_demand,\r\n   });\r\n   const ztracy_module = ztracy_dep.module(\"root\");\r\n\r\n   exe.root_module.addImport(\"ztracy\", ztracy_module);\r\n   exe_unit_tests.root_module.addImport(\"ztracy\", ztracy_module);\r\n\r\n   exe.linkLibrary(ztracy_dep.artifact(\"tracy\"));\r\n}\r\n```\r\n\r\n## Zig documentation\r\n\r\nYou can generate the ecez API documentation using `zig build docs`. This will produce some web resources in `zig-out/doc/ecez`. \r\nYou will need a local server to serve the documentation since browsers will block resources loaded by the index.html. \r\n\r\nThe simplest solution to this is just using a basic python server:\r\n```bash\r\npython -m http.server 8000 -d ecez/zig-out/doc/ecez # you can then access the documentation at http://localhost:8000/#ecez.main \r\n```\r\n\r\n## Features\r\n\r\n### Compile time based and type safe API\r\nZig's comptime feature is utilized to perform static reflection on the usage of the API to validate usage and report useful messages to the user (in theory :)). \r\n\r\nhttps://github.com/Avokadoen/ecez/blob/7210c43d2dbe6202806acf3e5ac361cbbaed11af/examples/readme/main.zig#L1-L190\r\n\r\n### System arguments\r\n\r\nSystems can take 3 argument types:\r\n * Queries - Storage queries requesting a certain entity composition. T\r\n * Storage.Subset - A subset of the storage. This is just the normal storage with limitations on which \r\n    components can be touched. You can create entities, (un)set components .. etc\r\n * EventArgument - Any non query or subset. Can be useful as a \"context\" for the event\r\n\r\n### Implicit multithreading of systems\r\n\r\nWhen you trigger a system dispatch or an event with multiple systems then ecez will schedule this work over multiple threads. \r\nSynchronization is handled by ecez although there are some caveats that you should be aware of:\r\n\r\n * Dont request write access (query result members that are of pointer type) unless you need it.\r\n    * Writes has more limitations on what can run in parallel \r\n * Be specific, only request the types you will use.\r\n * EventArgument will not be considered when synchronizing. This means that if you mutate an event argument then you must take some care in order to ensure legal behaviour\r\n \r\n\r\n### Serialization through the ezby format\r\n\r\necez uses a custom byte format to convert storages into a slice of bytes.\r\n\r\n#### Example\r\n\r\nhttps://github.com/Avokadoen/ecez/blob/7210c43d2dbe6202806acf3e5ac361cbbaed11af/examples/readme/main.zig#L191-L201\r\n\r\n### Tracy integration using [ztracy](https://github.com/michal-z/zig-gamedev/tree/main/libs/ztracy)\r\n![ztracy](media/ztracy.png)\r\n\r\nThe codebase has integration with tracy to allow both the library itself, but also applications to profile using a [tracy client](https://github.com/wolfpld/tracy). The extra work done by tracy is of course NOPs in builds without tracy!\r\n\r\n\r\n### Demo/Examples\r\n\r\nCurrently the project has two simple examples in the [example folder](https://github.com/Avokadoen/ecez/tree/main/examples):\r\n * Implementation of [conway's game of life](https://github.com/Avokadoen/ecez/blob/main/examples/game-of-life/main.zig) which also integrate tracy\r\n * The code from this [readme](https://github.com/Avokadoen/ecez/blob/main/examples/readme/main.zig)\r\n\r\n There is also [wizard rampage](https://github.com/Avokadoen/wizard_rampage) which is closer to actual game code. This was originally a game jam so some of the code is \"hacky\" but the ecez usage should be a practical example\r\n\r\n### Test Driven Development\r\n\r\nThe codebase also utilize TDD to ensure a certain level of robustness, altough I can assure you that there are many bugs to find yet! ;)\r\n\r\n### Planned\r\n\r\nPlease see the issues for planned features.\r\n\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAvokadoen%2Fecez","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAvokadoen%2Fecez","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAvokadoen%2Fecez/lists"}