Adding Experiences

To test our system we need some experiences.

Prerequisites

Before creating experiences, you need to configure ReSim to access your experience data. See the Experience Data Sources guide for instructions on setting up access to:

• AWS S3
• Google Cloud Storage
• Foxglove Data Platform
• Local paths in your build container

Experience Locations

Each experience can have multiple locations. In many cases, a single location is sufficient, but it can be helpful to reference common assets, or store MCAPs recorded from different sources in different locations.

ReSim supports the following location prefixes:

Source	Prefix	Example
AWS S3	s3://	s3://my-bucket/experiences/exp_001/
Google Cloud Storage	gs://	gs://my-bucket/experiences/exp_001/
Foxglove	foxglove://	foxglove://rec_abc123def456
Local	None	/experiences/my-scenario/

For cloud storage locations (S3, GCS), each location should have a unique prefix containing the input files. Anything contained in that prefix will be treated as the same experience and downloaded into your tasks. We recommend using a prefix structure that represents your ReSim projects:

📂 .
├── 📂 project_a
│  └── 📂 experiences
│     └── 📂 experience_56ccce99
│        └── ⚙️ test_file
│
└── 📂 project_b
   └── 📂 experiences
      └── 📂 experience_679bef80
         └── ⚙️ test_file

How experience files are accessed

For cloud-based experiences (S3, GCS, Foxglove), files are copied into /tmp/resim/inputs/ when the experience build runs. If you use multiple locations, all files are copied directly into the inputs directory. Take care to ensure there are no file or directory name clashes at the root of the locations.

Avoiding file clashes with multiple locations

If your experience has two locations with the same directory structure:

s3://your-bucket/experience1      s3://your-bucket/experience2
└── mcaps                         └── mcaps
    └── log.mcap                      └── log.mcap

The mcaps/log.mcap file will clash - one will overwrite the other in /tmp/resim/inputs/.

Solution: Change the path or filename to ensure uniqueness. For example, use distinct directory names:

s3://your-bucket/experience1      s3://your-bucket/config
└── mcaps                         └── params.yaml
    └── log.mcap

This results in:

/tmp/resim/inputs/
├── mcaps/
│   └── log.mcap
└── params.yaml

Experience caching is enabled by default, so we only copy files that have been added or changed since the last run.

For local experiences, files remain at their original location and you access them using the path from /tmp/resim/test_config.json. See Local Experiences for details.

Experience Timeouts

Each experience has a timeout. This is the maximum amount of time that a build can run for a given experience. If the build does not finish running before the timeout is reached, it will be sent a SIGTERM and then a SIGKILL after a grace period.

The default timeout is 1 hour, but you can specify a different timeout when creating an experience.

Creating an experience

You can create new experiences like so:

resim experiences create \
    --project "my-project" \
    --name "Experience_56ccce99" \
    --description "In this experience, we test that our robot can navigate to the goal without colliding with any other agents." \
    --locations "s3://my-experiences-bucket/project_hal9000/experiences/experience_56ccce99/" \
    --systems "perception" "localization" \
    --tags "navigation" "collision-avoidance"

This command should return a message containing the UUID of the created experience, and it should now be browsable through the ReSim app.

The --systems flag enables you to specify any systems that this experience is compatible with. You can specify multiple systems by providing multiple system names or IDs.

The --tags flag allows you to apply tags to the experience for better organization and filtering. You can specify multiple tags by providing multiple tag names or IDs.

Optional flags are:

    --timeout "1h10m" # the maximum expected duration of the container \
    --environment-variable "SYSTEM_CONFIGURATION=Foo" # many allowed \
    --environment-variable "AN=other" \
    --profile "left-arm" # a docker compose profile to select the subset of compose services to run \

Examples with different sources

AWS S3:

resim experiences create \
    --project "my-project" \
    --name "S3 Experience" \
    --locations "s3://my-bucket/experiences/exp_001/"

Google Cloud Storage:

resim experiences create \
    --project "my-project" \
    --name "GCS Experience" \
    --locations "gs://my-gcs-bucket/experiences/exp_001/"

Foxglove:

resim experiences create \
    --project "my-project" \
    --name "Foxglove Experience" \
    --locations "foxglove://rec_abc123def456"

Local:

resim experiences create \
    --project "my-project" \
    --name "Local Experience" \
    --locations "/experiences/my-scenario/"

Updating an experience

You can update various aspects of an experience, including its systems and tags:

resim experiences update \
    --project "my-project" \
    --experience "Experience_56ccce99" \
    --name "Updated Experience Name" \
    --description "Updated description" \
    --location "s3://my-experiences-bucket/project_hal9000/experiences/updated_experience/" \
    --timeout "2h" \
    --systems "perception" "planning" \
    --tags "updated-tag" "new-functionality"

When updating systems or tags, the provided lists will replace the existing systems and tags associated with the experience.

You can also add or remove individual systems from an experience:

resim experiences add-system \
    --project "my-project" \
    --system "<system name>" \
    --experience "Experience_56ccce99"

resim experiences remove-system \
    --project "my-project" \
    --system "<system name>" \
    --experience "Experience_56ccce99"

Similarly you can add and remove individual tags:

resim experiences tag \
    --project "my-project" \
    --tag "<tag string>" \
    --experience "Experience_56ccce99"

resim experiences untag \
    --project "my-project" \
    --tag "<tag string>" \
    --experience "Experience_56ccce99"