Tutorial: Creating a Freight Car (Basics)

This tutorial describes the steps for building a basic freight car mod for Railroader. You’ll learn how to:

• Create an Asset Pack (mod) using the Asset Development Kit (ADK)
• Add a model to the asset pack
• Build the asset pack
• Use the in-game Definition Editor to define a Car using the model you imported, and set it up to carry freight

Once you’ve built a working car here, the intermediate tutorial continues with decals, renderer groups, and animations.

1. Prerequisites

• You will need a basic understanding of 3D modeling, or at least how to work with 3D models. Basic experience importing models into Unity and managing materials will also be important.
• Install Unity and the Asset Development Kit (ADK).
• Create a model of your chosen freight car. We use Blender, but you can use any 3D modeling tool that exports to a format that Unity can read. We recommend FBX; see Blender Workflow for export settings. If you don’t have a boxcar model, try creating a rectangular prism about 12 x 2 x 2. This can be a stand-in for your boxcar.
• Determine the appropriate AAR car type. For most cases you will use one of these car types, as industries and loads are configured to work with specific car types. For a boxcar, XM is a good choice.
• Decide on a domain and identifier for your car. The domain should relate to your identity, such as your handle or name, and the identifier should describe the car itself. Example: domain railfan4014 and identifier xm-10t-lo-cube.

2. Basic Setup

Create the Pack

• Use the Asset Packs window in the ADK (Railroader > Asset Packs) to create a new pack (mod) to hold your creation. For more detail on this, see Building Asset Packs. Use the domain and identifier you settled on in the last step to give the pack a full identifier: railfan4014/xm-10t-lo-cube. The pack can have the same identifier as the car itself. This pack will be in the ADK Unity project under Assets/AssetPacks.
• Make sure to configure a Storage path under Paths in the toolbar. Click “Save” on the pack to copy it there. You can use this however you like but we think of it as the home of the pack data. Packs are copied into Unity only for editing (“Load from Storage”). This helps keep things tidy if you are working on a number of packs.
• Find your pack directory in the Unity project navigator. It will be empty except for an Info.json file. This is where your domain/identifier are stored, along with author and other information about the pack.

Tip: We recommend creating one asset pack per car, unless you are making a set, such as a set of passenger cars, or a steam locomotive and tender.

Import the Model

• Create a subdirectory inside your asset pack directory called Model and export your FBX file there. We recommend keeping the root directory of the asset pack relatively sparse. Note: Do not export trucks with your model! Trucks are separate assets in Railroader. Your car should be modeled such that Y=0 (in Unity) is the rail head.

Tip: We recommend using LODs wherever possible! If you name your objects with matching prefixes and _LOD0, _LOD1, etc. suffixes, Unity will automatically create an LOD Group on import. You can then tweak the LOD transition points.

Configure Materials

• Configure the materials for your FBX file. Select the FBX file and switch to the Materials tab in the inspector. Click “Extract Materials…” and place them in the Model directory alongside the FBX. Note that these materials are now listed in the section below, on the Materials tab of the FBX.
• Configure the materials themselves: for each one, change its Shader to “Railroader/Standard Car Shader Metallic (Shared)” (or the Specular version, if you prefer specular workflow).
• Assign your textures. The metallic shader takes a base color map, a packed metallic/AO/smoothness map, and a normal map — see Texturing Workflow for how to produce those and what import settings they need.

Build the Prefab

• Create an empty Prefab in the root of the asset pack directory. You can give it whatever name you like, but we recommend using the identifier. In this case, xm-10t-lo-cube. This will be the model identifier later in the process!
• Open the empty prefab you created. From the Model directory, drag the FBX model into the prefab in the Hierarchy panel. Now the prefab contains the model. Railroader loads prefabs as models. Using a prefab lets you add components and other objects to a model without being tied directly to the model itself.
• Ensure that the FBX model is at position (0, 0, 0) in the prefab! It may have a scale of (100, 100, 100) — this is normal for Unity importing Blender FBX files!

3. Add A Collider

We need to define a collider for our car; otherwise the player will be able to pass through the car. Note that the collider is not used for Railroader’s train movement physics.

For a simple test, you can create a new GameObject, zero it (position 0, 0, 0), and add a Box Collider component. Size the box to match the car model.

For a real model you would want to import a separate FBX and add a Mesh Collider component to it. If you do this, disable the Mesh Renderer Unity adds so that the collider isn’t drawn.

For both cases, make sure to set the Layer to Clickable.

The collider is separate from the car mesh because Railroader may disable the car model when it is loaded but not visible, but keep the collider on if for example the player is riding on the car.

4. Build the Pack

Now that you have the prefab configured, Save (Ctrl-S) and close the prefab.

In the Asset Packs window, select your asset pack to open its detail view, then click “Build”. Unity will begin building the pack. The pack will be installed in Documents\Railroader\ModDev!

Watch for errors in the Unity console. If an error occurs during the build the asset pack may not be installed in ModDev.

5. In-Game Definition Editor

• Now that you have the pack built, launch Railroader and click on the “Editor” button on the main menu.
• Once the map loads into Bryson, you will see a window which should include your pack.
• Open the pack and click to create a new Car. Enter the domain/identifier combination you selected earlier. Click Create.

This is the Definition Editor, which edits a file called Definitions.json, which will be written as soon as you click the Save button.

In the Model Identifier field, enter the base name of the prefab, preceded by ./. For example, ./xm-10t-lo-cube. The . is shorthand for “this asset pack”. You could also enter the actual domain of your asset pack, instead. Railroader uses the domain + identifier combination to find the unique model asset to load as the body of the boxcar.

You should see the model appear once you hit enter. If no model appears, double check that the identifier is correct. Otherwise, double check that the asset pack was successfully built into ModDev.

Note that your changes have not been saved yet. We will look at that soon.

6. Car Geometry & Trucks

• Enter the car length in meters into the Car Length field. A 40 foot car is 12.19 meters. As you change the length you will see the car flicker and the coupler positions update. Adjust the length until the couplers are correctly positioned.
• Next, in Truck Identifier, enter rr/truck.aar.50-ton. This is a reasonable default truck to use. Trucks are configured separately from cars, as their own definitions.
• Adjust the Truck Separation field until the trucks are positioned correctly. 9 meters is a good starting point for a 40 foot car.

7. Car Type & Weight

The car looks right at this point, but the game still knows nothing about what it is or what it can carry. Three more fields settle that.

• CarType — enter the AAR car type you chose in step 1: XM for a boxcar. Industries, loads, and styles all match cars by this code, so it decides what work your car can be sent to do.
• WeightEmpty — the car’s light weight, in pounds (the one field here that isn’t metric). A 40 foot boxcar runs around 44500. This is the car’s weight in a consist, and its braking force is scaled from it, so leave this at zero and you get a car that weighs nothing and barely brakes.
• LoadSlots — a freight car needs at least one, or it has nowhere to put cargo. Click the add button on LoadSlots (0 elements) and set MaximumCapacity to 80000, leaving LoadUnits on Pounds. Leave RequiredLoadIdentifier empty so the car accepts any load; set it only for a car built around one load, the way a tank car is.

Don’t skip that last one: the car type prefix is what marks a car as freight, and a freight car with no load slots is reported as an error when your pack loads.

The remaining fields have workable defaults. BasePrice (dollars) is worth setting once you know what your car is worth — a 40 foot boxcar is about 800.

8. Saving & Workflow

The Asset Packs window is designed to support a specific workflow moving asset files between three locations:

ModDev <-> ADK (Assets/AssetPacks) <-> Storage (external)

• ModDev describes the pack’s Documents\Railroader\ModDev directory, packs which are installed for in-game development. These packs have been built into a Unity asset bundle, but the JSON files and other text resources are copied as-is.
• ADK describes packs in the ADK/Unity project. All files are in their “unbuilt” form: JSON, FBX files, etc.
• Storage describes the permanent storage of your pack sources. An offline copy of the files, usually under source control.

In Railroader, click “Save” in the lower right corner of the Definition Editor window. This writes the Definitions.json to the ModDev copy of the pack. To bring that change back into the ADK copy, select your pack in the Asset Packs window: it will show “Live edits”, and the “Text differences” list tells you which files changed and in which direction. Click “Pull” to copy them into the ADK project.

Finally, click “Save” on the pack to copy the files from the Unity ADK project into your Storage location on disk.

Adjusting the model itself works the other way around. Instead of editing in-game, you edit the FBX, materials, or prefab in your ADK project, rebuild the pack into ModDev, and relaunch to see the change.

The Development Loop

Pulling the last few sections together, we recommend the following loop while building an asset pack or mod:

1. Edit sources in the ADK. Make model, material, and prefab changes in the ADK project (Assets/AssetPacks) — the unbuilt source lives here.
2. Build the pack. Click “Build” to compile it into ModDev.
3. Launch and iterate on the definition. In the Definition Editor, adjust your Car and Save, writing Definitions.json into the ModDev copy.
4. Pull. Click “Pull” to bring those definition edits back into your ADK sources.
5. Save. When you’re happy with the result, click “Save” on the pack to store the known-good state in Storage (ideally under version control).
6. Repeat. Model or material changes send you back to step 1; definition-only tweaks can loop through steps 3–4 without rebuilding.

If you are only changing text — Definitions.json or scripts — “Push Text” sends them straight to ModDev without a full rebuild, which is much faster than step 2.

The single rule that keeps this tidy: model, material, and prefab edits flow from ADK to ModDev (rebuild); definition edits flow from ModDev to ADK (Pull). Land each change back in the ADK, then out to Storage, before starting the next round.

This tooling was built to support our own development process, and the loop above mirrors how we build first-party content. Following it keeps your sources, your in-game test build, and your backup in sync as your mod grows.

Next Steps

You now have a working freight car. The intermediate tutorial builds directly on this pack, adding decals, renderer groups (for the style system), and animations.