World Builder file formats¶

The Custom World Builder has two outputs, plus the track's waypoints file (.npy).

Output	What you get	Use
Publish	The track files (worlds/models/meshes) on the worlds CDN under a world ID	Install into the simulator by world ID, remix in the builder
Print	A high-resolution top-down `.jpg`	Print a real floor track

There is no file download/upload step: Publish uploads the track under a 32-hex world ID, and the simulator installs it directly from the CDN (the App's world modal or POST /sim/api/worlds/install, both by world ID). Published worlds are immutable — every Publish creates a new world ID (one project can publish many worlds), and only the access level (and name) can be changed afterwards from the Published tab.

Evaluation¶

A world can optionally carry an evaluation (enabled in the builder's right-panel Evaluation section): a config + a Python script that judges student runs. It ships as two files in the world bundle (world name baked into the path, like routes/, so the simulator's generic install loop places them):

evaluations/custom_<world-id>.json — the config document (human-readable):

{ "version": 1,
  "config": { "description": "...", "better": "lower" | "higher",
              "time_limit_s": 180, "robot": "physicar" } }

evaluations/custom_<world-id>.py — the judging script itself, as a plain Python file (def initialize / def evaluate). It never runs in the browser — the simulator runs it in a fresh container for each evaluation (Python 3.14, standard library; file system and internet available).

In the simulator, worlds with an evaluation show a ⚑ button (only when the sim's robot generation matches config.robot). Pressing it places the car behind the start line, runs initialize, launches the student's code (the run command the student enters when starting; its process is killed when the run ends), then calls evaluate(sim) on every observation until sim.finish() or the sim-time limit (exceeding it disqualifies the run). The script sees only the evaluation contract: observations sim.state (time, paused, rtf, pose with roll/pitch, objects, lights, brightness, run, audio — what the robot plays: .playing and the .events since the previous observation, including the played file's bytes and realtime-stream chunks) plus static sim.config / sim.track (with .bounds) / sim.objects (the object catalog) / sim.origins; actions sim.teleport / sim.move_object (both also with duration= or path=, speed=, loop= for continuous motion the simulator carries out) / sim.set_light / sim.overlay(text, secs, size) / sim.set_brightness / sim.pause; verdict sim.record(value) / sim.finish(). Judgment logic (line crossing, off-track, collisions) is written in the script itself — the default template is a complete lap-time evaluation with +5 s penalties. The run is owned by the simulator, so every viewer sees the same run, and result records are stored on the simulator (GET /sim/api/evaluation/record).

Track compatibility¶

The published track files load in the simulator.

Objects¶

3D objects placed in the builder are exported as inline models in the .world file. The model name is the object's Name as set in the editor (editable in the properties card; defaults like box1, cylinder2, signal1; unique, A-Za-z0-9_). Object kind is marked by the SDF link name so tools don't depend on model names:

Object type	Link marker	Notes
Box (`box`)	`object`	Box collision + optional per-face textures. Boxes using the default PhysiCar skin reference the built-in `physicar_box_obstacle` mesh (already present in the simulator) instead of bundling a new mesh — customized boxes ship their own COLLADA + textures.
Cylinder / Sphere (`cylinder`, `sphere`)	`object`	SDF primitive collision + visual, optional face textures (side/top/bottom, surface). Cylinders default to A4 proportions (21 cm tall, 29.7 cm circumference) so a printed side texture rolls into the real thing; spheres default to the built-in soccer-ball skin (references the shared `physicar_ball` mesh; 22 cm diameter).
Traffic Cone (`cone`)	`object`	Square base plate + truncated cone with real traffic-cone proportions (13.5 cm base, 23 cm tall by default). Only the slanted side takes a wrap-around texture — the base and the cut top use the object color. Default look references the built-in `physicar_cone` mesh (orange with a white band); customized cones ship their own COLLADA. No SDF cone primitive exists in Gazebo Classic, so the collision is the bounding box and the `<collision name="cone">` marker tells tools the actual kind (`type: "cone"` in the `objects` reward parameter).
Traffic Light (`light`)	`light`	Parametric device stand (SDF primitives) showing the Remote Traffic Light screen — width and back-tilt are editable and the height/screen/lamps scale proportionally at a fixed 16:9 aspect — midway between a phone and a tablet (default: 18×32 cm at 15°). The exported model's `lamp_red`/`lamp_green` visuals and the `screen` visual (pose + size) are the contract: the simulator recolors the lamps at runtime to display red/green, and during the 3 s yellow transition overlays a bright yellow disc in front of the screen center — mirroring the Remote Traffic Light app (click the light in the viewer for its control panel, or use `/sim/api/traffic_lights`). It takes part in crash detection like any object (`type: "light"`). The legacy `signal` link marker is still recognized when loading older worlds.
Perimeter fence	`wall` (models `wall_0..3`)	Auto-generated collision markers — hitting the fence counts as a crash. The fence visual (part of the racetrack model) is a solid user-set color, 3 cm thick, with a user-set height of 0.2–1 m (default 0.25 m; Wall row in the Objects list).

Every marked object takes part in crash detection. The world's evaluation and automation scripts see the catalog as sim.objects — {name: {type, static, movable, origin, size}} — the published origins as sim.origins, and the live poses as sim.state.objects.

Floor graphics (decals) are not exported as models — they are baked into the track's visual mesh in layer order.

Ground (Field) — the 1 m-tiled ground surface is selectable: built-in presets (Carpet / Grass) or a user-uploaded image (Field row in the Decals list). Preset fields and the standard track textures (road, lines, start line) are not bundled with exports — the COLLADA meshes reference the shared meshes/world_builder/textures/ folder already installed in the simulator. Only a custom-uploaded field image ships with the track (textures/field.png).

Waypoints (`.npy`)¶

Each official/custom track offers a Waypoints download — an (N, 6) NumPy array, one row per point along the track:

[ center_x, center_y, inner_x, inner_y, outer_x, outer_y ]

The scripts' sim.track.waypoints is columns 0 and 1 (the center line); inner and outer are the rest. Download it to analyze a track's shape.