[MLA-1912] Move Match3 to com.unity.ml-agents

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

@@ -2,7 +2,7 @@
 using UnityEngine;
 using Unity.MLAgents;
 using Unity.MLAgents.Actuators;
-using Unity.MLAgents.Extensions.Match3;
+using Unity.MLAgents.Integrations.Match3;
 
 namespace Unity.MLAgentsExamples
 {

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

@@ -1,5 +1,5 @@
 using System;
-using Unity.MLAgents.Extensions.Match3;
+using Unity.MLAgents.Integrations.Match3;
 using UnityEngine;
 using UnityEngine.Serialization;
 

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

@@ -1,5 +1,5 @@
 using Unity.MLAgents;
-using Unity.MLAgents.Extensions.Match3;
+using Unity.MLAgents.Integrations.Match3;
 
 namespace Unity.MLAgentsExamples
 {

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

@@ -1,6 +1,6 @@
 using Unity.MLAgents;
 using Unity.MLAgents.Actuators;
-using Unity.MLAgents.Extensions.Match3;
+using Unity.MLAgents.Integrations.Match3;
 
 namespace Unity.MLAgentsExamples
 {

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

@@ -18,8 +18,7 @@ The following table describes the package folder structure:
 | _Runtime_        | Contains core C# APIs for integrating ML-Agents into your Unity scene. |
 | _Tests_          | Contains the unit tests for the package.                               |
 
-The Runtime directory currently contains three features:
- * [Match-3 sensor and actuator](Match3.md)
+The Runtime directory currently contains these features:
  * [Grid-based sensor](Grid-Sensor.md)
  * Physics-based sensors
  * [Input System Package Integration](InputActuatorComponent.md)

com.unity.ml-agents/CHANGELOG.md

@@ -52,6 +52,7 @@ determine whether `Agent.RequestDecision()` and `Agent.RequestAction()` are call
 amount of memory that needs to be allocated during runtime. (#5233)
 - Optimzed `ObservationWriter.WriteTexture()` so that it doesn't call `Texture2D.GetPixels32()` for `RGB24` textures.
 This results in much less memory being allocated during inference with `CameraSensor` and `RenderTextureSensor`. (#5233)
+- The Match-3 integration utilities were moved from `com.unity.ml-agents.extensions` to `com.unity.ml-agents`. (#5259)
 
 #### ml-agents / ml-agents-envs / gym-unity (Python)
 - Some console output have been moved from `info` to `debug` and will not be printed by default. If you want all messages to be printed, you can run `mlagents-learn` with the `--debug` option or add the line `debug: true` at the top of the yaml config file. (#5211)

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

@@ -35,13 +35,14 @@ GitHub repo].
 
 The following table describes the package folder structure:
 
-| **Location**     | **Description**                                                        |
-| ---------------- | ---------------------------------------------------------------------- |
-| _Documentation~_ | Contains the documentation for the Unity package.                      |
-| _Editor_         | Contains utilities for Editor windows and drawers.                     |
-| _Plugins_        | Contains third-party DLLs.                                             |
-| _Runtime_        | Contains core C# APIs for integrating ML-Agents into your Unity scene. |
-| _Tests_          | Contains the unit tests for the package.                               |
+| **Location**           | **Description**                                                         |
+| ---------------------- | ----------------------------------------------------------------------- |
+| _Documentation~_       | Contains the documentation for the Unity package.                       |
+| _Editor_               | Contains utilities for Editor windows and drawers.                      |
+| _Plugins_              | Contains third-party DLLs.                                              |
+| _Runtime_              | Contains core C# APIs for integrating ML-Agents into your Unity scene.  |
+| _Runtime/Integrations_ | Contains utilities for integrating ML-Agents into specific game genres. |
+| _Tests_                | Contains the unit tests for the package.                                |
 
 <a name="Installation"></a>
 

com.unity.ml-agents.extensions/Runtime/Match3/AbstractBoard.cs → com.unity.ml-agents/Runtime/Integrations/Match3/AbstractBoard.cs

@@ -4,10 +4,10 @@
 using UnityEngine;
 using Debug = UnityEngine.Debug;
 
-namespace Unity.MLAgents.Extensions.Match3
+namespace Unity.MLAgents.Integrations.Match3
 {
     /// <summary>
-    /// Representation of the AbstractBoard size and number of cell and special types.
+    /// Representation of the AbstractBoard dimensions, and number of cell and special types.
     /// </summary>
     public struct BoardSize
     {
@@ -125,7 +125,7 @@ public virtual BoardSize GetCurrentBoardSize()
         public abstract bool IsMoveValid(Move m);
 
         /// <summary>
-        /// Instruct the game to make the given move. Returns true if the move was made.
+        /// Instruct the game to make the given Move. Returns true if the move was made.
         /// Note that during training, a move that was marked as invalid may occasionally still be
         /// requested. If this happens, it is safe to do nothing and request another move.
         /// </summary>

com.unity.ml-agents.extensions/Runtime/Match3/Match3Actuator.cs → com.unity.ml-agents/Runtime/Integrations/Match3/Match3Actuator.cs

@@ -2,7 +2,7 @@
 using Debug = UnityEngine.Debug;
 
 
-namespace Unity.MLAgents.Extensions.Match3
+namespace Unity.MLAgents.Integrations.Match3
 {
     /// <summary>
     /// Actuator for a Match3 game. It translates valid moves (defined by AbstractBoard.IsMoveValid())
@@ -23,7 +23,6 @@ public class Match3Actuator : IActuator, IBuiltInActuator
         /// <param name="forceHeuristic">Whether the inference action should be ignored and the Agent's Heuristic
         /// should be called. This should only be used for generating comparison stats of the Heuristic.</param>
         /// <param name="seed">The seed used to initialize <see cref="System.Random"/>.</param>
-        /// <param name="agent"></param>
         /// <param name="name"></param>
         public Match3Actuator(AbstractBoard board,
                               bool forceHeuristic,

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

@@ -2,7 +2,7 @@
 using UnityEngine;
 using UnityEngine.Serialization;
 
-namespace Unity.MLAgents.Extensions.Match3
+namespace Unity.MLAgents.Integrations.Match3
 {
     /// <summary>
     /// Actuator component for a Match3 game. Generates a Match3Actuator at runtime.

com.unity.ml-agents.extensions/Runtime/Match3/Match3Sensor.cs → com.unity.ml-agents/Runtime/Integrations/Match3/Match3Sensor.cs

@@ -3,7 +3,7 @@
 using Unity.MLAgents.Sensors;
 using UnityEngine;
 
-namespace Unity.MLAgents.Extensions.Match3
+namespace Unity.MLAgents.Integrations.Match3
 {
     /// <summary>
     /// Delegate that provides integer values at a given (x,y) coordinate.
@@ -164,7 +164,6 @@ public int Write(ObservationWriter writer)
                 }
             }
 
-
             return offset;
         }
 

com.unity.ml-agents.extensions/Runtime/Match3/Match3SensorComponent.cs → com.unity.ml-agents/Runtime/Integrations/Match3/Match3SensorComponent.cs

@@ -2,7 +2,7 @@
 using Unity.MLAgents.Sensors;
 using UnityEngine;
 
-namespace Unity.MLAgents.Extensions.Match3
+namespace Unity.MLAgents.Integrations.Match3
 {
     /// <summary>
     /// Sensor component for a Match3 game.

com.unity.ml-agents.extensions/Runtime/Match3/Move.cs → com.unity.ml-agents/Runtime/Integrations/Match3/Move.cs

@@ -1,7 +1,7 @@
 using System;
 using UnityEngine;
 
-namespace Unity.MLAgents.Extensions.Match3
+namespace Unity.MLAgents.Integrations.Match3
 {
     /// <summary>
     /// Directions for a Move.
@@ -141,7 +141,7 @@ public void Next(BoardSize maxBoardSize)
         }
 
         /// <summary>
-        /// Construct a Move from the row, column, and direction.
+        /// Construct a Move from the row, column, direction, and board size.
         /// </summary>
         /// <param name="row"></param>
         /// <param name="col"></param>

com.unity.ml-agents.extensions/Tests/Editor/Match3/AbstractBoardTests.cs → com.unity.ml-agents/Tests/Editor/Integrations/Match3/AbstractBoardTests.cs

@@ -2,9 +2,9 @@
 using System.Collections.Generic;
 using UnityEngine;
 using NUnit.Framework;
-using Unity.MLAgents.Extensions.Match3;
+using Unity.MLAgents.Integrations.Match3;
 
-namespace Unity.MLAgents.Extensions.Tests.Match3
+namespace Unity.MLAgents.Tests.Integrations.Match3
 {
     internal class StringBoard : AbstractBoard
     {

com.unity.ml-agents.extensions/Tests/Editor/Match3/Match3ActuatorTests.cs → com.unity.ml-agents/Tests/Editor/Integrations/Match3/Match3ActuatorTests.cs

@@ -1,10 +1,10 @@
 using System.Collections.Generic;
 using NUnit.Framework;
 using Unity.MLAgents.Actuators;
-using Unity.MLAgents.Extensions.Match3;
+using Unity.MLAgents.Integrations.Match3;
 using UnityEngine;
 
-namespace Unity.MLAgents.Extensions.Tests.Match3
+namespace Unity.MLAgents.Tests.Integrations.Match3
 {
     internal class SimpleBoard : AbstractBoard
     {

com.unity.ml-agents.extensions/Tests/Editor/Match3/Match3SensorTests.cs → com.unity.ml-agents/Tests/Editor/Integrations/Match3/Match3SensorTests.cs

@@ -2,12 +2,12 @@
 using System.IO;
 using System.Reflection;
 using NUnit.Framework;
-using Unity.MLAgents.Extensions.Match3;
 using UnityEngine;
-using Unity.MLAgents.Extensions.Tests.Sensors;
+using Unity.MLAgents.Integrations.Match3;
 using Unity.MLAgents.Sensors;
+using Unity.MLAgents.Tests;
 
-namespace Unity.MLAgents.Extensions.Tests.Match3
+namespace Unity.MLAgents.Tests.Integrations.Match3
 {
     public class Match3SensorTests
     {
@@ -373,7 +373,7 @@ void SavePNGs(byte[] concatenatedPngData, string pathPrefix)
             for (var i = 0; i < splitPngs.Count; i++)
             {
                 var pngData = splitPngs[i];
-                var path = $"Packages/com.unity.ml-agents.extensions/Tests/Editor/Match3/{pathPrefix}{i}.png";
+                var path = $"Packages/com.unity.ml-agents/Tests/Editor/Integrations/Match3/{pathPrefix}{i}.png";
                 using (var sw = File.Create(path))
                 {
                     foreach (var b in pngData)
@@ -389,7 +389,7 @@ byte[] LoadPNGs(string pathPrefix, int numExpected)
             var bytesOut = new List<byte>();
             for (var i = 0; i < numExpected; i++)
             {
-                var path = $"Packages/com.unity.ml-agents.extensions/Tests/Editor/Match3/{pathPrefix}{i}.png";
+                var path = $"Packages/com.unity.ml-agents/Tests/Editor/Integrations/Match3/{pathPrefix}{i}.png";
                 var res = File.ReadAllBytes(path);
                 bytesOut.AddRange(res);
             }

com.unity.ml-agents.extensions/Tests/Editor/Match3/MoveTests.cs → com.unity.ml-agents/Tests/Editor/Integrations/Match3/MoveTests.cs

@@ -1,8 +1,8 @@
 using System;
 using NUnit.Framework;
-using Unity.MLAgents.Extensions.Match3;
+using Unity.MLAgents.Integrations.Match3;
 
-namespace Unity.MLAgents.Extensions.Tests.Match3
+namespace Unity.MLAgents.Tests.Integrations.Match3
 {
     public class MoveTests
     {

com.unity.ml-agents/Tests/Editor/Unity.ML-Agents.Editor.Tests.asmdef

@@ -5,7 +5,8 @@
         "Unity.ML-Agents",
         "Unity.Barracuda",
         "Unity.ML-Agents.CommunicatorObjects",
-        "Unity.ML-Agents.Runtime.Utils.Tests"
+        "Unity.ML-Agents.Runtime.Utils.Tests",
+        "Unity.ML-Agents.Runtime.Sensor.Tests"
     ],
     "optionalUnityReferences": [
         "TestAssemblies"

com.unity.ml-agents.extensions/Documentation~/Match3.md → docs/Integrations-Match3.md

@@ -3,14 +3,13 @@
 <img src="images/match3.png" align="center" width="3000"/>
 
 ## Getting started
-The C# code for Match-3 exists inside of the extensions package (com.unity.ml-agents.extensions). A good first step
-would be to familiarize with the extensions package by reading the document [here](com.unity.ml-agents.extensions.md).
-The second step would be to take a look at how we have implemented the C# code in the example Match-3 scene (located
+The C# code for Match-3 exists inside of the Unity package (`com.unity.ml-agents`).
+The good first step would be to take a look at how we have implemented the C# code in the example Match-3 scene (located
 under /Project/Assets/ML-Agents/Examples/match3). Once you have some familiarity, then the next step would be to
 implement the C# code for Match-3 from the extensions package.
 
 Additionally, see below for additional technical specifications on the C# code for Match-3. Please note the Match-3 game
- isn't human playable as implemented and can be only played via training.
+isn't human playable as implemented and can be only played via training.
 
 ## Technical specifications for Match-3 with ML-Agents
 
@@ -108,7 +107,3 @@ If you are a Match-3 developer and are trying to leverage ML-Agents for this sce
 [we want to hear from you](https://forms.gle/TBsB9jc8WshgzViU9). Additionally, we are also looking for interested
 Match-3 teams to speak with us for 45 minutes. If you are interested, please indicate that in the
 [form](https://forms.gle/TBsB9jc8WshgzViU9). If selected, we will provide gift cards as a token of appreciation.
-
-### Interested in more game templates?
-Do you have a type of game you are interested for ML-Agents? If so, please post a
-[forum issue](https://forum.unity.com/forums/ml-agents.453/) with [GAME TEMPLATE] in the title.

docs/Integrations.md

@@ -0,0 +1,10 @@
+# Game Integrations
+ML-Agents provides some utilities to make it easier to integrate with some common genres of games.
+
+## Match-3
+The [Match-3 integration](Integrations-Match3.md) provides an abstraction of a match-3 game board and moves, along with
+a sensor to observe the game state, and an actuator to translate the ML-Agent actions into game moves.
+
+## Interested in more game templates?
+Do you have a type of game you are interested for ML-Agents? If so, please post a
+[forum issue](https://forum.unity.com/forums/ml-agents.453/) with `[GAME TEMPLATE]` in the title.

docs/Migrating.md

@@ -95,6 +95,8 @@ public CompressionSpec GetCompressionSpec()
 - The abstract method `SensorComponent.CreateSensor()` was replaced with `CreateSensors()`, which returns an `ISensor[]`.
 
 ### Match3 integration changes
+The Match-3 integration utilities were moved from `com.unity.ml-agents.extensions` to `com.unity.ml-agents`.
+
 The `AbstractBoard` interface was changed:
 * `AbstractBoard` no longer contains `Rows`, `Columns`, `NumCellTypes`, and `NumSpecialTypes` fields.
 * `public abstract BoardSize GetMaxBoardSize()` was added as an abstract method. `BoardSize` is a new struct that