← Back to Dojo|Architecture Reference

Trainable Entities & SensorSuite

In Dojo V2, the training model shifts from omniscient global state wrappers to completely isolated, sensor-first **Trainable Entities**. This page details the architectural implementation, memory footprint, and physical constraints of our entity model.

Sensor-First Isolation

Traditional reinforcement learning environments allow policies to query arbitrary simulator state (e.g. precise floating-point positions of external objects relative to the world frame). This omniscient coupling guarantees a sim-to-real failure.

Dojo V2 deprecates legacy global observation structures. Instead, **Entities** explicitly own their sensors, brains, and memory. The training pipeline can only feed policies with data compiled by an active SensorSuite pipeline.

Snippet: Isolated SensorSuite Registry

class TrainableEntity(DojoEntity):
    def __init__(self, config: EntityConfig):
        super().__init__(config)
        self.sensor_suite = SensorSuite([
            IMUSensor(pin_channel=0, sample_rate_hz=200),
            JointEncoderSensor(joints=[0, 1], noise_level_rad=0.002),
            CameraSensor(resolution=(224, 224), channels=3)
        ])
        self.brain = SACMLPBrain(
            observation_space=self.sensor_suite.space,
            action_space=config.action_space
        )
        
    def step(self, state: WorldState) -> Action:
        # Entity is restricted to localized sensor observations
        local_obs = self.sensor_suite.read(state)
        return self.brain.decide(local_obs)

Physical Geometries & URDF Registry

Physical hardware is registered in Dojo via URDF (Unified Robot Description Format) parsing. Because Dojo targets highly optimized parallel simulation, the parser is engineered strictly for speed and collision density.

Supported Geometries

The Dojo backend compiler and accelerated parser actively support:

  • Box: kontact-optimized bounding boxes.
  • Cylinder: Contiguous joint and wheel contact sweeps.
  • Tilemap: Grid-aligned terrain maps.

Missing parser support

The following geometries are intentionally bypassed by the parser and frontend renderer:

  • Sphere: Requires contact manifold approximations.
  • Capsule & Complex Mesh: Bypassed in the parser to avoid compute overhead on physical hardware models.

Note: If physical models contain custom sphere or capsule shapes, they must be represented as Box or Cylinder approximations to be correctly compiled by the Dojo engine.

Decoupled Memory Layout

To prevent OS paging limits and thread-blocking locks from slowing down GPU matrix operations, each entity holds its state in contiguous physical buffers. This allows the Vectorized Cluster Buffer (VCB) to read entity transitions in parallel streams via PCIe Direct Memory Access (DMA), avoiding costly serialization layers.