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.