Animal-AI

This repository manages the Python interface for the Animal-AI environment.

The main project repository is located here.

• Website: here
• Unity Source code: here
• Python Source code: here
• Bug reports: here

For more information about the ways you can contribute to Animal-AI, visit our website. If you’re unsure where to start or how your skills fit in, reach out! You can ask on GitHub, by opening a new issue or leaving a comment on a relevant issue that is already open.

If you are new to contributing to open source, this guide helps explain why, what, and how to successfully get involved.

Multiple agents

An arena can contain several Agent items (one per agent, each with its own positions, rotations, skins, frozenAgentDelays and optional teams: [N]), plus an optional arena-level episodeEnd: any | all. All agents on a team share one behavior (AnimalAI?team=0 by default) and arrive together in its DecisionSteps, one row per agent:

from animalai.actions import AAIActions, stack_actions

behavior = list(env.behavior_specs.keys())[0]
actions = AAIActions()
decision_steps, terminal_steps = env.get_steps(behavior)
for agent_id, obs in zip(decision_steps.agent_id, env.get_obs_dicts(decision_steps.obs)):
    print(agent_id, obs["health"], obs["position"])
# one action per agent, in the order of decision_steps.agent_id
env.set_actions(behavior, stack_actions([actions.FORWARDS for _ in decision_steps.agent_id]))

Agents in an arena finish their episodes together. The gymnasium wrappers and LLM scaffolds are single-agent and raise an error for multi-agent arenas, and play mode (play=True) supports one agent only. See tests/multiAgent.py for a complete example.

Rays report 18 object types, including other agents (RayCastObjects.AGENT). RayCastParser raises if asked for an object the environment's rays don't report.

Version History

• v6.2.0
  • Downloads Animal-AI build 4.4.0 by default (the first with multi-agent support)
  • Multi-agent support: AnimalAIEnvironment.get_obs_dict(obs, agent_index) and get_obs_dicts(obs), stack_actions, RayCastObjects.AGENT
  • Fixed AAIActions(no_agents=N) building a single discrete row for N > 1
  • RayCastParser raises for objects the environment's rays don't report (previously returned zeros)
  • Gymnasium wrappers and FrameByFrameScaffold give clear errors for multi-agent arenas
• v6.1.3
  • Added UnityToGymnasium and AnimalAIGymnasiumWrapper wrappers
  • Added make_animalai_vec_env / make_animalai_env_fns helpers for vectorised (parallel) environments
  • Added an optional timeout argument to AnimalAIEnvironment
• v6.1.2
  • Fixed the version string for the executable autodownload
  • Misc fixes to the inspect wrapper
• v6.1.1
  • Updated the type hints in the scaffold to be supported by more python versions
• v6.1.0
  • Added automatic binary downloading
  • Added prototype scaffold for LLM integration
• v6.0.0 Note: Version 6.0.0 is not backward compatible with previous versions of Animal-AI due to breaking changes.
  • Minimum Python version is now 3.14.0 (breaking change).
  • Switch the mlagents-envs to our fork mlagents-envs-aai 1.0.0.
• v5.0.1
  • Added new contributor to list of PyPI contributors list.
• v5.0.0 Note: Version 5.0.0 is not backward compatible with previous versions of Animal-AI due to breaking changes.
  • Minimum Python version is now 3.10.0 (<3.10.13) (breaking change).
  • Upgraded to ml-agents-ml-env 1.0.0.
  • Adds no graphics monitor support.
• v4.1.0
  • Updated RaycastParser to accept new object:
    • HollowBox.
  • Added a new low-level random agent implemented on Braitenberg model.
  • Bug fixes and performance improvements, specifically on improving the reliability of the Braitenberg model.
  • Added built-in functionality to run yaml configuration files directly via Python.
• v4.0.1
  • Updated RaycastParser to accept two new objects:
    • DecoyGoal and DecoyGoalBounce.
• v4.0.0 Note: Version 4.0.0 is not backward compatible with previous versions of Animal-AI due to breaking changes.
  • Only implements mlagents 0.30.0 package to avoid dependency issues; also reduces package size considerably.
  • Cleaned up package and removed redundant files.
  • Implemented tests for the package.
  • Added documentation for the package.
• v3.0.5
  • Removed redundant packages in setup.py.
  • Added download stats.
• v3.0.4
  • Added current and past contributors.
  • Added project description and metadata.
• v3.0.3
  • Asserted python version to be 3.6.1 or higher, but less than 3.10.0 (exclusive).
  • Added package description to setup.py and package metadata.
• v3.0.2
  • Fixed major package dependency issues, related to mlagents 0.30.0, protobuf, and shimmy.
  • Updated project setup.py to accommodate the latest version of Animal-AI package dependencies.
    • Users can now use pip install animalai to install latest version of Animal-AI from PyPI effortlessly.