arena-composer¶

A visual editor, headless renderer and MCP server for authoring IsaacLab-Arena YAML environment specs.¶

Search Arena's assets and NVIDIA's SimReady props, and drag one onto the layout. Every entry of the spec is a card in the panel.	The spatial graph: a node per object, an edge per relation. A click opens its card, and the view draws the relation's shape over the layout.

Contents¶

• Highlights
• Commands
• How it works
• Compared with Arena's Agentic Environment Generation
• Install
  • Which Arena it runs on
• Developing
  • The showcase on Artefacts
  • The Isaac Sim comparison on Artefacts
• License

Highlights¶

• Kit-less scene renderer. Arena's solved layouts, drawn live and headless without Isaac Sim; no GPU required.
• CAD-style visual editor for humans. Drag assets in, set the relations between them, and watch Arena's solver place them.
• MCP tools for agents. Search assets, edit the spec, and check the solved layout by its numbers or in pictures.

Commands¶

• arena-view <spec>.yaml opens the visual editor, a window with the layout Arena solves for the spec in 3D, beside a form that edits the spec.
• arena-mcp is an MCP server whose tools search assets, add and remove objects, and describe and render the solved layout.
• arena-render <spec>.yaml... draws the solved layout headless, a PNG per --view: default (perspective), or orthographic top, front and side. It needs no display, and a machine with no GPU draws through Mesa's lavapipe.
• arena-resolve-layout <spec>.yaml prints the solved layout as JSON or text.
• arena-composer new environments/tasks/<name>.yaml starts a spec: a task, and the scene it includes, holding a pick-and-place that validates, solves and builds.

A project that registers its own assets or kinds names the modules that do it with --import MODULE, or in ARENA_COMPOSER_IMPORTS, separated by :.

How it works¶

The YAML is the source of truth: the visual editor, your agent's MCP tools and your text editor all change the same files, and the view follows whichever one did. Edits from the editor and the tools are checked before they are written, Arena's own solver places the objects, and a lightweight Rust renderer draws them, so Isaac Sim never loads.

The guide goes further: how it works, the visual editor and working with an agent.

Compared with Arena's Agentic Environment Generation¶

Arena's Agentic Environment Generation (experimental) works on the same specs, and a spec it generates opens here like any other.

Install¶

A project made from the template needs none of this: its source setup.sh installs a pinned release and runs init. The steps below add arena-composer to an Arena install of your own.

Into the venv Arena is installed in, from PyPI. isaaclab_arena is not on PyPI, so the package goes where Arena already is. Linux x86_64, Python 3.12 or newer.

uv pip install --python <Arena's venv>/bin/python arena-composer

Then point the project's agent clients at the MCP server. init writes bin/arena-mcp and the configs Claude Code, VS Code and Cursor read, keeping any that already exist:

<Arena's venv>/bin/arena-composer init <project>

An MCP client starts the server with almost no environment, so init --import MODULE writes ARENA_COMPOSER_IMPORTS into bin/arena-mcp itself.

init also links the author-arena-spec skill into .agents/skills/ and .claude/skills/. The skill is the procedure an agent follows to write a spec with the MCP tools, through to every sampled layout passing.

Which Arena it runs on¶

arena-composer's main is synced with IsaacLab-Arena's main at dc77564 (2026-10-20), the commit the template pins. Arena's main changes with no new version number, so the install cannot check which one you have.

Developing¶

See AGENTS.md and docs/.

The showcase on Artefacts¶

The showcase builds about twenty environments and draws each from four views. artefacts.yaml runs it as an Artefacts job, so every run checks two ways: an environment that does not build or draw fails its test, and the pictures show at a glance whether the rest still look right.

From this repo's root, with Arena's venv active and this checkout installed in it:

artefacts config add artefacts/arena-composer   # once: the project's API key
artefacts run showcase

The dashboard gets a test per environment and a PNG per environment and view. More in the Artefacts docs.

The Isaac Sim comparison on Artefacts¶

The composer draws a scene without Isaac Sim, so parity/ checks it against Isaac Sim's own renders. A second job in artefacts.yaml builds a handful of specs in Isaac Sim and draws each from the same cameras in both, after moving the composer's scene to where physics left everything. Each camera is a test, which fails when the composer draws further from Isaac Sim than it did before. The dashboard shows the two pictures side by side.

It also needs Isaac Sim in Arena's venv and a GPU that RTX renders on, and its EULA accepted, which nothing here does for you:

OMNI_KIT_ACCEPT_EULA=YES artefacts run parity

How the pictures are scored, and how to record a closer baseline, is in docs/development.md.

License¶

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.