Implementation:Google deepmind Dm control Composer Arena
| Attribute | Value |
|---|---|
| Implementation | Composer Arena |
| Workflow | Composer_Environment_Building |
| Domain | Reinforcement_Learning, Composition |
| Source | dm_control |
| Last Updated | 2026-02-15 00:00 GMT |
Overview
Concrete tool for creating the top-level simulation world (ground plane, lights, global settings) in a dm_control Composer environment through the Arena class.
Description
The Arena class in dm_control.composer.arena extends Entity and serves as the root of the entity hierarchy in a Composer environment. It loads an MJCF XML template (by default the bundled arena.xml) that defines a ground plane, lighting, and global simulation options. Custom arenas can supply an alternative XML path.
The class provides one key convenience method beyond what Entity offers: add_free_entity(entity), which attaches a child entity to the arena's worldbody and adds a freejoint to the resulting frame, giving the child full translational and rotational freedom.
Because Arena is itself an Entity, it participates in the standard Composer lifecycle (callbacks, observables, attachment).
Usage
Instantiate Arena directly for a default flat-ground scene, or subclass it to customize the terrain, lighting, or physics options. Use add_free_entity to place free-moving props and robots into the arena.
Code Reference
| Attribute | Value |
|---|---|
| Source Location | dm_control/composer/arena.py:L26-70
|
| Signature (__init__) | Arena.__init__(self, *args, **kwargs)
|
| Signature (_build) | Arena._build(self, *args, **kwargs) -> None (accepts positional name and xml_path)
|
| Signature (add_free_entity) | Arena.add_free_entity(self, entity) -> mjcf.Frame
|
| Import | from dm_control.composer import arena
|
I/O Contract
Inputs
| Name | Type | Description |
|---|---|---|
name |
str or None | Optional model name; if None, uses the name defined in the MJCF file
|
xml_path |
str or None | Optional path to a custom arena XML file; defaults to the bundled arena.xml
|
entity |
Entity |
(for add_free_entity) The entity to place into the arena with a free joint
|
Outputs
| Name | Type | Description |
|---|---|---|
mjcf_model |
mjcf.RootElement |
The root MJCF model of the arena, containing worldbody, lights, and global settings |
return of add_free_entity |
mjcf.Frame |
The attachment frame of the newly added entity, with a freejoint child
|
Usage Examples
Default arena with a free-moving ball
from dm_control import mjcf
from dm_control.composer import arena as arena_module
from dm_control.composer import entity as entity_module
class Ball(entity_module.Entity):
def _build(self, radius=0.05):
self._model = mjcf.RootElement(model='ball')
body = self._model.worldbody.add('body', name='ball_body')
body.add('geom', type='sphere', size=[radius], rgba=[1, 0, 0, 1])
@property
def mjcf_model(self):
return self._model
# Create arena and add a free ball
my_arena = arena_module.Arena()
ball = Ball(radius=0.1)
frame = my_arena.add_free_entity(ball)
# The ball now has a freejoint and can move freely
physics = mjcf.Physics.from_mjcf_model(my_arena.mjcf_model)
Custom arena from a different XML template
class TableArena(arena_module.Arena):
def _build(self, name='table_arena'):
super()._build(name=name, xml_path='/path/to/table_arena.xml')
# Add a table surface
self.mjcf_model.worldbody.add(
'geom', name='table', type='box',
size=[0.5, 0.5, 0.02], pos=[0, 0, 0.4],
rgba=[0.6, 0.4, 0.2, 1])
table_arena = TableArena()