Lights and materials
The DS’s 3D engine can light a model the way a modern engine does in principle (light from a direction, brighter where a surface faces it) but with a fixed formula, four lights, and colour worked out only at the corners of polygons. This page explains that formula. The way games change light through the day is on How light follows the hour, and what a creator sets is on Light, time of day and weather.
Overview
Section titled “Overview”Every corner (vertex) of a polygon gets a colour, and the engine blends those colours across the polygon and multiplies them by the texture. A game gives a corner its colour in one of two ways:
- A colour directly. The model carries its shading baked in, painted by the artist or computed by a tool. Nothing changes at run time.
- A normal. A normal is the direction the surface faces at that corner. When the geometry engine receives one, it computes the corner’s colour at once from the lights and the material, and uses that as the colour.
The second is hardware lighting. It costs no more than sending a colour, which is why the original games use it for models that should respond to light.
Lights
Section titled “Lights”The DS has four directional lights. Each is only two things:
- a direction, like sunlight: the same everywhere in the world, with no position and no fall-off with distance;
- a colour, 15 bits like every DS colour. Black means off.
A polygon says which of the four light it. There are no point lights, no spotlights and no shadows cast by lights. A lamp on a street cannot light the ground around it; games paint the pool of light instead.
Materials
Section titled “Materials”The surface being lit has four colours of its own, set before its polygons are sent:
| Colour | What it means |
|---|---|
| Diffuse | How much of a light the surface reflects when facing it: its main colour under light |
| Ambient | How much of each light it reflects whatever way it faces: the colour of its shaded side |
| Specular | How much shine it shows where a light glances toward the viewer |
| Emission | Light of its own, added whatever the lights do |
Computation
Section titled “Computation”For each corner the engine starts from the emission, then, for each light the polygon takes, adds:
- the diffuse colour times the light’s colour times how directly the surface faces the light (nothing if it faces away);
- the ambient colour times the light’s colour;
- the specular colour times the light’s colour times a shine factor, which is largest where the light’s reflection points at the viewer.
Each channel is then capped at full brightness (31). In words: a colour of its own, plus every light’s share, each light lighting the facing side fully and the far side only by the ambient part.
Two details matter in practice:
- Ambient belongs to the lights. There is no separate ambient light. A surface lit by no light shows only its emission.
- The shine is cheap. The viewer is treated as looking straight into the screen, so the shine depends only on the light and the normal. The DS can also pass the shine through a 128-step table to shape it (glossy or dull); without the table it is used as it is.
Appearance
Section titled “Appearance”The lit colour exists only at the corners. Across a polygon the engine blends the corners’ colours in straight lines. So:
- A large flat polygon is evenly lit, or shaded in a smooth ramp; it never gets a bright spot in its middle.
- Curved shapes look smooth only if they have enough corners.
- Hard light and crisp shadows have to be painted into textures.
This is why most DS scenery is lit by its art and its palettes, and hardware light is kept for models that move or turn: creatures in battle, or buildings whose light shifts with the hour.
PokeLoom
Section titled “PokeLoom”PokeLoom has two kinds of light, and a project can use either or both.
Palette light (the usual one). The texture’s palette is multiplied by the period’s light colour when the period begins. Because the engine multiplies texels by the corner colour anyway, this lights everything drawn with that palette at no cost per frame. A material says which palette light it takes: the sun, the lamps, a constant one, or a pool of light. This is what PokeLoom’s own art uses.
Hardware light. A light table in lights.toml may give, in every period, the four
lights and the material colours. A material that names lights is drawn with normals
instead of colours, and the hardware (or the desktop’s copy of it) lights it:
[evening]periods = [ { start = "00:00", sun = "#ffffff", night = true, lights = [["#9090c0", 0, -480, -160], ["#000000", 0, 0, 0], ["#000000", 0, 0, 0], ["#000000", 0, 0, 0]], material = ["#b0b0b0", "#585868", "#000000", "#101018"] },](one line in the file). Each light is [colour, x, y, z], the direction in the world
in 512ths (x east, y up, z south). material is [diffuse, ambient, specular, emission]. A material takes the lights with lights = [0] in pieces.toml, or
pl_lights 0 in its MTL file, which can also give its own four colours.
- Directions are in the world. The engine turns them by the camera’s matrix as it sends them, so a light from the north stays from the north whatever the camera does.
- A period can impose its material colours on every lit material (
material_all), as an original game does outdoors, or let models keep their own. - Characters are flat cards. They are lit as a face turned up, or by a normal and
colours of their own (
card_normal,card_material), so a person matches the ground they stand on. - In a period with hardware lights, materials without
lightsshow their vertex colours as they are.
Every key is in the lights.toml reference. Imported games write their own tables from the original’s light files, so their models are lit as the original lights them.
On desktop the software renderer computes the lit colour with the same integer steps as the DS, in the same order, with the same rounding and capping. A lit model is the same colour, step for step, on both.
Planned (plan 42): on desktop, a player may choose per-pixel lighting and lamps as point lights. These are presentation settings; the DS’s per-corner rule stays the reference.