HammeriteBrushEntityLighting

Core: lighting. Inherits RefCounted

The handover for brushwork that is baked into the world and then moves.

A secret door is built flush with the wall it hides in and has to be lit as that wall, which means being in the bake (HammeriteLightingProperties.KEY_BAKE_STATIC). The moment it slides, that bake is a photograph of somewhere it no longer is - the shading is of the wall's surface, in the wall's place - so it hands over to the light probes, which is how everything else that moves in this engine is lit. Neither half alone is right, which is why this is a BLEND rather than a swap. Swapped outright, the surface changes appearance in one frame while the eye is on it; blended over the first moment of movement, the change happens under the motion, where nobody reads it. Every brush entity base has one, which drives itself, so a door needs only to say when it moves:

func open() -> void:
hand_over_to_probes()   # HammeriteBrushEntityNode3D.hand_over_to_probes, and the bodies' alike

One made with new(node) instead is driven by its owner calling update(). Costs nothing until hand_over_to_probes() is called: brushwork that never moves keeps its lightmap, and its shader's probe branch is never taken.

Methods

Constants

BLEND_SECONDS

const BLEND_SECONDS = 0.25

How long the handover takes, in seconds. Short enough to be over before a door has swung far, long enough not to be a cut.

REGATHER_DISTANCE

const REGATHER_DISTANCE = 32.0

How far the brushwork moves before its probes are gathered again, in world units. The probe grid is coarser than this is precise, and a gather is a query plus a visibility test per probe.

Method descriptions

is_baked_static()

func is_baked_static() -> bool

Whether the brushwork this lights was baked into the world at all. An entity that was never baked has nothing to hand over FROM: it is unlit brushwork wearing the ambient minimum, and probes are strictly better. Such an entity may still call hand_over_to_probes() - and should.

hand_over_to_probes()

func hand_over_to_probes() -> void

Light this from the probes from now on, blending over BLEND_SECONDS. Call it as the movement STARTS, not when it finishes: the blend wants the motion to hide under.

hand_back_to_lightmap()

func hand_back_to_lightmap() -> void

Go back to the lightmap, for brushwork that returns exactly where it was baked. Only true of something that closes flush again. A door left ajar is not where its bake says it is, and asking for the lightmap back would light it as though it were.

update()

func update(delta: float) -> void

Drive from the entity's _process, for one that does not drive itself. Does nothing while the lightmap is what lights it.

get_blend()

func get_blend() -> float

How far over to the probes the shaders are, from 0 (the lightmap) to 1 (the probes).

refresh_materials()

func refresh_materials() -> void

Collect the materials again, after anything that rebuilds the entity's meshes.