{"id":16209917,"url":"https://github.com/annulusgames/entitiesevents","last_synced_at":"2025-03-02T08:35:03.740Z","repository":{"id":198992644,"uuid":"695423584","full_name":"annulusgames/EntitiesEvents","owner":"annulusgames","description":"Provides inter-system messaging functionality to Unity ECS","archived":false,"fork":false,"pushed_at":"2023-11-27T12:43:57.000Z","size":64,"stargazers_count":44,"open_issues_count":1,"forks_count":4,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-02T03:24:15.719Z","etag":null,"topics":["ecs","events","unity"],"latest_commit_sha":null,"homepage":"","language":"C#","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/annulusgames.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}},"created_at":"2023-09-23T06:14:26.000Z","updated_at":"2025-02-17T10:15:33.000Z","dependencies_parsed_at":null,"dependency_job_id":"38743723-a27a-44fb-82b0-021b58506a50","html_url":"https://github.com/annulusgames/EntitiesEvents","commit_stats":null,"previous_names":["annulusgames/entitiesevents","yn01dev/entitiesevents","yn01-dev/entitiesevents"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/annulusgames%2FEntitiesEvents","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/annulusgames%2FEntitiesEvents/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/annulusgames%2FEntitiesEvents/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/annulusgames%2FEntitiesEvents/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/annulusgames","download_url":"https://codeload.github.com/annulusgames/EntitiesEvents/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241481967,"owners_count":19969833,"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","events","unity"],"created_at":"2024-10-10T10:34:07.444Z","updated_at":"2025-03-02T08:35:03.714Z","avatar_url":"https://github.com/annulusgames.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Entities Events\nProvides inter-system messaging functionality to Unity ECS\n\n[![license](https://img.shields.io/badge/LICENSE-MIT-green.svg)](LICENSE)\n\n[日本語版READMEはこちら](README_JA.md)\n\n## Overview\n\nEntities Events is a library that adds event functionality to Unity's Entity Component System (ECS). It allows for easy implementation of messaging between systems using EventWriter/EventReader.\n\n## Features\n\n* Natural inter-system messaging using EventWriter/EventReader\n* Creating a custom event system using Events\u003cT\u003e\n\n### Requirements\n\n* Unity 2022.3 or higher\n* Entities 1.0.0 or higher\n\n### Installation\n\n1. Open the Package Manager from Window \u003e Package Manager.\n2. Click the \"+\" button and select \"Add package from git URL.\"\n3. Enter the following URL:\n\n```\nhttps://github.com/AnnulusGames/EntitiesEvents.git?path=Assets/EntitiesEvents\n```\n\nAlternatively, open Packages/manifest.json and add the following to the dependencies block:\n\n```json\n{\n    \"dependencies\": {\n        \"com.annulusgames.entities-events\": \"https://github.com/AnnulusGames/EntitiesEvents.git?path=Assets/EntitiesEvents\"\n    }\n}\n```\n\n## Basic Usage\n\nIn Entities Events, you perform event writing/reading based on the type of event. First, define a structure to be used for events. The structure used for events cannot contain reference types and must be an unmanaged type.\n\n```cs\npublic struct MyEvent { }\n```\n\nThe type of event you want to use must be registered in advance using the `RegisterEvent` attribute. Adding this attribute generates code that includes the necessary System and assembly attributes during compilation.\n\n```cs\nusing EntitiesEvents;\n\n// Add RegisterEvent attribute to the assembly\n[assembly: RegisterEvent(typeof(MyEvent))]\n```\n\nIn the sending System, use `EventWriter` to publish events.\n\n```cs\nusing Unity.Burst;\nusing Unity.Entities;\nusing EntitiesEvents;\n\n[BurstCompile]\npublic partial struct WriteEventSystem : ISystem\n{\n    // Cache the obtained EventWriter within the System\n    EventWriter\u003cMyEvent\u003e eventWriter;\n\n    [BurstCompile]\n    public void OnCreate(ref SystemState state)\n    {\n        // Obtain the EventWriter with GetEventWriter\n        eventWriter = state.GetEventWriter\u003cMyEvent\u003e();\n    }\n\n    [BurstCompile]\n    public void OnUpdate(ref SystemState state)\n    {\n        // Publish the event using Write\n        eventWriter.Write(new MyEvent());\n    }\n}\n```\n\nIn the receiving System, use `EventReader` to read the published events.\n\n```cs\nusing Unity.Burst;\nusing Unity.Entities;\nusing EntitiesEvents;\n\n[BurstCompile]\npublic partial struct ReadEventSystem : ISystem\n{\n    // Cache the obtained EventReader within the System\n    EventReader\u003cMyEvent\u003e eventReader;\n\n    [BurstCompile]\n    public void OnCreate(ref SystemState state)\n    {\n        // Obtain the EventReader with GetEventReader\n        eventReader = state.GetEventReader\u003cMyEvent\u003e();\n    }\n\n    [BurstCompile]\n    public void OnUpdate(ref SystemState state)\n    {\n        // Read unread events with eventReader.Read()\n        foreach (var eventData in eventReader.Read())\n        {\n            Debug.Log(\"received!\");\n        }\n    }\n}\n```\n\nIf your System inherits from a class that extends SystemBase, you can obtain EventWriter/EventReader using `this.GetEventWriter\u003cMyEvent\u003e()` or `this.GetEventWriter\u003cMyEvent\u003e()`.\n\n```cs\nusing Unity.Burst;\nusing Unity.Entities;\nusing EntitiesEvents;\n\n[BurstCompile]\npublic partial class WriteEventSystemClass : SystemBase\n{\n    EventWriter\u003cMyEvent\u003e eventWriter;\n\n    [BurstCompile]\n    protected override OnCreate()\n    {\n        // Obtain the EventWriter with this.GetEventWriter\n        eventWriter = this.GetEventWriter\u003cMyEvent\u003e();\n    }\n\n    [BurstCompile]\n    protected override void OnUpdate()\n    {\n        eventWriter.Write(new MyEvent());\n    }\n}\n```\n\n\u003e **Warning**\n\u003e Always obtain EventWriter/EventReader and cache it in OnCreate. In particular, EventReader records the count of unread events for each reader, so calling `state.GetEventReader()` each time you read can lead to duplicated event reads.\n\n## Event Mechanism\n\nEntities Events generates a singleton Entity and a System for each type registered with the `RegisterEvent` attribute to hold event buffers and update the buffers. The generated EventSystem is executed within `EventSystemGroup` and clears the event buffers every frame.\n\nHowever, events are held for one additional frame after being sent. This means that even if the receiving System is executed before the sending System, there will be a one-frame delay. To prevent this, you can explicitly specify the execution order between Systems using the `UpdateBefore` and `UpdateAfter` attributes.\n\nAlso, events have a lifespan of two frames, so if you do not read events every frame, there is a risk of events being lost. If you want to manually update the buffer, you can create your own EventSystem using `Events\u003cT\u003e` as described below.\n\n## Events\u003cT\u003e\n\nA custom NativeContainer `Events\u003cT\u003e` is provided as a collection to store event information.\n\n```cs\nusing Unity.Collections;\nusing EntitiesEvents;\n\n// Create a new Events\nvar events = new Events\u003cMyEvent\u003e(32, Allocator.Temp);\n```\n\nYou can call `Update` to update the container, which swaps the internal buffer and removes the oldest buffer to prevent memory consumption due to event accumulation. It is recommended to perform this update every frame.\n\n```cs\n// Call Update to clear and swap the buffer\nevents.Update();\n```\n\nWriting and reading are done through `EventWriter/EventReader`, which can be obtained using `GetWriter/GetReader`.\n\n```cs\n// Obtain EventWriter and write\nvar eventWriter = events.GetWriter();\neventWriter.Write(new MyEvent());\n\n// Obtain EventReader and read\nvar eventReader = events.GetReader();\n```\n\nAfter use, like other NativeContainers, you must release the memory using `Dispose`. Forgetting to do this can lead to memory leaks.\n\n```cs\n// Dispose to release the container and free memory\nevents.Dispose();\n```\n\n## License\n\n[MIT License](LICENSE)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fannulusgames%2Fentitiesevents","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fannulusgames%2Fentitiesevents","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fannulusgames%2Fentitiesevents/lists"}