Skip to content
Connected RailsConnected Rails

Route editor

Terminal window
cargo run -p route-editor # example line
cargo run -p route-editor -- line.ron --imagery my_imagery.ron

The line is edited in a flown 3D view over the aerial imagery. The tool palette sits on the left, the selected element’s fields on the right; the middle mouse button pans, the wheel zooms. Every edit goes through undo/redo (Ctrl+Z, Ctrl+Y or Ctrl+Shift+Z), the rule check flags what the compiler will reject, and saving guards against discarding unsaved work.

The palette is grouped by what the work is about — the track itself, what is mounted along it, and the landscape it runs through — and every tool carries a consistent Phosphor icon beside its name. A bar sits above the viewport with the controls that belong to looking rather than to the document: gizmo mode, aerial imagery on or off, the camera speed, and the view point as latitude and longitude — the Train Simulator Classic editor’s coordinate readout. A click on it opens a field that takes a pair of coordinates as a map or a GPS writes them (52.0123, 10.4567) and jumps there on Enter, landing on the ground where the terrain has one. The terrain is always drawn; the imagery is a layer draped over its shape.

Library (the content drawer — Ctrl+Space, the Library button at the left of the status bar, or View ▸ Library): a panel that comes up from the bottom edge with everything the installed mods brought, each entry with the mod it came from. It is the one place that answers whether the editor found a newly installed mod at all; the tool pickers only ever show one kind.

The categories are a column on the left, in the order a line is built, each with how many entries it holds — the count answers “is my mod there” before anything is clicked:

Category What it holds A click
Track types Superstructures to lay track with arms the lay tool with that type
Signal kits The base forms of the signal kits — the usual way to place a signal arms the place-device tool with the naked signal; heads and boards follow in the kit dialog
Signal types Complete signals outside the kits arms the place-device tool with that type and its default model (an earlier model override is dropped)
Signal models Models only arms the place-device tool with that model for the type in hand
Scenery objects Everything beside the track arms the object tool — or drag the card onto the map to place it right there

Hovering a category row says what it is for; hovering a card shows its full name, its key (for most kinds what a .ron writes to refer to it; for a kit base <kit>/<base>), its tags and what a click on it will do. Cards are sorted by name (the kit bases keep the order their kit lists them in) and the title may take two lines, so a family of signals whose names only differ at the end can still be told apart.

Above the cards: a search, where every word has to match somewhere in name, key, mod, system or tags, in any order (exit hv); the mod; the epoch and the operator, read from the epoch-<n> and operator-<name> tags mods give their entries (see modding guide) — an entry that names no epoch passes every epoch filter, so a tree stays in the list whichever epoch is picked; and, for kit bases and signal types, the signal system. Epoch and operator stay set across categories, because a line is built for one epoch, its track and signals and scenery alike. A filter only appears where it can narrow something — or where it is already set, so a list is never cut down by a filter that is out of sight. The count beside them reads n of m while a filter is set, and Reset filters clears them all. Enter in the search picks the first result: type b70, Enter, lay track.

A mod can keep entries out of the list — building blocks, generated variants — with library: (hide: …) in its mod.ron (modding guide). They still load; the count says how many the category hides (“Hidden: 437”), and Show hidden lists them, marked as hidden on the card.

Picking closes the library, because what it armed is used on the map the library covers; dragging an object leaves it open for the next one. When the library opens, the card of what is in hand is scrolled to the middle of the list and wears the accent border; the list holds it there for half a second while the panel settles, and any scroll or click hands it back. If an entry cannot be armed (a kit base whose module is broken), the reason stays above the cards instead of the library closing on nothing. The tools’ own pickers carry a way into the library on the matching category: a library button beside the track type, signal kit and object combos, and a “Pick in the library…” button in the signal type and signal model rows.

Everything that has a model carries a rendered preview of it. The editor renders each one once, off to the side on its own render layer, and reads the picture back off the render target into an ordinary image — a target only holds its contents while an active camera points at it. One at a time, and only for what the drawer is actually drawing, so a catalogue nobody opens costs nothing. The card list is virtualized by row and metadata is reused until its source catalogue changes. Scrolling or closing discards pending offscreen preview requests; at most 128 recently viewed previews retain their image and texture registration. Track types show their colour instead, which is what a track type is.

The viewport is flown the way an Unreal one is: hold the right mouse button to look and fly with WASD (Q/E down and up, Shift slower, the wheel turns the camera speed dial), Alt+left orbits the view point, the middle button pans, F frames the selection. Selecting is a question about pixels: whatever is under the cursor, near or far.

The camera speed dial is Unreal’s in shape: steps that each double the flight speed — twelve of them rather than Unreal’s eight, from 2.5 m/s up to 5 km/s, because a module is tens of kilometres long and the wheel is the one control a flying hand can reach — and a free multiplier of 1 to 128 on top of them. It sits on the viewport bar as the step with a caret, and the same value is under the wheel while the right mouse button is held — one notch, one step, so the speed is set with the hand that is already flying. Shift is the precision modifier and halves the speed, as it does in Unreal: the dial is what makes the camera fast, Shift is for the last metres up to a signal. The speed is metres per second and nothing else: it is deliberately not scaled by how far the view point is away, because a speed that changes underfoot as the builder zooms is a speed they do not control, and controlling it is what the dial is for.

The selection carries a transform gizmo, W for the arrows and E for the rotation ring (the letters are free the moment the right mouse button is let go). Its axes are the fields the item actually has, not world X/Y/Z: dragging the red arrow slides a signal along the track (s), the green one across it (lateral_offset) and the blue one up (height) — so the saved file still reads like a placement. Trees, markers and terrain strokes are free of the track and get east/north instead. There is no scale handle, because nothing in the file format has a scale. A selected track with a free start — a geo-anchored start nothing else is welded to — carries the gizmo too, at that start: the arrows move the whole piece, the ring turns it about its anchor, the way the World Editor’s gizmo moves a selected track piece; a track welded at its start is bent by its support points alone. Every handle answers before it is taken: a support point, a gradient break point or a gizmo arrow under the cursor turns the grab yellow, the pointer becomes a hand, and a label beside the cursor reads out what the handle stands for — the length and radius of the segment a support point ends, the height and the two per mille at a break point.

A module starts as a place, not as a blank sheet. File → New module (Ctrl+N) asks for a name and the module’s anchor — latitude and longitude as fields, and beneath them a small OpenStreetMap map with a place search: type “Göttingen Bahnhof”, pick the hit, click the exact spot, and the coordinates fill themselves in. The dialog also asks what the module portrays — the year and whether it is a rebuild of a real place or invented — and both are written into the module file. Around that anchor the new module gets its first envelope, a square of the initial size the dialog asks for (4 km by default), whose corners are dragged into shape afterwards (see the Envelope tool below, and Modules and compositions). The anchor decides which elevation tiles, which aerial imagery and which neighbours the module will meet, so typing it blind is the one thing worth a dialog.

The tool sidebar on the left uses labelled rows and the bundled Phosphor icon set. Workspaces (track, equipment, landscape, terrain, people, module and aerial imagery) stay visible above the current workspace’s tools. The selected workspace and tool have both a tinted background and an accent edge; keyboard focus has a separate outline. The sidebar can be resized, remembers its width and scrolls on short windows.

Every tool shows its number key on the right. Select belongs to every workspace: 1 always selects, and the workspace’s own tools count from 2. Buttons and shortcuts read the same list. Switching workspaces returns to Select and cancels the current gesture. Tooltips explain how to use each tool. Labelled checkboxes below the tools control radius snap, easements and terrain snap, as applicable to the active tool. The properties panel on the right carries its remaining parameters in the Tool section; these configure the next piece, without changing one already placed.

The navigation follows recognition-over-recall guidance: names stay visible instead of requiring users to decode unfamiliar symbols (Nielsen Norman Group). Rows are 32 logical pixels high, viewport icon buttons are 28 × 28, and focus/selection markers use the existing high-contrast accent. WCAG 2.2 informs the contrast and target-size choices; this is not a claim of full accessibility conformance or a substitute for usability testing with route builders.

Tool What a click does
Every category
1 Select In every category: pick whatever stands on the map and edit its fields; Delete removes it. An overhead line is picked by any of its pylons, anywhere up the mast. A plain click replaces the whole selection, the gathered one included; Ctrl+click gathers devices, objects, parametric buildings, trees, markers and overhead lines into a multi-selection instead (a second Ctrl+click takes one out again); a press on empty ground dragged open selects everything inside the circle — Ctrl adds it to what is gathered, Delete removes the lot in one step
Track
2 Lay track Press and drag sets the standing end and its heading — on an open end it continues that track, on a track’s middle it starts the branch of a turnout (drag along the track = facing, against it = trailing). With a standard turnout chosen in the Tool section (EW 190-1:7.5 … EW 2500-1:26.5, default EW 190-1:9), the first click lays that turnout’s diverging leg to the side of the track the cursor is on, and the leg carries its diverging speed; Free draws the branch as clicked. Every further click appends the arc that leaves the alignment tangentially and hits the point — G1-continuous by construction — or a straight while Ctrl is held; the running end snaps onto open ends and closes the gap with two tangent arcs. Length and radius read out beside the cursor, as the World Editor writes them at the running end, and in the status bar; an arrowhead on the running end shows which way the next piece would leave. Enter or right-click finishes, Esc cancels. The Tool section sets what the piece is laid as: track type, speed, gradient, electrification, parallel tracks at a spacing; the sidebar’s tool options snaps radii onto the standard series, lays easements — a curve then goes down as clothoid – arc – clothoid with the rulebook’s cant for the piece’s speed, ramped over the transitions — and snaps the piece to the terrain: sampled ground heights become its gradient profile, a free start drops onto the surface, an end joined onto other track keeps that track’s height
3 Split track Cuts the track at the click — two tracks on one joint
4 Join ends First click one open end, then another: ends on the same spot are welded into one node, ends apart are staked out like Zusi’s Absteckrechner — transitions, arc and one compensating straight (the radius on automatic grows until exactly one remains), or a double arc with an intermediate straight where no single arc reaches. The Tool section carries the staking parameters: design speed, radius (0 = automatic), transition length, cant, and the least intermediate straight; the transitions themselves are the toolbox’s easement toggle
5 Parallel track Lays the clicked track’s parallel at the set spacing, on the side of the click — exact offsets for straights and arcs
6 Crossover First click cuts the track it leaves, the second names the parallel track it reaches: both are cut and wired into the two turnouts of a crossover: the diverging legs of the chosen standard turnout with a straight on the crossing angle between them, at the turnout’s diverging speed — or, with Free, two arcs of the set radius
7 Gradient Puts a gradient break point on the track; the break points of every track are shown, and one taken hold of is pulled up or down by moving the mouse up or down the screen — the stretches either side change their per mille, every other point keeps its height (the World Editor’s elevation gesture). The selection panel edits the figures and reads out the climb
8 Mark area Press on a track and drag along it: the tool paints a wide coloured stroke over the rails, and that stretch is the area. With an area selected the next stroke joins it. A marked area carries speed, cant, gradient, track type and electrification — set the stretch once instead of editing a step profile per property per track
Lineside equipment
2 Place device Puts the chosen device kind (signal, magnet, LZB, platform, …) on the clicked track
3 Link PZB magnet Click a magnet, then its controlling signal; Escape cancels. The link is drawn as a line between the two
4 Place object Places a mod’s 3D object. A translucent ghost of it stands under the cursor before the click, turned with Ctrl + wheel (15° a notch, 5° with Shift) or by the rotation field of the tool panel. Align to track (toolbox option) measures the object from the nearest track within reach and turns its front along it — on for objects authored with a lateral offset (masts, platforms), off for everything else (cars, pylons, landmarks), and flipped at will; off, the object stands where the click is, its front to the north. The terrain-snap toggle bases an aligned object on the ground instead of the rail plane; a free one always stands on the ground
5 Parametric building Places an editable residential, commercial or industrial building or an open-deck car park. Its properties panel controls dimensions, floors and total height, facade colour/material, six roof shapes with overhang and dormers, windows, shutters and shop fronts, stable night lighting, balconies in the middle or per bay behind railings or coloured panels, a recessed ground floor on columns, a louvre screen, a cross wing and an annex with their own roofs, and plinth, string courses, cornice and corner pilasters, plus parapet, roof house, skylight grid, solar arrays, light band and docked loading gates for halls; twenty-five presets from bungalow to car park fill the fields; Ctrl+C / Ctrl+V preserves the complete recipe
6 Place marker A reference marker in a named layer — a drawing aid, nothing in the simulation reads it
Vegetation
2 / 3 Tree / forest One tree per click, or an outlined area baked into single trees — each one stays editable
4 Field Clicks outline a piece of farmland, Enter or right-click closes it, the crop comes from the tool options. The usual way to get fields is File ▸ Import fields…, which fetches them from the state agricultural registers. Roads, overhead lines, wind turbines and water come the same way from OpenStreetMap (File ▸ Import roads… and so on): a dialog fetches what the module envelope covers, lists it, and adds it on Commit
5 Road Clicks lay the centre line of a road; Enter or right-click finishes it, Esc cancels; the preset decides what it is made of. The usual way to get roads is File ▸ Import roads…
6 Marking brush Sweep to mark trees, objects and parametric buildings in bulk and delete them together
Terrain
2 Raise ground One lifting stroke per click, by the set amount and radius. The track keeps its height, cutting and embankment are laid over the strokes afterwards
3 Lower ground The same stroke downward — a hollow, a pond bed, a pit
4 Flatten Pulls the circle to the ground height under the click — the plateau gesture
5 Level to rail Pulls the ground to the height of the nearest rail — forecourts, depots, level yards
6 DGM tiles Shows the terrain tile grid and picks single tiles of the module’s ground for the height import; without a pick the whole module is imported
7 Terrain tiles Extends the ground: a click attaches the tile under it to the module, a click on an attached tile lets it go. The tiles along the track stay. An attached tile is flat until the DGM import fills it
People
2 Footpath Clicks draw a way people walk up and down; Enter or right-click finishes, Esc cancels. On a drawn way: drag a vertex, click a side of the selected one to add a vertex there, Delete removes the held vertex (or the way)
3 Walk area The same for a polygon people are about on — some wander between spots inside it, the rest stand. The panel sets how many, the share that walks, and the height above the ground
Module
2 Envelope Reshapes the module boundary: drag a corner, a click on a side adds one there, Delete removes the selected one. Everything the module owns has to lie inside it — the landscape strictly, the track up to the boundary itself
Imagery
2 AI area Clicks outline the patch of ground a model is let loose on, Enter or right-click closes it. The other way to say it is a corridor along the track, which needs no gesture — see File ▸ Detect from imagery… below

A turnout no longer needs a tool of its own: laying from the middle of a track is the switch, split and wired on finish, and whether it is faced or trailed is in the first drag. Picking a track type in the library arms the lay tool with it, the browser-first order of the World Editor.

While the track category is up, the map wears the World Editor’s own markings: the spline line over every edge (over aerial imagery the grey rails vanish at height — the line is what keeps the alignment readable), grey squares at rail joints and switches, red squares at loose ends — the thing to continue from or to fix — and, on the selected track, the red/blue direction arrows out of its start and end, which say which way the metre figures of the panel run. While laying or joining, the end the cursor would take turns accent and the join tool’s first pick is filled.

Placement is previewed before it happens: the object and tree tools carry a ghost of the model at the cursor, standing on its track snap with the spec’s own offset and rotation — the World Editor’s loose preview — and every tool that lands on a track (split, parallel, crossover, gradient, area, device, object, and the lay tool before its first press) marks the point on the rail the click would take with the World Editor’s yellow arrow, pointing the running direction; the parallel tool adds a ring where the new track’s centre will lie, on the side of the cursor. The select tool lights the track a click would pick before the click. A double click on anything selectable sends the properties panel to its selection section, and with the gradient tool the map wears slope chevrons: a V every 60 m pointing uphill on every graded stretch. The editor also remembers language, window size and panel width between runs (settings.rs, %APPDATA%\Connected Rails\route-editor.ron), the vehicle editor’s pattern — --window and TRAINSIM_LANG override the stored values for one run.

The viewport bar has labelled Move, Rotate, Imagery and Top-down controls, followed by the live north compass and camera-speed dial. It wraps on narrow viewports. The properties panel closes from its own header; a labelled Properties button restores it from the viewport bar. The File and Edit menus retain their keyboard shortcuts, with Save, Undo and Redo also directly available in the menu bar beside the document name and save state.

The right Properties inspector shows one page at a time: Tool, Selection or Sections. Sections lists the active workspace’s pages (track areas and interlocking for tracks; height data for terrain; boundaries, lighting, checks, imagery and cache for modules). Each page has its own scroll position. For reproducible screenshots, --tool envelope --inspector module opens module boundaries directly; --inspector selection opens the Selection page. Tool changes open the Tool page when the inspector is visible; selection jumps and findings open the requested page. The module name stays editable above the tabs. Detailed tool instructions expand on demand, and the empty Selection page explains how to pick an object. Form controls are at least 28 logical pixels high, and the resize minimum keeps the label and value columns inside the panel.

The status bar prioritises the current operation and the Library action. Its clock button opens preview lighting controls (date and time); Scene details shows coordinates, height, object counts, performance and the document path. Frame rate and rule findings stay visible in the bar, and a truncated status message is available in full on hover.

The Library puts its categories in a labelled column on the left (space::LIBRARY_CATEGORIES, rows with a count badge) and the search, filters and result count in one row above a full-width asset grid — the drawer is wide and low, so the categories sit beside the cards rather than above them. Entries are 224 × 72 logical pixels, with model previews, a title of up to two lines and mod provenance; the armed entry has an accent border. Category and filter changes are applied before constructing the visible cards, so a click always selects the displayed asset with the correct placement tool.

The scene is rendered into the whole window and the panels are drawn on top of it — bevy_egui hangs its context on the same camera, so a camera viewport of its own would squeeze the UI into that rect as well. The camera is therefore shifted sideways instead, by exactly what the panels cover: the pivot sits in the middle of what is visible, and the imagery tiles are fetched around that point rather than around a spot behind the side panel.

T swaps the aerial imagery for the module’s terrain, built exactly as the run builds it — so track types, objects and vegetation can be judged against the ground they sit on. The interlocking (signals, sections, routes), the track areas and the module boundaries are forms of their own, with a ghost of the neighbouring module at the boundary. Every painted area lies on the map in its own colour, all the time — a marking that only shows while it is selected is a marking nobody trusts.

The overlay configuration (imagery.ron) is created on first start and is fully editable: provider, opacity, zoom level or target resolution, load radius, tile limit, image offset against the track position, overlay height, cache (location, budget, memory tiles, offline mode, maximum age) and fetch behaviour (user agent, timeout, concurrency, retries). Changes can be reloaded at runtime with F5 and written back with F2.

Providers are data, not a hard-wired list. Shipped are Esri World Imagery, BKG TopPlusOpen, OpenStreetMap and a WMS template for the orthophotos of the state surveying offices. Your own services are added as an entry — either as a tile template with the placeholders {z} {x} {y} {-y} {s} {key} or as WMS, whose BBOX is formed from the tile in EPSG:3857:

(
id: "dop_nrw",
name: "DOP Nordrhein-Westfalen",
url: Wms(
endpoint: "https://www.wms.nrw.de/geobasis/wms_nw_dop",
layers: "nw_dop_rgb",
version: "1.3.0",
styles: "",
extra: [("TRANSPARENT", "FALSE")],
),
max_zoom: 20,
tile_size: 512,
format: Jpeg,
attribution: "Geobasis NRW",
attribution_url: Some("https://www.geoportal.nrw/nutzungsbedingungen"),
)

attribution is the credit the service requires; attribution_url is optional and turns it into a link to the licence, which OpenStreetMap’s attribution guidelines ask for.

Availability and terms of use of each service must be checked before use; for bulk fetching, put your own access keys into the configuration.

Cache: tiles end up under <cache>/<provider>/<z>/<x>/<y>.<ext>, with an in-memory cache in front of it. Once loaded, the line can be edited offline (L toggles offline mode). Disk space is capped; when the budget is full, the oldest tiles go first. The HUD shows hits, loads, evictions and usage.

Key Function
Right mouse + WASD Q E Look and fly, Shift faster
Middle mouse / wheel Pan the view point / zoom
Alt + left mouse Orbit the view point
F Frame the selection
Ctrl + wheel Turn the placement ghost of the object and tree tools (Shift for finer steps)
W / E Move or rotate handles of the gizmo
1–0 Pick a tool (see the table above)
Ctrl+Space Library (content drawer): everything the installed mods bring
O Aerial imagery on/off — it drapes over the terrain, which is always drawn
P Switch provider
[ ] Opacity
, . Zoom level, Z back to target resolution
Numpad 4/6/8/2 Image offset (with Shift in 5 m steps), 5 to reset
L Offline mode
C / R Clear cache / reset failed attempts
F5 / F2 Load / save configuration

The route editor draws the module under the simulator’s own sky. Its Time of day section sets the date, the clock, the time zone and the cloud cover, and a slider runs a whole day past in one drag — which is how you find out that the platform lies in the shadow of its own canopy all morning. Latitude and longitude are not edited there: they are the module’s anchor, the same pair a run reads, so both programs put the sun over the same hillside. Underneath, the panel reads out where the sun and the moon actually stand. The date and that slider sit in the status bar as well — a calendar behind the date and the sun itself as the handle of the day rail — because the light is judged on the map, not in a panel.