Baked Light

Light that bounces round a 3D scene, baked once and saved with the cart

The sun lights what faces it and the scene's shadows fall where they should, but nothing in a plain scene is lit by light that bounced: a doorway is as bright as the yard outside it, and a red wall leaves no red on the floor beside it. scene.bake adds that light.

import { useEffect } from "react"
import { mount, useScene, useModel } from "oj"

function Room() {
    const scene = useScene()
    const room = useModel("room.glb")
    useEffect(() => {
        if (!scene || !room) return
        scene.spawn(room, { static: true })
        scene.bake("room.light.png")
    }, [scene, room])
    return null
}

mount(<Room />)

Run it and the room appears at once, then its light fades in over a second or so on a desktop, and some seconds on a phone. The console says the light was baked here and ends in Save. Press it, and room.light.png is in the cart beside index.tsx, to commit and push like any other file. From then on the cart loads the file and bakes nothing, so a player gets the light the moment the file arrives.

What the bake adds is the light from the sky and the ground, and the sun's light after it bounces. The sun's own light and shadows stay live, so a cart can still move its sun; call bake again for the bounce to follow it. The light showing stays until the new light is ready, so a rebake never drops the scene to flat light in between.

The name is a path from the cart's root ending in .light.png, like "room.light.png" or "levels/room.light.png". Any other name is refused at the call.

What is baked into

Call bake once everything that never moves has been spawned.

  • An actor spawned with static: true is baked into, and its shadow and bounce fall on the rest.
  • The actor of a physics body that does not move, neither dynamic nor kinematic, is static already. A physics cart marks nothing.
  • Everything else, a character, a car, a crate that can be knocked over, takes the baked light where it stands, as it moves.
world.box({ at: [0, -0.5, 0], size: [40, 1, 40], actor: scene.spawn(m.ground) })   // baked into
world.box({ at, size: [1, 1, 1], dynamic: true, actor: scene.spawn(m.crate) })     // lit where it stands
scene.bake("yard.light.png")

A static actor moved anyway keeps its light where it was until the next bake.

When the file is out of date

The file remembers the scene it was baked for: every static actor's model and place, the sun, the ambient and the options. When any of them changes, the cart bakes again on whatever device runs it, and the console says what changed:

[oj] room.light.png was baked for a different scene (wall.glb at [5, 1, 0] is not in it): baked here instead. Save

Press Save again. Until you do, a player gets the right light a few seconds late, never the old light on the new scene. A file saved on runtime 1.4 is baked on the device once when its cart moves to 1.5, and the console says was saved by an older oj. Save it again and it is smaller: Crate Yard's went from 889 KB to 566.

To bake a saved file again without changing anything, run the cart, click the file in the list and press Bake again.

A level made as the cart runs has no file to save. Leave the name out and it bakes on the device every time:

for (const piece of makeLevel(seed)) scene.spawn(models[piece.kind], { static: true, position: piece.at })
scene.bake()

Options

None are needed. Give any of four as numbers:

scene.bake("yard.light.png", { bounces: 3, occlusion: 0.5 })
Option What it does Default
bounces How many times light bounces before it stops, 0 to 8. More carries light further round corners and under cover. 2
samples Rays for each texel, 1 to 4096. More is smoother and slower. 256
occlusion Extra darkening in corners and where things touch, within a metre, 0 to 1. 0
detail Texels a metre, 1 or more. From the scene's size

Changing an option makes the saved file out of date, so press Save once more.

Big scenes

Each page of light is one 512 by 512 picture. With no detail given, the light takes one page: 24 texels a metre for a room, fewer for a bigger scene, down to 12. A scene too big for one page at 12 is spread over up to four at 12, and one large actor, a floor or a terrain, may cross all four. A detail given is kept over as many pages as it needs. Past four, the detail is lowered to fit, and the console line says to what:

[oj] yard.light.png is not in the cart yet: baked here, at 7.9 texels a metre, as 12 does not fit 4 pages. Save

It is still one file. The Crate Yard example is an 80 m yard baked this way.

Waiting for it

A bake runs a little each frame, so the cart can be played while the light arrives. A cart that would rather show a loading screen reads the bake it gets back:

const light = scene.bake("level.light.png")
light.progress            // 0 to 1
const how = await light.done

done resolves to how the bake ended:

how What happened
"loaded" The saved file was current, and its light is showing.
"baked" The light was baked on this device, and is showing.
"failed" The light could not be baked; the console said why, and the scene keeps its plain light.
"stopped" A later bake, clearLight or the scene going stopped it first.

scene.clearLight() takes the baked light away, and stops a bake under way. Both are runtime 1.5's: on 1.4, done resolves with nothing and a rebake shows flat light until the new light arrives. List the file in oj.json's preload and bake reads it without waiting on the network.

At a terminal

npx ojplay bake

runs the cart on this machine, waits for every scene.bake(name), and writes each file baked here into the cart. Commit what it wrote before you push. With a script, as ojplay test takes, it drives the cart first, for a level behind a menu.

What it does not do yet

  • Point lights are not bounced; they stay live.
  • A skinned model is never baked into, even spawned static: true: it takes its light as a moving actor does, and the console says so.