Map Modding

Railroader’s in-game Editor mode has a Map Editor. You can build a new map from scratch, build a map mod that modifies an existing map, and distribute either as a mod (asset pack).

While the Map Editor will appeal to most players, it’s possible to use Data.rl’s modifyMap. This can be helpful for making more “surgical” edits, or if you want to associate some logic with the edits. See Using Relay to mod map data.

Opening the editor

The Map Editor is part of the Definition Editor: find your map in the list and click Edit Map. If you don’t have a map, create a mod if necessary and then create a new Map definition. You can then edit it.

Only maps in a mod in your ModDev folder can be edited. To change another map, including the base game map, build your own map on top of it; see Building on an existing map.

Capabilities

What you can edit

Track: create, move, delete, rotate, extrude, and dissolve nodes and segments, including switches, turntables, and diamond crossings.
Segment properties: ground/bridge/tunnel structure and bridge material, yard flag, speed limit, priority, and track group. A speed limit of 0 means the railroad speed limit, a company setting that also caps every posted limit.
Operations: areas and their industries (loaders, unloaders, interchanges, team tracks, passenger stops, and the rest), including their track spans.
Props: place any Prop definition from any loaded mod, move it with a transform gizmo, and recolor it where the definition offers colors.
Structures and paths: built-in structures (coaling towers, water towers, diesel fueling stands, and more), rivers and roads.
Terrain: fetch real-world elevation tiles, sculpt height with a brush (raise, lower, flatten, smooth), paint land cover (forest, grass, bushes), and shape terrain with curve, circle, and rectangle masks.
Spawn points: where a new session starts.

Undo and redo span all of it, so Ctrl+Z works across tool boundaries.

What you can’t edit

Signs, mileposts, map icons, and lakes
Milestones and progression data structures
Signals/CTC board
Individual trees and details (grass, plants, rocks), and terrain texture assets. Painting land cover controls where they appear. Custom biomes, trees, vegetation, and terrain textures are not presently supported.
Some scenery objects in the base game map that haven’t been ported to the new data format
Custom prop models: you can place any that are already loaded, but a new 3D asset still has to be built as a bundle in the ADK

We will be looking at how best to address these in future updates. Some map elements, such as trees/details/terrain textures, are sufficiently integrated such that we are not certain how feasible it is to make them moddable. We will reevaluate this as we deliver higher priority map modding features.

Placing props

Place props from the map editor’s create menu. Each placement is saved as an entry in objects in Data/Map.json, with the prop definition in identifier:

"barn": {
  "kind": "Prop",
  "identifier": "mymod/barn",
  "position": [1.0, 2.0, 3.0],
  "styles": { "Renderer.siding": { "color": "#f2efe6" } }
}

styles is optional and overrides the definition’s base styles for this placement.

Prop colors

If the definition has customize-color entries, the inspector shows a Colors section with one row per entry. Selecting several props of the same definition edits them together. Changed colors are saved in the placement’s styles; Reset on a row removes the override.

What the editor saves

Like the Definition Editor, saving in the map editor writes to your mod in ModDev. It saves Data/Map.json, plus Terrain/ for any terrain RIFF tiles you’ve fetched. This mod directory can be distributed as-is, but be sure the dependencies are configured correctly. Terrain RIFF files and JSON files do not need to be built using the ADK. See Terrain Tile Format for the file layout.

A map saved this way exists only in ModDev until you Pull it into the ADK. Pull carries your maps and terrain along with the rest, and Build replaces the ModDev copy with the ADK’s, so pull your in-game work before you build. Build warns you before overwriting anything you haven’t pulled.

A TerrainTileSet definition’s path can be any folder inside your pack, relative to the pack root; it defaults to Terrain. The ADK builds and syncs data files by extension from anywhere under the pack root, so a tile set works wherever you keep it.

Creating a new map

In the Definition Editor, use + New, choose Map, and give it an id. The map is saved to your mod and appears in the new-game map dropdown right away. Click Edit Map on its row to open it.

A new map starts with no terrain. Select Terrain in the outline, click Create Terrain…, enter a latitude, longitude, and radius, and click Create & Fetch. Terrain comes from real-world elevation data, so a map is tied to a real place. Reopen the map with Edit Map to see and edit the new terrain.

Click Save to write your changes. Exiting the Map Editor discards unsaved edits.

Building on an existing map

A Map definition can name other maps as layers, inheriting their content as a base you build on: add track and industries, override properties or positions, or remove things you don’t want. Inherited content shows up in the editor as the base it is, and your own Map.json stores only your changes on top of it.

Layers are set on the Map definition itself, not inside the editing session. Select your map in the Definition Editor and fill in its fields:

mapLayers: the maps to build on, as Map definition identifiers, topmost first. Your own map is always the topmost layer, so these all sit underneath it. List only the maps you build on directly; if one of those is itself layered on something else, that content comes along underneath it. Use the full domain/name form (someone/their-map) since a pack-relative ./name won’t resolve.
terrainTileSets: the matching terrain sources, if you’re inheriting terrain rather than fetching your own. Terrain doesn’t inherit the same way — this is a flat list, so name every tile set you need, including ones belonging to a map you’re layering on. If another mod’s tile set is first in the list, terrain is read-only in the Map Editor: you can’t fetch, paint, or change tiles.

Declare the mods providing those layers as required dependencies — a mapLayers entry that doesn’t resolve to a loaded Map definition fails the map load.

If the same map is reached more than once, because two of your layers both build on it, it still composes once, underneath everything that builds on it.

Conflicting layer orders produce a warning in the Map Editor naming the maps involved. A conflict with your own mapLayers can be resolved by reordering it. A conflict between other maps can’t be reordered, but since your map composes above all layers, it can override the affected content.

A cycle in mapLayers (two maps layered on each other, or a map listing itself) fails the map load.

Using Relay to mod map data

Data.rl’s modifyMap handler can be used to make programmatic modifications to map data. This handler applies a JSON merge patch to the map data before it’s deserialized, so you can add track and industries, or change fields on existing ones, without touching the map itself.

See Data.rl for the API (map.merge and map.modify) and its syntax. Two things worth knowing: modifyMap runs once per mod in dependency order, so a later mod sees an earlier one’s changes; and if you delete a node that a segment still references, that segment is skipped rather than failing the load, with a warning in the message log naming the segment and the missing node.

Map Editor sessions load map data straight from disk with no modifyMap patches applied, so the editor never holds or saves mod-mutated data.

Multiplayer

Editing is single-player and host-only. Playing a custom map in multiplayer works normally as long as every peer has the map mod installed. The host sends its mod list on join; a player missing a required mod, or holding a different version of one, can’t join until they install the matching version. Mods aren’t downloaded automatically.