Add CreateActuators API, obsolete old method. (#4899)

* Add CreateActuators method to the ActuatorComponent class which wraps the original method.  The original method will be removed in the future.

Co-authored-by: Vincent-Pierre BERGES <vincentpierre@unity3d.com>

Author: surfnerd

Project/Assets/ML-Agents/Examples/Basic/Scripts/BasicActuatorComponent.cs

@@ -17,7 +17,9 @@ public class BasicActuatorComponent : ActuatorComponent
         /// Creates a BasicActuator.
         /// </summary>
         /// <returns></returns>
+#pragma warning disable 672
         public override IActuator CreateActuator()
+#pragma warning restore 672
         {
             return new BasicActuator(basicController);
         }

Project/Assets/ML-Agents/Examples/Match3/Scripts/Match3ExampleActuatorComponent.cs

@@ -7,7 +7,9 @@ namespace Unity.MLAgentsExamples
     public class Match3ExampleActuatorComponent : Match3ActuatorComponent
     {
         /// <inheritdoc/>
+#pragma warning disable 672
         public override IActuator CreateActuator()
+#pragma warning restore 672
         {
             var board = GetComponent<Match3Board>();
             var agent = GetComponentInParent<Agent>();

com.unity.ml-agents.extensions/Runtime/Match3/Match3ActuatorComponent.cs

@@ -28,7 +28,9 @@ public class Match3ActuatorComponent : ActuatorComponent
         public bool ForceHeuristic;
 
         /// <inheritdoc/>
+#pragma warning disable 672
         public override IActuator CreateActuator()
+#pragma warning restore 672
         {
             var board = GetComponent<AbstractBoard>();
             var agent = GetComponentInParent<Agent>();

com.unity.ml-agents/CHANGELOG.md

@@ -30,6 +30,8 @@ removed when training with a player. The Editor still requires it to be clamped
   additional memory allocations. (#4887)
 - Added `ObservationWriter.AddList()` and deprecated `ObservationWriter.AddRange()`.
   `AddList()` is recommended, as it does not generate any additional memory allocations. (#4887)
+- Added `ActuatorComponent.CreateActuators`, and deprecate `ActuatorComponent.CreateActuator`.  The
+  default implementation will wrap `ActuatorComponent.CreateActuator` in an array and return that. (#4899)
 
 #### ml-agents / ml-agents-envs / gym-unity (Python)
 - Added a `--torch-device` commandline option to `mlagents-learn`, which sets the default

com.unity.ml-agents/Runtime/Actuators/ActuatorComponent.cs

@@ -1,3 +1,4 @@
+using System;
 using UnityEngine;
 
 namespace Unity.MLAgents.Actuators
@@ -12,8 +13,21 @@ public abstract class ActuatorComponent : MonoBehaviour
         /// Create the IActuator.  This is called by the Agent when it is initialized.
         /// </summary>
         /// <returns>Created IActuator object.</returns>
+        [Obsolete("Use CreateActuators instead.")]
         public abstract IActuator CreateActuator();
 
+        /// <summary>
+        /// Create a collection of <see cref="IActuator"/>s.  This is called by the <see cref="Agent"/> during
+        /// initialization.
+        /// </summary>
+        /// <returns>A collection of <see cref="IActuator"/>s</returns>
+        public virtual IActuator[] CreateActuators()
+        {
+#pragma warning disable 618
+            return new[] { CreateActuator() };
+#pragma warning restore 618
+        }
+
         /// <summary>
         /// The specification of the possible actions for this ActuatorComponent.
         /// This must produce the same results as the corresponding IActuator's ActionSpec.

com.unity.ml-agents/Runtime/Actuators/ActuatorManager.cs

@@ -369,6 +369,18 @@ void ClearBufferSizes()
             NumContinuousActions = NumDiscreteActions = SumOfDiscreteBranchSizes = 0;
         }
 
+        /// <summary>
+        /// Add an array of <see cref="IActuator"/>s at once.
+        /// </summary>
+        /// <param name="actuators">The array of <see cref="IActuator"/>s to add.</param>
+        public void AddActuators(IActuator[] actuators)
+        {
+            for (var i = 0; i < actuators.Length; i++)
+            {
+                Add(actuators[i]);
+            }
+        }
+
         /*********************************************************************************
          * IList implementation that delegates to m_Actuators List.                      *
          *********************************************************************************/
@@ -432,7 +444,7 @@ public bool Remove(IActuator item)
         public int Count => m_Actuators.Count;
 
         /// <inheritdoc/>
-        public bool IsReadOnly => m_Actuators.IsReadOnly;
+        public bool IsReadOnly => false;
 
         /// <inheritdoc/>
         public int IndexOf(IActuator item)

com.unity.ml-agents/Runtime/Agent.cs

@@ -1006,7 +1006,7 @@ void InitializeActuators()
 
             foreach (var actuatorComponent in attachedActuators)
             {
-                m_ActuatorManager.Add(actuatorComponent.CreateActuator());
+                m_ActuatorManager.AddActuators(actuatorComponent.CreateActuators());
             }
         }
 

docs/Migrating.md

@@ -21,6 +21,15 @@ double-check that the versions are in the same. The versions can be found in
 - `VectorSensor.AddObservation(IEnumerable<float>)` is deprecated. Use `VectorSensor.AddObservation(IList<float>)`
   instead.
 - `ObservationWriter.AddRange()` is deprecated. Use `ObservationWriter.AddList()` instead.
+- `ActuatorComponent.CreateAcuator()` is deprecated.  Please use override `ActuatorComponent.CreateActuators`
+  instead.  Since `ActuatorComponent.CreateActuator()` is abstract, you will still need to override it in your
+  class until it is removed.  It is only ever called if you don't override `ActuatorComponent.CreateActuators`.
+  You can suppress the warnings by surrounding the method with the following pragma:
+    ```c#
+    #pragma warning disable 672
+    public IActuator CreateActuator() { ... }
+    #pragma warning restore 672
+    ```
 
 
 # Migrating