Implementation:Google deepmind Dm control Composer Entity

Attribute	Value
Implementation	Composer Entity
Workflow	Composer_Environment_Building
Domain	Reinforcement_Learning, Composition
Source	dm_control
Last Updated	2026-02-15 00:00 GMT

Overview

Concrete tool for defining reusable physical objects in dm_control Composer environments through the Entity abstract base class, the Robot specialization, and the define decorator module.

Description

The Entity class in dm_control.composer.entity is the abstract base class for every physical object that participates in a Composer environment. Subclasses must implement two members:

_build(*args, **kwargs) -- called during __init__ to construct or load the MJCF model.
mjcf_model -- an abstract property that returns the root mjcf.RootElement of this entity.

The constructor (Entity.__init__) orchestrates a fixed initialization sequence: it pops an optional observable_options dict from kwargs, calls _build, calls _build_observables, and configures the returned observables with the given options.

The Robot class in dm_control.composer.robot extends Entity by adding a single abstract property actuators that must return the actuator elements of the robot.

The define module provides two decorators:

@define.cached_property -- a thread-safe property that evaluates its getter once per instance and caches the result in the instance dict.
@define.observable -- a subclass of cached_property used inside Observables subclasses to declare observable factory methods.

Usage

Use Entity as the base class for any object you want to place in a Composer scene. Use Robot when the object has actuators that an agent controls. Use @define.cached_property for expensive look-ups that should only be done once, and @define.observable inside an Observables subclass to declare observation channels.

Code Reference

Attribute	Value
Source Location	`dm_control/composer/entity.py:L202-605`, `dm_control/composer/robot.py:L22-33`, `dm_control/composer/define.py:L22-61`
Signature (Entity.__init__)	`Entity.__init__(self, args, *kwargs)`
Signature (_build)	`Entity._build(self, args, *kwargs)` (abstract)
Signature (mjcf_model)	`@property Entity.mjcf_model` (abstract)
Signature (Robot)	`class Robot(entity.Entity, metaclass=abc.ABCMeta)`
Signature (cached_property)	`class cached_property(property): def __init__(self, func, doc=None)`
Signature (observable)	`class observable(cached_property): pass`
Import	`from dm_control.composer import entity, define`, `from dm_control.composer.robot import Robot`

I/O Contract

Inputs

Name	Type	Description
`*args`	Any	Positional arguments forwarded to `_build`
`**kwargs`	Any	Keyword arguments forwarded to `_build`; may include `observable_options`
`observable_options`	dict or None	Optional dict of dicts mapping observable names to configuration options (`update_interval`, `buffer_size`, `delay`, `aggregator`, `corruptor`, `enabled`)

Outputs / Attributes

Name	Type	Description
`mjcf_model`	`mjcf.RootElement`	The MJCF sub-model owned by this entity
`observables`	`Observables`	Container of named observable objects
`parent`	`Entity` or None	The entity to which this entity is attached
`root_body`	`mjcf.Element`	The attachment frame body or worldbody
`actuators`	list of `mjcf.Element`	(Robot only) The actuator elements

Usage Examples

Minimal custom entity

from dm_control import mjcf
from dm_control.composer import entity as entity_module


class Ball(entity_module.Entity):
    """A simple sphere entity."""

    def _build(self, radius=0.05, rgba=(1, 0, 0, 1)):
        self._model = mjcf.RootElement(model='ball')
        body = self._model.worldbody.add('body', name='ball_body')
        body.add('geom', type='sphere', size=[radius], rgba=rgba)

    @property
    def mjcf_model(self):
        return self._model

Robot subclass with actuators

from dm_control import mjcf
from dm_control.composer import robot as robot_module


class SimpleArm(robot_module.Robot):
    """A two-joint planar arm."""

    def _build(self):
        self._model = mjcf.from_path('arm.xml')

    @property
    def mjcf_model(self):
        return self._model

    @property
    def actuators(self):
        return self._model.find_all('actuator')

Attaching entities and using cached properties

from dm_control.composer import define


class Gripper(entity_module.Entity):
    def _build(self):
        self._model = mjcf.from_path('gripper.xml')

    @property
    def mjcf_model(self):
        return self._model

    @define.cached_property
    def grip_site(self):
        return self._model.find('site', 'grip_site')


# Attach gripper to arm
arm = SimpleArm()
gripper = Gripper()
arm.attach(gripper)

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment