Configuring Locomotives in RLC PT2 - MagnumMacKivler/RLCPT2 GitHub Wiki

So you've just downloaded RLC PT2

And you've figured out that instead of storing all the information in the base chip, RLC PT2 references a locomotive config file and gets the information from there. Unless a bone-stock SD40 is everything you will ever want to model, you're probably thinking, "Can we please get more configs?" We could put more config files in there, but we think it'll be better for everyone if we taught the individual users how to make their own. This will come in handy if you want to make a new locomotive before we get the chance to add a wiki page for it, or if you want to make a fictional locomotive.

We'll start by examining the default RLC PT2 config.

And its associated data sheet!

@name ptgamma/locos/generic/emd_sd40
@inputs 
@outputs 
@persist 
@trigger 
CFG_Version = "2.0.63"
#This file defines what locomotive your RLC PT2 chip will simulate. It is recommended that you save one file for each locomotive you have!
#NOTE: YOU HAVE TO MANUALLY MAKE A NEW FOLDER BEFORE YOU CAN START SAVING E2S INTO IT!!!

#General:

LocomotiveType = "EMD SD40"
    
Horsepower = 3000 #Horsepower Rating; meaningless if there is no prime mover.
Weight = 368000 #Total Locomotive Weight in lb.
Adhesion = 0.25 #Factor of Adhesion.
Axles = 6 #Total Number of Axles.
Motors = 6 #Number of Traction Motors. Anything else is just absurd, really. Meaningless for Cabcars/Snails.
MotorType = 0 #0 for DC, 1 for AC.
MaxGenCurrent = 6000 #How much current the generator/alternator can put out (not the RATED value).
MaxLoad = 1500 #Peak amount of Load current used for starting (How high does the loadmeter go?).
MaxContLoad = 1050 #Maximum amount of Load current the traction motors can take before entering the Short Time zone. Does not impact AC traction motors.
BaseSpeed = 65 #The top speed that's considered "normal" for this locomotive.
TopSpeed = 65 #Top Speed, in Miles per Hour, that the locomotive is capable of reaching due to the gearing. If you don't know, put 65.

#Pick a Prime Mover Config File! You can find them in "ptgamma/engines/" !
#include "ptgamma/engines/EMD_V16_645E3_FuelSaver"
#What Engine should you pick for your locomotive? Google it.

UnitType = 0
#0 - Locomotive
#1 - Slug (No Prime Mover, has Traction Motors
#2 - Snail (No Traction Motors, has Prime Mover
#3 - Cab Car/Control Cab (No Traction Motors or Prime Mover)

#Transition
#                       1st 2nd 3rd 4th
TransitionGroups = array(2,  1         ) #The number of motors in series for each transition notch. Note that this number must divide into the number of motors evenly!
TransitionShunts = array(1,  1      ) #The ratio of current going through the field windings for each transition notch, as a fraction of the total load current.
GeneratorTransition = 0 #If a locomotive has Generator Transition, set this to 1.
LoadRampSpeed = 2 #How fast the engine loads when increasing power. 2 is sluggish, 10 is quick.

#Dynamic Braking Capabilities:

DynamicsMode = 1
#0 - No Dynamic Brakes
#1 - Dynamic Brakes with Mechanically-Driven Traction Motor Blowers
#2 - Dynamic Brakes with Electrically-Driven Traction Motor Blowers
MaxDynLoad = 700 #Maximum (peak) Dynamic Braking load current - If current limited, should be the same as continuous rating.
MaxContDynLoad = 700 #Maximum Continuous Dynamic Braking load current.
BlendedBraking = 0 #Modern Passenger Thing, turns on dynamic brakes when air brake application is made.
DB_Throttle = 0 #Throttle percentage to run the engine at for mechanical blowers. Use 0 for automatic adjustment (mechanical), electrical, or N/A.

#Bonus Features:

TractionMode = 2 #Traction Control Type:
#0 - No Traction Control (Early)
#1 - Automatic Power Reduction (Mid)
#2 - Automatic Power Reduction and Sand (Late)
#3 - Electronic Traction Control (Modern)
DPM = 0 #Dual Prime Movers. Set to 1 if your locomotive has two engines (Like a DDA40X, E unit, or GE 45 Tonner).
HEP = 0 #Head-End Power. Set to 1 if your locomotive is equipped with integrated HEP (like an F40PH or P42DC).
HEP_Subtract = 200 #The Amount of Horsepower to subtract when in HEP mode. GE locomotives use 200, EMD locomotives usually use 700.
HEPTYPE = 0 #0 for 4-8 HEP (Traditional), 1 for 2-4 HEP (For Modern, High-Horsepower Passenger Units like the GE Genesis series).
StarterMode = 0
#0 - Manual Primer, Manual Start
#1 - Latched Primer, Manual Start
#2 - Fully Automatic Start
OverloadProtection = 0 #If 1, the locomotive will reduce power if thermal limits of the traction motors are exceeded.

#Misc:

ClaspBrakes = 0 #Set to 1 if you have trucks fitted with Double Clasp or Triple Clasp brake cylinders.
HeadlightRGB = vec(255,255,200) #What color do you want your MU Headlights to be, if used.
Compressor_CFM = 255.1 #Flow rate of the air compressor when operating at rated speed, in Standard Cubic Feet per Minute
MainResVolume = 35 #Main air reservoir volume in cubic feet.

#End of Config

Most lines in the config correspond to a line in the locomotive's Data Sheet page... However, some don't! We'll break down, line by line, what each one means and does.

The Name

@name ptgamma/locos/generic/emd_sd40

LocomotiveType = "EMD SD40"

These two lines represent the name, I.E. what kind of locomotive the config represents. You are encouraged to put custom configs in their own separate folder. Let's say for example your railroad is called "G-Rail." You may find it helpful to make a folder inside the locos/ folder called "g_rail" and change the name to @name ptgamma/locos/g_rail/emd_sd40.

Note: you have to make the folder manually before you can save files into it! Saving the file without making the folder will say it saved correctly when in reality, it didn't.

The LocomotiveType line represents what is shown on the PT2 chip when it loads the config.

The Basic Stats

Horsepower = 3000

This is simply the locomotive's power rating in British Horsepower. If metric is more your cup of tea, Horsepower = kiloWatts / 0.746. This corresponds to the "Horsepower" entry in the data sheet.

Weight = 368000

This is the locomotive' weight in pounds. Pounds = kilograms x 2.205. Make sure to enter this correctly, because RLC PT2's scale weight system will actually weight the locomotive according to this weight! For a 4-axle locomotive, 240,000 lb is considered light while 290,000 lb is considered heavy. 6-axle locomotives can be as light as 280,000 lb and can go up to 420,000 lb (modern locomotives can be ballasted to nearly 450,000 lb!). This corresponds to the "Weight" entry in the data sheet.

Adhesion = 0.25

This is the factor of adhesion. It's a unitless fraction, and it represents how much of a locomotive's weight it can use for keeping the wheels gripping the rails. Values are typically given in percentages, so you'll have to convert to decimal (25% -> 0.25). Factor of adhesion depends on the truck type, and is almost always lower than advertized; the lowest you can usually get is 25% for old trucks. Trucks that advertise themselves as "High Traction" or "High Adhesion" usually get into the 27% range, radial/self-steering trucks can go to about 30%, and if you throw electronic traction control and AC motors into the mix, adhesion can get up to a staggering 50%! This corresponds to the "Factor of Adhesion" entry in the data sheet.

Axles = 6

This is the number of physical axles the locomotive rides on, unpowered plus powered. This corresponds to the "Axles" entry in the data sheet.

Motors = 6

This is the number of powered axles the locomotive rides on, which is usually also the number of traction motors (GG1s nonwithstanding). This corresponds to the "Traction Motors" entry in the data sheet.

MotorType = 0

This determines whether a locomotive has AC (1) or DC (0) traction motors. AC motors have better performance and can't overheat, but they require large and expensive inverters to control (not a problem in Gmod). This corresponds to the "Traction Motor Type" entry in the data sheet.

MaxGenCurrent = 6000

MaxLoad = 1500

Note: "Load" is synonymous with "Current."

These two are important, but must be explained together. Every locomotive has a generator (DC Generator or Alternator) that provides current for the traction motors. At a dead stop, the generator is supposed to put out at least enough current to completely fill the load meter ("maxing out" the traction motors). However, depending on what the first transition notch is, the current may be distributed in different ways.

MaxLoad is the largest number on the load meter (ammeter), measured in Amperes/Amps. If the locomotive starts in series-parallel, the MaxGenCurrent should be at least 2x the MaxLoad because the current is being evenly split two ways. If the locomotive starts in parallel, the MacGenCurrent should be at least Traction Motor Count x MaxLoad because the current is being evenly split between all the traction motors. If a locomotive starts in series, use the equation for series-parallel so you don't underpower the locomotive in the intermediate transition stages.

These values correspond to the "Generator Max Current" and "Max Traction Motor (TM) Current" entries on the data sheet.

MaxContLoad = 1050

This is the maximum continuous traction motor current, also in Amps. While you can put a higher current through a motor (which is sometimes necessary for starting trains), you can only do that for a finite period of time before the motors begin to overheat, melt, and explode. The max continuous load represents the highest ammeter reading you can hold indefinitely. This corresponds to the "Max Continuous TM Current" entry in the data sheet.

BaseSpeed = 65

TopSpeed = 65

BaseSpeed is the "default" speed that you can get a locomotive geared for, in miles per hour. MPH = Km/h x 0.62.

65 was the standard for a long time, however even as far back as the 1960s, locomotives with higher base speeds began to appear. This corresponds to the "Model Base Speed" value in the data sheet.

TopSpeed is the "geared" speed of a locomotive, also in miles per hour. Locomotives with higher gearing (TopSpeed > BaseSpeed) can attain higher speeds at the cost of some of their pulling power; locomotives with lower gearing (TopSpeed < BaseSpeed) can lug more easily, but can't go as fast. This value is up to the railroad, as builders offered many different gear ratios for many different speeds. As a rule of thumb, freight locomotives usually had top speeds equal to their base speeds.

#include "ptgamma/engines/EMD_V16_645E3_FuelSaver"

This defines another config file that specifies which engine (sound set) the locomotive has. This corresponds to the "Prime Mover" entry on the data sheet, however there are sometimes options. For example, the 645E3 has a number of sound sets that correspond to different low idle/fuel saver setups.

UnitType = 0

The Unit Type represents what the thing you're trying to make is, on a very general level. All actual locomotives (has an engine and traction motors) use 0, while all slugs (traction motors but no engine) use 1. 2 is reserved for "snails" (engine but no traction motors) and 3 is used for cab cars, shoving platforms, or anything that has no engine OR traction motors.

Transition

TransitionGroups = array(2, 1, 1 )

TransitionShunts = array(1, 1, 0.5 )

Transition is an enormous subject that is explained in further detail here. As a simplified explanation, TransitionGroups represents how many traction motors are in series with each other in each transition notch, and TransitionShunts represents what fraction of the current goes through the field windings of the traction motors.

When filling out the TransitionGroups array:

1 always means "Parallel."
2 means two motors in series (2 groups of 2 for a 4-motor locomotive, 3 groups of 2 for a 6-motor locomotive), which is what most manuals call "Series-Parallel."
3 means three motors in series, which only applies to 6-motor locomotives, and is also referred to as "Series-Parallel" (though thankfully, the manuals also usually clarify they mean 2 groups of 3 motors).
4 means all four motors in series (I've never seen a 6-motor locomotive with this transition setup) and is thus called "Series".

The purpose of TransitionShunts is to "bridge the gap" between TransitionGroups changes. The only time TransitionShunts should be anything other than 1 is when you don't rearrange the motors, but you still want another transition step. This can be a continuous value (an advantage) but increases circuit complexity in real life and wastes energy (disadvantages). 1 means full field strength, 0 means no field strength (pointless because it stops the motors from working and probably divides by zero). Sometimes, manuals will give field shunting as a percentage (for example 23% field shunting). To convert that into RLC PT speak, convert it to a decimal (23% -> 0.23) and subtract it from 1 (1 - 0.23 = 0.77). These values correspond to the "Transition Groups" and "Transition Shunts" entries in the data sheet.

So, let's take, as an example, the SD45's transition setup, and see how we'd convert that into PT2-ese.

According to the SD45 doc, the SD45 has six transition steps in Series-Parallel (3 groups of 2 motors) and four more in parallel, making a total of ten transition steps. By following the instructions above, we'd get this for the TransitionGroups array:

TransitionGroups = array(2, 2, 2, 2, 2, 2, 1, 1, 1, 1)

This particular manual very helpfully provides the % field shunting for each transition step. We then calculate the TransitionShunts based on the instructions above (For example 28% field shunting -> 1 - 0.28 = 0.72):

TransitionShunts = array(1, 0.72, 0.56, 0.46, 0.39, 0.34, 1, 0.72, 0.56, 0.46)

Note that the transition shunt goes back to 1 (full strength) when the grouping shifts from series-parallel to parallel.

If there are multiple times the transition groups shunt (say the Array looks like (3,3,3,2,2,2,2,1), then a really-REALLY general, best-guess effort would be to guess shunt values would be the following equation=

Shunt number series = ("n"rd array shunt / Number of Arrays)

Ex. If we look at "TransitionGroups = array(2, 2, 2, 2, 2, 2, 1, 1, 1, 1)", then we can say

(3rd array shunt/ 3 arrays total) = 3/3 = 1 OR (2nd array shunt/ 4 "Series Parallel" arrays total) = 2/4 = .5 Ergo a general would be (1/6, 2/6, 3/6, 4/6, 5/6, 6/6, 1/4, 2/4, 3/4, 4/4). In decimal form, this would be (0.16, 0.3, 0.5, 0.6, 0.83, 1, 0.25, 0.5 ,0.75 , 1)

Dynamic Brakes

DynamicsMode = 1

This defines whether or not a locomotive has dynamic brakes, and how the traction motors are cooled. 0 means no dynamic brakes, 1 means it has dynamic brakes and cools the traction motors via shaft-driven fans, and 2 means it has dynamic brakes but the fans are electrically-driven. The electric vs. mechanical fan drive affects how the engine spools up or down depending on dynamic braking effort (if it does at all). This corresponds to the "Dynamic Braking (DB) Mode (if used)" entry in the data sheet.

MaxDynLoad = 700

This is how much load you can put through the dynamic brake grids, in Amps. For locomotives without automatic current limiting, this can exceed the Maximum Continuous rating (see below), which can cause overheating issues.

MaxContDynLoad = 700

This is how much load you can put through the dynamic brake grids (in Amps) before they overheat and explode, sending the fan flying fifty feet into the air, arcing and zapping like every light fixture in Half-Life. This corresponds to the "DB Max Rated Current" entry in the data sheet.

BlendedBraking = 0

This determines whether or not a locomotive is equipped with blended braking. With blended braking, the engineer sets the air brakes, and the locomotive tries to accomplish as much of the required braking effort as it can using the dynamic brakes. It's a feature just about exclusive to passenger engines from the 1970s onward. This corresponds to the "Blended Braking" entry in the data sheet.

DB_Throttle = 0

This determines how much the engine revs to when dynamic braking is being used, on the RLC PT2 throttle scale from 0-100. If 0, it adjusts automatically. As far as we know, Fairbanks Morse locomotives were the only ones to use this feature, and used 75 percent throttle. All other builders used automatic, so set it to 0. This corresponds to the "Dynamic Braking (DB) Mode (if used)" entry in the data sheet (If no throttle value is given, use 0).

Extras (aka "Bonus Features")

Don't let the name fool you, these can be important.

TractionMode = 2

This defines the level of traction control the locomotive has, which helps stop wheelslip. 0 is for really old locomotives which don't have any form of traction control. 1 is for older locomotives which will reduce power automatically, slowly reigning in wheelslip. 2 is for mid-series locomotives which added automatic sand application to the mix, and 3 for newer locomotives with electronic traction control. This corresponds to the "Traction Control" entry in the data sheet.

DPM = 0

This determines whether or not a locomotive has two prime movers. Unless you start both engines, you'll only have half the amount of tractive effort! Only specific locomotives had two prime movers (some examples include the EMD E series, the GE 44-tonner, the ALCO C-855). This is represented by the "Prime Mover" entry in the data sheet (look for the "Dual").

HEP = 0

This determines whether or not a locomotive has shaft/driven (aka "integrated") HEP (Head-End Power). While any locomotive can have a separate or independent HEP generator (or a steam generator, depending on time period) provided they are for passenger service and have space in the carbody, shaft-driven HEP uses the traction generator as well as a separate HEP generator connected to the crankshaft to power the engine, and thus controls how the engine revs in order to keep the power flowing. This corresponds to the "Head End Power (HEP)" entry in the data sheet.

HEP_Subtract = 0

This represents how much horsepower the shaft-driven HEP generator consumes. You don't get something for nothing! This corresponds to the "HEP Power Consumption" entry in the data sheet.

HEPTYPE = 0

This determines how exactly the engine spools up when using shaft-driven HEP. Lower-power locomotives use mode 0, whereby the engine is required to be in Run 8 in order to power the coaches and move the locomotive, and Run 4 is used for long periods of idling. Higher-power locomotives, such as the GE P42DC, use Run 2 for idling and Run 4 for power, increasing engine speed as necessary. This corresponds to the "HEP Standby/Run Mode" entry in the data sheet.

StarterMode = 0

This determines how the locomotive starter sequence is to be operated. Mode 0 requires you to hold the primer AND the starter until each is ready (Mostly EMD). Mode 1 requires you to hold the starter, but the primer is replaced by a simple fuel pump switch which can be a toggled button that stays on (Everyone but EMD). Mode 2 is for a full automatic start, so you just press the Start button once and sit back and watch it go (Modern locomotives or retrofits). This corresponds to the "Starter Mode" entry in the data sheet.

OverloadProtection = 0

Ths determines whether or not a locomotive has automatic traction motor overload protection, which cuts back power automatically when thermal limits are exceeded. This still allows you to use the short time zone, but prevents you from frying your motors. This corresponds to the "TM Overload Protection" entry in the data sheet.

Misc

ClaspBrakes = 0

This determines whether or not a locomotive has clasp brakes. Clasp brakes give you more locomotive braking effort at the cost of being more expensive to maintain. Make sure to use the correct truck bodygroups!

HeadlightRGB = vec(255,255,200)

This is the color that RLC PT2 will use for the headlights if dimmable headlights are used.

Compressor_CFM = 255.1

This is the air compressor output rating, in Standard Cubic Feet Per Minute (SCFM, or CFM at atmospheric pressure and 70°F). It depends on the engine speed and the compressor type. This corresponds to the "Compressor CFM" entry in the data sheet.

MainResVolume = 35

The volume of the main reservoirs in cubic feet. Most locomotives have 35 ft³ of capacity. This corresponds to the "Main Reservoir Volume" entry in the data sheet.

And that's it!

There's a lot to keep track of, but you should get more familiar with what the variables do as time goes on and you get experience making configs!