Make large Subway Builder networks run more smoothly without changing gameplay by default.
I made this mod to put the safe rendering controls I actually wanted in one place: adaptive map resolution, a few careful level-of-detail options, lightweight monitoring, and a benchmark that makes before-and-after testing practical. The normal presets do not change simulation rules, routing, finances, or saves.
- Install and open Railyard.
- Find Subway Builder Performance in the mod browser and install it.
- Launch Subway Builder through Railyard, then enable Performance under Settings > Mods if it is not already enabled.
You can also download the ZIP from GitHub Releases. The ZIP is ready for Railyard and keeps manifest.json and index.js at its root.
- Adjusts only the map canvas resolution when render scaling is enabled.
- Uses conservative adaptive scaling with selectable 30, 45, or 60 FPS targets and a quality floor.
- Can hide a small audited set of distant decorative, arrow, and signal layers.
- Stops its own unnecessary monitoring when nothing needs frame data.
- Includes an FPS overlay, readable diagnostics, and a guided benchmark workflow.
- Restores the original map pixel ratio, layer visibility, listeners, timers, and experimental values when disabled or reloaded.
The mod uses the public Subway Builder Mod API and public MapLibre methods. It does not patch private game code.
| Preset | What it changes |
|---|---|
| Native / Safe | Keeps native map quality and all visual detail. This is the default. |
| Balanced | Targets 45 FPS, can scale to 70%, and hides distant 3D decoration. |
| Maximum Performance | Targets 60 FPS, can scale to 50%, and enables both visual LOD options. |
| Battery Saver | Targets 30 FPS, uses a 70% floor, and reduces this mod's work while unfocused. |
| Custom | Lets you choose the render scale, target, floor, and visual options independently. |
These presets only contain rendering and monitoring choices. They never turn on the gameplay-affecting Experimental settings.
The Performance Benchmark section can run Native / Safe, Balanced, and Maximum Performance one at a time. Each run:
- applies the selected visual preset temporarily;
- warms up for 15 seconds;
- measures for 30 seconds;
- saves the result; and
- restores your previous settings.
Keep the camera, zoom, simulation speed, and open panels the same between runs. The standard benchmark refuses to start while Experimental tuning is enabled, so the comparison stays about normal rendering behavior.
You can copy either a detailed JSON export or a readable report with median FPS, p95 frame time, worst frame time, long frames, environment details, network counts, and comparisons against Native. Repeated runs are aggregated using the median result for each preset. The report uses exact differences and does not invent a percentage claim.
See BENCHMARKS.md for the full methodology and correctness checklist.
v0.4.0 also reduces the mod's own overhead. Frame monitoring now uses bounded numeric buffers instead of allocating objects and shifting arrays every frame. Benchmark samples use a bounded ring buffer, LOD layer matches are cached until the style changes, the overlay updates twice per second, and periodic diagnostics no longer sort the full benchmark capture.
Those are concrete reductions in mod-side work. I am not presenting them as a measured game FPS improvement without a current in-game comparison.
The measurements already in BENCHMARKS.md were taken on Subway Builder 1.4.14 and are kept as historical design evidence. Subway Builder 1.5 and 1.6 made their own substantial performance changes, so current results still need a clean real-game run. No v0.4.0 benchmark values are inferred from unit tests.
Use Copy Diagnostics / Performance Report when something goes wrong or a network performs particularly badly. It produces a readable issue-ready report with:
- game and mod/API version information when available;
- platform, viewport, DPR, map scale, preset, and relevant settings;
- focus, pause, simulation speed, zoom, and safe network counts;
- LOD allowlist coverage, warnings, FPS, p95 frame time, heap data when available, and the current limitation hint; and
- the latest benchmark result when one exists.
The diagnostics report does not include the save name or stable session ID. It only says whether each is available.
- Manifest range: Subway Builder
>=1.4.12 <2.0.0 - Current documented Mod API:
1.0.0 - Settings use scoped mod storage on Subway Builder 1.5+ and the existing namespaced fallback on 1.4.x.
- Hook cleanup uses the unsubscribe support added in Subway Builder 1.6 when it is available.
The LOD allowlists were originally audited against the 1.4.14 map style. If a newer style no longer contains an audited layer, the option fails open, leaves the unknown layer visible, and reports the missing coverage in diagnostics.
The automated suite covers the documented 1.5/1.6 API behavior, but v0.4.0 still needs the current in-game matrix described in BENCHMARKS.md. No current-game values are published yet, and mock results are not treated as compatibility or performance claims.
Subway Builder 1.5+ exposes official game-variable controls. The mod has two separate Experimental options built on them:
- High-speed update batching changes how often game-state, train, and commuter updates are published at fast and ultra-fast speeds. Every simulation tick still runs, but visible updates become chunkier.
- Reduced pathfinding depth lowers the maximum journey transfers by one. This can reduce commute-simulation work, but it can change journey choices and ridership.
Both are clearly labeled, off by default, excluded from the normal presets and standard benchmark, and restored to the captured game defaults when disabled or unloaded.
- The mod is installed but missing in game: launch through Railyard and check Settings > Mods.
- The map looks soft: choose Native / Safe or set Map render scale to 100%.
- An LOD option seems to do nothing: copy diagnostics and check its allowlist coverage. Unknown layers deliberately remain visible.
- A benchmark cancels: keep the game focused and do not change settings during the run.
- Clipboard access is blocked: the mod logs the requested report or link to DevTools as a fallback.
- A problem remains after disabling the mod: reload the game and include the diagnostics report in a bug report so cleanup behavior can be checked.
Bug reports and performance reports are most useful when they include the copied diagnostics and benchmark output. Please use the issue forms so the game version, hardware, settings, and reproduction details do not get lost.
Pull requests are welcome. The short contributing guide explains the setup, architecture, test commands, and the evidence expected for performance changes.
If you use the mod and want to help the project, starring the GitHub repository is an easy way to help other Subway Builder players find it.