Documentation update

.pre-commit-config.yaml

@@ -132,9 +132,9 @@ repos:
         language: script
         entry: utils/validate_release_links.py
         require_serial: true
-    -   id: generate-markdown-docs
-        name: generate markdown docs
-        language: python
-        entry: ./utils/generate_markdown_docs.py --package_dirs ml-agents-envs ml-agents
-        pass_filenames: false
-        additional_dependencies: [pyyaml==5.3, pydoc-markdown==3.10.1, setuptools<81]
+#    -   id: generate-markdown-docs
+#        name: generate markdown docs
+#        language: python
+#        entry: ./utils/generate_markdown_docs.py --package_dirs ml-agents-envs ml-agents
+#        pass_filenames: false
+#        additional_dependencies: [pyyaml==5.3, pydoc-markdown==3.10.1, setuptools<81]

catalog-info.yaml

@@ -1,4 +1,4 @@
-# For more information about the available options please visit: http://go/backstage (VPN required)
+# For more information about the available options please visit: http://go/catalog-info (VPN required)
 apiVersion: backstage.io/v1alpha1
 kind: Component
 metadata:

com.unity.ml-agents/CHANGELOG.md

@@ -116,7 +116,7 @@ and this project adheres to
 #### ml-agents / ml-agents-envs
 - Add your trainers to the package using Ml-Agents Custom Trainers plugin. (#)
   - ML-Agents Custom Trainers plugin is an extensible plugin system to define new trainers based on the
-  High level trainer API, read more [here](../docs/Python-Custom-Trainer-Plugin.md).
+  High level trainer API, read more [here](https://github.com/Unity-Technologies/ml-agents/blob/release_20_docs/docs/Python-Custom-Trainer-Plugin.md).
 - Refactored core modules to make ML-Agents internal classes more generalizable to various RL algorithms. (#)
 - The minimum supported Python version for ML-agents has changed to 3.8.13. (#)
 - The minimum supported version of PyTorch was changed to 1.8.0. (#)

com.unity.ml-agents/Documentation~/Inference-Engine.md

@@ -1,6 +1,6 @@
 # Sentis
 
-The ML-Agents Toolkit allows you to use pre-trained neural network models inside your Unity games. This support is possible thanks to the [Sentis](https://docs.unity3d.com/Packages/com.unity.ai.inference@latest). Sentis uses [compute shaders](https://docs.unity3d.com/Manual/class-ComputeShader.html) to run the neural network within Unity.
+The ML-Agents Toolkit allows you to use pre-trained neural network models inside your Unity games. This support is possible thanks to [Sentis](https://docs.unity3d.com/Packages/com.unity.ai.inference@latest). Sentis uses [compute shaders](https://docs.unity3d.com/Manual/class-ComputeShader.html) to run the neural network within Unity.
 
 ## Supported devices
 

com.unity.ml-agents/Documentation~/Installation.md

@@ -5,7 +5,7 @@ This process includes installing Unity, configuring Python, and installing the M
 
 
 
-##  Install Unity
+## Install Unity
 
 Install Unity 6000.0 or later to use the ML-Agents Toolkit.
 
@@ -16,6 +16,27 @@ To install Unity, follow these steps:
    Unity Hub makes it easier to manage multiple Unity versions and associated projects.
 3. Verify that the Unity Editor version is 6000.0 or later.
 
+
+## Install the ML-Agents Unity package
+You can install ML-Agents in two ways:
+
+* [Package installation](#install-ml-agents-package-installation): Recommended for most users who want to use ML-Agents without modifying the source code or using the example environments.
+* [Advanced installation](#install-ml-agents-advanced-installation): For contributors, developers extending ML-Agents, or users who want access to the example environments.
+
+### Install ML-Agents (Package Installation)
+
+Use this method if you don’t plan to modify the toolkit or need the example environments.
+
+To install the package, follow these steps:
+
+1. In Unity, open **Window** > **Package Manager**.
+2. Select **+** > **Add package by name**.
+3. Enter `com.unity.ml-agents`.
+4. Enable **Preview Packages** under the **Advanced** drop-down list if the package doesn’t appear.
+
+If the package isn’t listed, follow the [Advanced Installation](#install-ml-agents-advanced-installation) method instead.
+
+
 ## Install Python 3.10.12 using Conda
 
 Use Conda or Mamba to install and manage your Python environment. This ensures that ML-Agents dependencies are isolated and version-controlled.
@@ -36,31 +57,13 @@ pip3 install torch~=2.2.1 --index-url https://download.pytorch.org/whl/cu121
 ```
 If prompted, install Microsoft Visual C++ Redistributable. For more installation options and versions, refer to the [PyTorch installation guide](https://pytorch.org/get-started/locally/).
 
+You can install the ML-Agents Python package in two ways:
 
-## Install ML-Agents
-You can install ML-Agents in two ways:
-
-* [Package installation](#install-ml-agents-package-installation): Recommended for most users who want to use ML-Agents without modifying the source code or using the example environments.
-* [Advanced installation](#install-ml-agents-advanced-installation): For contributors, developers extending ML-Agents, or users who want access to the example environments.
-
-### Install ML-Agents (Package installation)
-
-Use this method if you don’t plan to modify the toolkit or need the example environments.
-
-#### Install the ML-Agents Unity package
-
-To install the package, follow these steps:
-
-1. In Unity, open **Window** > **Package Manager**.
-2. Select **+** > **Add package by name**.
-3. Enter `com.unity.ml-agents`.
-4. Enable **Preview Packages** under the **Advanced** drop-down list if the package doesn’t appear.
-
-If the package isn’t listed, follow the [Advanced Installation](#install-ml-agents-advanced-installation) method instead.
-
+* [Package installation](#install-ml-agents-python-package-package-installation): Recommended for most users who want to use ML-Agents without modifying the source code or using the example environments.
+* [Advanced installation](#install-ml-agents-python-package-advanced-installation): For contributors, developers extending ML-Agents, or users who want access to the example environments.
 
 
-#### Install the ML-Agents Python package
+### Install the ML-Agents Python package
 
 Install the ML-Agents Python package to enable communication between Unity and your machine learning training environment.
 
@@ -86,11 +89,11 @@ This step resolves dependency conflicts that can occur with older versions of `g
 4. When the installation completes successfully, all the required Python dependencies listed in the [setup.py file](https://github.com/Unity-Technologies/ml-agents/blob/release/4.0.0/ml-agents/setup.py), including [PyTorch](Background-PyTorch.md) are automatically configured.
 
 
-### Install ML-Agents (Advanced Installation)
+## Install ML-Agents (Advanced Installation)
 
 Use the advanced installation method if you plan to modify or extend the ML-Agents Toolkit, or if you want to download and use the example environments included in the repository.
 
-#### Clone the ML-Agents repository
+### Clone the ML-Agents repository
 
 Clone the ML-Agents repository to access the source code, sample environments, and development branches.
 
@@ -110,7 +113,7 @@ git clone https://github.com/Unity-Technologies/ml-agents.git
 If you plan to contribute your changes, clone the develop branch (omit the `--branch` flag) and refer to the [Contribution Guidelines](CONTRIBUTING.md) for details.
 
 
-#### Add the ML-Agents Unity package
+### Add the ML-Agents Unity package
 
 After cloning the repository, add the `com.unity.ml-agents` Unity package to your project.
 
@@ -131,7 +134,7 @@ Unity adds the ML-Agents package to your project.
 <p align="center"> <img src="images/unity_package_manager_window.png" alt="Unity Package Manager Window" height="150" border="10" /> <img src="images/unity_package_json.png" alt="package.json" height="150" border="10" /> </p>
 
 
-#### Install the ML-Agents Python package
+### Install the ML-Agents Python package (Advanced Installation)
 
 Install the Python packages from the cloned repository to enable training and environment communication.
 

com.unity.ml-agents/Documentation~/Learning-Environment-Create-New.md

@@ -23,7 +23,7 @@ If you haven't already, follow the [installation instructions](Installation.md).
 The first task to accomplish is simply creating a new Unity project and importing the ML-Agents assets into it:
 
 1. Launch Unity Hub and create a new 3D project named "RollerBall".
-2. [Add the ML-Agents Unity package](Installation.md#install-the-comunityml-agents-unity-package) to your project.
+2. [Add the ML-Agents Unity package](Installation.md#install-ml-agents-package-installation) to your project.
 
 Your Unity **Project** window should contain the following Packages:
 
@@ -47,8 +47,7 @@ Next, we will create a very simple scene to act as our learning environment. The
 1. Right click in Hierarchy window, select 3D Object > Cube.
 2. Name the GameObject "Target".
 3. Select the Target Cube to view its properties in the Inspector window.
-4. Set Transform to Position = `(3, 0.5, 3)`, Rotation = `(0, 0, 0)`, Scale =
-   `(1, 1, 1)`.
+4. Set Transform to Position = `(3, 0.5, 3)`, Rotation = `(0, 0, 0)`, Scale = `(1, 1, 1)`.
 
 ![Target Cube Inspector window](images/roller-ball-target.png){: style="width:400px"}
 
@@ -112,8 +111,7 @@ In this example, each time the Agent (Sphere) reaches its target (Cube), the epi
 
 To move the target (Cube), we need a reference to its Transform (which stores a GameObject's position, orientation and scale in the 3D world). To get this reference, add a public field of type `Transform` to the RollerAgent class. Public fields of a component in Unity get displayed in the Inspector window, allowing you to choose which GameObject to use as the target in the Unity Editor.
 
-To reset the Agent's velocity (and later to apply force to move the agent) we need a reference to the Rigidbody component. A [Rigidbody](https://docs.unity3d.com/ScriptReference/Rigidbody.html) is Unity's primary element for physics simulation. (See [Physics](https://docs.unity3d.com/Manual/PhysicsSection.html) for full documentation of Unity physics.) Since the Rigidbody component is on the same GameObject as our Agent script, the best way to get this reference is using
-`GameObject.GetComponent<T>()`, which we can call in our script's `Start()`
+To reset the Agent's velocity (and later to apply force to move the agent) we need a reference to the Rigidbody component. A [Rigidbody](https://docs.unity3d.com/ScriptReference/Rigidbody.html) is Unity's primary element for physics simulation. (See [Physics](https://docs.unity3d.com/Manual/PhysicsSection.html) for full documentation of Unity physics.) Since the Rigidbody component is on the same GameObject as our Agent script, the best way to get this reference is using `GameObject.GetComponent<T>()`, which we can call in our script's `Start()`
 method.
 
 So far, our RollerAgent script looks like:
@@ -123,6 +121,7 @@ using System.Collections.Generic;
 using UnityEngine;
 using Unity.MLAgents;
 using Unity.MLAgents.Sensors;
+using Unity.MLAgents.Actuators;
 
 public class RollerAgent : Agent
 {
@@ -179,13 +178,16 @@ The final part of the Agent code is the `Agent.OnActionReceived()` method, which
 
 To solve the task of moving towards the target, the Agent (Sphere) needs to be able to move in the `x` and `z` directions. As such, the agent needs 2 actions: the first determines the force applied along the x-axis; and the second determines the force applied along the z-axis. (If we allowed the Agent to move in three dimensions, then we would need a third action.)
 
-The RollerAgent applies the values from the `action[]` array to its Rigidbody component `rBody`, using `Rigidbody.AddForce()`:
+The RollerAgent applies the values from the `actionBuffers.ContinuousActions[]` array to its Rigidbody component `rBody`, using `Rigidbody.AddForce()`:
 
 ```csharp
-Vector3 controlSignal = Vector3.zero;
-controlSignal.x = action[0];
-controlSignal.z = action[1];
-rBody.AddForce(controlSignal * forceMultiplier);
+public override void OnActionReceived(ActionBuffers actionBuffers)
+{
+    Vector3 controlSignal = Vector3.zero;
+    controlSignal.x = actionBuffers.ContinuousActions[0];
+    controlSignal.z = actionBuffers.ContinuousActions[1];
+    rBody.AddForce(controlSignal * forceMultiplier);
+}
 ```
 
 #### Rewards
@@ -216,8 +218,7 @@ if (this.transform.localPosition.y < 0)
 
 #### OnActionReceived()
 
-With the action and reward logic outlined above, the final version of
-`OnActionReceived()` looks like:
+With the action and reward logic outlined above, the final version of `OnActionReceived()` looks like:
 
 ```csharp
 public float forceMultiplier = 10;
@@ -320,6 +321,8 @@ behaviors:
 
 Hyperparameters are explained in [the training configuration file documentation](Training-Configuration-File.md)
 
+Make sure the behavior name in the 'Behavior Parameters' component matches the one in the config file.
+
 Since this example creates a very simple training environment with only a few inputs and outputs, using small batch and buffer sizes speeds up the training considerably. However, if you add more complexity to the environment or change the reward or observation functions, you might also find that training performs better with different hyperparameter values. In addition to setting these hyperparameter values, the Agent **DecisionFrequency** parameter has a large effect on training time and success. A larger value reduces the number of decisions the training algorithm has to consider and, in this simple environment, speeds up training.
 
 To train your agent, run the following command before pressing **Play** in the Editor:

com.unity.ml-agents/Documentation~/Migrating.md

@@ -369,7 +369,7 @@ To do it manually, copy your `<BehaviorName>` sections from `trainer_config.yaml
 
 - We [fixed a bug](https://github.com/Unity-Technologies/ml-agents/pull/2823) in `RayPerception3d.Perceive()` that was causing the `endOffset` to be used incorrectly. However this may produce different behavior from previous versions if you use a non-zero `startOffset`. To reproduce the old behavior, you should increase the value of `endOffset` by `startOffset`. You can verify your raycasts are performing as expected in scene view using the debug rays.
 - If you use RayPerception3D, replace it with RayPerceptionSensorComponent3D (and similarly for 2D). The settings, such as ray angles and detectable tags, are configured on the component now. RayPerception3D would contribute `(# of rays) * (# of tags + 2)` to the State Size in Behavior Parameters, but this is no longer necessary, so you should reduce the State Size by this amount. Making this change will require retraining your model, since the observations that RayPerceptionSensorComponent3D produces are different from the old behavior.
-- If you see messages such as `The type or namespace 'Sentis' could not be found` or `The type or namespace 'Google' could not be found`, you will need to [install the Sentis preview package](Installation.md#package-installation).
+- If you see messages such as `The type or namespace 'Sentis' could not be found` or `The type or namespace 'Google' could not be found`, you will need to install the Sentis package(https://docs.unity3d.com/Packages/com.unity.ai.inference@latest).
 
 ## Migrating from ML-Agents Toolkit v0.10 to v0.11.0
 
@@ -436,7 +436,7 @@ To do it manually, copy your `<BehaviorName>` sections from `trainer_config.yaml
 
 ### Important Changes
 
-- We no longer support TFS and are now using the [Sentis](Inference-Engine.md)
+- We no longer support TFS and are now using [Sentis](Inference-Engine.md)
 
 #### Steps to Migrate