store hit GameObject in raycast output (#4111)

* store hit GameObject in raycast output

* changelog

* fix unit tests

* formatting

Author: Chris Elion

com.unity.ml-agents/CHANGELOG.md

@@ -14,6 +14,7 @@ and this project adheres to
 
 ### Minor Changes
 #### com.unity.ml-agents (C#)
+- `RayPerceptionSensor.Perceive()` now additionally store the GameObject that was hit by the ray. (#4111)
 #### ml-agents / ml-agents-envs / gym-unity (Python)
 
 ### Bug Fixes

com.unity.ml-agents/Runtime/Sensors/RayPerceptionSensor.cs

@@ -161,6 +161,12 @@ public struct RayOutput
             /// </summary>
             public float HitFraction;
 
+            /// <summary>
+            /// The hit GameObject (or null if there was no hit).
+            /// </summary>
+            public GameObject HitGameObject;
+
+
             /// <summary>
             /// Writes the ray output information to a subset of the float array.  Each element in the rayAngles array
             /// determines a sublist of data to the observation. The sublist contains the observation data for a single cast.
@@ -334,7 +340,7 @@ public void Update()
         }
 
         /// <inheritdoc/>
-        public void Reset() { }
+        public void Reset() {}
 
         /// <inheritdoc/>
         public int[] GetObservationShape()
@@ -456,7 +462,8 @@ out DebugDisplayInfo.RayInfo debugRayOut
                 HasHit = castHit,
                 HitFraction = hitFraction,
                 HitTaggedObject = false,
-                HitTagIndex = -1
+                HitTagIndex = -1,
+                HitGameObject = hitObject
             };
 
             if (castHit)

com.unity.ml-agents/Tests/Editor/Sensor/RayPerceptionSensorTests.cs

@@ -27,6 +27,16 @@ public class RayPerception3DTests
         const string k_CubeTag = "Player";
         const string k_SphereTag = "Respawn";
 
+        [TearDown]
+        public void RemoveGameObjects()
+        {
+            var objects = GameObject.FindObjectsOfType<GameObject>();
+            foreach (var o in objects)
+            {
+                UnityEngine.Object.DestroyImmediate(o);
+            }
+        }
+
         void SetupScene()
         {
             /* Creates game objects in the world for testing.
@@ -44,18 +54,22 @@ void SetupScene()
             var cube = GameObject.CreatePrimitive(PrimitiveType.Cube);
             cube.transform.position = new Vector3(0, 0, 10);
             cube.tag = k_CubeTag;
+            cube.name = "cube";
 
             var sphere1 = GameObject.CreatePrimitive(PrimitiveType.Sphere);
             sphere1.transform.position = new Vector3(-5, 0, 5);
             sphere1.tag = k_SphereTag;
+            sphere1.name = "sphere1";
 
             var sphere2 = GameObject.CreatePrimitive(PrimitiveType.Sphere);
             sphere2.transform.position = new Vector3(5, 0, 5);
             // No tag for sphere2
+            sphere2.name = "sphere2";
 
             var sphere3 = GameObject.CreatePrimitive(PrimitiveType.Sphere);
             sphere3.transform.position = new Vector3(0, 0, -10);
             sphere3.tag = k_SphereTag;
+            sphere3.name = "sphere3";
 
             Physics.SyncTransforms();
         }
@@ -296,5 +310,33 @@ public void TestRayZeroLength()
                 Assert.LessOrEqual(outputBuffer[2], 1.0f);
             }
         }
+
+        [Test]
+        public void TestStaticPerceive()
+        {
+            SetupScene();
+            var obj = new GameObject("agent");
+            var perception = obj.AddComponent<RayPerceptionSensorComponent3D>();
+
+            perception.RaysPerDirection = 0; // single ray
+            perception.MaxRayDegrees = 45;
+            perception.RayLength = 20;
+            perception.DetectableTags = new List<string>();
+            perception.DetectableTags.Add(k_CubeTag);
+            perception.DetectableTags.Add(k_SphereTag);
+
+            var radii = new[] { 0f, .5f };
+            foreach (var castRadius in radii)
+            {
+                perception.SphereCastRadius = castRadius;
+                var castInput = perception.GetRayPerceptionInput();
+                var castOutput = RayPerceptionSensor.Perceive(castInput);
+
+                Assert.AreEqual(1, castOutput.RayOutputs.Length);
+
+                // Expected to hit the cube
+                Assert.AreEqual("cube", castOutput.RayOutputs[0].HitGameObject.name);
+            }
+        }
     }
 }