World Builder file formats¶

The Custom World Builder has two outputs, plus a waypoints file available from DeepRacer tracks.

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, DeepRacer training, 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 JavaScript script that scores 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",
              "run_command": "cd /home/physicar/physicar_ws/ && python3 -u run.py" } }

evaluations/custom_<world-id>.js — the scoring script itself, as a plain JS file (initialize / evaluate). Served as text/plain so it can never be executed via a <script> tag — the runner fetches it as text and runs it in a sandboxed Worker.

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 (run_command, editable at start), 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, pose, objects, lights, run, audio) plus static sim.config / sim.track / sim.origins; actions sim.teleport / sim.moveObject / sim.setLight / sim.overlay; verdict sim.result(v) / sim.finish(v?). 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.

Track compatibility¶

The published track files load in physicar-sim and in the DeepRacer training container (which uses an older ROS/Gazebo) — they're exported to be compatible with both.

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 physicar-sim and DeepRacer) 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: physicar-sim 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`). In DeepRacer it participates 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 ends a DeepRacer episode as a crash. The fence visual (part of the racetrack model) is a solid user-set color (Wall row in the Objects list).

In DeepRacer training, every marked object participates in crash detection and is passed to the reward function as the objects parameter — a list of {"name", "x", "y", "z", "heading", "size": [sx, sy, sz], "type"} dicts in the same order as the editor's Objects list (index 0 = bottom). Positions are the world-file poses (static). This is separate from DeepRacer's standard objects_location family, which only covers dynamically spawned obstacles/bot cars.

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 physicar-sim and DeepRacer. 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 reward function's waypoints parameter uses columns 0 and 1 (the center line). Download it to analyze a track's shape or design a reward function.