ballot.toml lives at the root of your project. You rarely write it by hand: ballot sim init and ballot package init generate it, and preparation fills in what it can read from your code. It only records the choices Ballot can’t work out for itself.

​
Complete simulation

ballot.toml

​
Top level

​
integer
required
The file format version. Currently 1.
​
string
required
Your project’s name, in the form owner/name.
​
string[]
The files and folders to upload. Anything else in the folder stays on your computer. Use .ballotignore to leave out files inside these paths.

​
[python]

​
string
required
application for a project you run as an app, with one import root. project for a normal installable Python package, which reusable parts use.
​
string
For application mode, the folder your imports start from.
​
string
For project mode, the folder containing pyproject.toml.

​
[runtime]

​
string
required
The runtime profile to run on, such as robosuite-arm-v1. Run ballot sim profiles list to see the options. Preparation pins the exact version it used.

​
[exports.NAME]

An export is something your package offers. A complete simulation has one export, of kind experience.
​
string
required
experience, world, robot or task.
​
string
The function or class to import, as module.path:name.
​
string
task for recorded attempts with an outcome, or free_play.
​
string
native uses your environment’s own success rule, endings and time limit, unchanged.
​
string
The recording profile. native-replay-v1 records everything replay and download need.

​
World part

​
string
required
The framework interface the part is written for, such as robosuite.parts/v1. Parts only combine with parts for the same interface.
​
table
A named spot a task can use. type says what kind of spot it is; the other fields point at real sites, geoms or joints in your model.

​
Robot part

​
string
The robot as the framework names it.
​
string
The attached gripper. Leave it out to use the robot’s default.
​
string
native-default uses the framework’s standard controller for that robot.

​
Task part

The task’s code declares which roles it needs, such as start and destination. Recipes connect those roles to world ports.

​
Recipe

ballot.toml
​
string
required
A part reference: owner/package@version#export.
​
string
Which world port the robot attaches to.
​
table
Which world port fills each role the task needs.

​
Robot package

​
string
required
The robot type: arm, two_arms, mobile_base, legged, humanoid, drone or mobile_manipulator. It decides the VR controls pilots get.
​
string
required
The robot’s MJCF file, relative to the package. A URDF works once its actuators are added.
​
string
required
The function that creates your controller, as module.path:name. Ballot calls its reset at the start of every attempt and its step with the latest commands.
​
string[]
required
The commands your controller accepts: end_effector, gripper, base_velocity, stance, hand_targets, hand_grasp or flight_velocity.
​
number
How often your controller receives commands.
​
table
Upper limits pilots are held to, such as base_speed in m/s or turn_rate in rad/s. Your controller’s own limits always apply as well.

​
Scenario with seats

ballot.toml
​
string
required
The seat’s name, as pilots see it in the lobby.
​
string
required
The robot for this seat: a robot package reference, or a robot your framework names.
​
string
required
The world port where this robot starts.
​
boolean
default:"true"
Whether a run needs a pilot in this seat to start.
​
integer[]
The fewest and most pilots a run can start with.
​
string
default:"hold"
What an empty or disconnected seat’s robot does: hold keeps it still, park returns it to its start.
​
number
How long a run can last before it ends.
​
string or table
default:"equal"
The default split of a team reward: equal, or a weight per seat. A request can set its own.

​
.ballotignore

Uses the same patterns as .gitignore. Anything it matches isn’t uploaded.
.ballotignore