rearrange match3 docs (#5215)

* rearrange match3 docs

* changelog and migration from previous PR

Author: Chris Elion

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

@@ -2,41 +2,15 @@
 
 <img src="images/match3.png" align="center" width="3000"/>
 
-## Overview
-One of the main feedback we get is to illustrate more real game examples using ML-Agents. We are excited to provide an
-example implementation of Match-3 using ML-Agents and additional utilities to integrate ML-Agents with Match-3 games.
-
-Our aim is to enable Match-3 teams to leverage ML-Agents to create player agents to learn and play different Match-3
-levels. This implementation is intended as a starting point and guide for teams to get started (as there are many
-nuances with Match-3 for training ML-Agents) and for us to iterate both on the C#, hyperparameters, and trainers to
-improve ML-Agents for Match-3.
-
-This implementation includes:
-
-* C# implementation catered toward a Match-3 setup including concepts around encoding for moves based on
-[Human Like Playtesting with Deep Learning](https://www.researchgate.net/publication/328307928_Human-Like_Playtesting_with_Deep_Learning)
-* An example Match-3 scene with ML-Agents implemented (located under /Project/Assets/ML-Agents/Examples/Match3).
-More information on the Match-3 example is [here](https://github.com/Unity-Technologies/ml-agents/tree/release_15_docs/docs/docs/Learning-Environment-Examples.md#match-3).
-
-### Feedback
-If you are a Match-3 developer and are trying to leverage ML-Agents for this scenario,
-[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.
-
 ## Getting started
-The C# code for Match-3 exists inside of the extensions package (com.unity.ml-agents.extensions).  A good first step
+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
- 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.
+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.
+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.
 
 ## Technical specifications for Match-3 with ML-Agents
 
@@ -128,3 +102,13 @@ The indexing for actions is the same as described in
 [Human Like Playtesting with Deep Learning](https://www.researchgate.net/publication/328307928_Human-Like_Playtesting_with_Deep_Learning)
 (for example, Figure 2b). The horizontal moves are enumerated first, then the vertical ones.
 <img src="images/match3-moves.png" align="center"/>
+
+## Feedback
+If you are a Match-3 developer and are trying to leverage ML-Agents for this scenario,
+[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.

com.unity.ml-agents/CHANGELOG.md

@@ -27,6 +27,8 @@ interface was removed. (#5164)
 - `Match3Sensor` was refactored to produce cell and special type observations separately, and `Match3SensorComponent` now
 produces two `Match3Sensor`s (unless there are no special types). Previously trained models will have different observation
 sizes and will need to be retrained. (#5181)
+- The `AbstractBoard` class for integration with Match-3 games was changed to make it easier to support boards with
+different sizes using the same model. For a summary of the interface changes, please see the Migration Guide. (##5189)
 
 #### ml-agents / ml-agents-envs / gym-unity (Python)
 

docs/Migrating.md

@@ -18,7 +18,8 @@ double-check that the versions are in the same. The versions can be found in
 - The official version of Unity ML-Agents supports is now 2019.4 LTS. If you run
   into issues, please consider deleting your project's Library folder and reponening your
   project.
-- If you used any of the APIs that were deprecated before version 2.0, you need to use their replacement. These deprecated APIs have been removed. See the migration steps bellow for specific API replacements.
+- If you used any of the APIs that were deprecated before version 2.0, you need to use their replacement. These
+deprecated APIs have been removed. See the migration steps bellow for specific API replacements.
 ### IDiscreteActionMask changes
 - The interface for disabling specific discrete actions has changed. `IDiscreteActionMask.WriteMask()` was removed,
 and replaced with `SetActionEnabled()`. Instead of returning an IEnumerable with indices to disable, you can
@@ -93,6 +94,17 @@ public CompressionSpec GetCompressionSpec()
 - The abstract method `SensorComponent.GetObservationShape()` was removed.
 - The abstract method `SensorComponent.CreateSensor()` was replaced with `CreateSensors()`, which returns an `ISensor[]`.
 
+### Match3 integration changes
+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
+contains `Rows`, `Columns`, `NumCellTypes`, and `NumSpecialTypes` fields, with the same meanings as the old
+`AbstractBoard` fields.
+* `public virtual BoardSize GetCurrentBoardSize()` is an optional method; by default it returns `GetMaxBoardSize()`. If
+you wish to use a single behavior to work with multiple board sizes, override `GetCurrentBoardSize()` to return the
+current `BoardSize`. The values returned by `GetCurrentBoardSize()` must be less than or equal to the corresponding
+values from `GetMaxBoardSize()`.
+
 ## Migrating to Release 13
 ### Implementing IHeuristic in your IActuator implementations
  - If you have any custom actuators, you can now implement the `IHeuristicProvider` interface to have your actuator