MSTS Environment Files

Environment files (.env)

MSTS environment files define the visual environment used by a route for a season and weather condition. They describe layered sky geometry, sun and moon sprites, ambient and directional colours, fog, precipitation, wind, and animated water materials. They normally reside under a route's ENVFILES/ directory and refer to ACE assets under ENVFILES/TEXTURES/.

An .env file does not select itself. The route's [[.trk definition|MSTS-Route-Definition]] maps season/weather keys to environment filenames, and an activity supplies initial season and weather selectors. Tile-local water extent and corner heights are stored separately in terrain files.

This first edition is based on 28 environment files from seven original MSTS route directories, a separately produced route sample, and the derived FTS/Open Rails parser. Record presence varies among clear, rain, snow, and Route Editor files; unsupported or unfamiliar records must be preserved rather than reduced to the subset one renderer currently uses.

On this page

• File model: Location and selection · Serialization · Top-level structure
• Environment: Sky layers · Satellites and lighting · Water · Fog and precipitation · Wind
• Materials: Animated shaders · Texture lookup
• Preservation: Observed variants · Preservation rules · Open questions · Sources

Location and selection

Season/weather mapping keys, environment filenames, textures, and variant contexts follow MSTS names and resource lookup.

A route commonly contains a structure like:

<route>/
|-- ENVFILES/
|   |-- <environment>.env
|   `-- TEXTURES/
|       `-- <sky-water-or-satellite>.ace
|-- TILES/
`-- <route>.trk

The .trk file's Environment block maps named season/weather combinations to .env filenames. The examined derived model expects twelve entries: four seasons multiplied by clear, rain, and snow weather. Original-route observations contain shared filenames across multiple keys, so twelve selectors do not require twelve distinct files.

Activity Season and Weather records select the initial combination. Keep these numeric or named selectors separate from the route mapping and from the selected .env contents. An environment filename can also serve Route Editor use, commonly through an editor.env file, without being one of the ordinary activity combinations. See MSTS units and numeric values for the shared treatment of selectors, colours, times, physical quantities, and unresolved scales.

Serialization

Observed original .env files use SIMISA structured Unicode text with a JINX0w0t-family header and a world root. They follow the token-and-parenthesized-block syntax documented in Kuju structured file format. A typical opening is:

SIMISA...JINX0w0t...

world (
    world_fog_day_colour ( colour )
    world_fog_night_colour ( colour )
    world_sky ( ... )
    world_water ( ... )
)

The header is abbreviated here; readers must detect the actual encoding and preserve the complete envelope. Do not assume ASCII or UTF-8 because the decoded text contains only ASCII characters.

Top-level structure

Across the examined original-route set, every file contains world, world_sky, and world_water. The broader observed top-level vocabulary is:

world (
    world_fog_day_colour ( ... )
    world_fog_night_colour ( ... )
    world_fog_distance ( ... )
    world_sky ( ... )
    world_water ( ... )
    world_precipitation ( ... )
    world_wind ( ... )
    _world_wind_layers ( ... )
)

Group	Purpose	Presence in examined original-route set
world_sky	Sky layers, horizon, and satellites	All 28 files.
world_water	Terrain water map, waves, reflection, and material layers	All 28 files.
world_precipitation	Precipitation type, density, speed, and animated material	14 rain/snow files.
world_wind	Counted wind layers	Present in several variants; repeated top-level groups occur.
_world_wind_layers	Underscore-prefixed wind-layer form	Present in 27 of 28 files. Its relationship to world_wind_layers remains unresolved.
Fog colour/distance records	Day/night fog colour and visibility distance	Varies by route and weather file.

Counts describe this corpus, not universal requirements. Top-level records may be absent, repeated, or ordered differently.

Sky layers

world_sky commonly contains:

world_sky (
    world_sky_nlayers_behind_satellites ( value )
    world_sky_layers ( count
        world_sky_layer ( ... )
        ...
    )
    world_sky_horizon ( ... )
    world_sky_satellites ( count ... )
)

Each world_sky_layer can contain a top surface, an edge surface, optional time-of-day fades, and an animated shader:

Record	Serialized role
world_sky_layer_fadein	Start and end times for bringing a layer into view.
world_sky_layer_fadeout	Start and end times for removing a layer from view.
world_sky_layer_top_nfaces	Number associated with the top surface's radial geometry.
world_sky_layer_top_radius	Top-surface radius value.
world_sky_layer_top_height	Top-surface height value.
world_sky_layer_edge_steps	Counted edge-profile steps.
world_sky_layer_edge_step_height	Height value for one edge step.
world_sky_layer_edge_step_radius	Radius value for one edge step.
world_anim_shader	Texture, blend mode, UV layout, and optional animation for the layer.

Implementations treat height and radius values as spatial quantities, but the original units, coordinate origin, face topology, and interpolation between edge steps need stronger primary evidence. Preserve the raw numeric form.

world_sky_horizon contains a shader definition for the horizon treatment. An empty or textureless shader is still serialized state and should not be discarded.

Satellites and lighting

world_sky_satellites is a counted collection of world_sky_satellite records. Original-route files commonly contain two entries whose textures identify the sun and moon, but the schema is a collection rather than two fixed named fields.

Observed satellite records include:

• world_sky_satellite_low_scale and world_sky_satellite_high_scale;
• world_sky_satellite_rise_position;
• world_sky_satellite_rise_time and world_sky_satellite_set_time;
• directional rise, high, and set colours;
• ambient rise, high, and set colours;
• world_sky_satellite_light;
• optional world_sky_satellite_fog;
• an animated shader selecting a satellite texture.

The colour values are commonly serialized as eight hexadecimal digits. Preserve the raw integer/token spelling: channel order, alpha interpretation, and colour space should not be inferred solely from visual results in a later renderer.

Time values use HH:MM:SS spelling in the observed content and can cross midnight. Preserve them as times plus original text rather than converting them irreversibly to a same-day linear range.

Water

world_water commonly contains:

world_water (
    world_water_terrain_patch_map ( size filename )
    world_water_wave_height ( value )
    world_water_wave_speed ( value )
    world_water_layer_sky_reflection ( value )
    world_water_layers ( count
        world_water_layer (
            world_water_layer_height ( value )
            world_anim_shader ( ... )
        )
        ...
    )
)

world_water_terrain_patch_map contains an integer and a filename in the observed original files. Its payload's exact format and relationship to terrain patch flags are not yet documented; retain both fields and the referenced file even when an implementation ignores them.

world_water_wave_height and world_water_wave_speed are interpreted as distance and speed by the derived parser. Each water layer adds a relative height and an animated material, commonly selecting bottom, middle, or top water textures. Tile-local terrain metadata controls where water is enabled and supplies four corner heights; the environment layers control appearance around those heights.

Fog and precipitation

Observed fog records include:

Record	Working interpretation
world_fog_day_colour	Fog colour used for daytime lighting.
world_fog_night_colour	Fog colour used for nighttime lighting.
world_fog_distance	Visibility/fog-distance value. Exact units and transition behavior remain open.

world_precipitation occurs in all 14 examined rain/snow variants and contains:

• world_precipitation_type;
• world_precipitation_density;
• world_precipitation_speed;
• an animated shader describing the precipitation texture and UV behavior.

The raw type value, density, speed, texture, frame records, and order must be retained. Names such as rain and snow come from the owning route mapping and visible assets as well as the numbers; the complete original type enumeration and units remain to be established.

Wind

Wind is represented through counted world_wind_layer records. The observed layer vocabulary includes:

• world_wind_layer_maxheight;
• world_wind_layer_direction;
• world_wind_layer_speed;
• world_wind_layer_turbulencep.

The corpus contains both world_wind_layers and _world_wind_layers, and some files contain more than one world_wind group. Do not normalize underscore-prefixed records, combine repeated groups, or collapse layers by height. The coordinate convention for direction, units for speed/height, meaning and scale of turbulencep, and precedence between the two layer forms remain unresolved.

Animated shaders

Sky, satellite, water, and precipitation groups reuse a common material vocabulary:

world_anim_shader (
    world_anim_shader_framelen ( value )
    world_anim_shader_frames ( count
        world_anim_shader_frame (
            world_anim_shader_frame_uvtiles ( u v )
            world_anim_shader_frame_uvscroll ( u v )
            world_anim_shader_frame_uvstamp ( ... )
        )
        ...
    )
    world_shader ( mode
        terrain_texslots ( count
            terrain_texslot ( filename value value )
        )
        terrain_uvcalcs ( count
            terrain_uvcalc ( value value value value )
        )
    )
)

Not every shader contains every record. The original-route set includes uvtiles, uvscroll, and uvstamp frame forms, and some shaders contain more frames than others. Shader mode names such as TexDiff, BlendATex, BlendATexDiff, and AddATexDiff are observed serialized values, not interchangeable display labels.

Counts, frame order, texture-slot order, UV calculations, and empty frames are significant preservation data. The complete blend equations, time basis, UV coordinate convention, and tuple-field meanings remain incomplete.

Texture lookup

Environment terrain_texslot records normally name ACE files resolved under ENVFILES/TEXTURES/. Typical roles include daytime sky, stars, low sky/clouds, sun, moon, precipitation, and several water layers.

Keep the raw filename, case, extension, slot values, and referring shader. Environment textures are distinct from terrain-surface textures under TERRTEX/ and ordinary route object textures under TEXTURES/, even where basenames coincide. See texture files for the ACE container itself.

Observed variants

The 28-file original-route sample comprises seven route directories with clear/sun, rain, snow, and editor variants. It establishes the following variation without claiming universal rules:

• clear, rain, snow, and editor files can share the same broad sky/water grammar;
• precipitation records are confined to rain and snow in this sample;
• fog records differ in presence among routes and variants;
• every file has three sky layers and two satellites in this sample, but the format serializes counts and should not be hard-coded to those values;
• water layers total four per file in the inventory, though individual structures and reflection settings still need comparison;
• repeated world_wind groups and two wind-layer token spellings occur;
• texture and route-folder capitalization varies.

A separately produced route sample uses the same world root and the same broad sky/water material vocabulary, adding useful producer evidence but not changing the original-route baseline.

Preservation rules

• Detect the SIMISA envelope and character encoding from bytes; preserve the original Unicode representation.
• Retain top-level order, repeated world_wind groups, underscore-prefixed records, counted collection order, empty blocks, and unknown records.
• Keep route season/weather mappings separate from activity selectors and environment payloads.
• Preserve raw times, hexadecimal colours, numeric tokens, shader mode names, texture-slot values, UV tuples, and count declarations.
• Do not assume exactly three sky layers, two satellites, four water layers, or twelve distinct files merely because those patterns occur in the examined content.
• Keep missing textures and unfamiliar patch-map references as diagnosable references rather than deleting their records.
• Separate original MSTS records from Open Rails weather files, activity weather-change extensions, and replacement sky/weather systems.
• Preserve the owning .env filename and every route key that selects it; several keys may intentionally share one file.

Open questions

• Establish the original required and optional top-level record set and whether record ordering affects MSTS.
• Resolve world_wind_layers versus _world_wind_layers, repeated world_wind groups, and wind-layer units and precedence.
• Decode world_water_terrain_patch_map and document its referenced file format.
• Confirm water wave, layer-height, fog-distance, precipitation-density/speed, sky geometry, and satellite scale units.
• Establish hexadecimal colour channel order, alpha behavior, interpolation, and transition timing.
• Document every shader mode, frame type, UV tuple, texture-slot value, and animation time base.
• Determine route and global fallback behavior for missing environment textures and filenames.
• Map original Route Editor behavior for editor.env and identify whether it is selected outside authoring tools.
• Compare more community producers while keeping Open Rails environment and weather extensions in a separate namespace.

Sources

• Observed original MSTS route content: 28 .env files across seven route directories, covering clear/sun, rain, snow, and Route Editor variants. Private corpus locations are intentionally omitted.
• FTS EnvironmentFile.cs, EnvironmentLayer.cs, Route.cs, and FolderStructure.cs: derived parser, selector, and lookup evidence. FTS/Open Rails are one shared lineage.
• Observed independent-producer route content: Unicode world environment structure and associated sky, satellite, and water ACE assets.
• Route definition, activity files, terrain files, and texture files: selecting and consuming schemas.