Builder

Use the Builder application to create new simulation scenarios. A scenario is composed of a road network and traffic demand for a rectangular area on the map.

The Builder offers three ways to create a scenario:

• create a custom scenario with the web wizard,
• create a scenario from a catalog template, or
• upload a custom scenario from a zip archive.

Everyone can use the web wizard and browse the template catalog. Uploading a zip archive and creating a scenario from a template depend only on the plan, not on whether you are registered: guests use the Starter plan, which includes neither, while the Basic and Premium plans of registered users include both. Every completed path creates an ordinary scenario in the Workspace.

Upload custom scenario from zip archive

Choose a SUMO zip archive, review its name and simulation settings, and start the upload. The archive may contain the scenario files directly or inside one root folder. It must contain exactly one .sumocfg file and only supported scenario files. SESAM validates and prepares the archive in the background before the scenario appears in the Workspace.

The maximum file size depends on the current plan. Each upload consumes one creation from the shared rolling 24-hour scenario-creation quota, together with custom builds and template copies.

Create a scenario from a template

The catalog shows each template's description, source and geographic extent. Select a template, enter a name and optionally a comment, project and duration, then create your copy. The duration defaults to the lower of the template duration and your plan's maximum. You can shorten it, but cannot extend it beyond that limit. The template's network area stays unchanged and does not use the map Builder's area limit.

Creating a copy uses one scenario creation from the shared rolling 24-hour quota. Once ready, it appears in your Workspace as an ordinary scenario: you can edit, simulate, duplicate, export or delete it according to your plan. The source template remains unchanged. Later template updates, removal or a plan downgrade do not change the copy's duration or files.

Create custom scenario

The builder is organized into a full-screen map with the scenario options floating over its right side as cards, and a toolbar at the top with a hint for the current step and the Build button. Each card has an icon, a title and a short description. Click a card's header to collapse or expand it; several cards can be open at the same time. Scenario properties, Area selection and Random traffic are open when the page loads, Traffic flows and Advanced properties are collapsed. On narrow screens the cards are stacked below the map.

Map

Navigate to the area of interest by dragging the map, using the zoom controls, jumping to your current location, or by searching. The current cursor coordinates are shown at the bottom left, above the map scale.

Searching

Click the search button in the top-left corner of the map to open the search dialog. You can enter a place name (resolved via OpenStreetMap) or a coordinate pair such as 52.517, 13.38. A list of matching results is shown; selecting an entry centers the map on that location.

Using your current location

The geolocate control of the map asks the browser for your current location and, if granted, recenters the map and marks your approximate position with a blue dot. The map controls (zoom, compass, fullscreen and your location) sit at the top left, below the search button.

Scenario properties

The Scenario properties card is the first step. It holds the scenario name, the location where the scenario is saved (the workspace or one of your projects, only if your plan supports projects), the duration as hours and minutes and an optional comment. Click Add comment to show the comment field.

The maximum allowed duration depends on your plan; a notice in the card header shows the limit when the duration exceeds it.

Scenario name

As soon as an area is selected, the magic wand button next to the name field is enabled. Hovering it shows a name suggestion based on the road network around the center of the selected area; clicking it applies the suggestion.

Area selection

An area selection is required to create a custom scenario. Click Start rectangle selection in the Area selection card and then click and drag on the map to draw a rectangle.

Once a rectangle exists:

• It can be resized by dragging any of the four corner handles.
• It can be moved by clicking and dragging the marker inside the rectangle.
• The current width and height of the selection are displayed directly on the rectangle as a live readout, and the coordinate of each side is shown in the middle of that side.
• The card shows the size and the bounding coordinates (north, south, east, west) of the selection.
• The selection can be cleared with Remove or by pressing Esc.

The maximum allowed side length depends on your plan. If the rectangle would exceed that limit, a notice in the card header shows the current maximum and a hint to upgrade the plan.

Opening the Builder with an area

A link to the Builder can contain an area, for example one that your MCP assistant found for a street intersection. The area is already selected when the page opens, exactly as if you had drawn it, and you can still move or resize it. Nothing is built until you click Build. If the area in the link is invalid or larger than your plan allows, the Builder says so and you select the area yourself.

Random traffic

The Random traffic card controls background traffic that is generated automatically to populate the network. It lists the six main vehicle types (cars, trucks, buses, motorcycles, bicycles and pedestrians); More reveals trams, urban trains, trains and ships. Each vehicle type supports the presets Off, Low, Normal, High, or Custom. Selecting Custom reveals two input fields that start with the values of the Normal preset:

• Through Traffic Factor (TTF)¹
• Vehicle Count²

The information button after the card description opens a dialog that explains both values and lists the values of the presets. The Normal preset follows the defaults of the SUMO OSM Web Wizard.

The header of the Random traffic card shows the icons of the vehicle types that currently contribute traffic, so you can see at a glance which kinds of vehicles will be present.

If Car-only network is enabled in Advanced properties (see below), the vehicle types that the imported network cannot serve are greyed out.

Traffic flows

Beyond background traffic you can define explicit traffic flows between two locations. Use the dashed Add flow entry below the list in the Traffic flows card to create a flow. There is no fixed limit on the number of flows; every flow is routed separately, so a scenario with many flows takes longer to build. The header of the card shows one color dot per flow.

Each flow is a compact row with its color, name, vehicle type and rate. A click on the row opens the fields of the flow:

• A flow name (defaults to Flow 1, Flow 2, ...).
• A color used both as the accent color of the flow and as the line color on the map.
• A vehicle type, currently one of: Car (passenger), Taxi, Delivery, Electric vehicle, Bicycle, Motorcycle, Bus, Truck.
• Vehicles per hour as the flow rate. The width of the flow line on the map scales with this value.
• A delete button to remove the flow.

Each flow has a begin marker (green) and an end marker (red) on the map that can be dragged independently. Dragging the line itself moves both markers together while keeping the flow's geometry. Hovering a flow line shows the flow name as a tooltip.

The flow will start on the edge closest to the green marker and end on the edge closest to the red marker.

Warning

Flows must lie inside the selected area. A flow with a marker outside the selection gets a warning marker on its row and a hint appears below the list. At build time such flows are cropped to the selected area if possible, or otherwise discarded.

The straight line between begin and end markers is only a visualization aid for selection and dragging. The actual route is computed during the scenario build.

Advanced properties

The Advanced properties card covers what is imported and how traffic drives. Every option has a short explanation in the card.

• Import polygons: Imports building shapes and points of interest from OpenStreetMap into the scenario.
• Import public transport: Imports public transport routes and stops from OpenStreetMap.
• Car-only network: Imports only roads usable by passenger vehicles. This significantly reduces complexity and speeds up the simulation. When enabling this option, a confirmation dialog lists the vehicle types (bicycles, pedestrians, trams, urban trains, trains, ships) that will be switched off in Random traffic.
• Handedness of road traffic: Selects left-hand or right-hand traffic for the scenario.

Starting the build

The Build button at the top right is enabled as soon as:

• an area is selected,
• a scenario name is provided in the scenario properties, and
• the duration is within the limits of the current plan.

The hint in the middle of the toolbar tells you the next step. When your plan's 24-hour limit for scenario creations is reached, a notice appears at the top of the cards and the button shows a lock and stays disabled.

Background traffic and traffic flows are optional; it is possible to create a custom scenario with no traffic at all.

When you click Build, the builder switches to a results page that shows the live build status.

• A spinner with the current state (Processing) is shown while the scenario is being created. The log section updates as the backend reports progress.
• On success, the spinner turns into a green check mark and quick action buttons are offered to Open the scenario in the workspace, Edit it in the editor, Download the result as a zip archive, or directly Run simulation in the simulator.
• On failure, the spinner turns into a red error icon, the log section opens automatically and shows the error message produced by the build.

If your plan limits the number of scenario creations (Builder, templates and ZIP uploads share one limit) per 24 hours and the limit is reached, the builder shows an upgrade prompt instead of the build button. The limit is a rolling window covering the last 24 hours, not a calendar day: a creation counts again 24 hours after it was started. A creation that fails does not count. The current numbers are shown under Monitor Usage in your account (guests find them in the About dialog).

If the form contains validation errors when Build is clicked, a Builder Errors dialog lists the problematic fields so they can be corrected and the build can be retried.

Once the build succeeds, the new scenario is available in the Workspace.

---

1. The Through Traffic Factor (TTF) defines how much more likely it is for an edge on the boundary of the scenario to be chosen as the depart or arrival edge for a random trip compared to an edge located entirely inside the simulation area. ↩

2. The Vehicle Count parameter defines how many trips are generated per hour and per lane-kilometer for the corresponding category. ↩