MassProcessor.h

Go to the documentation of this file.

// Copyright Epic Games, Inc. All Rights Reserved.
 
#pragma once
 
#if UE_ENABLE_INCLUDE_ORDER_DEPRECATED_IN_5_6
#include "CoreMinimal.h"
#include "MassEntityManager.h"
#endif // UE_ENABLE_INCLUDE_ORDER_DEPRECATED_IN_5_6
#include "MassProcessingTypes.h"
#include "Async/TaskGraphInterfaces.h"
#include "MassCommandBuffer.h"
#include "MassRequirements.h"
#include "MassProcessor.generated.h"
 
 
#define UE_API MASSENTITY_API
 
struct FMassProcessingPhaseConfig;
class UMassCompositeProcessor;
struct FMassDebugger;
struct FMassEntityQuery;
struct FMassEntityManager;
struct FMassExecutionContext;
struct FMassExecutionRequirements;
struct FMassSubsystemRequirements;
namespace UE::Mass
{
    struct FQueryExecutor;
}
 
enum class EProcessorCompletionStatus : uint8
{
    Invalid,
    Threaded,
    Postponed,
    Done
};
 
USTRUCT()
struct FMassProcessorExecutionOrder
{
    GENERATED_BODY()
 
    
    UPROPERTY(EditAnywhere, Category = Processor, config)
    FName ExecuteInGroup = FName();
 
    UPROPERTY(EditAnywhere, Category = Processor, config)
    TArray<FName> ExecuteBefore;
 
    UPROPERTY(EditAnywhere, Category = Processor, config)
    TArray<FName> ExecuteAfter;
};
 
UENUM()
enum class EActivationState : uint8
{
    Inactive,
    Active,
    OneShot,    // one-shot processor will auto-disable itself after the next CallExecute call
};
 
UENUM()
enum class EMassQueryBasedPruning : uint8
{
    Prune,      // pruning will always be applied at runtime
    Never,      // pruning will never be applied at runtime
    Default = Prune
};
 
UCLASS(abstract, EditInlineNew, CollapseCategories, config = Mass, defaultconfig, ConfigDoNotCheckDefaults, MinimalAPI)
class UMassProcessor : public UObject
{
    GENERATED_BODY()
 
public:
 
    UE_API UMassProcessor();
    UE_API explicit UMassProcessor(const FObjectInitializer& ObjectInitializer);
 
    bool IsInitialized() const;
 
    UE_API void CallInitialize(const TNotNull<UObject*> Owner, const TSharedRef<FMassEntityManager>& EntityManager);
    
    UE_API virtual FGraphEventRef DispatchProcessorTasks(const TSharedPtr<FMassEntityManager>& EntityManager, FMassExecutionContext& ExecutionContext, const FGraphEventArray& Prerequisites = FGraphEventArray());
 
    EProcessorExecutionFlags GetExecutionFlags() const;
 
    bool ShouldExecute(const EProcessorExecutionFlags CurrentExecutionFlags) const;
    UE_API void CallExecute(FMassEntityManager& EntityManager, FMassExecutionContext& Context);
 
    bool ShouldAllowMultipleInstances() const;
 
    void DebugOutputDescription(FOutputDevice& Ar) const;
    UE_API virtual void DebugOutputDescription(FOutputDevice& Ar, int32 Indent) const;
    UE_API virtual FString GetProcessorName() const;
    
    //----------------------------------------------------------------------//
    // Ordering functions 
    //----------------------------------------------------------------------//
    UE_API virtual bool ShouldAllowQueryBasedPruning(const bool bRuntimeMode = true) const;
 
    UE_API virtual EMassProcessingPhase GetProcessingPhase() const;
    UE_API virtual void SetProcessingPhase(EMassProcessingPhase Phase);
    bool DoesRequireGameThreadExecution() const;
    
    const FMassProcessorExecutionOrder& GetExecutionOrder() const;
 
    UE_API virtual void ExportRequirements(FMassExecutionRequirements& OutRequirements) const;
 
    const FMassSubsystemRequirements& GetProcessorRequirements() const;
 
    int16 GetExecutionPriority() const;
 
    void SetExecutionPriority(const int16 NewExecutionPriority);
 
    UE_API void RegisterQuery(FMassEntityQuery& Query);
 
    void MarkAsDynamic();
    bool IsDynamic() const;
 
    void MakeActive();
    void MakeOneShot();
    void MakeInactive();
 
    bool IsActive() const;
 
    bool ShouldAutoAddToGlobalList() const;
#if WITH_EDITOR
    bool ShouldShowUpInSettings() const;
#endif // WITH_EDITOR
 
    UE_API void SetShouldAutoRegisterWithGlobalList(const bool bAutoRegister);
 
    UE_API void GetArchetypesMatchingOwnedQueries(const FMassEntityManager& EntityManager, TArray<FMassArchetypeHandle>& OutArchetype);
    UE_API bool DoesAnyArchetypeMatchOwnedQueries(const FMassEntityManager& EntityManager);
    int32 GetOwnedQueriesNum() const;
    
#if CPUPROFILERTRACE_ENABLED
    FString StatId;
#endif
    
protected:
    UE_API virtual void InitializeInternal(UObject& Owner, const TSharedRef<FMassEntityManager>& EntityManager);
 
    UE_API virtual void ConfigureQueries(const TSharedRef<FMassEntityManager>& EntityManager);
 
    UE_API virtual void PostInitProperties() override;
 
    UE_API virtual void Execute(FMassEntityManager& EntityManager, FMassExecutionContext& Context);
 
protected:
    UPROPERTY(EditDefaultsOnly, Category = Processor, config)
    FMassProcessorExecutionOrder ExecutionOrder;
 
    UPROPERTY(EditDefaultsOnly, Category = Processor, config)
    EMassProcessingPhase ProcessingPhase = EMassProcessingPhase::PrePhysics;
 
    UPROPERTY(EditAnywhere, Category = "Pipeline", meta = (Bitmask, BitmaskEnum = "/Script/MassEntity.EProcessorExecutionFlags"), config)
    uint8 ExecutionFlags;
 
    UPROPERTY(EditDefaultsOnly, Category = Processor, config)
    uint8 bAutoRegisterWithProcessingPhases : 1 = true;
 
    uint8 bAllowMultipleInstances : 1 = false;
 
    UPROPERTY(EditDefaultsOnly, Category = Processor, config)
    uint8 bRequiresGameThreadExecution : 1 = false;
 
#if WITH_EDITORONLY_DATA
    UPROPERTY(config)
    uint8 bCanShowUpInSettings : 1 = true;
#endif // WITH_EDITORONLY_DATA
 
private:
    uint8 bIsDynamic : 1 = false;
 
    uint8 bInitialized : 1 = false;
 
    UPROPERTY(EditDefaultsOnly, Category = Processor, config)
    EActivationState ActivationState = EActivationState::Active;
 
protected:
    UPROPERTY(EditDefaultsOnly, Category = Processor, config)
    int16 ExecutionPriority = 0;
 
    EMassQueryBasedPruning QueryBasedPruning = EMassQueryBasedPruning::Default;
 
    friend UMassCompositeProcessor;
    friend FMassDebugger;
 
    FMassSubsystemRequirements ProcessorRequirements;
 
    TSharedPtr<UE::Mass::FQueryExecutor> AutoExecuteQuery;
 
private:
    TArray<FMassEntityQuery*> OwnedQueries;
 
#if WITH_MASSENTITY_DEBUG
    FString DebugDescription;
#endif
 
    //-----------------------------------------------------------------------------
    // DEPRECATED
    //-----------------------------------------------------------------------------
public:
    UE_DEPRECATED(5.6, "Initialize is deprecated. Override InitializeInternal(UObject&, const TSharedRef<FMassEntityManager>&) instead. If you want to call the function, use CallInitialize.")
    UE_API virtual void Initialize(UObject& Owner) final;
    UE_DEPRECATED(5.6, "This flavor of ConfigureQueries is deprecated. Override ConfigureQueries(const TSharedRef<FMassEntityManager>&) instead.")
    virtual void ConfigureQueries() final {};
};
 
 
UCLASS(MinimalAPI)
class UMassCompositeProcessor : public UMassProcessor
{
    GENERATED_BODY()
 
    friend FMassDebugger;
public:
    struct FDependencyNode
    {
        FName Name;
        UMassProcessor* Processor = nullptr;
        TArray<int32> Dependencies;
#if WITH_MASSENTITY_DEBUG
        int32 SequenceIndex = INDEX_NONE;
#endif // WITH_MASSENTITY_DEBUG
    };
 
public:
    UE_API UMassCompositeProcessor();
 
    UE_API void SetChildProcessors(TArrayView<UMassProcessor*> InProcessors);
    UE_API void SetChildProcessors(TArray<TObjectPtr<UMassProcessor>>&& InProcessors);
 
    UE_API virtual void InitializeInternal(UObject& Owner, const TSharedRef<FMassEntityManager>& InEntityManager) override;
    UE_API virtual void DebugOutputDescription(FOutputDevice& Ar, int32 Indent = 0) const override;
    UE_API virtual void SetProcessingPhase(EMassProcessingPhase Phase) override;
 
    UE_API void SetGroupName(FName NewName);
    FName GetGroupName() const;
 
    UE_API virtual void SetProcessors(TArrayView<UMassProcessor*> InProcessorInstances, const TSharedPtr<FMassEntityManager>& EntityManager = nullptr);
 
    UE_API virtual void BuildFlatProcessingGraph(TConstArrayView<FMassProcessorOrderInfo> SortedProcessors);
 
    UE_API void UpdateProcessorsCollection(TArrayView<FMassProcessorOrderInfo> InOutOrderedProcessors, EProcessorExecutionFlags InWorldExecutionFlags = EProcessorExecutionFlags::None);
 
    UE_API void AddGroupedProcessor(FName RequestedGroupName, UMassProcessor& SubProcessor);
 
    UE_API virtual FGraphEventRef DispatchProcessorTasks(const TSharedPtr<FMassEntityManager>& EntityManager, FMassExecutionContext& ExecutionContext, const FGraphEventArray& Prerequisites = FGraphEventArray()) override;
 
    bool IsEmpty() const;
 
    UE_API virtual FString GetProcessorName() const override;
 
    TConstArrayView<UMassProcessor*> GetChildProcessorsView() const;
 
protected:
    UE_API virtual void ConfigureQueries(const TSharedRef<FMassEntityManager>& EntityManager) override;
    UE_API virtual void Execute(FMassEntityManager& EntityManager, FMassExecutionContext& Context) override;
 
    UE_API UMassCompositeProcessor* FindOrAddGroupProcessor(FName RequestedGroupName, FString* OutRemainingGroupName = nullptr);
 
protected:
    UPROPERTY(VisibleAnywhere, Category=Mass)
    FMassRuntimePipeline ChildPipeline;
 
    UPROPERTY()
    FName GroupName;
 
#if WITH_MASSENTITY_DEBUG
    bool bDebugLogNewProcessingGraph = false;
#endif // WITH_MASSENTITY_DEBUG
 
    TArray<FDependencyNode> FlatProcessingGraph;
 
    struct FProcessorCompletion
    {
        FGraphEventRef CompletionEvent;
        EProcessorCompletionStatus Status = EProcessorCompletionStatus::Invalid;
 
        bool IsDone() const 
        {
            return Status == EProcessorCompletionStatus::Done || (CompletionEvent.IsValid() && CompletionEvent->IsComplete());
        }
 
        void Wait()
        {
            if (CompletionEvent.IsValid())
            {
                CompletionEvent->Wait();
            }
        }
    };
    TArray<FProcessorCompletion> CompletionStatus;
 
    //-----------------------------------------------------------------------------
    // DEPRECATED
    //-----------------------------------------------------------------------------
public:
 
    /*UE_DEPRECATED(5.6, "This flavor of Initialize is deprecated. Please use the one requiring a FMassEntityManager parameter")
    virtual void Initialize(UObject& Owner) final;*/
 
    UE_DEPRECATED(5.6, "This flavor of SetChildProcessors is deprecated. Please use one of the others.")
    UE_API void SetChildProcessors(TArray<UMassProcessor*>&& InProcessors);
};
 
 
//-----------------------------------------------------------------------------
// UMassProcessor inlines
//-----------------------------------------------------------------------------
inline bool UMassProcessor::IsInitialized() const
{
    return bInitialized;
}
 
inline EProcessorExecutionFlags UMassProcessor::GetExecutionFlags() const
{
    return static_cast<EProcessorExecutionFlags>(ExecutionFlags);
}
 
inline bool UMassProcessor::ShouldExecute(const EProcessorExecutionFlags CurrentExecutionFlags) const
{
    return (GetExecutionFlags() & CurrentExecutionFlags) != EProcessorExecutionFlags::None;
}
 
inline bool UMassProcessor::ShouldAllowMultipleInstances() const
{
    return bAllowMultipleInstances;
}
 
inline int32 UMassProcessor::GetOwnedQueriesNum() const
{
    return OwnedQueries.Num();
}
 
inline void UMassProcessor::DebugOutputDescription(FOutputDevice& Ar) const
{
    DebugOutputDescription(Ar, 0);
}
 
inline bool UMassProcessor::DoesRequireGameThreadExecution() const
{
    return bRequiresGameThreadExecution;
}
    
inline const FMassProcessorExecutionOrder& UMassProcessor::GetExecutionOrder() const
{
    return ExecutionOrder;
}
 
inline const FMassSubsystemRequirements& UMassProcessor::GetProcessorRequirements() const
{
    return ProcessorRequirements;
}
 
inline int16 UMassProcessor::GetExecutionPriority() const
{
    return ExecutionPriority; 
}
 
inline void UMassProcessor::SetExecutionPriority(const int16 NewExecutionPriority)
{
    ExecutionPriority = NewExecutionPriority; 
}
 
inline void UMassProcessor::MarkAsDynamic()
{
    bIsDynamic = true;
}
 
inline bool UMassProcessor::IsDynamic() const
{
    return bIsDynamic != 0;
}
 
inline void UMassProcessor::MakeActive()
{
    ActivationState = EActivationState::Active;
}
 
inline void UMassProcessor::MakeOneShot()
{
    ActivationState = EActivationState::OneShot;
}
 
inline void UMassProcessor::MakeInactive()
{
    ActivationState = EActivationState::Inactive;
}
 
inline bool UMassProcessor::IsActive() const
{
    return ActivationState != EActivationState::Inactive;
}
 
inline bool UMassProcessor::ShouldAutoAddToGlobalList() const
{
    return bAutoRegisterWithProcessingPhases;
}
 
#if WITH_EDITOR
inline bool UMassProcessor::ShouldShowUpInSettings() const
{
    return ShouldAutoAddToGlobalList() || bCanShowUpInSettings;
}
#endif // WITH_EDITOR
 
//-----------------------------------------------------------------------------
// UMassCompositeProcessor inlines
//-----------------------------------------------------------------------------
inline FName UMassCompositeProcessor::GetGroupName() const
{
    return GroupName;
}
 
inline bool UMassCompositeProcessor::IsEmpty() const
{
    return ChildPipeline.IsEmpty();
}
 
inline TConstArrayView<UMassProcessor*> UMassCompositeProcessor::GetChildProcessorsView() const
{
    return ChildPipeline.GetProcessors();
}
 
#undef UE_API