Fade Screen

Screen fade transition system - fade to/from black with optional loading screen content.

Overview

ui_fadeScreen provides fade-to-black and fade-from-black transitions used during level loading, mission starts, and scene changes. It communicates with the UI via LoadingScreen guihook and manages global audio fading.

Extension path: lua/ge/extensions/ui/fadeScreen.lua

Exports (M)

Internals

Fade To Black

local function fadeToBlack(fade, screenData, args)
  fade = fade or 1
  guihooks.trigger("LoadingScreen", {
    active = true,
    custom = {
      fadeIn = fade,
      pause = -1,        -- infinite pause (stays black)
      fadeOut = 0,
      data = screenData  -- optional {image, title, text}
    }
  })
  -- Audio fade
  SFXSystem.setGlobalParameter("g_FadeTimeMS", fade * 1000)
  SFXSystem.setGlobalParameter("g_GameLoading", 1)
end

Fade From Black

local function fadeFromBlack(fade, args)
  fade = fade or 1
  guihooks.trigger("LoadingScreen", {
    active = false,
    custom = { fadeOut = fade }
  })
  SFXSystem.setGlobalParameter("g_FadeTimeMS", fade * 1000)
  SFXSystem.setGlobalParameter("g_GameLoading", 0)
end

Fade Sequence

A full cycle (fade in → pause → fade out):

ui_fadeScreen.cycle(1, 2, 1, {title = "Loading..."})
-- Fades to black in 1s, pauses 2s, fades back in 1s

The pause phase triggers onScreenFadeState(1) → delayed callback → onScreenFadeState(2) → auto-calls fadeFromBlack.

Frame Delay

State transitions are delayed by delayFrames (default 3) to ensure the screen is fully black before proceeding:

local function onGuiUpdate()
  if delayedData[1] then
    if delayCounter <= 0 then
      for _, state in ipairs(delayedData) do
        extensions.hook("onScreenFadeState", state)
      end
    end
    delayCounter = delayCounter - 1
  end
end

Audio Integration

Both fadeToBlack and fadeFromBlack control global audio:

• g_FadeTimeMS - Fade duration in milliseconds
• g_GameLoading - 1 = mute during fade, 0 = unmute

Can be disabled with args.useGlobalAudioFade = false.

Headless Mode

In headless mode, fade states are triggered immediately without UI:

if headless_mode then
  extensions.hook("onScreenFadeState", 1)
end

onScreenFadeState Hook

Other extensions can listen for fade state changes by implementing onScreenFadeState in their own module (this is a hook, not an export of fadeScreen):

-- Usage in your extension:
local function onScreenFadeState(state)
  if state == 2 then
    -- Screen is fully black - safe to do visual changes
    -- (teleport, swap vehicles, change scene)
    doHiddenWork()
  end
end
M.onScreenFadeState = onScreenFadeState

Real-world examples from source:

• career/modules/inventory.lua - Swaps vehicles while screen is black
• core/recoveryPrompt.lua - Teleports vehicle during recovery
• ui/vehicleSelector/vehicleOperations.lua - Spawns/changes vehicles

How It Works

1. System calls fadeToBlack(1) to start a 1-second fade
2. UI receives LoadingScreen guihook and renders the fade overlay
3. When fully black, UI triggers onScreenFadeStateDelayed(2) callback
4. After 3 frame delay, onScreenFadeState(2) hook fires for gameplay code
5. For sequences, fadeFromBlack is auto-called after the pause phase

Additional Exports

The following exports are available but not yet documented in detail:

• M.cycle
• M.delayFrames
• M.fadeFromBlack
• M.fadeSequence
• M.fadeToBlack
• M.onGuiUpdate
• M.onScreenFadeStateDelayed
• M.start
• M.stop