I wanted to document my journey in understanding how ML-Agents ToolKit by Unity works. There is a very cool tutorial on Youtube that I recommend by Dilmer Valecillos.
In this video, he is using a Windows machine so, here I would like to add some tips and tricks that I needed to do on my own to follow his tutorial on a Mac machine (macOS Catalina 10.15.5).
0. Install Unity 2018.4 or later (first time user)
Let's start with step 0: Installing Unity. As a first time user, I was initially confused when I needed to download Unity Hub but soon I realised that you should download Unity Hub first (at least that's what they recommend), and then you can download the latest official release of Unity from Hub directly. Download Unity Hub. Once you are in the Unity Hub window, the first thing that you need to specify is the License, which in my case is for personal use and not for commercial purposes. Then click on "Installs", "Add". I have installed 2020.1.1f1 version of Unity.
Ok, now we are ready to follow his tutorial.
1. Download Python 3.6.1 or higher
The only recommendation is that, as of today, the ML-Agents tool kit has been tested on Python 3.6 and 3.7 (not yet 3.8) therefore, make sure you have at least 3.6.1 or higher to continue with this tutorial. In the video, Dilmer is using 3.8 and I couldn't see any major issue. I personally have 3.7.
2. git clone the repository
The aim is to clone this git repo, but we don't want to clone the master branch. Instead, we want the latest stable official release. In the documentation, you will see a list of the latest release (in my case is release_5) so clone that branch on your local machine. I have multiple git user so I need to specify my user while cloning.
if you need to specify your git user:
git clone --branch release_5 https://username@github.com/Unity-Technologies/ml-agents.gitif you don't need to specify yout git user.
git clone --branch release_5 git@github.com:Unity-Technologies/ml-agents.git3. Create a new Unity 3D project
Now you are ready to create a new project from Unity Hub: go to "Projects", "New".
4. Go To Package Manager and install the ml-agents
On Mac, while you are in Unity, you need to click on "Window", "Package Manager". Here, click on "Packages" and choose Unity Registry. Then go to the advanced setting, and Enable Preview Packages. Then you are ready to search for ml-agents package.
5. Copy ml-agents\Project\Assets\ML-Agents to Your Assets Folder
From the repository that you just cloned in step 2, copy the folder ML-Agents under Assets and paste it in your Unity project under Asset.
At this point, you are already able to see the different demos that the Unity team has built for us! ML-Agents -> Examples -> e.g. Soccer -> Scenes -> Soccer Twos -> Click on the Play button (top).
So far, we have been using already trained model. From this point onwards, we will try to create ones on our own.
6. Create a new Virtual Environment
As explained in the video we need to create a new virtual environment so that all the libraries will be installed on this new virtual environment. Personally, I find this tutorial useful:
On mac:
python3 -m venv mlagents_envChoose a self-explanatory name for your virtual enviroment.
7. Activate your virtual environment
now, activate it.
source mlagents_env/bin/activate8. pip install mlagents
no additional comments
9. mlagents-learn
So when you are ready to run the mlagents-learn command, make sure that you have your Unity project open, ready for training your agent. Open the 3DBall Scenario in Unity. (After a certain time, if the command sees inactivity will abort the command automatically.)
On mac:
mlagents-learn ./config/ppo/3DBall.yaml --run-id=first3DBallRunAs usual use the / (slash) instead of \ (backslash) which is used in Windows.
The run-id is important because it represents the name of your training session and the result files will be stored in a folder named as your run-id.
As you can see it's written: "Start training by pressing the Play button in the Unity Editor". Let's do it.
10. Go back to Unity and hit play and training should begin
Once you hit the play button, you should see your agents training from scratch. In the command line, you can also see the progress and the increase in the reward that they are achieving. When you are satisfied with the training, press the stop button. This will allow creating a .nn file that can be used in Unity. All the results are stored in the 'results' folder in the ml-agents repository.
Hope that this was useful for Mac users & have fun using ML-Agent Toolkit!