Skip to content

Lighting and weather

Everything on a map is drawn in its own colours, multiplied by a light. The light changes with the clock: a day is cut into periods, each with its own colours, and when the clock passes into the next period the game changes them. This is how the DS games make one map look like morning, evening and night without drawing it three times. How the originals do it is on Time of day, and the hardware’s lights on Lights and materials. This page is what you set.

From the widest to the narrowest:

What Where Lasts
The light tables of the whole game lights.toml in the project folder always
Which table a map uses, or an hour it is fixed at light in map.toml always
A colour multiplied into a map’s light at every hour grade in map.toml always
Which light a material takes light of a material in pieces.toml always
Baked shade on the ground shade.png beside map.toml always
Fog that thickens with distance fog in map.toml always (weather turns it on)
Outlines where pieces meet edges in game.toml [light] or map.toml always
The weather’s light and fog weather in map.toml, the weather command until the map is left
The main light replaced by one colour the tint command until the map is left

Each material of a piece says which light it takes, with light in pieces.toml:

light Lit by For
sun (the default) the period’s main light ground, buildings, characters
lamp the period’s lamp colour: dark by day, lit at night window glass, lanterns
constant nothing: always as drawn signs, screens
glow a pool of light, as strong as the period’s glow light on the ground under a lamp

The sample’s houses and field station have windows of their own material with light = "lamp": dark glass by day, lit at night, with no script. Pieces and materials are on Art.

A map’s light names a light table. The engine has four: day (twelve periods through the day, lamps lit from 17:30 to 1:00, night from 19:30 to 5:00), bright (white at all hours, lamps lit), dim and warm. Outdoors the default is day; indoors and in caves it is bright. The sample’s lab says light = "bright" so it is lit the same at every hour.

A project’s own tables go in lights.toml. A table named after a built-in replaces it on every map that uses it; any other name is a new table:

[glasshouse] # maps with light = "glasshouse" use it
periods = [
{ start = "00:00", sun = "#8c9cd8", lamp = "#ffe0a0", glow = 24, night = true },
{ start = "06:00", sun = "#d8e8c8" },
{ start = "11:00", sun = "#f8fff0" },
{ start = "17:30", sun = "#f0c8a0", lamp = "#ffd890", glow = 12 },
{ start = "20:00", sun = "#8c9cd8", lamp = "#ffe0a0", glow = 24, night = true },
]
  • A table has 1 to 16 periods. The first starts at "00:00", they are in order of time, and each lasts until the next begins.
  • sun multiplies everything that takes the main light. "#ffffff" shows the pictures as drawn.
  • lamp multiplies lamp materials (white if not given). glow (0 to 31) is how strongly pools of light show; 0 hides them.
  • night is what the rest of the game asks (“is it night?”): a battle begun in a night period shows its night scene.
  • A period may also give its own clear and fog colours, used as given.

Every key is in the lights.toml reference.

A map can also stop the clock. light = "21:00" fixes the map in the period of the day table that holds that hour: a place that is always seen at night.

  • grade = "#f0f8e8" multiplies the table’s sun at every hour: a forest a little greener, a desert warmer, without a table of its own.
  • shade = "shade.png" is a grey picture one pixel larger than the map each way, one pixel a cell corner: white for full light, darker for shade. Paint shadows under trees and beside walls with a soft brush. The sample’s rooms each have one.
  • clear is the colour behind everything, seen past the edge of the ground. The sample’s outdoor maps use "#63a54a", a dark green, so the edge of the world reads as more trees.

A map that uses a built-in table and no grade costs nothing in its file. One with its own table or grade carries it: two words, and two a period.

The DS’s 3D engine has four directional lights and computes a lit colour from a material’s diffuse, ambient, specular and emission colours and its normals. Imported games light their models this way, and a project can too. A period may give the four lights, each [colour, x, y, z] with its direction in 512ths (x east, y up, z south; black is off), and the colours lit materials reflect:

{ start = "12:00", sun = "#ffffff",
lights = [["#f8f8f0", 0, -400, -300], ["#000000", 0, 0, 0],
["#000000", 0, 0, 0], ["#000000", 0, 0, 0]],
material = ["#c0c0c0", "#606060", "#000000", "#000000"] }

(one line in the file). Give every period of the table both lights and material. A material takes these lights when it names them: lights = [0] on a material or a ground piece in pieces.toml, or pl_lights 0 in the model’s MTL file. Its faces are lit from the model’s normals, on the DS by its geometry engine and on desktop by the same rule to the step. In a period with lights, materials without lights are drawn in their vertex colours.

Use this when your models have normals and you want light to fall on them from a side. For painted pieces the palette light above is simpler and cheaper.

The DS can draw an outline where one polygon meets another of a different ID behind it. Give a piece’s materials an id (1 to 63) different from the ground’s (0), then set the outline colours:

[light]
edges = ["#202018"] # in game.toml: every map; a map.toml may set its own

One colour serves IDs 0 to 7, the next 8 to 15, and so on; a shorter list repeats its last. Without edges there are no outlines. See Toon shading, edges and fog for how the hardware does it.

fog = { color = "#c4cad0", start = 29150, shift = 3 }

Fog thickens with distance from the camera: start is the depth where it begins (0 at the camera to 32767; with the default camera the bottom of the screen is near 29000) and shift how fast it thickens (0 slowest to 10). These three give a morning mist. slow = true makes it come and go at half speed, and on = false makes it wait for a script. The defog field move fades a map’s fog away.

dark = true in a map’s map.toml makes it dark until the flash move lights it. A script can make a map dark with weather dark.

A map’s weather, or a script’s weather command, is one of ten kinds:

Kind What falls The light A battle here begins in
none nothing as the hour has it no weather
rain slanted streaks, splashes a little dimmer, cooler rain
heavyrain long streaks; lightning flashes much dimmer rain
snow flakes falling slowly a little cooler snow
blizzard flakes driven in gusts dimmer, cooler snow
sand grains flying in from the side yellow-brown a sandstorm
fog nothing a little dimmer, thick fog no weather
sun nothing; the screen glares a little warmer harsh sunlight
ash grey flakes drifting dull, yellow no weather
diamonddust glints of ice a little cooler no weather
  • The weather multiplies the hour’s light, and its fog takes the hour’s light too: rain at night is dark grey, not a glowing wall. Lamps and constant materials keep their own light.
  • Harsh sunlight shines by day only. In the night periods a sun map has no weather at all; it comes back at dawn.
  • A map with its own fog keeps its colour: a weather with fog turns the map’s fog on instead of its own.
  • A script’s weather fades: old particles thin out over about two seconds as the new ones fill in. Arriving on a map, its weather is full from the first picture, and so is a weather in on load. It lasts until the map is left.
  • A battle on the map begins in its weather, which lasts until a move or an ability changes it.

The sample’s hill has a lookout who changes the weather on request, every kind in turn:

choice "Which weather?", ["Rain", "Heavy rain", "Snow", "Blizzard", "Sandstorm", "More", "Clear"] -> temp(0)
if temp(0) == 0 {
weather rain
}

What weather costs on the DS: at most 56 of the top screen’s 128 sprites, 16 sprite tiles and one sprite palette. A menu screen that needs its own sprites hides the weather while it is open.

No weather plays a sound yet: looping a rain sound needs the sound system to loop an effect. Play a track that has the sound in it.

tint 80, 90, 160

tint makes one colour the main light in place of the hour’s, the grade and the weather’s, until the map is left or tint alone brings them back. Lamps and constant materials keep their light. Every palette is redone at once, which takes a few frames on a DS, so do it under a fade.

Planned (plan 25): light tables chosen by area, and by area and season, as generation-5 games choose theirs; a light direction that turns through the day.

Planned (plan 25): a light or grade per zone inside one joined world. Today the maps of a world share one light table and grade.

Planned (plan 42): on desktop, modern lighting and post-processing as presentation settings a player may choose. They change only how the game is drawn; the software renderer that follows the DS’s rules stays the reference. See Presentation settings.