Publishing Projects
Railyard does not host mods or maps within the service. Instead, Railyard pulls directly from its registry, which contains the data pointing to all the user-created projects. To add a project to Railyard for people to download and play with, you must first add it to the registry.
Step 1 - Hosting the File#
In order to make a submission to the Railyard registry, you need to first upload the source code and release to GitHub and link it to Railyard. To do this, create a new GitHub repository. The actual contents can contain the source code for your map/mod.
Mod Dependencies
Mods must declare dependencies in their manifest.json (the one shipped inside the mod's download ZIP). The dependencies field is required and must include a subway-builder semver range:
"dependencies": {
"subway-builder": ">=1.0.0",
"some-library": ">=2.0.0"
}Each key is a mod ID from the Railyard registry (or subway-builder for the base game) and the value is a semver range for the minimum required version.
Caution
Versions must be in semantic versioning format. 1.0, abc, version-A, etc. will not work. Your version must be X.Y.Z or vX.Y.Z.
Once you have the repository set up, create a new release. In this release, place ALL the ZIP files containing your various projects (as different release assets). The ZIP files should contain exactly the files that are used for the mods, meaning no nested subfolders.
For maps, use the ZIP that you made using the custom map creation guide.
Important
If you are publishing a mod, you must expose your mod's manifest.json (the same file already inside the ZIP) outside the archive so Railyard can validate it without downloading the full ZIP. Specifically, Railyard checks that the dependencies field is present and includes subway-builder.
- GitHub Releases: Upload
manifest.jsonas a separate release asset alongside the.zipfile. - Custom URL: Provide a Manifest URL in the issue form pointing to the
manifest.jsonfor the current release.
This requirement applies to mods only — maps are exempt.
Step 2 - Submitting to the Registry#
Now that your files are hosted on GitHub, you are ready to make a submission to the registry. Go to the registry's issues page and click on "New Issue". Here, you can create your submission, which will then be reviewed by a Railyard maintainer. Once you have the issue selection screen open, select "Publish New Map" or "Publish New Mod", depending on the type of the project you are trying to submit. The next process will differ a little depending on if you are submitting a map or a mod.
Note
If you want to host multiple projects within a single repository, follow the using custom URL guide for further instructions. This will teach you how to set up your custom Update JSON for Railyard to pull from.
Info
You should likely only need to do this if you are the creator of a large amount of maps. For single maps, GitHub Releases is usually the simpler option. For mods, you likely want to keep each project separate anyways for source code management reasons, so GitHub Releases is also recommended.
Step 3 - Using the Issue Template#
Once you select "Publish New Map", a popup window will appear to input some information about the map. The information should be inputted as follows:
Map ID: A unique identifier for your map in kebab-case. This is the
permanent directory name in the registry and cannot be changed
later. Must be unique across all maps, so if another map of the
same city already exists, use a distinct ID (e.g. london-detailed,
london-mini). Only lowercase letters, numbers, and hyphens allowed.
City Name: The human-readable city name shown in Railyard. This is the title
of the map that people will see when downloading it.
City Code: 2-4 letter IATA/ICAO-style city code used by the game internally.
Must be uppercase letters/numbers. Must not clash with vanilla city
codes or other registered maps. Check existing maps before choosing
a code.
Country Code: ISO 3166-1 alpha-2 country code — two uppercase letters (e.g. US,
GB, CA, DE, JP). Used to group maps by country in Railyard. It is
REQUIRED that you use ISO codes according to this list:
https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes.
Population: Approximate metropolitan area population. Number only, no commas or
separators. Used for display and sorting in Railyard and it doesn't
need to be exact.
Description: A short description of what your map does. This is shown in the map
browser. Mention notable features, coverage area, etc.
## Data Attestation
Provide details about your map's data source, data source quality, and level of detail.
Be honest and transparent in your descriptions and please include the methodology you
used to generate the map's data. See the Data Quality guide for more information
(https://subwaybuildermodded.com/docs/railyard/v0.1/developers/data-quality).
Data Source: Enter the data source used to generate the demand data for your map.
The source name should use common abbreviations like LODES, INSEE,
ONS, etc.
Source Quality: Approximate quality of the data source used for your map. Official
government sources are considered high-quality while raw open-source
data is considered low-quality. If your data source includes OSM, we
will not consider that high-quality data.
Level of Detail: Approximate level of detail of your map. Demand resolution at the
level of census blocks is considered high-detail, while neighborhood/
city resolutions are considered low-detail.
Methodology: Description of how demand data was generated for your map. Please include
any details about overcoming data source limitations or any augmentations
done with real-world data.
## Tagging & Image Preview
Railyard allows users to search for maps based on tags and presents a preview image for
discovery. Please check whichever tags best represent your map. Note that "Location" is
required.
Location: Select the real-world region that your map is located in.
Special Demand: Use these tags only when the map models a meaningful amount of demand
related to the feature.
airports: passenger (non-worker) demand from major airports
entertainment: leisure/tourist demand at stadiums/venues/nightlife
ferries: passenger (non-worker) demand from ferry terminals
hospitals: visitation demand for major medical centers
parks: leisure/tourist demand from large local or national parks
schools: demand from primary/secondary school students
universities: demand from university school students
Gallery: Drag and drop screenshots here, or paste image URLs (one per line). These
will be displayed in the map browser. At least one image of your demand data
is required.
## Source Code Information
Provide information on where your map is hosted so that Railyard will be able to check your
repository for updates and allow users to install the map on demand.
Source URL: URL to your map's source code repository or download page.
Update Type: The method used by Railyard to fetch updates for your map. Most
maps should use GitHub Releases. Use
Custom URL only if you host your own Update JSON file.
GitHub Repo: Required ONLY if using GitHub Releases. The owner/repo path (e.g.
username/sb-raleigh) in plaintext, NOT a URL. The repo must exist,
have at least one release, and the latest release must contain a
.zip asset. Leave blank if you are using Custom URL.
Custom URL: Required ONLY if you selected Custom URL. The full URL to your
self-hosted Update JSON file. The file must follow the Railyard
Update JSON schema. Leave blank if using GitHub Releases. The
guide for using an Update JSON can be found at:
https://subwaybuildermodded.com/docs/railyard/v0.1/developers/using-custom-url.
Data Source and Quality
Railyard requires all map makers to submit the source and quality of their data. This is then used to categorize the data for users looking to download maps. For more detailed information on the specifications of data quality, see Data Quality.
Using the Update JSON
For Custom URL, place a link to your raw Update JSON file. You can paste the raw link directly copied from your repository, however, it is instead recommended to deploy it to GitHub pages and paste that link there. This can help some users who may be rate limited. To deploy to GitHub pages, create a new file located at .github/workflows/deploy-releases.yml. Paste the following into the file:
name: Deploy Update JSON to GitHub Pages
on:
push:
branches: [main]
paths: [releases/**]
workflow_dispatch:
permissions:
pages: write
id-token: write
concurrency:
group: pages
cancel-in-progress: true
jobs:
deploy:
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- uses: actions/checkout@v4
- uses: actions/upload-pages-artifact@v3
with:
path: releases
- id: deployment
uses: actions/deploy-pages@v4This will automatically deploy your Update JSON files to GitHub Pages. Once you do this, put the direct link to your Update JSON file for the corresponding map in the Custom URL field. Now every time you update your map (and your Update JSON file), it will automatically deploy the latest Update JSON file for Railyard to use.
Once you fill out the submission ticket, a Pull Request should automatically be created. A Railyard maintainer will review it and it will be automatically submitted once they do. After that, it will be available on Railyard for everyone to download.
Tip
If you input a field incorrectly, the validation will fail. If this happens, you can edit the message above automatically created by the fields you set earlier. Once you edit that message, send a new comment simply commenting revalidate.