---
title: "sky"
description: "The sky namespace — the engine's Luau API reference for sky."
section: "API Reference"
slug: "api-sky"
canonical: "https://origozero.ai/docs/api-sky"
updated: "2026-09-05T23:13:47.221403519+00:00"
tags: ["api", "reference"]
---

# sky

The `sky` namespace — 20 functions.

## globals/sky/get {#globals-sky-get}

```lua
sky.get() -> { [string]: any }
```

Get all current sky configuration as a table. Returns the
same fields as `sky.set` accepts, plus read-only fields like
`material_name` and `type`. Color values are returned as
positional arrays `[r, g, b]`.

**Returns** `{ [string]: any }` — Full sky configuration table.

```lua
local cfg = sky.get(); print(cfg.time_of_day)
```

## globals/sky/getTimeOfDay {#globals-sky-gettimeofday}

```lua
sky.getTimeOfDay() -> number
```

Get the current time of day in hours (0-24).

**Returns** `number` — Current time of day.

```lua
local t = sky.getTimeOfDay()
```

## globals/sky/preset {#globals-sky-preset}

```lua
sky.preset(name: string)
```

Apply a named sky preset. Available: `clear_day`, `sunset`,
`sunrise`, `overcast`, `night`, `studio`, `none`. Raises a Luau
error for unrecognized names — wrap in `pcall` if uncertain.

**Parameters**

- `name` `string` — Preset name (case-sensitive).

```lua
sky.preset("sunset")
```

## globals/sky/set {#globals-sky-set}

```lua
sky.set(opts: SkyOpts)
```

Configure the sky system. All fields are optional — only
provided fields are updated. Color fields accept both named
`{x=r, y=g, z=b}` and positional `{r, g, b}` forms. `color` is
an alias for `solid_color`.

**Parameters**

- `opts` `SkyOpts` — Sky configuration properties.

```lua
sky.set({ type = "procedural", time_of_day = 14, sync_sun_to_light = true })
```

## globals/sky/setSunDirection {#globals-sky-setsundirection}

```lua
sky.setSunDirection(dir: SkyColor)
```

Set an explicit sun direction and disable time-based sun
positioning. The directional light is updated to match.

**Parameters**

- `dir` `SkyColor` — Normalized sun direction vector.

```lua
sky.setSunDirection({ 0.5, -1, 0.3 })
```

## globals/sky/setTimeOfDay {#globals-sky-settimeofday}

```lua
sky.setTimeOfDay(time: number)
```

Set the time of day (0-24 hours). 0 = midnight, 6 = sunrise,
12 = noon, 18 = sunset.

**Parameters**

- `time` `number` — Time of day in hours.

```lua
sky.setTimeOfDay(18.5)
```

## modules/sky/README {#modules-sky-readme}

```lua
require("@builtin/modules/api/engine/sky") -- sky (also available as global 'sky')
```

Sky configuration — type, time of day, day/night cycle, procedural parameters, presets, explicit sun direction. Public Luau surface over the `__sky` Internal FFI namespace.

Usage: local sky = require("@builtin/modules/api/engine/sky")
Also available as global: sky

## modules/sky/get {#modules-sky-get}

```lua
get(): { [string]: any }
```

Get all current sky configuration as a table. Returns the
same fields as `sky.set` accepts, plus read-only fields like
`material_name` and `type`. Color values are returned as
positional arrays `[r, g, b]`.

```lua
local cfg = sky.get(); print(cfg.time_of_day)
```

## modules/sky/getTimeOfDay {#modules-sky-gettimeofday}

```lua
getTimeOfDay(): number
```

Get the current time of day in hours (0-24).

```lua
local t = sky.getTimeOfDay()
```

## modules/sky/installFallback {#modules-sky-installfallback}

```lua
installFallback()
```

Register the engine fallback sky material and install it as the
engine-level fallback (rendered when a scene has no sky entity).
Idempotent; requires a live renderer — the scene loader calls it.

```lua
sky.installFallback()
```

## modules/sky/preset {#modules-sky-preset}

```lua
preset(name: string)
```

Apply a named sky preset. Available: `clear_day`, `sunset`,
`sunrise`, `overcast`, `night`, `studio`, `none`. Raises a Luau
error for unrecognized names — wrap in `pcall` if uncertain.

**Parameters**

- `name` `string` — Preset name (case-sensitive).

```lua
sky.preset("sunset")
```

## modules/sky/set {#modules-sky-set}

```lua
set(opts: SkyOpts)
```

Configure the sky system. All fields are optional — only
provided fields are updated. Color fields accept both named
`{x=r, y=g, z=b}` and positional `{r, g, b}` forms. `color` is
an alias for `solid_color`.

**Parameters**

- `opts` `SkyOpts` — Sky configuration properties.

```lua
sky.set({ type = "procedural", time_of_day = 14, sync_sun_to_light = true })
```

## modules/sky/setSunDirection {#modules-sky-setsundirection}

```lua
setSunDirection(dir: SkyColor)
```

Set an explicit sun direction and disable time-based sun
positioning. The directional light is updated to match.

**Parameters**

- `dir` `SkyColor` — Normalized sun direction vector.

```lua
sky.setSunDirection({ 0.5, -1, 0.3 })
```

## modules/sky/setTimeOfDay {#modules-sky-settimeofday}

```lua
setTimeOfDay(time: number)
```

Set the time of day (0-24 hours). 0 = midnight, 6 = sunrise,
12 = noon, 18 = sunset.

**Parameters**

- `time` `number` — Time of day in hours.

```lua
sky.setTimeOfDay(18.5)
```

## typed/builtin//modules/api/engine/sky/sky/get {#typed-builtin-modules-api-engine-sky-sky-get}

```lua
sky.get() -> { [string]: any }
```

Get all current sky configuration as a table. Returns the
same fields as `sky.set` accepts, plus read-only fields like
`material_name` and `type`. Color values are returned as
positional arrays `[r, g, b]`.

## typed/builtin//modules/api/engine/sky/sky/getTimeOfDay {#typed-builtin-modules-api-engine-sky-sky-gettimeofday}

```lua
sky.getTimeOfDay() -> number
```

Get the current time of day in hours (0-24).

**Returns** `number` — Current time of day.

```lua
local t = sky.getTimeOfDay()
```

## typed/builtin//modules/api/engine/sky/sky/preset {#typed-builtin-modules-api-engine-sky-sky-preset}

```lua
sky.preset(name: string)
```

Apply a named sky preset. Available: `clear_day`, `sunset`,
`sunrise`, `overcast`, `night`, `studio`, `none`. Raises a Luau
error for unrecognized names — wrap in `pcall` if uncertain.

**Parameters**

- `name` `string` — Preset name (case-sensitive).

```lua
sky.preset("sunset")
```

## typed/builtin//modules/api/engine/sky/sky/set {#typed-builtin-modules-api-engine-sky-sky-set}

```lua
sky.set(opts: SkyOpts)
```

Configure the sky system. All fields are optional — only
provided fields are updated. Color fields accept both named
`{x=r, y=g, z=b}` and positional `{r, g, b}` forms. `color` is
an alias for `solid_color`.

## typed/builtin//modules/api/engine/sky/sky/setSunDirection {#typed-builtin-modules-api-engine-sky-sky-setsundirection}

```lua
sky.setSunDirection(dir: SkyColor)
```

Set an explicit sun direction and disable time-based sun
positioning. The directional light is updated to match.

**Parameters**

- `dir` `SkyColor` — Normalized sun direction vector.

```lua
sky.setSunDirection({ 0.5, -1, 0.3 })
```

## typed/builtin//modules/api/engine/sky/sky/setTimeOfDay {#typed-builtin-modules-api-engine-sky-sky-settimeofday}

```lua
sky.setTimeOfDay(time: number)
```

Set the time of day (0-24 hours). 0 = midnight, 6 = sunrise,
12 = noon, 18 = sunset.

**Parameters**

- `time` `number` — Time of day in hours.

```lua
sky.setTimeOfDay(18.5)
```