Custom Scenario Configurations

HoloOcean worlds are meant to be configurable by changing out the scenario (see Scenarios). There are some scenarios included with HoloOcean packages distributed as .json files, but HoloOcean is intended to be used with user-created scenarios as well.

These can be created using a dictionary in a Python script or by creating a .json file. Both methods follow the same format, see Scenario File Format

Using a Dictionary for a Scenario Config

Create a dictionary in Python that matches the structure specified in Scenario File Format, and pass it in to holoocean.make().


import holoocean

cfg = {
    "name": "test_rgb_camera",
    "world": "SimpleUnderwater",
    "package_name": "Ocean",
    "main_agent": "auv0",
    "ticks_per_sec": 60,
    "agents": [
            "agent_name": "auv0",
            "agent_type": "HoveringAUV",
            "sensors": [
                    "sensor_type": "RGBCamera",
                    "socket": "CameraSocket",
                    "configuration": {
                        "CaptureWidth": 512,
                        "CaptureHeight": 512
            "control_scheme": 0,
            "location": [0, 0, -10]

with holoocean.make(scenario_cfg=cfg) as env:
    for _ in range(200):

Using a .json file for a Scenario Config

You can specify a custom scenario by creating a .json file that follows the format given in Scenario File Format and either:

  1. Placing it in HoloOcean’s scenario search path

  2. Loading it yourself and parsing it into a dictionary, and then using that dictionary as described in Using a Dictionary for a Scenario Config

HoloOcean’s Scenario Search Path

When you give a scenario name to holoocean.make(), HoloOcean will search look each package folder (see Package Installation Location) until it finds a .json file that matches the scenario name.

So, you can place your custom scenario .json files in that folder and HoloOcean will automatically find and use it.


If you remove and re-install a package, HoloOcean will clear the contents of that folder