Lib.Screen

Last updated on

Permission screen.effects. The client gives the image back when timeoutMs expires, whatever your code does.

Spec bounds: durations 0..10000 ms, hold 0..30000 ms, timeoutMs 1000..60000 and at least 500 ms past the planned sequence (else screen_timeout_too_short), colour integer channels with alpha 255 only. Defaults: durationMs 500, holdMs 250, fadeInMs 500.

Lib.Screen.FadeOut

Starts a fade to black. The call returns before the screen is black; wait on .covered.

Lib.Screen.FadeOut(spec)

Parameters

• spec?: table — durationMs, color, timeoutMs

Returns

• Result — the transition id; .covered promise; errors invalid_screen_options, invalid_screen_color, screen_timeout_too_short

Lib.Screen.FadeIn

Brings the image back.

Lib.Screen.FadeIn(id, spec)

Parameters

• id: string — from FadeOut or Transition; do not convert it
• spec?: { durationMs }

Returns

• Result — .restored promise; error invalid_transition_id

Lib.Screen.Transition

Fade, hold and return in one call.

Lib.Screen.Transition(preset, spec)

Parameters

• preset: 'fade'
• spec?: table — durationMs, holdMs, fadeInMs, timeoutMs, color

Returns

• Result — the id; .finished promise; error unsupported_screen_preset, and the spec codes

local t = Lib.Screen.Transition('fade', { holdMs = 1000 })

Lib.Screen.Cancel

Restores the image now.

Lib.Screen.Cancel(id)

Parameters

• id: string

Returns

• Result — error invalid_transition_id

Lib.Screen.Await

Waits on .covered, .restored or .finished. Yields. A rejection's reason becomes the error code, with Why as the detail.

Lib.Screen.Await(promise)

Parameters

• promise?: table — nil answers ok at once

Returns

• Result — the state table

Lib.Screen.Why

A rejection reason as a sentence. Unknown tokens pass through.

Lib.Screen.Why(reason)

Parameters

• reason: string
  • requested, timeout, native_interrupted (a vanilla fade took priority), world_unavailable, restore_failed, resource_error, resource_stopped, never_covered (returned without ever reaching black)

Returns

• string

Lib.Screen.Black

Covers the screen, runs body, always restores. Yields. spec may be left out: Black(body).

Lib.Screen.Black(spec, body)

Parameters

• spec?: table — durationMs, color, timeoutMs, fadeInMs
• body: function

Returns

• Result — body's answer; .restored
  • screen_busy: another fade holds the slot.
  • screen_body_raised: body raised.
  • also invalid_body, invalid_screen_options

CreateThread(function()
  Lib.Screen.Black({ timeoutMs = 10000 }, function() teleportPlayer() end)
end)

Lib.Screen.IsFaded

Whether any fade, from anyone, covers the screen. Answers true when it cannot tell.

Lib.Screen.IsFaded()

Returns

• boolean

Lib.Screen.NativeState

The engine's fade state.

Lib.Screen.NativeState()

Returns

• Result — { faded, fading, out, busy, ready, remainingMs }

Lib.Screen.State

A snapshot of one of your transitions, with over added. Phases: fading_out, covered, fading_in, finished, cancelled, failed.

Lib.Screen.State(id)

Parameters

• id: string

Returns

• Result — the snapshot; error invalid_transition_id

Lib.Screen.Over

Whether a snapshot is in a terminal phase (finished, cancelled, failed), so the id can be dropped.

Lib.Screen.Over(snap)

Parameters

• snap: table

Returns

• boolean

Lib.Screen.Catalog

The presets this build supports.

Lib.Screen.Catalog()

Returns

• Result