Skip to content
Connected RailsConnected Rails

Baked light

A model in the open is lit by the whole sky, and the simulator’s sky is a real one: an environment map rebuilt every frame from the sun’s position, the date and the weather. What it does not know is what stands between one of your surfaces and it. The soffit of a bridge, the underside of a canopy, the inside of a signal’s hood and the back of a recess are all lit as though they stood in a field, and that is the flattest-looking thing left in a model.

tools/lightmap/bake.py measures it once, offline, and writes it beside the model:

Terminal window
blender --background --python tools/lightmap/bake.py -- mods/yourmod/assets/hall.gltf

Three things come out, and the model itself is touched only to name them:

  • hall_sky.png — one greyscale value per texel, how much of the hemisphere that point can see. Zero bounces, a white world, a white surface: the integral Cycles computes then is the cosine-weighted sky visibility, with no ambient-occlusion distance to guess at.
  • hall_lightmap.bin — the UV layout that map is laid out in, appended to the model as one more buffer and one TEXCOORD_1 accessor per primitive. Your existing buffers are not rewritten; not a byte of your geometry moves. A primitive that had no TEXCOORD_0 at all (untextured parts, as on the BR 101) gets a zero-filled one in the same buffer, because Bevy’s PBR shader will not compile a second UV set without a first.
  • On every material, an extra: connected_rails.sky_occlusion = { texture, texCoord: 1 }. The simulator’s weather material reads it and multiplies the map into the material’s own occlusion (crates/world-render/src/weather.rs). Your occlusionTexture stays yours — most of the stock has authored ambient occlusion in that slot, and the two are meant to multiply, not to compete for it.

So your model still reddens at dusk, greys under an overcast and goes dark at night — the map scales the sky’s contribution, it does not replace it — and it simply stops seeing sky through its own roof.

One limit, and it is the weather material’s rather than the bake’s: that material dresses what is anchored in the world — scenery, signals, buildings — and not the vehicles, which do not get rain or snow either. A vehicle’s bake is written like any other and sits inert until the day vehicles are dressed too; the eight of them in the stock cost nothing to carry.

What Blender is and is not asked to do. It imports the model, lays out the lightmap UVs and renders the bake. It does not export the model: its exporter is a round trip that the stock did not survive when the first version of this tool tried it — duplicate node names uniquified (the BR 101’s cab digits are found by name), tangents re-derived mirrored, vertex colours on the pylons reset to white, asset.copyright dropped from every file — five independent regressions across 81 models, found by comparing every triangle of the stock against the commit. Instead each glTF triangle is found among Blender’s by its three corner positions and takes its corners’ UVs; the file is then patched in Python. A triangle that cannot be found stops the run.

Your model needs a free UV channel, and Bevy has two. The bake takes channel 1 unless something already reads it: a glTF texture with texCoord: 1, or the simulator’s own surface_detail extra, which samples channel 1 at run time although no glTF texture points at it (the Wolfsburg buildings). Such a model is left out — bake_all.py --list will not name it — rather than have its detail layout overwritten. A texCoord of 2 is not an option: Bevy addresses Uv0 and Uv1 and answers anything higher with a silent fallback to 0.

  • --size defaults to auto, which sizes the atlas from the island count or the model’s surface at five centimetres a texel, whichever asks for more: each island needs its cell and its gap whatever its area, and a platform of eighteen islands still wants its resolution.
  • --samples is rays per texel; 32 is grainless on a sky-visibility integral.
  • --margin is the bleed past each island, 1 texel by default — enough for a texture without mipmaps, and paid for tens of thousands of times over on a dense model.
  • --bounces stays at 0: light that bounces between your own surfaces is not in the sky’s cubemap, so counting it here would count it in the wrong place.
  • --out writes elsewhere; keep it in the model’s directory, the textures are referenced.

How the atlas is laid out. Blender’s pack_islands would be the obvious tool and is not: driven headless it packs per object, so every object comes back spanning the whole square and they land on top of one another (0.7 % of the atlas covered on the city bridge). The script packs the islands itself — each scaled so its atlas area is proportional to its world area, laid in shelves tall-first, the global scale bisected until it fits and then placed once more at the scale that did — for 80 % on the same bridge. The model is imported welded, because a glTF stores every corner of every triangle as its own vertex and an unwelded import gives the unwrap one island per triangle; welded, a surface is one island. Each island is then nudged by up to half a texel so that the centroid of its largest face sits on a texel centre: Cycles writes a texel only when its centre lies inside a face, and a small triangle in a one-texel cell would otherwise bake nothing half the time and sample the black between the islands. What Cycles leaves unwritten inside a cell — the corners of a thin face, beyond its one-texel margin — the script fills from the written texels of the same cell afterwards.

V runs the other way in Blender. Its UV origin is the bottom-left of the image and glTF’s the top-left, so the layout is written with V turned over. If you make your own lightmap UVs some other way, that is the convention: the first row of the PNG is v = 0.

For the whole stock at once there is a driver:

Terminal window
python3 tools/lightmap/bake_all.py # every model that wants it, incrementally
python3 tools/lightmap/bake_all.py mods/yourmod # just yours
python3 tools/lightmap/bake_all.py --list # say what would run, do nothing
python3 tools/lightmap/bake_all.py --check # exit non-zero if any model lacks its bake

It skips a model whose materials already carry the extra, the trees (alpha-cut foliage the wind moves every frame), anything with an animations or skins block (the people), any model with no free UV channel, and LFS pointer files. It divides the machine’s cores between its workers rather than letting each Cycles take all of them, and it needs memory in proportion to the atlases — eight workers on a 30 GB machine is where a run of the stock sits comfortably.

A regenerated model has no bake. The glTFs under mods/ are build output — tools/gen_hv_signals.py and its siblings rewrite them — so two things catch that: the three signal generators (gen_hv_signals.py, gen_ks_signals.py, gen_form_signals.py) take --bake and do it themselves on exactly the models the run wrote (tools/lightmap.bake_written, three lines any generator can copy), and CI runs bake_all.py --check, which reads glTF JSON only and needs no Blender on the runner.

Re-baking is safe: the script recognises its earlier work from the extra, lays the lightmap out afresh in the channel it finds (glTF stores no layer names, so the old layer comes back as UVMap.001 and is simply taken over), and rewrites the same accessors rather than adding beside them. bake_all.py --force re-bakes what is already baked. Baked textures and the lightmap buffers go through Git LFS like every other binary under mods/.

Sky visibility is the right bake for everything in the open, because the sky it scales moves. A sealed interior — the concourse of a station building, a depot, a tunnel’s service room — is the one place where the opposite is right: what lights it are its own lamps, which do not move, and the light they throw around the room, bounced off the walls, is exactly what a real lightmap holds. The same tool bakes it when the model asks for it; the example is tools/gen_station_hall.py (example:station_hall, behind the platform of the example line).

What the model has to say, all of it in glTF:

Where What
Every material seen from inside extras: { connected_rails: { interior: true } }
The lamps KHR_lights_punctual point or spot lights, intensity in candela — the glTF unit, the one the simulator’s loader turns into lumens
A node, usually the root extras: { connected_rails: { interior_volume: { min: [x, y, z], max: [x, y, z] } } } — the box the room encloses, in that node’s frame. Its faces are the room’s faces; keep anything that faces outwards — a door leaf, a pane — more than 10 cm behind them, because the room’s light probe reaches that far into the walls
Optional, asset.extras connected_rails: { lightmap_texel_m: 0.1 } — a coarser atlas than the default five centimetres; the light of lamps is smooth, and the interior map is four bytes a texel

Split inside from outside. A wall is two faces with two materials, never one box: a mesh that is half under the roof and half under the sky cannot carry one lightmap, because the lightmap replaces the sky’s diffuse on everything it is on. The facade and the roof keep the sky-visibility map like any other model. The door leaves and the glass may stay outside materials. Only the lamps that stand inside the volume are the room’s: a lantern over the door outside, a lamp whose definition is shared with one outside, and any directional light are left out of the bake and stay ordinary lights.

bake.py then bakes, on the same layout as the sky map:

  • hall_light.ktx2 — the radiance the lamps put on a white surface, direct and bounced four times off your own materials (a red floor bounces red), in cd/m². RGB9E5, a shared-exponent float format Bevy samples directly. No sky, and no emissive materials: the lamps are the punctual lights, and a glowing diffuser counted as well would count each lamp twice.
  • On every interior material, connected_rails.lightmap = { texture, texCoord: 1 } — except a glowing one (a lamp’s diffuser, a departure board): its texels would hold the lamp’s light from a hand’s breadth away, and with its own glow on top the lamp would be counted twice.
  • On every lamp it baked, connected_rails.baked = true. The simulator does not spawn those lamps as lights at all: a point light without a shadow map shines through walls, so it would light the platform and the train outside, and the bake has already paid for its light.
  • On the volume, illuminance_lx — the mean illuminance the bake measured on the interior surfaces, glowing ones left out — and ambient_nits, two sets of three bands (from above, the side, below): the light that arrives where people stand (the lamps’ direct light at waist and head height plus the bounce) and the light the surfaces send back. The simulator makes the volume a light probe out of them, so a train or a person in the hall is lit by the hall and not by the sky outside.

While the camera is inside the volume, the exposure meters the hall instead of the sky, no rain or snow falls, the weather’s fog and the atmosphere’s haze stay outside (the air under a roof is not the weather’s), the sun keeps its shadows even under a closed deck (the roof casts one) and is the only time the sun reaches a lightmapped surface at all — with shadows off, or beyond the last cascade, nothing would stop it at the roof — and the bloom loses its wide skirt, which would otherwise spread the eight-stops-brighter windows over the whole picture. The weather does not touch an interior material at all.

The units need no tuning. Every light in the simulator carries its real photometric figure and the camera’s exposure does the rest, so a lamp of 2600 cd in your file is 2600 cd in the lightmap and in the probe, in the same units as the sun outside. The chain is checked against a floor under one lamp, whose answer is known (python3 tools/lightmap/check_interior.py, needs Blender). Choose lamps the way a lighting planner would: the example hall’s eight pendants of 2600 cd put a mean 198 lx on its surfaces, about the 200 lx a station concourse is planned for.

What the bake cannot know. Daylight through the windows. While you stand inside, the sun shines in with its shadows; the diffuse sky through the glass is gone from every lightmapped surface, which is why this is for interiors that are lit mainly by their lamps. Seen from outside, the hall’s inside gets no sun at all. Lamps are always on, and a person in the hall is lit evenly by the probe, without the shadows of single lamps. Every copy of your hall loads the one atlas, but Bevy gives each lightmapped mesh its own lightmap slot, so each copy costs its own draws: a handful of interiors, not a class of object placed a thousand times.