ML-Agents Release 17

Package Versions

NOTE: It is strongly recommended that you use packages from the same release together for the best experience.

Breaking Changes

Minimum Version Support

• The minimum supported Unity version was updated to 2019.4. (#5166)

C# API Changes

• Several breaking interface changes were made. See the Migration Guide for more details.
• Some methods previously marked as Obsolete have been removed. If you were using these methods, you need to replace them with their supported counterpart. (#5024)
• The interface for disabling discrete actions in IDiscreteActionMask has changed. WriteMask(int branch, IEnumerable<int> actionIndices) was replaced with SetActionEnabled(int branch, int actionIndex, bool isEnabled). (#5060)
• IActuator now implements IHeuristicProvider. (#5110)
• ISensor.GetObservationShape() has been removed, and GetObservationSpec() has been added. The ITypedSensor and IDimensionPropertiesSensor interfaces have been removed. (#5127)
• ISensor.GetCompressionType() has been removed, and GetCompressionSpec() has been added. The ISparseChannelSensor interface has been removed. (#5164)
• The abstract method SensorComponent.GetObservationShape() was no longer being called, so it has been removed. (#5172)
• SensorComponent.CreateSensor() has been replaced with SensorComponent.CreateSensors(), which returns an ISensor[]. (#5181)
• The default InferenceDevice is now InferenceDevice.Default, which is equivalent to InferenceDevice.Burst. If you depend on the previous behavior, you can explicitly set the Agent's InferenceDevice to InferenceDevice.CPU. (#5175)

Model Format Changes

• Models trained with 1.x versions of ML-Agents no longer work at inference if they were trained using recurrent neural networks (#5254)
• The .onnx models input names have changed. All input placeholders now use the prefix obs_ removing the distinction between visual and vector observations. In addition, the inputs and outputs of LSTM have changed. Models created with this version are not usable with previous versions of the package (#5080, #5236)
• The .onnx models discrete action output now contains the discrete actions values and not the logits. Models created with this version are not usable with previous versions of the package (#5080)

Features Moved from com.unity.ml-agents.extensions to com.unity.ml-agents

Match3

• The Match-3 integration utilities have been moved from com.unity.ml-agents.extensions to com.unity.ml-agents. (#5259)
• Match3Sensor has been refactored to produce cell and special type observations separately, and Match3SensorComponent now produces two Match3Sensors (unless there are no special types). Previously trained models have different observation sizes and need to be retrained. (#5181)
• The AbstractBoard class for integration with Match-3 games has been 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)

Grid Sensor

• GridSensor has been refactored and moved to the main package, with changes to both sensor interfaces and behaviors. Existing GridSensor created by the extension package do not work in newer versions. Previously trained models need to be retrained. Please see the Migration Guide for more details. (#5256)

Minor Changes

com.unity.ml-agents / com.unity.ml-agents.extensions (C#)

• Updated the Barracuda package to version 1.4.0-preview(#5236)
• Added ML-Agents package settings. Now you can configure project-level ML-Agents settings in Editor > Project Settings > ML-Agents. (#5027)
• Made com.unity.modules.unityanalytics an optional dependency. (#5109)
• Made com.unity.modules.physics and com.unity.modules.physics2d optional dependencies. (#5112)
• 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 to use the new Goal Signal feature. (#5193)
• DecisionRequester.ShouldRequestDecision() and ShouldRequestAction()methods have been 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)
• ActionBuffers are now reset to zero before being passed to Agent.Heuristic() and IHeuristicProvider.Heuristic(). (#5227)
• Agent now calls IDisposable.Dispose() on all ISensors that implement the IDisposable interface. (#5233)
• CameraSensor, RenderTextureSensor, and Match3Sensor now reuse their Texture2Ds, reducing the amount of memory that needs to be allocated during runtime. (#5233)
• Optimized 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)

ml-agents / ml-agents-envs / gym-unity (Python)

• Some console outputs have been moved from info to debug and are no longer 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)
• The embedding size of attention layers used when a BufferSensor is in the scene has been changed. It is now fixed to 128 units. It might be impossible to resume training from a checkpoint of a previous version. (#5272)

Bug Fixes

com.unity.ml-agents / com.unity.ml-agents.extensions (C#)

• Fixed a potential bug where sensors and actuators could get sorted inconsistently on different systems to different Culture settings. Unfortunately, this may require retraining models if it changes the resulting order of the sensors or actuators on your system. (#5194)
• Removed additional memory allocations that were occurring due to assert messages and iterating of DemonstrationRecorders. (#5246)
• Fixed a bug where agents were trying to access uninitialized fields when creating a new RayPerceptionSensorComponent on an agent. (#5261)
• Fixed a bug where the DemonstrationRecorder would throw a null reference exception if Num Steps To Record > 0 and Record was turned off. (#5274)

ml-agents / ml-agents-envs / gym-unity (Python)

• Fixed a bug where --results-dir has no effect. (#5269)
• Fixed a bug where old .pt checkpoints were not deleted during training. (#5271)