home / skills / plurigrid / asi / mujoco-scenes

mujoco-scenes skill

safe

This skill helps you generate diverse MuJoCo training scenes by composing terrains, objects, and obstacles for robust robot learning.

npx playbooks add skill plurigrid/asi --skill mujoco-scenes

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

5.0 KB

---
name: mujoco-scenes
description: Package for creating different scenes in MuJoCo. Compose environments with objects, terrains, and obstacles for robot training.
version: 1.0.0
category: robotics-simulation
author: K-Scale Labs
source: kscalelabs/mujoco-scenes
license: MIT
trit: 0
trit_label: ERGODIC
color: "#9FD875"
verified: false
featured: false
---

# MuJoCo Scenes Skill

**Trit**: 0 (ERGODIC - coordination/infrastructure)
**Color**: #9FD875 (Soft Green)
**URI**: skill://mujoco-scenes#9FD875

## Overview

Package for composing MuJoCo scenes with objects, terrains, and obstacles. Enables diverse environment generation for robot training.

## Usage

```python
from mujoco_scenes import SceneBuilder, Terrain, Object

# Build a training scene
scene = SceneBuilder()

# Add terrain
scene.add_terrain(
    Terrain.FLAT,
    size=(10, 10),
    friction=1.0,
)

# Add obstacles
scene.add_object(
    Object.BOX,
    pos=(2, 0, 0.5),
    size=(0.5, 0.5, 0.5),
    color=(1, 0, 0, 1),
)

scene.add_object(
    Object.SPHERE,
    pos=(-1, 2, 0.3),
    radius=0.3,
    mass=0.5,
)

# Add terrain variations
scene.add_terrain(
    Terrain.STAIRS,
    pos=(5, 0, 0),
    step_height=0.15,
    step_count=5,
)

# Export to MJCF
mjcf = scene.to_mjcf()
```

## Terrain Types

```
┌─────────────────────────────────────────────────────────────┐
│                     TERRAIN TYPES                            │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  FLAT        ═══════════════════════════                    │
│                                                              │
│  STAIRS      ┌─┐                                            │
│            ┌─┘ └─┐                                          │
│          ┌─┘     └─┐                                        │
│                                                              │
│  RAMP        ╱╲                                             │
│             ╱  ╲                                            │
│                                                              │
│  ROUGH      ∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿                                │
│  (heightfield)                                               │
│                                                              │
│  GAPS       ═══   ═══   ═══   ═══                           │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

## Domain Randomization

```python
from mujoco_scenes import DomainRandomizer

randomizer = DomainRandomizer(
    terrain_roughness=(0.0, 0.1),
    friction_range=(0.5, 1.5),
    object_position_noise=0.2,
    lighting_variation=True,
)

# Generate randomized scenes
for i in range(100):
    scene = randomizer.generate()
    scene.save(f"scene_{i}.mjcf")
```

## Integration with KSIM

```python
from ksim import RLTask
from mujoco_scenes import SceneBuilder

class WalkingWithObstacles(RLTask):
    def build_scene(self):
        scene = SceneBuilder()
        scene.add_terrain(Terrain.FLAT)
        scene.add_random_obstacles(count=10)
        return scene.to_mjcf()
```

## GF(3) Triads

This skill acts as the **ERGODIC (0)** coordinator:

```
ksim-rl (-1) ⊗ kos-firmware (+1) ⊗ mujoco-scenes (0) = 0 ✓
evla-vla (-1) ⊗ kos-firmware (+1) ⊗ mujoco-scenes (0) = 0 ✓
urdf2mjcf (-1) ⊗ kos-firmware (+1) ⊗ mujoco-scenes (0) = 0 ✓
kbot-humanoid (-1) ⊗ kos-firmware (+1) ⊗ mujoco-scenes (0) = 0 ✓
zeroth-bot (-1) ⊗ kos-firmware (+1) ⊗ mujoco-scenes (0) = 0 ✓
```

## Related Skills

- `ksim-rl` (-1): Uses scenes for training
- `kos-firmware` (+1): Robot firmware
- `urdf2mjcf` (-1): Model conversion
- `kbot-humanoid` (-1): K-Bot robot

## References

```bibtex
@misc{mujocoscenes2024,
  title={MuJoCo Scenes: Environment Composition for Robot Training},
  author={K-Scale Labs},
  year={2024},
  url={https://github.com/kscalelabs/mujoco-scenes}
}
```


## SDF Interleaving

This skill connects to **Software Design for Flexibility** (Hanson & Sussman, 2021):

### Primary Chapter: 1. Flexibility through Abstraction

**Concepts**: combinators, compose, parallel-combine, spread-combine, arity

### GF(3) Balanced Triad

```
mujoco-scenes (○) + SDF.Ch1 (+) + [balancer] (−) = 0
```

**Skill Trit**: 0 (ERGODIC - coordination)

### Secondary Chapters

- Ch5: Evaluation

### Connection Pattern

Combinators compose operations. This skill provides composable abstractions.

Overview

This skill provides a Python package for composing MuJoCo scenes with terrains, objects, and obstacles to accelerate robot training environment creation. It exposes builders and domain-randomization utilities so you can generate deterministic or varied MJCF scenes programmatically. The goal is fast iteration on environment design and repeatable exports to MuJoCo-compatible formats.

How this skill works

You create SceneBuilder instances and add terrain primitives (flat, stairs, ramps, heightfields, gaps) and objects (boxes, spheres, meshes) with configurable properties like size, mass, friction, and color. A DomainRandomizer can sweep parameters such as terrain roughness, friction range, object placement noise, and lighting variation to generate many randomized scenes. Scenes export to MJCF for direct use in MuJoCo or integration into RL frameworks like KSIM.

When to use it

Designing training environments for locomotion, manipulation, or perception tasks.
Rapidly prototyping obstacle layouts and terrain variations before running experiments.
Generating large batches of randomized scenes for domain randomization and sim-to-real transfer.
Composing modular environments that need to be exported as MJCF for MuJoCo pipelines.
Integrating scene generation into evaluation suites or automated curriculum systems.

Best practices

Start with simple flat or ramp terrains to validate robot models before adding complexity.
Use the DomainRandomizer to sample one factor at a time when diagnosing failure modes.
Keep object sizes and masses physically plausible to avoid unrealistic dynamics.
Seed randomizers for reproducibility when comparing policies or ablations.
Layer terrains and objects modularly so individual components can be reused across scenes.

Example use cases

Create a walking-with-obstacles training task that places 10 randomized obstacles on a flat plane.
Generate 100 varied scenes with different friction and roughness to robustify a locomotion policy.
Compose staircases and ramps to test robot stair-climbing and step-negotiation behaviors.
Build rough heightfields and gap patterns to evaluate perception and foot placement strategies.
Export MJCF scenes programmatically to feed into an RL pipeline or a physics benchmark suite.

FAQ

Can scenes be exported for direct use in MuJoCo?

Yes. SceneBuilder exports scenes to MJCF which MuJoCo can load directly.

Does the package support domain randomization?

Yes. DomainRandomizer exposes ranges for terrain roughness, friction, object noise, and lighting to generate batches of varied scenes.