LevelStreaming.h

Go to the documentation of this file.

// Copyright Epic Games, Inc. All Rights Reserved.
 
#pragma once
 
#include "UObject/ObjectMacros.h"
#include "UObject/Object.h"
#include "UObject/ScriptMacros.h"
#include "UObject/UObjectAnnotation.h"
#include "Engine/LatentActionManager.h"
#include "LatentActions.h"
#include "ProfilingDebugging/ProfilingHelpers.h"
#include "GameFramework/UpdateLevelVisibilityLevelInfo.h"
#include "Misc/TransactionallySafeRWLock.h"
#include "Misc/Timeout.h"
 
#if WITH_EDITOR
#include "Folder.h"
#include "Misc/Optional.h"
#endif
 
class ALevelScriptActor;
class ALevelStreamingVolume;
class ULevel;
class ULevelStreaming;
class IWorldPartitionCell;
struct FNetLevelVisibilityTransactionId;
 
enum class ENetLevelVisibilityRequest
{
    MakingVisible,
    MakingInvisible
};
 
struct FNetLevelVisibilityState
{
    TOptional<bool> ClientAckedRequestCanMakeVisible;
    TOptional<ENetLevelVisibilityRequest> PendingRequestType;
    uint32 ServerRequestIndex = 0;
    uint32 ClientPendingRequestIndex = 0;
    uint32 ClientAckedRequestIndex = 0;
    bool bHasClientPendingRequest = false;
 
    void InvalidateClientPendingRequest()
    {
        bHasClientPendingRequest = false;
        PendingRequestType.Reset();
    }
};
 
ENGINE_API DECLARE_LOG_CATEGORY_EXTERN(LogLevelStreaming, Log, All);
 
// Stream Level Action
class FStreamLevelAction : public FPendingLatentAction
{
public:
    bool            bLoading;
    bool            bMakeVisibleAfterLoad;
    bool            bShouldBlock;
    TWeakObjectPtr<ULevelStreaming> Level;
    FName           LevelName;
 
    FLatentActionInfo LatentInfo;
 
    ENGINE_API FStreamLevelAction(bool bIsLoading, const FName& InLevelName, bool bIsMakeVisibleAfterLoad, bool bShouldBlock, const FLatentActionInfo& InLatentInfo, UWorld* World);
 
    static ENGINE_API FString MakeSafeLevelName( const FName& InLevelName, UWorld* InWorld );
 
    static ENGINE_API ULevelStreaming* FindAndCacheLevelStreamingObject( const FName LevelName, UWorld* InWorld );
 
    ENGINE_API void ActivateLevel( ULevelStreaming* LevelStreamingObject );
    ENGINE_API bool UpdateLevel( ULevelStreaming* LevelStreamingObject );
 
    ENGINE_API virtual void UpdateOperation(FLatentResponse& Response) override;
 
#if WITH_EDITOR
    // Returns a human readable description of the latent operation's current state
    ENGINE_API virtual FString GetDescription() const override;
#endif
};
 
#include "LevelStreaming.generated.h"
 
// Delegate signatures
DECLARE_DYNAMIC_MULTICAST_DELEGATE( FLevelStreamingLoadedStatus );
DECLARE_DYNAMIC_MULTICAST_DELEGATE( FLevelStreamingVisibilityStatus );
 
enum class ELevelStreamingState : uint8
{
    Removed,
    Unloaded,
    FailedToLoad,
    Loading,
    LoadedNotVisible,
    MakingVisible,
    LoadedVisible,
    MakingInvisible
};
ENGINE_API const TCHAR* EnumToString(ELevelStreamingState InState);
 
enum class ELevelStreamingTargetState : uint8
{
    Unloaded,
    UnloadedAndRemoved,
    LoadedNotVisible,
    LoadedVisible,
};
ENGINE_API const TCHAR* EnumToString(ELevelStreamingTargetState InTargetState);
 
UCLASS(abstract, editinlinenew, BlueprintType, Within=World, MinimalAPI)
class ULevelStreaming : public UObject
{
    GENERATED_UCLASS_BODY()
 
    enum class UE_DEPRECATED(5.2, "ULevelStreaming::ECurrentState has been replaced by ELevelStreamingState")
    ECurrentState : uint8
    {
        Removed = (uint8)ELevelStreamingState::Removed,
        Unloaded = (uint8)ELevelStreamingState::Unloaded,
        FailedToLoad = (uint8)ELevelStreamingState::FailedToLoad,
        Loading = (uint8)ELevelStreamingState::Loading,
        LoadedNotVisible = (uint8)ELevelStreamingState::LoadedNotVisible,
        MakingVisible = (uint8)ELevelStreamingState::MakingVisible,
        LoadedVisible = (uint8)ELevelStreamingState::LoadedVisible,
        MakingInvisible = (uint8)ELevelStreamingState::MakingInvisible
    };
ENGINE_API PRAGMA_DISABLE_DEPRECATION_WARNINGS
    static const TCHAR* EnumToString(ECurrentState InCurrentState);
    friend bool operator==(ELevelStreamingState A, ECurrentState B)
    {
        return A == (ELevelStreamingState)B;
    }
    friend bool operator==(ECurrentState A, ELevelStreamingState B)
    {
        return (ELevelStreamingState)A == (ELevelStreamingState)B;
    }
    friend bool operator!=(ELevelStreamingState A, ECurrentState B)
    {
        return A != (ELevelStreamingState)B;
    }
    friend bool operator!=(ECurrentState A, ELevelStreamingState B)
    {
        return (ELevelStreamingState)A != (ELevelStreamingState)B;
    }
ENGINE_API PRAGMA_ENABLE_DEPRECATION_WARNINGS
 
    static ULevelStreaming* FindStreamingLevel(const ULevel* Level);
    static ENGINE_API void RemoveLevelAnnotation(const ULevel* Level);
 
    // Annotation for fast inverse lookup
    struct FLevelAnnotation
    {
        FLevelAnnotation() {}
        FLevelAnnotation(ULevelStreaming* InLevelStreaming) : LevelStreaming(InLevelStreaming){}
    
        inline bool IsDefault()
        {
            return !LevelStreaming;
        }
 
        ULevelStreaming* LevelStreaming = nullptr;
    };
 
    static ENGINE_API FUObjectAnnotationSparse<FLevelAnnotation, false> LevelAnnotations;
 
 
#if WITH_EDITORONLY_DATA
    UPROPERTY()
    FName PackageName_DEPRECATED;
#endif
 
protected:
    UPROPERTY(Category=LevelStreaming, VisibleAnywhere, BlueprintReadOnly, meta=(DisplayName = "Level", AllowPrivateAccess="true"))
    TSoftObjectPtr<UWorld> WorldAsset;
 
    UPROPERTY(EditAnywhere, Category = LevelStreaming, BlueprintSetter = SetPriority)
    int32 StreamingPriority;
 
private:
    TOptional<int32> StreamingPriorityOverrideBackup;
 
public:
 
    UPROPERTY()
    FName PackageNameToLoad;
 
    UPROPERTY()
    TArray<FName> LODPackageNames;
 
    TArray<FName> LODPackageNamesToLoad;
 
    UPROPERTY(EditAnywhere, Category=LevelStreaming, BlueprintReadWrite)
    FTransform LevelTransform;
 
    UPROPERTY()
    bool bClientOnlyVisible;
 
#if WITH_EDITORONLY_DATA
    UPROPERTY(Transient)
    TWeakObjectPtr<UObject> EditorPathOwner;
#endif
 
private:
 
    UPROPERTY(transient, Category = LevelStreaming, BlueprintSetter = SetLevelLODIndex)
    int32 LevelLODIndex;
 
    uint8 bIsRequestingUnloadAndRemoval:1;
 
    /* Whether CachedWorldAssetPackageFName is valid */
    mutable uint8 bHasCachedWorldAssetPackageFName:1;
 
    /* Whether CachedLoadedLevelPackageName is valid */
    mutable uint8 bHasCachedLoadedLevelPackageName:1;
 
#if WITH_EDITORONLY_DATA
    UPROPERTY()
    uint8 bShouldBeVisibleInEditor:1;
#endif
 
    UPROPERTY(Category=LevelStreaming, BlueprintSetter=SetShouldBeVisible)
    uint8 bShouldBeVisible:1;
 
protected:
    UPROPERTY(Category=LevelStreaming, BlueprintSetter=SetShouldBeLoaded, BlueprintGetter=ShouldBeLoaded)
    uint8 bShouldBeLoaded:1;
 
    uint8 bSkipClientUseMakingInvisibleTransactionRequest:1;
 
    uint8 bSkipClientUseMakingVisibleTransactionRequest:1;
 
    FPackagePath LastAsyncLoadPackagePath;
 
    TArray<int32> AsyncRequestIDs;
 
private:
    mutable FTransactionallySafeRWLock CurrentStateLock;
 
    ELevelStreamingState CurrentState;
 
    ELevelStreamingTargetState TargetState;
 
public:
 
    UPROPERTY()
    uint8 bLocked:1;
 
    UPROPERTY(EditDefaultsOnly, Category=LevelStreaming)
    uint8 bIsStatic:1;
 
    UPROPERTY(Category=LevelStreaming, BlueprintReadWrite)
    uint8 bShouldBlockOnLoad:1;
 
    UPROPERTY(Category=LevelStreaming, BlueprintReadWrite)
    uint8 bShouldBlockOnUnload:1;
 
    UPROPERTY(transient, Category=LevelStreaming, BlueprintReadWrite)
    uint8 bDisableDistanceStreaming:1;
 
    UPROPERTY(EditAnywhere, AdvancedDisplay, Category = LevelStreaming)
    uint8 bDrawOnLevelStatusMap : 1;
 
    uint8 bGarbageCollectionClusteringEnabled : 1;
 
#if WITH_EDITORONLY_DATA
    UPROPERTY()
    FColor DrawColor_DEPRECATED;
#endif
 
    UPROPERTY(EditAnywhere, Category = LevelStreaming)
    FLinearColor LevelColor;
 
    UPROPERTY(EditAnywhere, Category=LevelStreaming, meta=(DisplayName = "Streaming Volumes", NoElementDuplicate))
    TArray<TObjectPtr<ALevelStreamingVolume>> EditorStreamingVolumes;
 
    UPROPERTY(EditAnywhere, AdvancedDisplay, Category=LevelStreaming, meta=(ClampMin = "0", UIMin = "0", UIMax = "10"))
    float MinTimeBetweenVolumeUnloadRequests;
 
    float LastVolumeUnloadRequestTime;
 
#if WITH_EDITORONLY_DATA
    UPROPERTY()
    TArray<FString> Keywords;
#endif
 
    //~ Begin UObject Interface
    ENGINE_API virtual void PostLoad() override;
    ENGINE_API virtual void Serialize( FArchive& Ar ) override;
    virtual const IWorldPartitionCell* GetWorldPartitionCell() const { return nullptr; }
#if WITH_EDITOR
    ENGINE_API virtual void PostEditChangeProperty(FPropertyChangedEvent& PropertyChangedEvent) override;
    
    ENGINE_API void RemoveStreamingVolumeDuplicates();
#endif
    //~ End UObject Interface
 
PRAGMA_DISABLE_DEPRECATION_WARNINGS
    UE_DEPRECATED(5.2, "ULevelStreaming::ECurrentState has been replaced by ELevelStreamingState. Use GetLevelStreamingState instead.")
    ECurrentState GetCurrentState() const { return (ECurrentState)GetLevelStreamingState(); }
PRAGMA_ENABLE_DEPRECATION_WARNINGS
 
    ENGINE_API ELevelStreamingState GetLevelStreamingState() const;
 
protected:  
    ENGINE_API void SetCurrentState(ELevelStreamingState NewState);
 
    ENGINE_API virtual bool RequestVisibilityChange(bool bVisible);
 
    ENGINE_API bool CanMakeVisible();
 
    ENGINE_API bool CanMakeInvisible();
 
private:
 
    ENGINE_API bool ShouldClientUseMakingInvisibleTransactionRequest() const;
    ENGINE_API bool ShouldClientUseMakingVisibleTransactionRequest() const;
    ENGINE_API bool ShouldWaitForServerAckBeforeChangingVisibilityState(ENetLevelVisibilityRequest InRequestType);
    ENGINE_API void AckNetVisibilityTransaction(FNetLevelVisibilityTransactionId AckedClientTransactionId, bool bClientAckCanMakeVisible);
 
    ENGINE_API ELevelStreamingTargetState DetermineTargetState() const;
 
    ENGINE_API bool UpdateTargetState();
 
    ENGINE_API void UpdateStreamingState(bool& bOutUpdateAgain, bool& bOutRedetermineTarget, const TOptional<const UE::FTimeout>& InExternalTimeout);
 
    ENGINE_API void OnLevelAdded();
 
    ENGINE_API void OnLevelRemoved();
 
    ENGINE_API bool IsDesiredLevelLoaded() const;
 
public:
 
    ENGINE_API void BeginClientNetVisibilityRequest(bool bInShouldBeVisible);
 
    ENGINE_API bool IsWaitingForNetVisibilityTransactionAck(ENetLevelVisibilityRequest InRequestType = ENetLevelVisibilityRequest::MakingInvisible) const;
 
    ENGINE_API void UpdateNetVisibilityTransactionState(bool bInShouldBeVisible, FNetLevelVisibilityTransactionId TransactionId);
 
    bool GetShouldBeVisibleFlag() const { return bShouldBeVisible; }
 
    UFUNCTION(BlueprintSetter)
    ENGINE_API void SetShouldBeVisible(bool bInShouldBeVisible);
 
    virtual bool ShouldRequireFullVisibilityToRender() const { return LODPackageNames.Num() > 0; }
 
    virtual bool CanReplicateStreamingStatus() const { return true; }
 
    UFUNCTION(BlueprintSetter)
    ENGINE_API virtual void SetShouldBeLoaded(bool bInShouldBeLoaded);
 
    int32 GetLevelLODIndex() const { return LevelLODIndex; }
 
    UFUNCTION(BlueprintSetter)
    ENGINE_API void SetLevelLODIndex(int32 LODIndex);
 
    int32 GetPriority() const { return StreamingPriority; }
 
    UFUNCTION(BlueprintSetter)
    ENGINE_API void SetPriority(int32 NewPriority);
 
    ENGINE_API void SetPriorityOverride(int32 PriorityOverride);
 
    ENGINE_API void ResetPriorityOverride();
 
    bool HasLoadRequestPending() const { return CurrentState == ELevelStreamingState::Loading; }
 
    bool HasLoadedLevel() const
    {
        return (LoadedLevel || PendingUnloadLevel);
    }
 
    const TArray<int32>& GetAsyncRequestIDs() const
    {
        return AsyncRequestIDs; 
    }
 
    UFUNCTION(BlueprintPure, Category = LevelStreaming)
    bool GetIsRequestingUnloadAndRemoval() const { return bIsRequestingUnloadAndRemoval; }
 
    UFUNCTION(BlueprintCallable, Category = LevelStreaming)
    ENGINE_API void SetIsRequestingUnloadAndRemoval(bool bInIsRequestingUnloadAndRemoval);
 
#if WITH_EDITORONLY_DATA
    bool GetShouldBeVisibleInEditor() const { return bShouldBeVisibleInEditor; }
#endif
#if WITH_EDITOR
    ENGINE_API void SetShouldBeVisibleInEditor(bool bInShouldBeVisibleInEditor);
 
    virtual bool ShowInLevelCollection() const { return true; }
 
    virtual bool IsUserManaged() const { return true; }
#endif
 
    const TSoftObjectPtr<UWorld>& GetWorldAsset() const { return WorldAsset; }
 
    ENGINE_API virtual void SetWorldAsset(const TSoftObjectPtr<UWorld>& NewWorldAsset);
 
    ENGINE_API FString GetWorldAssetPackageName() const;
 
    UFUNCTION(BlueprintCallable, Category = "Game")
    ENGINE_API virtual FName GetWorldAssetPackageFName() const;
 
    ENGINE_API void SetWorldAssetByPackageName(FName InPackageName);
 
    ENGINE_API void RenameForPIE(int PIEInstanceID, bool bKeepWorldAssetName = false);
 
    UFUNCTION(BlueprintGetter)
    virtual bool ShouldBeLoaded() const { return true; }
 
    ENGINE_API virtual bool ShouldBeVisible() const;
 
    virtual bool ShouldBlockOnUnload() const { return bShouldBlockOnUnload; }
 
    virtual bool ShouldBeAlwaysLoaded() const { return false; }
 
    ENGINE_API FBox GetStreamingVolumeBounds();
 
    UFUNCTION(BlueprintCallable, Category="Game")
    ULevel* GetLoadedLevel() const { return LoadedLevel; }
    
    void ClearLoadedLevel() { SetLoadedLevel(nullptr); }
    
#if WITH_EDITOR
    ENGINE_API virtual void PostEditUndo() override;
#endif
    
    struct FPackageNameMatcher
    {
        FPackageNameMatcher( const FName& InPackageName )
            : PackageName( InPackageName )
        {
        }
 
        bool operator()(const ULevelStreaming* Candidate) const
        {
            return Candidate->GetWorldAssetPackageFName() == PackageName;
        }
 
        FName PackageName;
    };
 
    ENGINE_API virtual UWorld* GetWorld() const override final;
 
    ENGINE_API virtual UWorld* GetStreamingWorld() const;
 
    UFUNCTION(BlueprintCallable, Category="Game")
    ENGINE_API bool IsLevelVisible() const;
 
    UFUNCTION(BlueprintCallable, Category="Game")
    bool IsLevelLoaded() const { return (LoadedLevel != nullptr); }
 
    UFUNCTION(BlueprintCallable, Category="Game")
    ENGINE_API bool IsStreamingStatePending() const;
 
    UFUNCTION(BlueprintCallable, Category="Game")
    ENGINE_API ULevelStreaming* CreateInstance(const FString& UniqueInstanceName);
 
    UFUNCTION(BlueprintPure, meta = (BlueprintInternalUseOnly = "true"))
    ENGINE_API ALevelScriptActor* GetLevelScriptActor();
 
    ENGINE_API bool IsValidStreamingLevel() const;
 
    ENGINE_API EStreamingStatus GetLevelStreamingStatus() const;
 
    static ENGINE_API FColor GetLevelStreamingStatusColor(EStreamingStatus Status);
 
    static ENGINE_API const TCHAR* GetLevelStreamingStatusDisplayName(EStreamingStatus Status);
 
    static ENGINE_API void DebugDrawLegend(const UWorld* World, class UCanvas* Canvas, const FVector2D& Offset);
 
#if WITH_EDITOR
    ENGINE_API const FName& GetFolderPath() const;
 
    ENGINE_API void SetFolderPath(const FName& InFolderPath);
 
    ENGINE_API virtual TOptional<FFolder::FRootObject> GetFolderRootObject() const;
#endif  // WITH_EDITOR
 
    //~==============================================================================================
    // Delegates
    
    UPROPERTY(BlueprintAssignable)
    FLevelStreamingLoadedStatus         OnLevelLoaded;
    
    UPROPERTY(BlueprintAssignable)
    FLevelStreamingLoadedStatus         OnLevelUnloaded;
    
    UPROPERTY(BlueprintAssignable)
    FLevelStreamingVisibilityStatus     OnLevelShown;
    
    UPROPERTY(BlueprintAssignable)
    FLevelStreamingVisibilityStatus     OnLevelHidden;
 
    static ENGINE_API bool DefaultAllowClientUseMakingInvisibleTransactionRequests();
 
    static ENGINE_API bool DefaultAllowClientUseMakingVisibleTransactionRequests();
 
    static ENGINE_API bool ShouldServerUseMakingVisibleTransactionRequest();
 
    static ENGINE_API bool ShouldReuseUnloadedButStillAroundLevels(const ULevel* InLevel);
 
    static ENGINE_API bool AllowIncrementalRemovalWhilePendingVisibility();
 
    static ENGINE_API void BroadcastLevelLoadedStatus(UWorld* PersistentWorld, FName LevelPackageName, bool bLoaded);
    
    static ENGINE_API void BroadcastLevelVisibleStatus(UWorld* PersistentWorld, FName LevelPackageName, bool bVisible);
 
    enum EReqLevelBlock
    {
        BlockAlwaysLoadedLevelsOnly,
        AlwaysBlock,
        NeverBlock,
    };
 
#if WITH_EDITOR
    // After a sub level is reloaded in the editor the cache state needs to be refreshed
    ENGINE_API void RemoveLevelFromCollectionForReload();
    ENGINE_API void AddLevelToCollectionAfterReload();
#endif
 
protected:
    ENGINE_API virtual bool RequestLevel(UWorld* PersistentWorld, bool bAllowLevelLoadRequests, EReqLevelBlock BlockPolicy);
 
    ENGINE_API void PrepareLoadedLevel(ULevel* InLevel, UPackage* InLevelPackage, int32 InPIEInstanceID);
 
    ENGINE_API virtual void SetLoadedLevel(ULevel* Level);
 
    virtual void OnLevelLoadedChanged(ULevel* Level) {}
 
    virtual void OnCurrentStateChanged(ELevelStreamingState OldState, ELevelStreamingState NewState) {}
 
    bool ValidateUniqueWorldAsset(UWorld* PersistentWorld);
 
    ENGINE_API void OnLoadingStarted();
    ENGINE_API void OnLoadingFinished();
 
    ENGINE_API FName GetLoadedLevelPackageName() const;
 
    UPROPERTY(transient)
    TObjectPtr<class ULevel> LoadedLevel;
 
    UPROPERTY(transient)
    TObjectPtr<class ULevel> PendingUnloadLevel;
 
private:
    ENGINE_API FName GetLODPackageName() const;
 
    ENGINE_API FName GetLODPackageNameToLoad() const;
 
    ENGINE_API void DiscardPendingUnloadLevel(UWorld* PersistentWorld);
 
    ENGINE_API void AsyncLevelLoadComplete(const FName& PackageName, UPackage* LevelPackage, EAsyncLoadingResult::Type Result);
 
#if WITH_EDITORONLY_DATA
    UPROPERTY()
    FName FolderPath;
#endif  // WITH_EDITORONLY_DATA
 
    mutable FName CachedWorldAssetPackageFName;
 
    mutable FName CachedLoadedLevelPackageName;
 
    FNetLevelVisibilityState NetVisibilityState;
 
    ENGINE_API bool IsConcernedByNetVisibilityTransactionAck() const;
 
    ENGINE_API void ServerUpdateLevelVisibility(bool bIsVisible, bool bTryMakeVisible = false, FNetLevelVisibilityTransactionId TransactionId = FNetLevelVisibilityTransactionId());
 
    friend struct FAckNetVisibilityTransaction;
    friend struct FStreamingLevelPrivateAccessor;
};
 
struct FAckNetVisibilityTransaction
{
private:
    static void Call(ULevelStreaming* StreamingLevel, FNetLevelVisibilityTransactionId TransactionId, bool bClientAckCanMakeVisibleResponse)
    {
        StreamingLevel->AckNetVisibilityTransaction(TransactionId, bClientAckCanMakeVisibleResponse);
    }
    friend class APlayerController;
};
 
struct FStreamingLevelPrivateAccessor
{
private:
 
    static void SetLoadedLevel(ULevelStreaming* StreamingLevel, ULevel* Level) { StreamingLevel->SetLoadedLevel(Level); }
    static bool RequestLevel(ULevelStreaming* StreamingLevel, UWorld* PersistentWorld, bool bAllowLevelLoadRequests, ULevelStreaming::EReqLevelBlock BlockPolicy) { return StreamingLevel->RequestLevel(PersistentWorld, bAllowLevelLoadRequests, BlockPolicy); }
    static void OnLevelAdded(ULevelStreaming* StreamingLevel) { StreamingLevel->OnLevelAdded(); }
    static void OnLevelRemoved(ULevelStreaming* StreamingLevel) { StreamingLevel->OnLevelRemoved(); }
    static bool UpdateTargetState(ULevelStreaming* StreamingLevel) { return StreamingLevel->UpdateTargetState(); }
    static void UpdateStreamingState(ULevelStreaming* StreamingLevel, bool& bOutUpdateAgain, bool& bOutRedetermineTarget, const TOptional<const UE::FTimeout>& InExternalTimeout) { StreamingLevel->UpdateStreamingState(bOutUpdateAgain, bOutRedetermineTarget, InExternalTimeout); }
 
    friend class UEngine;
    friend class UWorld;
};