Decal

A decal projected onto the car surface — road numbers, reporting marks, dimensional data, and images (via the Image content type).

• Kind: Decal
• Availability: Car

Decals carry a real runtime cost

Each decal is a runtime projector with a real performance cost. Decals fade out and are culled on distant cars, and players can adjust how far away that happens with the Decal Distance graphics preference. Image decals are the most expensive kind. Where possible, use a single decal to represent multiple elements.

Due to this performance cost we strongly recommend not using decals as decorative “paint strokes”. Instead, use colorable RendererGroups and the style system to apply uniform color and appearance to a car’s materials. This approach is recommended for steam locomotives with colorable elements (boiler jacketing, cab roof, cab exterior, etc.). It can also be used for whole-car colors, such as for freight cars and diesel locomotives.

For more complex paint schemes, use paint maps, which build upon RendererGroups. We recommend this for diesel locomotives.

See the Freight Cars: Intermediate Features tutorial for the full rationale.

Fields

content

DecalContent = RoadNumber

What the decal displays — either a car or railroad value the game fills in, or Text for lettering a style supplies. See DecalContent below.

contentFlags

DecalDataContent = None

Data plate content flags (when content is Data). These flags are ORed together, letting one decal display several data fields. See DecalDataContent below.

forceColor

string

Deprecated, will be removed. Color to force this to in hex format (e.g. "#FFFFFF"). Use styles on the Car definition instead.

image

AssetReference

Texture asset this decal displays when content is Image. The decal renders this texture directly.

A car style’s image property overrides this per style, the same way uvRect does — so one definition can carry a herald that each style swaps for its own. A style value must be an absolute pack/asset reference: a relative ./ reference in a style resolves against the car’s pack, not the style’s. A Relay script (if attached) can override the texture in turn.

// on the car definition
"herald-right": { "kind": "Decal", "content": "Image", "styleClass": "herald", "image": "./herald-default" }

// in a style
"Decal.herald": { "image": "mypack/herald-panamoils" }

size

float[3] = [2, 1, 0.05]

Decal dimensions [width, height, depth], in meters. The decal is drawn by a projector that projects along its local +Z (blue) axis; its origin sits at the center of this box, so position the component to straddle the car surface.

Keep the depth shallow

A depth (Z) of 0.05 (5 cm) is a reasonable default. Too shallow and the decal may Z-fight; too deep and it bleeds onto faces it shouldn’t touch — a decal has no awareness of the geometry it projects onto and passes straight through to any deeper faces inside the box.

styleClass

string

Style class naming which style rules apply to this decal (e.g. "lettering", "roadNumber"). Space- or comma-separated for more than one class (e.g. "lettering shopDate"), in which case the decal is a member of each. See Styles for more.

Class names may use ASCII letters, digits, - and _; anything else is reported as a warning when the pack loads. See Names Within a Definition.

If null or empty, a default derived from content is used — see the table under DecalContent below. Every style property resolves against whichever class ends up in effect, text included.

text

string

The words to display, for Text content. A style’s text property overrides it, so this is the default a style or the player can replace. Ignored for any other content.

"no-hump": { "kind": "Decal", "content": "Text", "text": "DO NOT HUMP", "size": [1.2, 0.2, 0.05] }

uvRect

string

Sub-rectangle of the image texture to show, for Image content whose image is a sprite atlas. Four space-separated 0-1 fractions, "x y w h", in top-left-origin order (SVG viewBox convention). When set to a real sub-rect, the decal shows only that cell, scaled to its own aspect ratio and centered in the decal box with transparent margins around it. Empty or "0 0 1 1" means the whole image. A car style’s uvRect property can override this per style.

Style Properties

Most of what a decal looks like is not fixed by the definition — it is resolved from the style system at load time, against the decal’s styleClass and its component id. That is what lets one car definition wear a different herald, lettering, or color in every style. These are the properties the game itself resolves for a Decal; see Styles for how selectors, the cascade, and the paint-material color DSL work.

Property	Type	Description
color	string	Decal color — hex or a paint-material function. With no color at all, lettering falls back to a shade that contrasts with the Renderer.body color
text	string	The words to display. Applies to Text content (replacing the component’s own text field) and RailroadName (replacing the railroad name). A Text decal with no text from either source stays hidden
font-size	float	Absolute text size in points, 100 pt to the meter. That measures the em, so capitals come out shorter — 40 pt is about 31 cm of capital height. Unset keeps the template’s fill-to-box auto-sizing
font-family	string	"serif" (the default) or "sans-serif", representing the standard fonts in Railroader. A given font-size gives the same letter height in either
text-align	string	"left", "center" (the default) or "right": where the text sits across the decal’s box, as seen from outside the car. Because text is automatically sized to fit the decal’s box, font-size may be necessary to reliably see left or right alignment
image	string	Source texture for Image content, overriding the component’s own image field. Must be an absolute pack/asset reference
uvRect	string	Sub-rectangle of that texture, for picking one cell out of a sprite atlas: "x y w h", four 0-1 fractions in top-left-origin (SVG viewBox) order. Overrides the component’s own uvRect field. Ignored for non-Image content
offset	string	Positional nudge in meters, "x y [z]" — e.g. nudging a road number along the car side for a style with a wider stripe
offset-space	string	Coordinate frame for offset: "local" (default, the decal’s own rotated frame) or "parent" (the car’s frame)
enabled	bool	Whether the decal exists at all, so a style can drop a stencil another style carries. Unresolved leaves the decal as the definition left it

"styles": {
  "Decal": { "color": "F2F2F2" },
  "Decal.railroadName": { "text": "SOUTHERN", "color": "metallic(#D4AF37, 0.8)" },
  "Decal.herald": { "image": "mypack/heralds", "uvRect": "0 0 0.5 0.5" },
  "Decal.shopDate": { "text": "NEW 6-52", "font-size": 4, "text-align": "left" },
  "Decal.roadNumber": { "font-family": "sans-serif" },
  "Decal#left-number-board": { "offset": "0.02 0" }
}

Enums

DecalContent

Value	Default styleClass	Description
RoadNumber	roadNumber	Car road number
ReportingMark	reportingMark	Railroad reporting mark
RailroadName	railroadName	Full railroad name. A style’s text property can replace it
Data	data	Dimensional/weight data (see contentFlags)
Text	text	Free-form lettering. The decal shows its own text field unless a style’s text property replaces it, and stays hidden when neither supplies any
Image	image	A herald, logo, or other image projected from a texture rather than rendered as text. Its image is supplied by image, a car style’s image property, or a Relay script

Fixed lettering. For words that never change, set text on the decal and you’re done; no styleClass or style rule is needed.

Lettering a style supplies. Text is also how per-style wording — shop dates, build dates, slogans, division names — comes out of a single car definition. The definition places the decal and names its class; each style fills in the words:

"components": {
  "shop-date": {
    "kind": "Decal",
    "content": "Text",
    "styleClass": "shopDate",
    "size": [0.6, 0.25, 0.05]
  }
}

"styles": {
  "Decal.shopDate": { "text": "NEW 6-52", "color": "#E8E8E8" }
}

Styles that set no text on Decal.shopDate simply don’t show the decal, so one definition covers both the styles that carry the stencil and the ones that don’t.

DecalDataContent

Value	Int	Description
DataIdVerticalPlain	2	Vertical ID plate (plain)
DataIdVerticalBar	4	Vertical ID plate (with bar)
DataIdHorizontal	8	Horizontal ID plate
DataCapacityWeight	16	Capacity and weight data
DataDimensionsExt	32	External dimensions
DataDimensionsInt	64	Internal dimensions
DataBuilt	128	Build date