CarStyle

A paint scheme that can be applied to cars. See Styles for details on the style system, and Standard Classes for the class names a scheme can rely on across packs.

• Kind: CarStyle
• Extends: ObjectDefinition

Fields

carIdentifiers

string[] = null

Restricts this style to specific car definition identifiers (e.g. ["myhandle/gp7"]), bypassing carTypeFilter entirely. Use this when a style depends on car-specific geometry, like a herald control texture sized for one model, rather than being paintable onto any car of a given type.

carSeries

Dictionary<string, CarSeries> = null

Road number series this scheme keeps, keyed by reporting mark. See CarSeries below.

carTypeFilter

string = null

AAR car type codes this applies to. null = any.

name

string

Display name (e.g. "Southern Railway Green").

reportingMark

string = null

Comma-separated reporting marks this scheme letters (e.g. "SOU,SR"), or "*" for any declared road willing to letter the car. A car is only ever painted in a scheme that admits its mark. See Car Spawn Identity below for how a mark and a scheme are chosen together.

styles

object = {}

Map of style class selectors to property values.

CarSeries

An entry in carSeries. Each key is a reporting mark; the value is the road number block that road’s cars are numbered in when spawned in this scheme.

start

string

The road number the series counts up from, e.g. "20" or, for a road that letters cabooses and work equipment with a letter prefix, "X100".

end

string = null

The last road number of the series, inclusive — { "start": "20", "end": "99" } is an eighty-car block, not a hundred-and-nineteen-car one. It must wear the same letters as start, so "X100" pairs with "X199". Omit it and the series has no upper bound.

Numbering inside a block

With end set, cars are numbered within the block and spread across it rather than counting up from start, which is what a real number block looks like once its cars are scattered over the map. The number a given car draws is derived from the car itself, so it is the same every time that car is spawned from the same save.

If every number in the block is on a car that is on the map at once, the next car takes the first free number above end instead of failing to spawn — real fleets are never exhausted, because most of the fleet is somewhere else. A warning naming the series is written to the log when that happens. Size a block for the traffic you expect rather than for the prototype’s exact roster.

Road numbers are unique per reporting mark, not per series. Two schemes lettering SHPX draw from one pool, so give each its own block — overlapping blocks contend, and can push each other above their declared end sooner than either author would expect.

Car Spawn Identity

A car’s reporting mark, paint scheme, and road number are chosen together, so the card and the lettering never disagree. When a car spawns:

1. The game collects every (scheme, road) pair that’s actually possible: each style eligible for the car (by carTypeFilter/carIdentifiers), crossed with the roads its reportingMark admits — the roads it names, or, if it’s "*", every declared road that letters this car’s type. A car whose definition sets requiresDedicatedStyles contributes only the schemes that name it in carIdentifiers.
2. It draws the road from that list, so a road’s odds are proportional to how many eligible schemes can letter it: a road several schemes can dress is drawn more often than one only a single scheme can.
3. It then picks the scheme from among that road’s pairs. A scheme that names the road outright beats one that letters "*", so a road with its own scheme always wears it, and a wildcard scheme is used only for roads no scheme names.
4. The car is numbered from that scheme’s carSeries entry for the chosen road, if one exists — inside the block when that entry sets an end — otherwise it falls back to the car definition’s own baseRoadNumber.

The player’s own road is never drawn this way — it isn’t foreign traffic.

Two schemes can letter the same road without conflict — a shared boxcar scheme worn by six roads is one scheme with six roads in reportingMark, one dictionary entry per road in carSeries. And two schemes can letter the same road with different numbers, which is how a single road ends up with more than one series: give each scheme its own carSeries entry for that mark.

For example, Pan Am Oils and Shippers Car Line paint the same fleet of tank cars, both lettered SHPX, but each keeps its own numbers:

{ "identifier": "acme/style.panam", "metadata": { "name": "Pan Am Oils" },
  "definition": {
    "kind": "CarStyle",
    "reportingMark": "SHPX",
    "carSeries": { "SHPX": { "start": "80", "end": "159" } },
    "styles": { "...": "..." }
  }
}

{ "identifier": "acme/style.shipperscarline", "metadata": { "name": "Shippers Car Line" },
  "definition": {
    "kind": "CarStyle",
    "reportingMark": "SHPX",
    "carSeries": { "SHPX": { "start": "20", "end": "79" } },
    "styles": { "...": "..." }
  }
}

Nothing but the paint distinguishes the two batches — draw the Pan Am scheme and the car numbers somewhere in 80–159, draw Shippers Car Line and it numbers somewhere in 20–79. The two blocks don’t overlap, so neither can take a number the other wants.