I thought it would be useful for complete beginners (like me) to have a tutorial in the Wiki. I wrote a detailed guide but before creating a new page or editing an existing one I would like you to review it, maybe there are some things you want to add/change/remove :)
Overview
This is a very small introduction on how to setup a new Github project with Unity and tests (for this I'm using xUnit but it shouldn't matter). I think it's important to mention that this is not about best practises here, it just explains the setup in its simplest form. The optional parts are mostly based on my personal preferences, except the setup for the Roslyn code generator.
Prerequisites
For this guide I'm using the following environment
Unity 2020.1.4f1
Unity Hub 2.4.2
Entitas 1.12.3 from the Asset Store
but it should work for all Unity versions above 2018.3.0.
Setting up the repository
First of all create a new repository on Github. I selected Github's Unity .gitignore template as a starting point.
Setting up the .gitignore file
Currently there is no golden rule for it. Github's Unity .gitignore template does not cover all the files that should be ignored. Below I will post my personal .gitignore file but please keep in mind to add files to the .gitignore file as you go. There might be more files which can be ignored later on. Edit the generated .gitignore file in the repository so that it meets your requirements.
in the terminal. Open the Unity Hub and create a new Unity project inside the root of that local repository.
Importing Entitas
In the editor open the Package Manager (which can be found under the Window tab) and switch to your own assets. Entitas should show up in the list. For now I will simply import everything
After that you should see multiple files in the root of your assets folder
(Optional) Organize external libraries
Create a new folder inside the assets folder and call it "Libraries" (you can name it anything you want) and move the imported files into it. There might be more libraries so you can create a subfolder "Entitas" and move everything into it. If everything was fine you should have this structure
Setting up Entitas
In the editor head over to the Tools section and select Jenny => Preferences. A window should pop up, simply hit the "Auto Import" button to setup the settings. A warning message appears, select "Continue and Overwrite".
The preferences should now looke like this
You can close the window after that for now.
(Optional) Organize Entitas code
The Jenny preferences have a section "Target Directory". The current value is "Assets". Jenny will create a "Generated" folder in the assets folder and put the generated code into it. If you want to keep Entitas related code in a subfolder, simply change the value to "Assets/Sources" (you can name it anything you want). Now generated code will be in "Assets/Sources/Generated".
Making sure the Assembly-Csharp.proj file exists
You will need a script acting as the glue between Unity and Entitas. Simply create a new script and call it "GameController" (you can name it anything you want). For now this script is empty but your IDE will create the needed script assemblies
using UnityEngine;
public class GameController : MonoBehaviour
{
}
You can close your IDE after that, Unity will refresh. Now click on Generate (which is found under the Tools section => Jenny). There should be no errors, in the console should be two logs
(Optional) Organize Unity code
In the assets folder create a new folder called "Scripts" (you can name it anything you want) and move the "GameController" into it. Unity related code will be here. The structure should look like
(Optional) Setting up the Roslyn Code generator
You can close Unity for now. Navigate to the root of your repository directory. Now search for the Jenny files which should be at
First delete the "Jenny.zip.meta" file. After that move the "Jenny.zip" file to the root of your Unity project (next to the assets folder, not the root of the repository). Extract the files from the .zip file, after that you can delete the .zip file.
You should see a "Jenny" directory now. Open up a terminal in that directory and run
mono Jenny/Jenny/Jenny.exe
A CLI should open up. Simply select the first (default) option "Use Jenny.properties"
On the next dialog select everything and after that select the first option "Save and continue (auto import)"
If everything is fine you should see this
Now run
mono Jenny/Jenny/Jenny.exe auto-import -s
once. After that you can run
mono Jenny/Jenny/Jenny.exe gen
to generate from your Entitas related code. So whenever you want to update your Entitas sources simply run this command (based on the directory of the Unity project).
Creating your first system
Open up your project with Unity. For the sake of simplicty create a initialize system creating a new entity on initialization. Create a new script called "CreateEntitySystem".
using Entitas;
public sealed class CreateEntitySystem : IInitializeSystem
{
private readonly Contexts contexts;
public CreateEntitySystem(Contexts contexts)
{
this.contexts = contexts;
}
public void Initialize()
{
contexts.game.CreateEntity();
}
}
(Optional) Organize systems
Move your system to "Assets/Sources/Systems/InitializeSystems".
Initilialize systems go here.
Creating your first feature
Create a new script called "GameSystems".
public sealed class GameSystems : Feature
{
public GameSystems(Contexts contexts)
{
Add(new CreateEntitySystem(contexts));
}
}
(Optional) Organize features
Move your feature to "Assets/Sources/Features".
Features go here.
Adding the features
Open up the script "GameController" and update it to
using UnityEngine;
public class GameController : MonoBehaviour
{
private GameSystems gameSystems;
private void Start()
{
Contexts contexts = Contexts.sharedInstance;
gameSystems = new GameSystems(contexts);
gameSystems.Initialize();
}
private void Update()
{
gameSystems.Execute();
}
}
Now regenerate the code.
Setting up the scene
Create an empty GameObject and call it "GameController" (you can name it anything you want). Attach the script "GameController" to it.
When running the play mode the scene hierarchy should look like this
You can close Unity now.
Setting up tests
Head over to the root of your repository. Create a new solution project with a unit test project
In your IDE add an existing project to the solution. Select the "Assembly-CSharp.csproj" file from your Unity project which should be at
In your tests project add a new reference. Select the Unity project.
Creating the test
Create a new .cs file or use the generated one (UnitTest1) and put in this code
public class UnitTest1
{
[Fact]
public void Test1()
{
Contexts contexts = new Contexts();
Systems systems = new Systems();
CreateEntitySystem createEntitySystem = new CreateEntitySystem(contexts);
systems.Add(createEntitySystem);
systems.Initialize();
Assert.True(contexts.game.count == 1);
}
}
Run your test, it should pass.
(Optional) Organize tests
You can delete your test file, this will be a complete rewrite.
Base class for system tests
To take away boilerplate code you have to setup for every system test create a file "SystemTests" (you can name it anything you want) in Tests => SourceTests => SystemTests
and use this code
using System;
using Entitas;
namespace Tests.SourceTests.SystemTests
{
public abstract class SystemTests : IDisposable
{
protected Contexts contexts;
protected Systems systems;
// ! This runs before every test !
protected SystemTests()
{
contexts = new Contexts();
systems = new Systems();
}
// ! This runs after every test !
public void Dispose()
{
}
}
}
Base class for initialize system tests
To take away boilerplate code you have to setup for every initialize system test create a file "InitializeSystemTests" (you can name it anything you want) in Tests => SourceTests => SystemTests => InitializeSystemTests
and use this code
using System;
using Entitas;
namespace Tests.SourceTests.SystemTests.InitializeSystemTests
{
public abstract class InitializeSystemTests<TInitializeSystem> : SystemTests where TInitializeSystem : IInitializeSystem
{
// ! This creates a new instance and initializes it before every test !
public InitializeSystemTests()
{
TInitializeSystem initializeSystem = (TInitializeSystem)Activator.CreateInstance(typeof(TInitializeSystem), contexts);
systems.Add(initializeSystem);
initializeSystem.Initialize();
}
}
}
Rewritten test
Right next to the file "InitializeSystemTests" create a new file called "CreateEntitySystemTests" (you can name it anything you want)
and use this code
using Xunit;
namespace Tests.SourceTests.SystemTests.InitializeSystemTests
{
public sealed class CreateEntitySystemTests : InitializeSystemTests<CreateEntitySystem>
{
[Fact]
private void ItCreatesOneEntity()
{
Assert.True(contexts.game.count == 1);
}
}
}
Hi, based on this guide
https://github.com/sschmid/Entitas-CSharp/wiki/Unity-Installation-Guide
and Simon's Youtube series
https://www.youtube.com/watch?v=L-18XRTarOM
I thought it would be useful for complete beginners (like me) to have a tutorial in the Wiki. I wrote a detailed guide but before creating a new page or editing an existing one I would like you to review it, maybe there are some things you want to add/change/remove :)
Overview
This is a very small introduction on how to setup a new Github project with Unity and tests (for this I'm using xUnit but it shouldn't matter). I think it's important to mention that this is not about best practises here, it just explains the setup in its simplest form. The optional parts are mostly based on my personal preferences, except the setup for the Roslyn code generator.
Prerequisites
For this guide I'm using the following environment
but it should work for all Unity versions above 2018.3.0.
Setting up the repository
First of all create a new repository on Github. I selected Github's Unity .gitignore template as a starting point.
Setting up the .gitignore file
Currently there is no golden rule for it. Github's Unity .gitignore template does not cover all the files that should be ignored. Below I will post my personal .gitignore file but please keep in mind to add files to the .gitignore file as you go. There might be more files which can be ignored later on. Edit the generated .gitignore file in the repository so that it meets your requirements.
Setting up the Unity project
First of all clone the repository locally by running (don't forget to update the git clone url to your own)
in the terminal. Open the Unity Hub and create a new Unity project inside the root of that local repository.
Importing Entitas
In the editor open the Package Manager (which can be found under the Window tab) and switch to your own assets. Entitas should show up in the list. For now I will simply import everything
After that you should see multiple files in the root of your assets folder
(Optional) Organize external libraries
Create a new folder inside the assets folder and call it "Libraries" (you can name it anything you want) and move the imported files into it. There might be more libraries so you can create a subfolder "Entitas" and move everything into it. If everything was fine you should have this structure
Setting up Entitas
In the editor head over to the Tools section and select Jenny => Preferences. A window should pop up, simply hit the "Auto Import" button to setup the settings. A warning message appears, select "Continue and Overwrite".
The preferences should now looke like this
You can close the window after that for now.
(Optional) Organize Entitas code
The Jenny preferences have a section "Target Directory". The current value is "Assets". Jenny will create a "Generated" folder in the assets folder and put the generated code into it. If you want to keep Entitas related code in a subfolder, simply change the value to "Assets/Sources" (you can name it anything you want). Now generated code will be in "Assets/Sources/Generated".
Making sure the Assembly-Csharp.proj file exists
You will need a script acting as the glue between Unity and Entitas. Simply create a new script and call it "GameController" (you can name it anything you want). For now this script is empty but your IDE will create the needed script assemblies
You can close your IDE after that, Unity will refresh. Now click on Generate (which is found under the Tools section => Jenny). There should be no errors, in the console should be two logs
(Optional) Organize Unity code
In the assets folder create a new folder called "Scripts" (you can name it anything you want) and move the "GameController" into it. Unity related code will be here. The structure should look like
(Optional) Setting up the Roslyn Code generator
You can close Unity for now. Navigate to the root of your repository directory. Now search for the Jenny files which should be at
Repository => Unity Project => Assets => Libraries => Entitas
First delete the "Jenny.zip.meta" file. After that move the "Jenny.zip" file to the root of your Unity project (next to the assets folder, not the root of the repository). Extract the files from the .zip file, after that you can delete the .zip file.
You should see a "Jenny" directory now. Open up a terminal in that directory and run
A CLI should open up. Simply select the first (default) option "Use Jenny.properties"
On the next dialog select everything and after that select the first option "Save and continue (auto import)"
If everything is fine you should see this
Now run
once. After that you can run
to generate from your Entitas related code. So whenever you want to update your Entitas sources simply run this command (based on the directory of the Unity project).
Creating your first system
Open up your project with Unity. For the sake of simplicty create a initialize system creating a new entity on initialization. Create a new script called "CreateEntitySystem".
(Optional) Organize systems
Move your system to "Assets/Sources/Systems/InitializeSystems".
Initilialize systems go here.
Creating your first feature
Create a new script called "GameSystems".
(Optional) Organize features
Move your feature to "Assets/Sources/Features".
Features go here.
Adding the features
Open up the script "GameController" and update it to
Now regenerate the code.
Setting up the scene
Create an empty GameObject and call it "GameController" (you can name it anything you want). Attach the script "GameController" to it.
When running the play mode the scene hierarchy should look like this
You can close Unity now.
Setting up tests
Head over to the root of your repository. Create a new solution project with a unit test project
In your IDE add an existing project to the solution. Select the "Assembly-CSharp.csproj" file from your Unity project which should be at
/.../my-new-project/my-new-project/Assembly-CSharp.csproj
Your project should now look similiar to this
Referencing the Unity project
In your tests project add a new reference. Select the Unity project.
Creating the test
Create a new .cs file or use the generated one (UnitTest1) and put in this code
Run your test, it should pass.
(Optional) Organize tests
You can delete your test file, this will be a complete rewrite.
Base class for system tests
To take away boilerplate code you have to setup for every system test create a file "SystemTests" (you can name it anything you want) in Tests => SourceTests => SystemTests
and use this code
Base class for initialize system tests
To take away boilerplate code you have to setup for every initialize system test create a file "InitializeSystemTests" (you can name it anything you want) in Tests => SourceTests => SystemTests => InitializeSystemTests
and use this code
Rewritten test
Right next to the file "InitializeSystemTests" create a new file called "CreateEntitySystemTests" (you can name it anything you want)
and use this code
When running the test it should pass.
All done!