Every simulation on Ballot runs in one of two modes. You choose when you run ballot sim init, and you can change it in ballot.toml.

Task

Each recorded attempt starts from a clean reset and ends with your environment’s own outcome. Use it for demonstrations of a specific job.

Free play

No success rule. The pilot starts and stops recording. Use it for open-ended exploration or simulations without a task.
A task can be one goal, like lifting a cube, or a sequence of steps. With more than one robot, steps can belong to different pilots: that’s a co-op scenario.

​
How a task attempt works

  1. Practice. The world runs and the pilot can move the robot freely. Practice is never recorded as a task attempt.
  2. Start task. Ballot resets your environment once, using your own reset, and opens a new episode. The pilot can’t move the robot until their headset shows the fresh starting state.
  3. Attempt. Your environment steps normally. Your task’s own code tracks progress.
  4. End. The attempt ends when your task reports success or failure, when its time limit is reached, or when the pilot presses Finish. The episode then saves.

​
Steps

A task can report progress as named steps, in order. Pilots see the steps in the headset, and every episode records when each step completed, so you can find the attempts that got stuck on step three.
  • Your code decides when each step is done, after every control step. Ballot shows and records it.
  • Steps don’t replace the outcome. The attempt succeeds when your task says so, usually when the last step is done.
  • Steps can be skipped or repeated if your task allows it. Ballot records what actually happened.
For a complete robosuite simulation, you don’t need steps: its own success check is the outcome.

​
Team tasks

In a scenario with several seats, each step lists the seats that do it. A shared step, like a humanoid loading a crate onto a rover, needs both robots. The whole team works from one reset and one run, which saves as one team episode. See Create a scenario for a full example.

​
Where the outcome comes from

Ballot never computes its own success check. It reads the one your environment already has, such as robosuite’s success check, and records it as reported. Each episode keeps three things apart, so you can filter on the one you care about: A pilot who presses Finish before succeeding still produces a complete, saved episode. That can be useful data too.

​
Time limits

Benchmark time limits suit scripted runs, not people, who need time to look around and line up a grasp. If your task has a short limit, consider a version with a longer one for piloting. Ballot won’t change your limit behind your back.

​
Resets and randomness

Your reset runs exactly as written, including any randomness, such as a different object position or size each time. Each episode records the actual starting values, so you can see what every pilot faced.

​
Pausing

When a pilot pauses, physics stops and your task’s timers stop with it, as long as they count simulation time. If your task measures wall-clock time instead, pausing can’t be fair, so preparation will ask you to say whether it supports pausing.

​
Free play

In free play, the pilot presses Start recording to capture from the current state without a reset, and Finish to stop. Episodes have no outcome, only an end reason. Restart rebuilds the world from scratch when the pilot wants a fresh start.

​
Tasks built from parts

A task can also be packaged on its own and reused in different worlds. It then declares what it needs, such as “somewhere to start the object” and “a destination”, and you connect those to places in a world. See Build from parts.