[4.0.0] - 2025-08-28

Major Changes

com.unity.ml-agents
Upgraded to Inference Engine 2.2.1 (#6212)
The minimum supported Unity version was updated to 6000.0. (#6207)
Merged the extension package com.unity.ml-agents.extensions to the main package com.unity.ml-agents. (#6227)

Minor Changes

com.unity.ml-agents
Removed broken sample from the package (#6230)
Moved to Unity Package documentation as the primary developer documentation. (#6232)
ml-agents / ml-agents-envs
Bumped grpcio version to >=1.11.0,<=1.53.2 (#6208)

[3.0.0] - 2024-09-02

Major Changes

com.unity.ml-agents / com.unity.ml-agents.extensions (C#)
Upgraded to Sentis 2.0.0 (#6137)
Upgraded to Sentis 1.3.0-pre.3 (#6070)
Upgraded to Sentis 1.3.0-exp.2 (#6013)
The minimum supported Unity version was updated to 2023.2. (#6071)
ml-agents / ml-agents-envs
Upgraded to PyTorch 2.1.1. (#6013)

Minor Changes

com.unity.ml-agents / com.unity.ml-agents.extensions (C#)
Added no-graphics-monitor. (#6014)
ml-agents / ml-agents-envs
Update Installation.md (#6004)
Updated Using-Virtual-Environment.md (#6033)

Bug Fixes

com.unity.ml-agents / com.unity.ml-agents.extensions (C#)
Fix failing ci post upgrade (#6141)
Fixed missing assembly reference for google protobuf. (#6099)
Fixed missing tensor Dispose in ModelRunner. (#6028)
Fixed 3DBall sample package to remove Barracuda dependency. (#6030)
ml-agents / ml-agents-envs
Fix sample code indentation in migrating.md (#5840)
Fixed continuous integration tests (#6079)
Fixed bad like format (#6078)
Bumped numpy version to >=1.23.5,<1.24.0 (#6082)
Bumped onnx version to 1.15.0 (#6062)
Bumped protobuf version to >=3.6,<21 (#6062)

[3.0.0-exp.1] - 2023-10-09

Major Changes

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

• Upgraded ML-Agents to Sentis 1.2.0-exp.2 and deprecated Barracuda. (#5979)
• The minimum supported Unity version was updated to 2022.3. (#5950)
• Added batched raycast sensor option. (#5950)

ml-agents / ml-agents-envs

• Updated to PyTorch 1.13.1 (#5982)
• Deprecated support for Python 3.8.x and 3.9.x (#5981)

Minor Changes

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

• Added DecisionStep parameter to DecisionRequester (#5940)
  • This will allow the staggering of execution timing when using multi-agents, leading to more stable performance.

ml-agents / ml-agents-envs

• Added timeout cli and yaml config file support for specifying environment timeout. (#5991)
• Added training config feature to evenly distribute checkpoints throughout training. (#5842)
• Updated training area replicator to add a condition to only replicate training areas when running a build. (#5842)

Bug Fixes

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

• Compiler errors when using IAsyncEnumerable with .NET Standard 2.1 enabled (#5951)

ml-agents / ml-agents-envs

Package Versions

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

Release Notes

Major Changes

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

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

ml-agents / ml-agents-envs

• Add your trainers to the package using Ml-Agents Custom Trainers plugin. (#)
  • ML-Agents Custom Trainers plugin is an extensible plugin system to define new trainers based on the
    High level trainer API, read morehere.
• Refactored core modules to make ML-Agents internal classes more generalizable to various RL algorithms. (#)
• The minimum supported Python version for ML-agents has changed to 3.8.13. (#)
• The minimum supported version of PyTorch was changed to 1.8.0. (#)
• Add shared critic configurability for PPO. (#)
• We movedUnityToGymWrapper andPettingZoo API toml-agents-envs package. All these environments will be
  versioned underml-agents-envs package in the future (#)

Minor Changes

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

• Added switch to RayPerceptionSensor to allow rays to be ordered left to right. (#)
  • Current alternating order is still the default but will be deprecated.
• Added suppport for enabling/disabling camera object attached to camera sensor in order to improve performance. (#)

ml-agents / ml-agents-envs

• Renaming the path that shadows torch with "mlagents/trainers/torch_entities" and update respective imports (#)

Bug Fixes

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

ml-agents / ml-agents-envs

Package Versions

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

Release Notes

Major Changes

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

• The minimum supported Unity version was updated to 2020.3. (#5673)
• Added a new feature to replicate training areas dynamically during runtime. (#5568)
• Update Barracuda to 2.3.1-preview (#5591)
• Update Input System to 1.3.0 (#5661)

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

Minor Changes

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

• Added the capacity to initialize behaviors from any checkpoint and not just the latest one (#5525)
• Added the ability to get a read-only view of the stacked observations (#5523)

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

• Set gym version in gym-unity to gym release 0.20.0 (#5540)
• Added support for havingbeta,epsilon, andlearning rate on separate schedules (affects only PPO and POCA). (#5538)
• Changed default behavior to restart crashed Unity environments rather than exiting. (#5553)
  • Rate & lifetime limits on this are configurable via 3 new yaml options
    1. env_params.max_lifetime_restarts (--max-lifetime-restarts) [default=10]
    2. env_params.restarts_rate_limit_n (--restarts-rate-limit-n) [default=1]
    3. env_params.restarts_rate_limit_period_s (--restarts-rate-limit-period-s) [default=60]
• Deterministic action selection is now supported during training and inference(#5619)
  • Added a new--deterministic cli flag to deterministically select the most probable actions in policy. The same thing can
    be achieved by addingdeterministic: true undernetwork_settings of the run options configuration.(#5597)
  • Extra tensors are now serialized to support deterministic action selection in onnx. (#5593)
  • Support inference with deterministic action selection in editor (#5599)
• Added minimal analytics collection to LL-API (#5511)
• Update Colab notebooks for GridWorld example with DQN illustrating the use of the Python API and how to export to ONNX (#5643)

Bug Fixes

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

• Update gRPC native lib to universal for arm64 and x86_64. This change should enable ml-agents usage on mac M1 (#5283,#5519)
• Fixed a bug where ml-agents code wouldn't compile on platforms that didn't support analytics (PS4/5, XBoxOne) (#5628)

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

• Fixed a bug where the critics were not being normalized during training. (#5595)
• Fixed the bug where curriculum learning would crash because of the incorrect run_options parsing. (#5586)
• Fixed a bug in multi-agent cooperative training where agents might not receive all of the states of
  terminated teammates. (#5441)
• Fixed wrong attribute name in argparser for torch device option (#5433)(#5467)
• Fixed conflicting CLI and yaml options regarding resume & initialize_from (#5495)
• Fixed failing tests for gym-unity due to gym 0.20.0 release (#5540)
• Fixed a bug in VAIL where the variational bottleneck was not properly passing gradients (#5546)
• Harden user PII protection logic and extend TrainingAnalytics to expose detailed configuration parameters. (#5512)

Package Versions

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

Release Notes

Minor Changes

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

• Updated Barracuda to 2.0.0-pre.3. (#5385)
• FixedNullReferenceException when adding Behavior Parameters with noAgent. (#5382)
• Added stacking option in Editor forVectorSensorComponent. (#5376)

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

• Locked cattrs dependency version to 1.6. (#5397)
• Added a fully connected visual encoder for environments with very small image inputs. (#5351)
• Colab notebooks illustrating the use of the Python API were added to the repository. (#5399)

Bug Fixes

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

• RigidBodySensorComponent now displays a warning if it's used in a way that won't generate useful observations. (#5387)
• Updated the documentation with a note saying thatGridSensor does not work in 2D environments. (#5396)
• Fixed an error where sensors would not reset properly before collecting the last observation at the end of an episode. (#5375)

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

• The calculation of the target entropy of SAC with continuous actions was incorrect and has been fixed. (#5372)
• Fixed an issue where the histogram stats would not be reported correctly in TensorBoard. (#5410)
• Fixed error when importing models which use the ResNet encoder. (#5358)

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 theMigration Guide for more details.
• Some methods previously marked asObsolete 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 inIDiscreteActionMask has changed.WriteMask(int branch, IEnumerable<int> actionIndices) was replaced withSetActionEnabled(int branch, int actionIndex, bool isEnabled). (#5060)
• IActuator now implements IHeuristicProvider. (#5110)
• ISensor.GetObservationShape() has been removed, andGetObservationSpec() has been added. TheITypedSensor andIDimensionPropertiesSensor interfaces have been removed. (#5127)
• ISensor.GetCompressionType() has been removed, andGetCompressionSpec() has been added. TheISparseChannelSensor interface has been removed. (#5164)
• The abstract methodSensorComponent.GetObservationShape() was no longer being called, so it has been removed. (#5172)
• SensorComponent.CreateSensor() has been replaced withSensorComponent.CreateSensors(), which returns anISensor[]. (#5181)
• The defaultInferenceDevice is nowInferenceDevice.Default, which is equivalent toInferenceDevice.Burst. If you depend on the previous behavior, you can explicitly set the Agent'sInferenceDevice toInferenceDevice.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 prefixobs_ 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 fromcom.unity.ml-agents.extensions tocom.unity.ml-agents. (#5259)
• Match3Sensor has been refactored to produce cell and special type observations separately, andMatch3SensorComponent now produces twoMatch3Sensors (unless there are no special types). Previously trained models have different observation sizes and need to be retrained. (#5181)
• TheAbstractBoard 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 version1.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)
• Madecom.unity.modules.unityanalytics an optional dependency. (#5109)
• Madecom.unity.modules.physics andcom.unity.modules.physics2d optional dependencies. (#5112)
• Added support forGoal Signal as a type of observation. Trainers can now use HyperNetworks to processGoal Signal. Trainers with HyperNetworks are more effective at solving multiple tasks. (#5142,#5159,#5149)
• Modified theGridWorld environment to use the newGoal Signal feature. (#5193)
• DecisionRequester.ShouldRequestDecision() andShouldRequestAction()methods have been added. These are used to determine whetherAgent.RequestDecision() andAgent.RequestAction() are called (respectively). (#5223)
• RaycastPerceptionSensor now caches its raycast results; they can be accessed viaRayPerceptionSensor.RayPerceptionOutput. (#5222)
• ActionBuffers are now reset to zero before being passed toAgent.Heuristic() andIHeuristicProvider.Heuristic(). (#5227)
• Agent now callsIDisposable.Dispose() on allISensors that implement theIDisposable interface. (#5233)
• CameraSensor,RenderTextureSensor, andMatch3Sensor now reuse theirTexture2Ds, reducing the amount of memory that needs to be allocated during runtime. (#5233)
• OptimizedObservationWriter.WriteTexture() so that it doesn't callTexture2D.GetPixels32() forRGB24 textures. This results in much less memory being allocated during inference withCameraSensor andRenderTextureSensor. (#5233)

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

• Some console outputs have been moved frominfo todebug and are no longer printed by default. If you want all messages to be printed, you can runmlagents-learn with the--debug option or add the linedebug: 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 ifNum Steps To Record > 0 andRecord 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)

ML-Agents Release 16

Package Versions

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

Major Changes

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

• The--resume flag now supports resuming experiments with additional reward providers or loading partial models if the network architecture has changed. Seehere for more details. (#5213)

Bug Fixes

com.unity.ml-agents (C#)

• Fixed erroneous warnings when using the Demonstration Recorder. (#5216)

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

• Fixed an issue which was causing increased variance when using LSTMs. Also fixed an issue with LSTM when used with POCA andsequence_length <time_horizon. (#5206)
• Fixed a bug where the SAC replay buffer would not be saved out at the end of a run, even ifsave_replay_buffer was enabled. (#5205)
• ELO now correctly resumes when loading from a checkpoint. (#5202)
• In the Python API, fixedvalidate_action to expect the right dimensions whenset_action_single_agent is called. (#5208)
• In theGymToUnityWrapper, raise an appropriate warning ifstep() is called after an environment is done. (#5204)
• Fixed an issue where using one of thegym wrappers would override user-set log levels. (#5201)

ML-Agents Release 15

Package Versions

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

Major Changes

com.unity.ml-agents (C#)

• TheBufferSensor andBufferSensorComponent have been added (documentation). They allow the Agent to observe variable number of entities. For an example, see theSorter environment. (#4909)
• TheSimpleMultiAgentGroup class andIMultiAgentGroup interface have been added (documentation). These allow Agents to be given rewards and end episodes in groups. For examples, see theCooperative Push Block,Dungeon Escape andSoccer environments. (#4923)

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

• The MA-POCA trainer has been added. This is a new trainer that enables Agents to learn how to work together in groups. Configurepoca as the trainer in the configuration YAML after instantiating aSimpleMultiAgentGroup to use this feature. (#5005)

Minor Changes

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

• Updated com.unity.barracuda to 1.3.2-preview. (#5084)
• Added 3D Ball to thecom.unity.ml-agents samples. (#5077)

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

• Theencoding_size setting for RewardSignals has been deprecated. Please usenetwork_settings instead. (#4982)
• Sensor names are now passed through toObservationSpec.name. (#5036)

Bug Fixes

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

• An issue that caused GAIL to fail for environments where agents can terminate episodes by self-sacrifice has been fixed. (#4971)
• Made the error message when observations of different shapes are sent to the trainer clearer. (#5030)
• An issue that prevented curriculums from incrementing with self-play has been fixed. (#5098)

ML-Agents Release 14

Package Versions

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

Minor Changes

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

• Thecattrs version dependency was updated to allow>=1.1.0 on Python 3.8 or higher. (#4821)

Bug Fixes

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

• Fix an issue where queuing InputEvents overwrote data from previous events in the same frame.