FAQ

Frequently Asked Questions

---

• How do I regenerate code when there are compile errors?
• How do I fix "Could Not Find .csproj" error message?
• How do I fix "Could not load file or assembly" error?
• Should I store references to entities inside components?
• I created specific assemblies and now components aren't being generated
• How to create custom CodeGenerator?
• Entity gets destroyed in one system and further systems can't react to it

---

Q: How do I regenerate code when there are compile errors?

A: Entitas code generation uses reflection, so it requires a solution with no compile errors. Renaming or editing components break links in generated code and cause compile errors, preventing you from regenerating your code. So you will have to first fix any compile errors before you will be able to regenerate your code.

Component Editing Guide

You can rename component fields safely without regeneration as long as you apply rename-refactoring (i.e. you change the name in the rest of your code base at the same time).

You cannot rename components or add/delete fields in components without breaking the generated code. Here is a guide to dealing with this problem:

1. Create a new folder and name it StreamingAssets (anything placed in this folder wont compile).
2. Move all non-generated code into this new folder (e.g. Components, Systems, GameController, etc.).
3. Delete the entire contents of the generated folder.
4. Generate new code (this will create new contexts and features).
5. Move your components back to their original location and perform refactoring.
6. Generate code again (this will create new component files).
7. Move the rest of your code back into your project.
8. Fix errors in your systems if the changes you made cause any.
9. Your done!

Alternatively, you can eliminate these steps and the issue itself entirely when refactoring by using the new Roslyn code generator available on the Asset Store.

See also: Code Generator

---

Q: How do I fix "Could Not Find .csproj" error message?

A: This error message means that either the project path is incorrect or the file doesn't exist.

First ensure that a project file already exist by selecting Assets>Open C# Project from the toolbar. Doing this will generate a new project file if one doesn't already exist. Then right-click on the Assets folder in the Unity project window and select Show in Explorer and ensure that the file found there that ends with .csproj matches the file name set in the Entitas project path (e.g. "Assembly-CSharp.csproj").

Q: How do I fix "Could not load file or assembly" error?

A: You'll receive this error when either the assembly file doesn't exist or the file path set in preferences is incorrect.

In new empty Unity projects you'll receive this error because the file has not yet been generated by Unity. To make Unity generate the file just open your C# project by going to the toolbar and selecting Assets>Open C# Project. Then verify that the path is correct by opening your Library/ScriptAssemblies/ folder located in the root of your Unity project folder and ensuring the Assemblies path in Entitas preferences matches it.

---

Q: Should I store references to entities inside components?

A: Storing direct references to other entities is not recommended (why?). Instead make use of the PrimaryEntityIndex along with a unique entity ID generator to create an IdComponent. In your game controller you can subscribe to the OnEntityCreated event on each of your contexts to invoke your id generator and assign an IdComponent to the newly created entity. Below is an example of such a system using an integer IdComponent which takes its value from a unique integer on each entity (its creationIndex).

Components.cs

[Game, Input, Ui]  // contexts here
public class IdComponent :IComponent {
    [PrimaryEntityIndex]
    public int value;
}

To auto-assign ids on entity creation do the following

Game Controller.cs

public class GameController : MonoBehaviour
{
    private Systems _systems;

    void Start()
    {
        Contexts contexts = Contexts.sharedInstance;
	foreach (var context in contexts.allContexts)
	{
            if (context.contextInfo.componentTypes.Contains(typeof(IdComponent)))
            {
	        context.OnEntityCreated += AddId;
            }
	}

        // ... systems init
    }

    // add an id to every entity as it's created
    private void AddId(IContext context, IEntity entity)
    {
        (entity as IId).AddId(entity.creationIndex);
    }
}

Note: The IId interface will only be generated if the component has multiple contexts, such as [Game, Input, Ui] in the example. If it is only in a single context, EG [Game] it will not generate the Interface.

To find an entity using its ID, call context.GetEntityWithId(id);. If it is null the entity was not found.

---

Q: I created specific assemblies (xx.assembly.json) and now components aren't being generated.

A: Entitas doesn't know about your assemblies. Go to Tools>Entitas>Preferences and make sure you add your newly generated assembly files path to the assemblies field (separated by a comma)

---

Q: How to create custom CodeGenerator?

1. Create a class inside any subfolder of the Editor folder in Unity (Unity Manual - Special Folder Names)
2. Add a using Entitas.CodeGeneration; statement and implement an ICodeGenerator interface
3. Open Entitas.properties file (located at the root of the project) and add your Assembly-CSharp-Editor.dll full path to the Entitas.CodeGeneration.CodeGenerator.Plugins key. Usually this assembly is located at Library/ScriptAssemblies/Assembly-CSharp-Editor.dll. This is needed for the Code Generation system to be able to find your custom generator implementations (so it appears inside Entitas properties window)
4. Make sure to add a folder path of other Unity dlls (Assembly-CSharp.dll and Assembly-CSharp-firstpass.dll) to the Entitas.CodeGeneration.CodeGenerator.SearchPaths key (example: Match-One - Entitas.properties)

Now the code generator will find your custom ICodeGenerator and will display in the drop down. Steps 3 and 4 can be executed once in a project's lifetime. All key-values stay the same if you continue adding new generators to the Editor scripts folder

---

Q: Entity gets destroyed in one system and further systems can't react to it.

One way to prevent this is creating destroy flag component. See DestroyComponent, DestroySystem

---

To Do

See #402 See #378

(issue links should be summarized and presented on the page)