Screen Fade Effects

<#

    A fully customisable, general purpose screen fade 
    effect which can be used for transitions, status 
    effects, death screens, flashbangs, ect..
    
    Includes two visual effects settings:
        FadeInOut
            fron InitialOpacity to FinalOpacity and back again
            this is the default effect for the device

        FadeTo
            from InitialOpacity to FinalOpacity and will need
            to be enabled on the device properties via the tickbox

    HideHUD Warning
        Be aware that UEFN's API does NOT support the ability to
        change the HUD for a specific player. This can only be done
        for specific classes, teams or everyone at once. Therefore
        do not use this feature except in single player games.

#>

using { /Fortnite.com/Devices }
using { /Verse.org/Simulation }
using { /UnrealEngine.com/Temporary/Diagnostics }

#imports
using { /UnrealEngine.com/Temporary/UI }
using { /Fortnite.com/UI }
using { /Verse.org/Colors }
using { /UnrealEngine.com/Temporary/SpatialMath }
using { /Verse.org/Assets }
using { /Fortnite.com/Characters }
using {EZUI}

EZ_FadeScreenFX := class () 
{

    EZ_LinkedCreativeDevice<public> : ez_ui_fadescreenfx    # a backreference to the device that created this EZUI class
    EZ_LinkedPlayer<public> : player                        # the player linked to this instance of the EZUI class
    EZ_UI_ID<public> : int                                  # used to control what UI is initialised by the class

    EZ_FadeFXColor<public> : color                          # the screen effect color
    EZ_InitialOpacity<public> : float                       # initial opacity
    EZ_FinalOpacity<public> : float                         # final opacity

    EZ_FadeInDuration : float                               # duration  (seconds) from initial to final opacity
    EZ_FadeHoldDuration : float                             # duration (seconds) of the widget being at final opacity
    EZ_FadeOutDuration : float                              # duration (seconds) from final to initial opacity for the FadeInout effect

    EZ_ZOrder : int                                         # the Z-Order of the effect for controlling what UI layers are covered by it

    EZ_DisablePlayerMovement : logic                        # if the player is to be immobilised during the vfx or not (useful for transitions, cutscenes ,ect..)
    EZ_HideHUD : logic                                      # hides and then restores the HUD during the effect. ONLY USE THIS IN SINGLE PLAYER!
    
    var IsInitialized<private> : logic = false              # a lock to prevent recreating the canvas after the first execution of Initialize()
    var MainCanvas<private> : canvas = canvas{}             # the canvas that holds all the screen elements and will be added to the PlayerUI

    AnchorFullscreen : anchors = anchors{Minimum := vector2{X := 0.0,Y := 0.0},Maximum := vector2{X := 1.0,Y := 1.0}}
    NoOffset : margin = margin{Top := 0.0, Left := 0.0, Right := 0.0, Bottom := 0.0}
    AlignCentre : vector2 = vector2{X := 0.5, Y := 0.5}

    ScreenFXWidget<private> : color_block = color_block
    {
        DefaultColor := color{R := 1.0, G := 1.0, B := 1.0}
    }


    # do all the things
    Ini<public>() : void =
        if (IsInitialized?): 
            return

        ScreenFX()
       
    #.........................
    
    OpenUI<public>() : void =

        if (EZ_DisablePlayerMovement?):
            DisablePlayerControls()
        
        if (EZ_HideHUD?):
            SetHUDVisibility(false)

        EZUI.InsertWidget (EZ_LinkedPlayer,GetMainCanvas())
        spawn{BeginVFX()}


    CloseUI<public>() : void =

        EZUI.DeleteWidget(EZ_LinkedPlayer,GetMainCanvas())
        set IsInitialized = false

        if (EZ_HideHUD?):
            SetHUDVisibility(true)

        if (EZ_DisablePlayerMovement?):
            RestorePlayerControls()

    #.........................

    GetMainCanvas<public>() : canvas = MainCanvas
    GetFXWidget<public>() : color_block = ScreenFXWidget

    #.........................

    # Builds a canvas
    ScreenFX <private>() : void =
        
        UI_ZOrder: type{_X:int where 0 <= _X, _X <= 2147483647 } = type{_X:int where 0 <= _X, _X <= 2147483647 }[EZ_ZOrder] or Err("Should be unfailable")
        set MainCanvas = canvas
        {
            Slots := array
                {
                    canvas_slot
                    {
                        Anchors := anchors{Minimum := vector2{X := 0.0,Y := 0.0},Maximum := vector2{X := 1.0,Y := 1.0}}
                        Offsets := margin{Top := 0.0, Left := 0.0, Right := 0.0, Bottom := 0.0}
                        Alignment := vector2{X := 0.5, Y := 0.5}
                        ZOrder := UI_ZOrder
                        SizeToContent := true
                        Widget := ScreenFXWidget
                    }

                }
        }
        
        set IsInitialized = true # Lock the inialization state to prevent from running this function again

    #.........................

    BeginVFX <private>()<suspends> : void =

        if(EZ_UI_ID = 1): #FadeIn/Out
            EZUI.FadeVFX(GetFXWidget(), EZ_FadeFXColor, EZ_InitialOpacity, EZ_FinalOpacity, EZ_FadeInDuration)
            Sleep(EZ_FadeInDuration + EZ_FadeHoldDuration)
            EZUI.FadeVFX(GetFXWidget(), EZ_FadeFXColor, EZ_FinalOpacity, EZ_InitialOpacity, EZ_FadeOutDuration)
            CloseUI()

        if(EZ_UI_ID = 2): #FadeTo
            EZUI.FadeVFX(GetFXWidget(), EZ_FadeFXColor, EZ_InitialOpacity, EZ_FinalOpacity, EZ_FadeInDuration)
            Sleep(EZ_FadeInDuration + EZ_FadeHoldDuration)
            CloseUI()

    #.........................

    DisablePlayerControls() : void =
        if(PlayerAgent := agent[EZ_LinkedPlayer]):
            PlayerCharacter := PlayerAgent.GetFortCharacter[] or Err("[EZUI] : DisablePlayerControls()  - Should be unfailable")
            PlayerCharacter.PutInStasis(stasis_args{})

    RestorePlayerControls() : void =
        if(PlayerAgent := agent[EZ_LinkedPlayer]):
            PlayerCharacter := PlayerAgent.GetFortCharacter[] or Err("[EZUI] : RestorePlayerControls()  - Should be unfailable")
            PlayerCharacter.ReleaseFromStasis()

    #.........................

    # not currently supported by the UEFN API on a per player basis
    SetHUDVisibility( ShowHUD : logic) : void = 

        # you may not use all HUD elements in your game so adjust this list as needed
        ActiveHUDElementsList  := array:
            player_hud_identifier_all{}
            creative_hud_identifier_build_menu{}
            creative_hud_identifier_crafting_resources{}
            creative_hud_identifier_elimination_counter{}
            creative_hud_identifier_equipped_item{}
            creative_hud_identifier_experience_level{}
            creative_hud_identifier_experience_supercharged{}
            creative_hud_identifier_experience_ui{}
            creative_hud_identifier_health{}
            creative_hud_identifier_health_numbers{}
            creative_hud_identifier_hud_info{}
            creative_hud_identifier_interaction_prompts{}
            creative_hud_identifier_map_prompts{}
            creative_hud_identifier_mimimap{}
            creative_hud_identifier_pickup_stream{}
            creative_hud_identifier_player_count{}
            creative_hud_identifier_player_inventory{}
            creative_hud_identifier_round_info{}
            creative_hud_identifier_round_timer{}
            creative_hud_identifier_shield_numbers{}
            creative_hud_identifier_shileds{}
            creative_hud_identifier_shields{}
            creative_hud_identifier_storm_notifications{}
            creative_hud_identifier_storm_timer{}
            creative_hud_identifier_team_info{}
            hud_identifier_world_resource_wood{}
            hud_identifier_world_resource_stone{}
            hud_identifier_world_resource_metal{}
            hud_identifier_world_resource_permanite{}
            hud_identifier_world_resource_gold_currency{}
            hud_identifier_world_resource_ingredient{}

        
        if (ShowHUD?): 
            EZUI.GetMyHUDController(EZ_LinkedCreativeDevice).ShowElements(ActiveHUDElementsList)
        else:
            EZUI.GetMyHUDController(EZ_LinkedCreativeDevice).HideElements(ActiveHUDElementsList)


    #.........................

         

} # END EZ_FadeScreenFX ------------------------------------------------------------------------------------------------------------------------------------

ez_ui_fadescreenfx := class(creative_device):

    @editable ShowUITrigger : trigger_device = trigger_device {}
    @editable FadeTo : logic = false

    @editable FadeFXColor : color = color{R := 0.0, G := 0.0, B := 0.0}
    @editable InitialOpacity : float = 0.0
    @editable FinalOpacity : float = 1.0

    @editable FadeInDuration : float = 1.0
    @editable FadeHoldDuration : float = 1.0
    @editable FadeOutDuration : float = 1.0

    @editable ZOrder : int = 99

    @editable DisablePlayerMovement : logic = true
    @editable HideHUD : logic = false


    # UI regisitration
    var PlayerToUIMap : [player]EZ_FadeScreenFX = map{} #[playerdata]/ez_ui class


    OnBegin<override>()<suspends> : void =
        ShowUITrigger.TriggeredEvent.Subscribe(OpenUI)

    # all the steps needed to open the Pop Up
    OpenUI<private>(MaybePlayer : ?agent) : void = 
    {
    
        # check that the event was triggered by a player and stop if it wasn't
        Result := EZUI.IsAPlayer(MaybePlayer,Self)
        if (Result = false):
            return
        #.........................


        # ui fx selected by a UI ID number
        var UI_ID : int = 1 ; # defaults to FadeIn/Out effect

        if (FadeTo?): 
            set UI_ID = 2

        #.........................

        if(PlayerAgent := MaybePlayer?): #set the typing to agent from ?agent

            # Verify if an Linked pop-up manager already exists and uses it, if not, create a new one
            if ( InteractingPlayer := player[PlayerAgent] ) 
            {   
                var OptPlayerUI :?EZ_FadeScreenFX = false
        
                if (ThisPlayerUI := PlayerToUIMap[InteractingPlayer])
                { set OptPlayerUI = option{ThisPlayerUI} }
                    
                else if (ThisPlayerUI := set PlayerToUIMap[InteractingPlayer] = EZ_FadeScreenFX

                            #everything that is passed to the pop-up manager
                            { 
                                EZ_LinkedPlayer := InteractingPlayer,
                                EZ_LinkedCreativeDevice := Self, 
                                EZ_UI_ID := UI_ID,

                                EZ_FadeFXColor := FadeFXColor,
                                EZ_InitialOpacity := InitialOpacity,
                                EZ_FinalOpacity := FinalOpacity,

                                EZ_FadeInDuration := FadeInDuration,
                                EZ_FadeHoldDuration := FadeHoldDuration,
                                EZ_FadeOutDuration := FadeOutDuration,
                                EZ_ZOrder := ZOrder,

                                EZ_DisablePlayerMovement := DisablePlayerMovement,
                                EZ_HideHUD := HideHUD


                            }
                        ) 
                    
                { ThisPlayerUI.Ini(), set OptPlayerUI = option{ThisPlayerUI} }
        
                # Try to open the Interface for the player
                if (PlayerUI := OptPlayerUI?):
                    PlayerUI.OpenUI()
                else 
                    { Print("Error when getting saved or creating ThisPlayerUI") }
            }
        #.........................
    }



<#
    a special thamks to: 
        Mayapple
        SprinterMax
        Daigorō
        UEFN Discord community

    ****************************************************************************************
    Made with EZUI, please follow @kryyative on Instagram Threads and @KryyssX on X (Twitter)
    for more useful Snippets, UEFN & UE5 news,tutorials and community spotlights!
    ****************************************************************************************

    If you found EZUI useful please include the text above in your credits to show your support
    for my work and encourage others to use EZUI for their projects. Thank you! ^_^
#>