Environment Builders
====================

DexSuite offers many ways to customize your setup, including different tasks, robots, controllers, and cameras.
 This section shows you three ways to quickly generate the ``ds.make(...)`` code you need to start your environment.

.. list-table::
   :widths: 25 75
   :header-rows: 1

   * - Builder
     - Best For
  * - Manual Build
     - Integration with other projects, ultimate control and customization.
   * - Web Builder
     - Instant code generation in a browser, no terminal needed.
   * - Interactive Builder
     - Guided terminal setup with a reusable JSON spec and optional live runner.

Manual Build
------------

The first way to create your setup is to write the ``ds.make(...)`` function by hand.

.. code-block:: python

   env = ds.make(
       "lift",
       manipulator="franka",
       gripper="robotiq",
       arm_control="osc_pose",
       gripper_control="joint_position",
       render_mode="human",
   )


We will go more in detail with the API in :doc:`../core_concepts/api_overview`.
Setting every parameter by hand can be time consuming, therefore we introduce two ways to simplify environment building.

Web-Based Builder
-----------------

The Web builder is a single, self-contained file that runs entirely in the browser. You can access it in one of two ways:

.. image:: ../_static/web_builder.png

Option 1: Run a Local Server
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You can serve the file locally using Python's built-in HTTP server. Run this command from your terminal:

.. code-block:: bash

   python3 -m http.server -d scripts/interactive_builder/

Once the server is running, open your web browser and navigate to ``http://localhost:8000/env_builder.html`` to access the builder.

Option 2: Open the File Directly
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Since it requires no backend, you can simply open the HTML file directly from your file manager into any browser. Locate the following file:

.. code-block:: text 

   scripts/interactive_builder/env_builder.html

Double-click the file to open it. Configure your environment using the dropdown menus, and copy the generated ``ds.make(...)`` snippet into your script or notebook.



What It Generates
~~~~~~~~~~~~~~~~~

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Parameter
     - Description
   * - Task key
     - The string identifier passed to ``ds.make()``.
   * - Robot configuration
     - Single-arm or bimanual, manipulator model, and gripper model.
   * - Controllers
     - Arm controller mode and gripper controller mode.
   * - Layout preset
     - Workspace layout for bimanual configurations.
   * - Cameras and modalities
     - Camera names and observation types (RGB, depth, segmentation).
   * - Workspace AABB
     - The 3D limits (bounding box) for the selected robot arm, displayed as a visual reference.

Interactive Builder
-------------------

The interactive builder guides you through a setup menu in your terminal and saves your choices in a reusable JSON file.
 It can also launch the simulation immediately after you finish configuring it.

.. image:: ../_static/interactive_builder.png

You can navigate the menus to customize parameters, or simply press Enter to keep the default settings.

.. code-block:: bash

   python -m dexsuite.interactive_builder

By default, the builder:

- Launches a full terminal UI (TUI). If ``curses`` is unavailable, it falls back to a simpler prompt-based UI.
- Writes the completed configuration to ``dexsuite_builder_spec.json``.
- Offers to run the environment immediately using the chosen input device.



Common Workflows
~~~~~~~~~~~~~~~~

Generate a spec file without launching the environment:

.. code-block:: bash

   python -m dexsuite.interactive_builder --no-run --output dexsuite_builder_spec.json

Run an environment from an existing spec file:

.. code-block:: bash

   python -m dexsuite.interactive_builder run \
     --config dexsuite_builder_spec.json \
     --input keyboard

Select a UI mode explicitly:

.. code-block:: bash

   # Full terminal UI
   python -m dexsuite.interactive_builder --ui tui

   # Simple prompt UI (for environments without curses support)
   python -m dexsuite.interactive_builder --ui simple

Supported Input Devices for the Runner
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~



Next Steps
----------

- :doc:`../core_concepts/api_overview` covers the full ``ds.make()`` API and all available parameters.
- :doc:`../core_concepts/cameras_sensors` explains how to configure cameras and sensor modalities.