Skybox
The scene's sky as a single **material**. Add it to an entity and the engine renders that material across the sky behind everything else:
Skybox
The scene's sky as a single material. Add it to an entity and the engine renders that material across the sky behind everything else:
entity.spawn("sky").component.add("Skybox", { material = "sky_cubemap" })
entity.spawn("sky").component.add("Skybox", { material = "my_custom_sky" })
entity.spawn("sky").component.add("Skybox", { kind = "none" }) -- explicit no sky
Skybox is the generic, material-driven sky: it points at any sky material
— a builtin (sky_procedural, sky_solid, sky_cubemap, sky_equirect) or
your own authored sky-domain material — and makes it the active sky. For the
editable procedural atmosphere (day/night, sun, stars, moon), use the
ProceduralSky component instead — it is
a Skybox over the sky_procedural material plus typed parameter controls.
A Skybox materialises its material's GPU handle when it binds it. The sky's
point-of-use is the sky pass, which never binds the material the way a Model
does, so the component performs the Disk→CPU→GPU upload (:handle()) itself. The
renderer binds the sky by the material's identity (the key it is resident
under once materialised), so a material-mode sky renders correctly after boot and
mode flips — no manual :handle() needed.
Like the directional light, the sky is conceptually singular per scene: the
engine copies the most recently authored sky into the scene-wide sky config the
renderer reads each frame. A sky belongs to the scene that spawned it; removing
the component reverts the scene to the engine fallback sky. State is bridged
through the native Sky ECS component (sky type material / none), so there
is no global sky singleton — two scenes can never clobber each other.
Fields
| Field | Type | Default | Meaning |
|---|---|---|---|
material | string | sky_procedural | The sky material to render. Any registered material whose shader is a sky-domain shader. Defaults to the procedural sky so an empty Skybox{} is never a black void. |
kind | string | material | "material" renders material; "none" turns the sky pass off — the explicit authored form of "this scene has no sky". |
Methods
| Method | Description |
|---|---|
skybox:setMaterial(name) | Point the sky at a different material (materialises its handle). |
skybox:setNone() | Turn the sky off explicitly. |
Scoped to this part · feeds back into the world's score.