Removing Obsolete methods from the package (#5024)

* Removing Obsolete methods from the package

* Missing depecration and modified changelog

* Readding the obsolete BrainParameter methods, will need a larger discussion on these

* Removing Action Masker, readding the warining when using a non-implemented Heuristic, Removing NumAction from Brain Parameters

* removing documentation and some calls to deprecated methods in the extensions package

* Editing the Changelog to put the unreleased on top

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

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

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

@@ -7,14 +7,12 @@ namespace Unity.MLAgentsExamples
  public class Match3ExampleActuatorComponent : Match3ActuatorComponent
  {
  /// <inheritdoc/>
-#pragma warning disable 672
- public override IActuator CreateActuator()
-#pragma warning restore 672
+ public override IActuator[] CreateActuators()
  {
  var board = GetComponent<Match3Board>();
  var agent = GetComponentInParent<Agent>();
  var seed = RandomSeed == -1 ? gameObject.GetInstanceID() : RandomSeed + 1;
- return new Match3ExampleActuator(board, ForceHeuristic, agent, ActuatorName, seed);
+ return new IActuator[] { new Match3ExampleActuator(board, ForceHeuristic, agent, ActuatorName, seed) };
  }
  }
 }

com.unity.ml-agents.extensions/Runtime/Input/InputActuatorComponent.cs

@@ -255,11 +255,6 @@ internal static InputControlScheme CreateControlScheme(InputControl device,
  return inputControlScheme;
  }
 
-#pragma warning disable 672
- /// <inheritdoc cref="ActuatorComponent.CreateActuator"/>
- public override IActuator CreateActuator() { return null; }
-#pragma warning restore 672
-
  /// <summary>
  ///
  /// </summary>

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

@@ -29,14 +29,12 @@ public class Match3ActuatorComponent : ActuatorComponent
  public bool ForceHeuristic;
 
  /// <inheritdoc/>
-#pragma warning disable 672
- public override IActuator CreateActuator()
-#pragma warning restore 672
+ public override IActuator[] CreateActuators()
  {
  var board = GetComponent<AbstractBoard>();
  var agent = GetComponentInParent<Agent>();
  var seed = RandomSeed == -1 ? gameObject.GetInstanceID() : RandomSeed + 1;
- return new Match3Actuator(board, ForceHeuristic, seed, agent, ActuatorName);
+ return new IActuator[] { new Match3Actuator(board, ForceHeuristic, seed, agent, ActuatorName) };
  }
 
  /// <inheritdoc/>

com.unity.ml-agents/CHANGELOG.md

@@ -9,6 +9,23 @@ and this project adheres to
 ## [Unreleased]
 ### Major Changes
 #### com.unity.ml-agents (C#)
+======
+- Some methods previously marked as `Obsolete` have been removed. If you were using these methods, you need to replace them with their supported counterpart.
+#### ml-agents / ml-agents-envs / gym-unity (Python)
+
+### Minor Changes
+#### com.unity.ml-agents / com.unity.ml-agents.extensions (C#)
+#### ml-agents / ml-agents-envs / gym-unity (Python)
+
+### Bug Fixes
+#### com.unity.ml-agents (C#)
+#### ml-agents / ml-agents-envs / gym-unity (Python)
+
+
+## [1.9.0-preview] - 2021-03-17
+### Major Changes
+#### com.unity.ml-agents (C#)
+- The `BufferSensor` and `BufferSensorComponent` have been added. They allow the Agent to observe variable number of entities. (#4909)
 #### ml-agents / ml-agents-envs / gym-unity (Python)
 
 ### Minor Changes

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

@@ -9,24 +9,12 @@ namespace Unity.MLAgents.Actuators
  /// </summary>
  public abstract class ActuatorComponent : MonoBehaviour
  {
- /// <summary>
- /// 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
- }
+ public abstract IActuator[] CreateActuators();
 
  /// <summary>
  /// The specification of the possible actions for this ActuatorComponent.

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

@@ -148,47 +148,6 @@ public override int GetHashCode()
  return (ContinuousActions.GetHashCode() * 397) ^ DiscreteActions.GetHashCode();
  }
  }
-
- /// <summary>
- /// Packs the continuous and discrete actions into one float array. The array passed into this method
- /// must have a Length that is greater than or equal to the sum of the Lengths of
- /// <see cref="ContinuousActions"/> and <see cref="DiscreteActions"/>.
- /// </summary>
- /// <param name="destination">A float array to pack actions into whose length is greater than or
- /// equal to the addition of the Lengths of this objects <see cref="ContinuousActions"/> and
- /// <see cref="DiscreteActions"/> segments.</param>
- [Obsolete("PackActions has been deprecated.")]
- public void PackActions(in float[] destination)
- {
- Debug.Assert(destination.Length >= ContinuousActions.Length + DiscreteActions.Length,
- $"argument '{nameof(destination)}' is not large enough to pack the actions into.\n" +
- $"{nameof(destination)}.Length: {destination.Length}\n" +
- $"{nameof(ContinuousActions)}.Length + {nameof(DiscreteActions)}.Length: {ContinuousActions.Length + DiscreteActions.Length}");
-
- var start = 0;
- if (ContinuousActions.Length > 0)
- {
- Array.Copy(ContinuousActions.Array,
- ContinuousActions.Offset,
- destination,
- start,
- ContinuousActions.Length);
- start = ContinuousActions.Length;
- }
- if (start >= destination.Length)
- {
- return;
- }
-
- if (DiscreteActions.Length > 0)
- {
- Array.Copy(DiscreteActions.Array,
- DiscreteActions.Offset,
- destination,
- start,
- DiscreteActions.Length);
- }
- }
  }
 
  /// <summary>

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

@@ -301,9 +301,6 @@ internal struct AgentParameters
  /// Whether or not the Agent has been initialized already
  bool m_Initialized;
 
- /// Keeps track of the actions that are masked at each step.
- DiscreteActionMasker m_ActionMasker;
-
  /// <summary>
  /// Set of DemonstrationWriters that the Agent will write its step information to.
  /// If you use a DemonstrationRecorder component, this will automatically register its DemonstrationWriter.
@@ -338,17 +335,6 @@ internal struct AgentParameters
  /// </summary>
  IActuator m_VectorActuator;
 
- /// <summary>
- /// This is used to avoid allocation of a float array every frame if users are still using the old
- /// OnActionReceived method.
- /// </summary>
- float[] m_LegacyActionCache;
-
- /// <summary>
- /// This is used to avoid allocation of a float array during legacy calls to Heuristic.
- /// </summary>
- float[] m_LegacyHeuristicCache;
-
  /// Currect MultiAgentGroup ID. Default to 0 (meaning no group)
  int m_GroupId;
 
@@ -952,29 +938,7 @@ public virtual void Initialize() { }
  /// <seealso cref="IActionReceiver.OnActionReceived"/>
  public virtual void Heuristic(in ActionBuffers actionsOut)
  {
- // Disable deprecation warnings so we can call the legacy overload.
-#pragma warning disable CS0618
-
- // The default implementation of Heuristic calls the
- // obsolete version for backward compatibility
- switch (m_PolicyFactory.BrainParameters.VectorActionSpaceType)
- {
- case SpaceType.Continuous:
- Heuristic(m_LegacyHeuristicCache);
- Array.Copy(m_LegacyHeuristicCache, actionsOut.ContinuousActions.Array, m_LegacyActionCache.Length);
- actionsOut.DiscreteActions.Clear();
- break;
- case SpaceType.Discrete:
- Heuristic(m_LegacyHeuristicCache);
- var discreteActionSegment = actionsOut.DiscreteActions;
- for (var i = 0; i < actionsOut.DiscreteActions.Length; i++)
- {
- discreteActionSegment[i] = (int)m_LegacyHeuristicCache[i];
- }
- actionsOut.ContinuousActions.Clear();
- break;
- }
-#pragma warning restore CS0618
+ Debug.LogWarning("Heuristic method called but not implemented. Returning placeholder actions.");
  }
 
  /// <summary>
@@ -1064,8 +1028,6 @@ void InitializeActuators()
  var param = m_PolicyFactory.BrainParameters;
  m_VectorActuator = new AgentVectorActuator(this, this, param.ActionSpec);
  m_ActuatorManager = new ActuatorManager(attachedActuators.Length + 1);
- m_LegacyActionCache = new float[m_VectorActuator.TotalNumberOfActions()];
- m_LegacyHeuristicCache = new float[m_VectorActuator.TotalNumberOfActions()];
 
  m_ActuatorManager.Add(m_VectorActuator);
 
@@ -1223,17 +1185,7 @@ public ReadOnlyCollection<float> GetObservations()
  /// [Agents - Actions]: https://github.com/Unity-Technologies/ml-agents/blob/release_15_docs/docs/Learning-Environment-Design-Agents.md#actions
  /// </remarks>
  /// <seealso cref="IActionReceiver.OnActionReceived"/>
- public virtual void WriteDiscreteActionMask(IDiscreteActionMask actionMask)
- {
- if (m_ActionMasker == null)
- {
- m_ActionMasker = new DiscreteActionMasker(actionMask);
- }
- // Disable deprecation warnings so we can call the legacy overload.
-#pragma warning disable CS0618
- CollectDiscreteActionMasks(m_ActionMasker);
-#pragma warning restore CS0618
- }
+ public virtual void WriteDiscreteActionMask(IDiscreteActionMask actionMask) { }
 
  /// <summary>
  /// Implement `OnActionReceived()` to specify agent behavior at every step, based
@@ -1301,34 +1253,7 @@ public virtual void WriteDiscreteActionMask(IDiscreteActionMask actionMask)
  /// <param name="actions">
  /// Struct containing the buffers of actions to be executed at this step.
  /// </param>
- public virtual void OnActionReceived(ActionBuffers actions)
- {
- var actionSpec = m_PolicyFactory.BrainParameters.ActionSpec;
- // For continuous and discrete actions together, we don't need to fall back to the legacy method
- if (actionSpec.NumContinuousActions > 0 && actionSpec.NumDiscreteActions > 0)
- {
- // Nothing implemented.
- return;
- }
-
- if (!actions.ContinuousActions.IsEmpty())
- {
- Array.Copy(actions.ContinuousActions.Array,
- m_LegacyActionCache,
- actionSpec.NumContinuousActions);
- }
- else
- {
- for (var i = 0; i < m_LegacyActionCache.Length; i++)
- {
- m_LegacyActionCache[i] = (float)actions.DiscreteActions[i];
- }
- }
- // Disable deprecation warnings so we can call the legacy overload.
-#pragma warning disable CS0618
- OnActionReceived(m_LegacyActionCache);
-#pragma warning restore CS0618
- }
+ public virtual void OnActionReceived(ActionBuffers actions) { }
 
  /// <summary>
  /// Implement `OnEpisodeBegin()` to set up an Agent instance at the beginning