Screen Module

The Screen module provides utility functions for controlling screen fade effects in RedM.

Getting Started

local Screen = exports.bln_lib:screen()

Methods

screen.fadeIn

Fade the screen in from black.

Screen.screen.fadeIn(duration, needWait)

Parameters

• duration (number, optional): Fade duration in milliseconds (default: 500)
• needWait (boolean, optional): Wait for fade to complete before continuing

Example

-- Simple fade in
Screen.screen.fadeIn()

-- Custom duration
Screen.screen.fadeIn(1000)

-- Wait for completion
Screen.screen.fadeIn(1000, true)

screen.fadeOut

Fade the screen out to black.

Screen.screen.fadeOut(duration, needWait)

Parameters

• duration (number, optional): Fade duration in milliseconds (default: 500)
• needWait (boolean, optional): Wait for fade to complete before continuing (default: true)

Example

-- Simple fade out
Screen.screen.fadeOut()

-- Custom duration
Screen.screen.fadeOut(1000)

-- Don't wait for completion
Screen.screen.fadeOut(1000, false)

Common Use Cases

Scene Transitions

-- Teleport player with fade effect
function TeleportPlayer(coords)
    -- Fade out
    Screen.screen.fadeOut(1000)
    
    -- Teleport
    SetEntityCoords(PlayerPedId(), coords)
    
    -- Fade back in
    Screen.screen.fadeIn(1000)
end

Cutscene Control

-- Start cutscene with fade
function StartCustomCutscene()
    -- Fade out
    Screen.screen.fadeOut()
    
    -- Setup cutscene
    PrepareCustomCutscene()
    
    -- Start cutscene and fade in
    StartCustomCutscene()
    Screen.screen.fadeIn(2000)
end

Loading Screens

-- Show loading screen
function ShowLoadingScreen()
    -- Fade out to black
    Screen.screen.fadeOut(500, true)
    
    -- Show loading text/spinner
    ShowLoadingPrompt()
    
    -- Do loading tasks
    LoadResources()
    
    -- Hide loading and fade in
    HideLoadingPrompt()
    Screen.screen.fadeIn(1000)
end

Interior/Exterior Transitions

-- Enter building
function EnterBuilding(interior)
    -- Fade out
    Screen.screen.fadeOut(1000, true)
    
    -- Load interior and teleport
    LoadInterior(interior.id)
    SetEntityCoords(PlayerPedId(), interior.coords)
    
    -- Fade in
    Screen.screen.fadeIn(1000)
end

Best Practices

1. Use Appropriate Durations

-- Quick transitions
Screen.screen.fadeOut(500)  -- Half second

-- Dramatic effect
Screen.screen.fadeOut(2000) -- Two seconds

2. Wait When Needed

-- Wait when doing post-fade actions
Screen.screen.fadeOut(1000, true)
DoSomething() -- This will run after fade completes

-- Don't wait when fade timing isn't critical
Screen.screen.fadeOut(1000, false)
DoSomething() -- This will run immediately

3. Error Handling

function SafeFadeAndTeleport(coords)
    if not coords then return end
    
    Screen.screen.fadeOut(1000, true)
    
    -- Ensure coordinates are valid
    if type(coords) == "vector3" then
        SetEntityCoords(PlayerPedId(), coords)
        Screen.screen.fadeIn(1000)
    else
        -- Fade back in if something went wrong
        Screen.screen.fadeIn(500)
    end
end

4. Resource Management

-- Clean up any ongoing effects when resource stops
AddEventHandler('onResourceStop', function(resourceName)
    if GetCurrentResourceName() ~= resourceName then return end
    
    -- Ensure screen is faded in when resource stops
    Screen.screen.fadeIn(0)
end)

Performance Considerations

1. Long fade durations with needWait create a blocking operation
2. Use shorter durations for frequent transitions
3. Consider using needWait = false for non-critical fade effects

Common Issues and Solutions

1. Black Screen Stuck

-- Force screen to fade in
Screen.screen.fadeIn(0)

2. Fade Timing Issues

-- Ensure proper sequencing
async function SafeTransition()
    await Screen.screen.fadeOut(1000, true)
    -- Safe to perform transition
    await Screen.screen.fadeIn(1000, true)
end