[MLA-1159] Add virtual methods to DecisionRequester (#5223)

Author: Chris Elion

com.unity.ml-agents/CHANGELOG.md

@@ -47,6 +47,8 @@ different sizes using the same model. For a summary of the interface changes, pl
 depend on the previous behavior, you can explicitly set the Agent's `InferenceDevice` to `InferenceDevice.CPU`. (#5175)
 - Added support for `Goal Signal` as a type of observation. Trainers can now use HyperNetworks to process `Goal Signal`. Trainers with HyperNetworks are more effective at solving multiple tasks. (#5142, #5159, #5149)
 - Modified the [GridWorld environment](https://github.com/Unity-Technologies/ml-agents/blob/main/docs/Learning-Environment-Examples.md#gridworld) to use the new `Goal Signal` feature. (#5193)
+- `DecisionRequester.ShouldRequestDecision()` and `ShouldRequestAction()`methods were added. These are used to
+determine whether `Agent.RequestDecision()` and `Agent.RequestAction()` are called (respectively). (#5223)
 - `RaycastPerceptionSensor` now caches its raycast results; they can be accessed via `RayPerceptionSensor.RayPerceptionOutput`. (#5222)
 
 #### ml-agents / ml-agents-envs / gym-unity (Python)

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

@@ -42,6 +42,14 @@ public class DecisionRequester : MonoBehaviour
         [NonSerialized]
         Agent m_Agent;
 
+        /// <summary>
+        /// Get the Agent attached to the DecisionRequester.
+        /// </summary>
+        public Agent Agent
+        {
+            get => m_Agent;
+        }
+
         internal void Awake()
         {
             m_Agent = gameObject.GetComponent<Agent>();
@@ -57,21 +65,58 @@ void OnDestroy()
             }
         }
 
+        /// <summary>
+        /// Information about Academy step used to make decisions about whether to request a decision.
+        /// </summary>
+        public struct DecisionRequestContext
+        {
+            /// <summary>
+            /// The current step count of the Academy, equivalent to Academy.StepCount.
+            /// </summary>
+            public int AcademyStepCount;
+        }
+
         /// <summary>
         /// Method that hooks into the Academy in order inform the Agent on whether or not it should request a
         /// decision, and whether or not it should take actions between decisions.
         /// </summary>
         /// <param name="academyStepCount">The current step count of the academy.</param>
         void MakeRequests(int academyStepCount)
         {
-            if (academyStepCount % DecisionPeriod == 0)
+            var context = new DecisionRequestContext
+            {
+                AcademyStepCount = academyStepCount
+            };
+
+            if (ShouldRequestDecision(context))
             {
                 m_Agent?.RequestDecision();
             }
-            if (TakeActionsBetweenDecisions)
+
+            if (ShouldRequestAction(context))
             {
                 m_Agent?.RequestAction();
             }
         }
+
+        /// <summary>
+        /// Whether Agent.RequestDecision should be called on this update step.
+        /// </summary>
+        /// <param name="context"></param>
+        /// <returns></returns>
+        protected virtual bool ShouldRequestDecision(DecisionRequestContext context)
+        {
+            return context.AcademyStepCount % DecisionPeriod == 0;
+        }
+
+        /// <summary>
+        /// Whether Agent.RequestAction should be called on this update step.
+        /// </summary>
+        /// <param name="context"></param>
+        /// <returns></returns>
+        protected virtual bool ShouldRequestAction(DecisionRequestContext context)
+        {
+            return TakeActionsBetweenDecisions;
+        }
     }
 }

com.unity.ml-agents/Tests/Editor/PublicAPI/PublicApiValidation.cs

@@ -1,6 +1,7 @@
 using System.Collections.Generic;
 using Unity.MLAgents.Sensors;
 using NUnit.Framework;
+using Unity.MLAgents;
 using UnityEngine;
 
 namespace Unity.MLAgentsExamples
@@ -76,5 +77,25 @@ public void CheckSetupRayPerceptionSensorComponent()
             Assert.AreEqual(outputs.RayOutputs.Length, 2*sensorComponent.RaysPerDirection + 1);
         }
 #endif
+
+        /// <summary>
+        /// Make sure we can inherit from DecisionRequester and override some logic.
+        /// </summary>
+        class CustomDecisionRequester : DecisionRequester
+        {
+            /// <summary>
+            /// Example logic. If the killswitch flag is set, the Agent never requests a decision.
+            /// </summary>
+            public bool KillswitchEnabled;
+
+            public CustomDecisionRequester()
+            {
+            }
+
+            protected override bool ShouldRequestDecision(DecisionRequestContext context)
+            {
+                return !KillswitchEnabled && base.ShouldRequestDecision(context);
+            }
+        }
     }
 }