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.
Overview
Section titled “Overview”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 |
Materials
Section titled “Materials”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.
Light tables
Section titled “Light tables”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 itperiods = [ { 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. sunmultiplies everything that takes the main light."#ffffff"shows the pictures as drawn.lampmultiplies lamp materials (white if not given).glow(0 to 31) is how strongly pools of light show; 0 hides them.nightis 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
clearandfogcolours, 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.
Map colours
Section titled “Map colours”grade = "#f0f8e8"multiplies the table’ssunat 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.clearis 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.
Hardware lights
Section titled “Hardware lights”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.
Outlines
Section titled “Outlines”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 ownOne 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 caves
Section titled “Dark caves”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.
Weather
Section titled “Weather”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
sunmap has no weather at all; it comes back at dawn. - A map with its own
fogkeeps its colour: a weather with fog turns the map’s fog on instead of its own. - A script’s
weatherfades: 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 aweatherinon 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.
Script tint
Section titled “Script tint”tint 80, 90, 160tint 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
Section titled “Planned”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.