FAQ

Frequently Asked Questions

---

• How do I fix .csproj file not found error?
• How do I regenerate code when there are compile errors?
• 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?

---

Q: How do I fix .csproj file not found error?

When you click Generate, if you get an error that the .csproj was not found, you can try a couple things:

1. Open the project in Visual Studio or MonoDevelop. This may regenerate the .csproj, which could be missing if it was created on a different computer and ignored by git.

2. If you find the .csproj has different name, which might happen on Windows, you can rename the preferences to match the file that you actually have and click Generate again.

3. If you are using Visual Studio,try temporarily changing your default External Script Editor by navigating to Edit->Preferences->External Tools. Change the default external scripting tool from Visual Studio to Mono Develop, create a script and open it from inside the project view (or open an already existing one). The .csproj file should now be generated. You can now change the default External Editing tool back to Visual Studio.

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 folder called "StreamingAssets" in your assets folder (or just create a folder outside of your unity project where your code won't be compiled).
2. Move all your Entitas code (Components/Systems/GameController) into this folder leaving only your "Generated" folder, where entitias generated code is found.
3. Delete the entire contents of the generated folder, but leave the folder itself in place.
4. Generate (this will create the contexts and feature classes again.
5. Move your components back to their original location and perform your renaming and refactoring.
6. Generate again (this creates all the component files)
7. Move the rest of your code (Systems/GameController) back into your project.
8. Fix errors in your systems if the changes you made cause any.
9. Your done!

This process is a workaround until we have the Roslyn code generator. It is not ideal, but the whole process only takes a minute or so once you've done it a few times. See also: Code Generator - Compile Errors

---

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

A: You'll receive this error when either the file doesn't exist or the path to the file is incorrect or missing. In new empty Unity projects you'll receive this error because the file "Assembly-CSharp.dll" has not been generated by Unity yet. To make Unity generate this file just create a new script anywhere inside the project and then wait for Unity to compile it. Your "[Unity Project folder]\Library\ScriptAssemblies" folder should then look something like this:

You should now no longer receive that error message when generating code with Entitas. However, if you continue to receive the error or this is not a new Unity project and the file already exist, then insure the file path is correctly set under "Assemblies" in the Entitas preferences settings.

---

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 {
    [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. In Tools -> Entitas -> Preferences, make sure you add your newly generated assembly files paths 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

---

To Do

See #402 See #378

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