![readme splash](https://raw.githubusercontent.com/jeffreylanters/unity-entity-component-system/master/.github/WIKI/repository-readme-splash.png) [![openupm](https://camo.githubusercontent.com/987380979a6cd89697197bb7f301a841ec623392ccc3b80e2bc87b52e3cc7dc7/68747470733a2f2f696d672e736869656c64732e696f2f6e706d2f762f6e6c2e656c726163636f6f6e652e656e746974792d636f6d706f6e656e742d73797374656d3f6c6162656c3d55504d2672656769737472795f7572693d68747470733a2f2f7061636b6167652e6f70656e75706d2e636f6d267374796c653d666f722d7468652d626164676526636f6c6f723d323332633337)](https://openupm.com/packages/nl.elraccoone.entity-component-system/) [![downloads](https://camo.githubusercontent.com/697a23077798fe135973745def12cc3c0298371d2194f2fcb4249d18341daee5/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f64796e616d69632f6a736f6e3f636f6c6f723d343041413732267374796c653d666f722d7468652d6261646765266c6162656c3d646f776e6c6f6164732671756572793d2532342e646f776e6c6f6164732675726c3d68747470732533412532462532467061636b6167652e6f70656e75706d2e636f6d253246646f776e6c6f616473253246706f696e74253246616c6c2d74696d652532466e6c2e656c726163636f6f6e652e656e746974792d636f6d706f6e656e742d73797374656d)](https://openupm.com/packages/nl.elraccoone.entity-component-system/) [![size](https://camo.githubusercontent.com/55ec006ba061eebb1cf917c1ca30bf6a551ff8f29252005c85bbed637deeec96/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c616e6775616765732f636f64652d73697a652f6a6566667265796c616e746572732f756e6974792d656e746974792d636f6d706f6e656e742d73797374656d3f7374796c653d666f722d7468652d6261646765)](https://github.com/jeffreylanters/unity-entity-component-system/raw/master/Runtime) [![sponsors](https://camo.githubusercontent.com/a7d7ebd7fa892f371dfe5869142c4d360f58beb1f5ae51483eafe5e52a7475ae/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f73706f6e736f72732f6a6566667265796c616e746572733f636f6c6f723d453132433941267374796c653d666f722d7468652d6261646765)](https://github.com/sponsors/jeffreylanters) [![donate](https://camo.githubusercontent.com/82b75e87934b4a0ac1ddb5852d00e13906c5ab9d74fd5ee30ad89550b377c8b7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f646f6e6174652d70617970616c2d4632333135303f7374796c653d666f722d7468652d6261646765)](https://paypal.me/jeffreylanters) A better approach to game design that allows you to concentrate on the actual problems you are solving: the data and behavior that make up your game. By moving from object-oriented to data-oriented design it will be easier for you to reuse the code and easier for others to understand and work on it. [**Installation**](https://github.com/jeffreylanters/unity-entity-component-system/raw/master/#installation) · [**Documentation**](https://github.com/jeffreylanters/unity-entity-component-system/raw/master/#documentation) · [**License**](https://github.com/jeffreylanters/unity-entity-component-system/blob/master/LICENSE.md) **Made with ♥ by Jeffrey Lanters**

# Installation ### Using the Unity Package Manager Install the latest stable release using the Unity Package Manager by adding the following line to your `manifest.json` file located within your project's Packages directory, or by adding the Git URL to the Package Manager Window inside of Unity. ```json "nl.elraccoone.entity-component-system": "git+https://github.com/jeffreylanters/unity-entity-component-system" ``` ### Using OpenUPM The module is availble on the OpenUPM package registry, you can install the latest stable release using the OpenUPM Package manager's Command Line Tool using the following command. ```sh openupm add nl.elraccoone.entity-component-system ``` # Documentation ## Getting Started It's recommended to get started by using the built-in File Generator. When it's your first time using the ECS, you might want to enable the _Overwrite All Virtuals_ option to see all the available methods for each type of class.

## Life Cycles It's recommended to build your entire project around these life cycle methods.

## Controllers ### Introduction The `Controller` is the heart of your Application, each Application should consist of just one, commonly named the MainController. The `Controller` is the first entry point of the Entity Component System and is the place where all of your `System` and `Services` are registered. Your `Controller` should be attached to a `GameObject` in your scene and will automatically be marked to not be destroyed when switching scenes. ```csharp public class MainController: Controller { } ``` ### Life Cycle Methods #### On Initialize Life Cycle Method The `Controller` consists of a virtual `OnInitialize` method. This lifecycle method can be overwritten and will be invoked at the very start of your Application. During this cycle, properties with the `Injected` and `Asset` attributes are being assigned, and the `OnInitialize` method of each registered `System` and `Service` will be invoked as well. ```csharp public class MainController: Controller { public override void OnInitialize() { } } ``` #### On Initialized Life Cycle Method The `Controller` consists of a virtual `OnInitialized` method. This lifecycle method can be overwritten and will be invoked after the `OnInitialize` method has been invoked. During this cycle, the `OnInitialized` method of each registered `System` and `Service` will be invoked as well. ```csharp public class MainController: Controller { public override void OnInitialized() { } } ``` #### On Update Life Cycle Method The `Controller` consists of a virtual `OnUpdate` method. This lifecycle method can be overwritten and will be invoked every frame. During this cycle, the `OnUpdate` method of each registered `System` will be invoked as well. ```csharp public class MainController: Controller { public override void OnUpdate() { } } ``` #### On Will Destroy Life Cycle Method The `Controller` consists of a virtual `OnWillDestroy` method. This lifecycle method can be overwritten and will be invoked when the Application is about to quit. During this cycle, the `OnWillDestroy` method of each registered `System` and `Service` will be invoked as well. ```csharp public class MainController: Controller { public override void OnWillDestroy() { } } ``` ### Methods #### Registering Systems and Services Use this method to `Register` the Systems and Services that are required for your Application to function. The `Register` method accepts a list of `Type` arguments, each of these types should be a `System` or `Service` type. Registering a `System` or `Service` can only be done once during the `Controller`'s `OnInitialize` life cycle method. ```csharp public class MainController: Controller { public override void OnInitialize() { Register( typeof(ExampleSystem), typeof(ExampleService) ); } } ``` #### Disabling a System's Update Life Cycles To enable or disable the life cycle of a `System` or `Service`, use the `SetSystemEnabled` methods. This method accepts a `Type` generic, and a `bool` value to enable or disable the life cycle of the `System` or `Service`. ```csharp public class MainController: Controller { void SomeMethod() { SetSystemEnabled(false); } } ``` #### Checking whether a System's Update Life Cycles are Enabled To check whether the life cycle of a `System` or `Service` is enabled, use the `IsSystemEnabled` methods. This method accepts a `Type` generic, and returns a `bool` value indicating whether the life cycle of the `System` or `Service` is enabled. ```csharp public class MainController: Controller { void SomeMethod() { if (IsSystemEnabled()) { } } } ``` #### Manually getting a reference to a System or Service Something you might want to get a reference to a `System` or `Service` from within something outside of the Entity Component System. To do this, use the `GetSystem`, `GetService`, `HasSystem` and `HasService` methods respectively. These methods accept a `Type` generic, or a `Type` parameter and return the `System` or `Service` instance. ```csharp public class MainController: Controller { void SomeMethod() { if (HasSystem()) { var exampleSystem = GetSystem(); var exampleSystem = GetSystem(typeof(ExampleSystem)); } if (HasService()) { var exampleService = GetService(); var exampleService = GetService(typeof(ExampleService)); } } } ``` #### Manually getting Assets Something you might want to get a reference to an `Asset` from within something outside of the Entity Component System. To do this, use the `GetAsset` and `HasAsset` methods respectively. These methods accepts an optional `Type` generic and a `name` parameter and returns the `Type` or `Object` ```csharp public class MainController: Controller { void SomeMethod() { if (HasAsset()) { var exampleAsset = GetAsset("MyAssetName"); var exampleAssetObject = GetAsset("MyAssetName"); } } } ``` ### Attributes #### Assets The `Controller` allows the use of the `Asset` attribute on properties to automatically assign the values of referenced Assets. Assets can be assigned on the `Controller` instance in your Scene. When assigning using the empty contructor, the property's name will be used for searching the Asset, to find an Asset by its name, use the string overload. All types of UnityEngine's Object can be used in these fields. These properties are assigned during the OnInitialize cycle and are available for use at the OnInitialized cycle. When an asset is not found, an error is thrown. ```csharp public class MainController: Controller { [Asset] public ExampleAsset exampleAsset; [Asset("MyAssetName")] public ExampleAsset exampleAsset; } ``` #### Injection The `Controller` allows the use of the `Injected` attribute on properties to automatically assign the values of referenced Systems and Services, making all public methods and properties accessible. These properties are assigned during the OnInitialize cycle and are available for use at the OnInitialized cycle. ```csharp public class MainController: Controller { [Injected] public ExampleSystem exampleSystem; [Injected] public ExampleService exampleService; } ``` ## Components ### Introduction `Components` are responsible for storing the data of your `entities` while `Systems` are responsible for manipulating that data. `Components` are added to your `entities` (`GameObjects`) in the `Scene`, an `Entity` is not limited to one `Component` and can hold as many as needed. ```csharp public class MovementComponent : EntityComponent { } ``` #### Entity Data To provide `Systems` entity data, we'll use properties to store this. All properties should be public and will be accessible to all `Systems` and `Controllers` since there is no need for privates. ```csharp public class MovementComponent : EntityComponent { public float speed; public Vector3 targetPosition; public int[] ids; public NpcDialog dialog; [HideInInspector] public bool isMoving; } ```