MassDebugger.h

Go to the documentation of this file.

// Copyright Epic Games, Inc. All Rights Reserved.
 
#pragma once
 
#include "MassProcessingTypes.h"
#include "MassEntityTrace.h"
#if WITH_MASSENTITY_DEBUG
#include "Containers/ContainersFwd.h"
#include "MassDebuggerBreakpoints.h"
#include "MassEntityQuery.h"
#include "MassProcessor.h"
#include "Async/TransactionallySafeMutex.h"
#include "Logging/TokenizedMessage.h"
#include "UObject/ObjectKey.h"
#if UE_ENABLE_INCLUDE_ORDER_DEPRECATED_IN_5_6
#include "StructUtils/InstancedStruct.h"
#endif // UE_ENABLE_INCLUDE_ORDER_DEPRECATED_IN_5_6
 
class FOutputDevice;
class FStructOnScope;
class UMassProcessor;
struct FMassEntityQuery;
struct FMassEntityManager;
struct FMassArchetypeHandle;
struct FMassArchetypeChunk;
struct FMassFragmentRequirements;
struct FMassFragmentRequirementDescription;
enum class EMassFragmentAccess : uint8;
enum class EMassFragmentPresence : uint8;
#endif // WITH_MASSENTITY_DEBUG
#include "MassDebugger.generated.h"
 
namespace UE::Mass::Debug
{
    struct FArchetypeStats
    {
        int32 EntitiesCount = 0;
        int32 EntitiesCountPerChunk = 0;
        int32 ChunksCount = 0;
        SIZE_T AllocatedSize = 0;
        SIZE_T WastedEntityMemory = 0;
        SIZE_T BytesPerEntity = 0;
    };
 
    using FProcessorProviderFunction = TFunction<void(TArray<const UMassProcessor*>&)>;
} // namespace UE::Mass::Debug
 
USTRUCT()
struct FMassGenericDebugEvent
{
    GENERATED_BODY()
    explicit FMassGenericDebugEvent(const UObject* InContext = nullptr)
#if WITH_EDITORONLY_DATA
        : Context(InContext)
#endif // WITH_EDITORONLY_DATA
    {
    }
 
#if WITH_EDITORONLY_DATA
    // note that it's not a uproperty since these events are only intended to be used instantly, never stored
    const UObject* Context = nullptr;
#endif // WITH_EDITORONLY_DATA
};
 
#if WITH_MASSENTITY_DEBUG
 
namespace UE::Mass::Debug
{
    extern MASSENTITY_API bool bAllowProceduralDebuggedEntitySelection;
    extern MASSENTITY_API bool bAllowBreakOnDebuggedEntity;
    extern MASSENTITY_API bool bTestSelectedEntityAgainstProcessorQueries;
    using FArchetypeFunction = TFunction<void(FMassArchetypeHandle)>;
} // namespace UE::Mass::Debug
 
#define MASS_IF_ENTITY_DEBUGGED(Manager, EntityHandle) (FMassDebugger::GetSelectedEntity(Manager) == EntityHandle)
#define MASS_BREAK_IF_ENTITY_DEBUGGED(Manager, EntityHandle) { if (UE::Mass::Debug::bAllowBreakOnDebuggedEntity && MASS_IF_ENTITY_DEBUGGED(Manager, EntityHandle)) { PLATFORM_BREAK();} }
#define MASS_BREAK_IF_ENTITY_INDEX(EntityHandle, InIndex) { if (UE::Mass::Debug::bAllowBreakOnDebuggedEntity && EntityHandle.Index == InIndex) { PLATFORM_BREAK();} }
#define MASS_SET_ENTITY_DEBUGGED(Manager, EntityHandle) { if (UE::Mass::Debug::bAllowProceduralDebuggedEntitySelection) {FMassDebugger::SelectEntity(Manager, EntityHandle); }}
 
enum class EMassDebugMessageSeverity : uint8
{
    Error,
    Warning,
    Info,
    // the following two need to remain last
    Default,
    MAX = Default
};
 
namespace UE::Mass::Debug
{
    struct FQueryRequirementsView
    {
        TConstArrayView<FMassFragmentRequirementDescription> FragmentRequirements;
        TConstArrayView<FMassFragmentRequirementDescription> ChunkRequirements;
        TConstArrayView<FMassFragmentRequirementDescription> ConstSharedRequirements;
        TConstArrayView<FMassFragmentRequirementDescription> SharedRequirements;
        const FMassTagBitSet& RequiredAllTags;
        const FMassTagBitSet& RequiredAnyTags;
        const FMassTagBitSet& RequiredNoneTags;
        const FMassTagBitSet& RequiredOptionalTags;
        const FMassExternalSubsystemBitSet& RequiredConstSubsystems;
        const FMassExternalSubsystemBitSet& RequiredMutableSubsystems;
    };
 
    FString DebugGetFragmentAccessString(EMassFragmentAccess Access);
    MASSENTITY_API extern void DebugOutputDescription(TConstArrayView<UMassProcessor*> Processors, FOutputDevice& Ar);
 
    MASSENTITY_API extern bool HasDebugEntities();
    MASSENTITY_API extern bool IsDebuggingSingleEntity();
 
    MASSENTITY_API extern bool GetDebugEntitiesRange(int32& OutBegin, int32& OutEnd);
    MASSENTITY_API extern bool IsDebuggingEntity(FMassEntityHandle Entity, FColor* OutEntityColor = nullptr);
    MASSENTITY_API extern FColor GetEntityDebugColor(FMassEntityHandle Entity);
 
    inline EMessageSeverity::Type MassSeverityToMessageSeverity(EMessageSeverity::Type OriginalSeverity, EMassDebugMessageSeverity MassSeverity)
    {
        static constexpr EMessageSeverity::Type ConversionMap[int(EMassDebugMessageSeverity::MAX)] =
        {
            /*EMassDebugMessageSeverity::Error=*/EMessageSeverity::Error,
            /*EMassDebugMessageSeverity::Warning=*/EMessageSeverity::Warning,
            /*EMassDebugMessageSeverity::Info=*/EMessageSeverity::Info
        };
        return MassSeverity == EMassDebugMessageSeverity::Default 
            ? OriginalSeverity
            : ConversionMap[int(MassSeverity)];
    }
} // namespace UE::Mass::Debug
 
struct FMassDebugger
{
    struct FEnvironment
    {
        TWeakPtr<const FMassEntityManager> EntityManager;
        TWeakPtr<FMassEntityManager> MutableEntityManager;
        TMap<FName, UE::Mass::Debug::FProcessorProviderFunction> ProcessorProviders;
        FMassEntityHandle SelectedEntity;
        FMassEntityHandle HighlightedEntity;
 
        bool bHasBreakpoint = false;
 
        TArray<UE::Mass::Debug::FBreakpoint> Breakpoints;
 
        MASSENTITY_API UE::Mass::Debug::FBreakpoint* FindBreakpointByHandle(UE::Mass::Debug::FBreakpointHandle Handle);
 
        TSet<TObjectKey<const UMassProcessor>> ProcessorsWithBreakpoints;
        TSet<TObjectKey<const UScriptStruct>> FragmentsWithBreakpoints;
 
#if UE_MASS_TRACE_ENABLED
        FDelegateHandle TraceStartedDelegateHandle;
#endif
 
        explicit FEnvironment(FMassEntityManager& InEntityManager);
        ~FEnvironment();
 
        bool IsValid() const { return EntityManager.IsValid(); }
 
        void ClearBreakpoints();
    };
 
    DECLARE_TS_MULTICAST_DELEGATE(FOnBreakpointsChanged);
    DECLARE_TS_MULTICAST_DELEGATE_TwoParams(FOnEntitySelected, const FMassEntityManager&, const FMassEntityHandle);
    DECLARE_TS_MULTICAST_DELEGATE_OneParam(FOnMassEntityManagerEvent, const FMassEntityManager&);
    DECLARE_TS_MULTICAST_DELEGATE_OneParam(FOnEnvironmentEvent, const FEnvironment&);
    DECLARE_TS_MULTICAST_DELEGATE_ThreeParams(FOnDebugEvent, const FName /*EventName*/, FConstStructView /*Payload*/, const EMassDebugMessageSeverity /*SeverityOverride*/);
 
    static MASSENTITY_API TConstArrayView<FMassEntityQuery*> GetProcessorQueries(const UMassProcessor& Processor);
    static MASSENTITY_API TConstArrayView<FMassEntityQuery*> GetUpToDateProcessorQueries(const FMassEntityManager& EntityManager, UMassProcessor& Processor);
 
    static MASSENTITY_API UE::Mass::Debug::FQueryRequirementsView GetQueryRequirements(const FMassEntityQuery& Query);
    static MASSENTITY_API void GetQueryExecutionRequirements(const FMassEntityQuery& Query, FMassExecutionRequirements& OutExecutionRequirements);
    static MASSENTITY_API TArray<FMassEntityHandle> GetEntitiesMatchingQuery(const FMassEntityManager& EntityManager, const FMassEntityQuery& Query);
 
    static MASSENTITY_API void ForEachArchetype(const FMassEntityManager& EntityManager, const UE::Mass::Debug::FArchetypeFunction& Function);
    static MASSENTITY_API TArray<FMassArchetypeHandle> GetAllArchetypes(const FMassEntityManager& EntityManager);
    static MASSENTITY_API const FMassArchetypeCompositionDescriptor& GetArchetypeComposition(const FMassArchetypeHandle& ArchetypeHandle);
 
    static MASSENTITY_API uint64 GetArchetypeTraceID(const FMassArchetypeData& ArchetypeData);
    static MASSENTITY_API uint64 GetArchetypeTraceID(const FMassArchetypeHandle& ArchetypeHandle);
    
    static MASSENTITY_API TConstArrayView<FMassEntityHandle> GetEntitiesViewOfArchetype(
        const FMassArchetypeData& ArchetypeData,
        const FMassArchetypeChunk& Chunk);
 
    static MASSENTITY_API const FMassArchetypeData* GetArchetypeData(const FMassArchetypeHandle& ArchetypeHandle);
    static MASSENTITY_API void EnumerateChunks(const FMassArchetypeData& Archetype, TFunctionRef<void(const FMassArchetypeChunk&)> Fn);
 
    static MASSENTITY_API void GetArchetypeEntityStats(const FMassArchetypeHandle & ArchetypeHandle, UE::Mass::Debug::FArchetypeStats & OutStats);
    static MASSENTITY_API const TConstArrayView<FName> GetArchetypeDebugNames(const FMassArchetypeHandle& ArchetypeHandle);
    static MASSENTITY_API TArray<FMassEntityHandle> GetEntitiesOfArchetype(const FMassArchetypeHandle& ArchetypeHandle);
 
    static MASSENTITY_API TConstArrayView<UMassCompositeProcessor::FDependencyNode> GetProcessingGraph(const UMassCompositeProcessor& GraphOwner);
    static MASSENTITY_API TConstArrayView<TObjectPtr<UMassProcessor>> GetHostedProcessors(const UMassCompositeProcessor& GraphOwner);
    
    static MASSENTITY_API FString GetSingleRequirementDescription(const FMassFragmentRequirementDescription& Requirement);
    static MASSENTITY_API FString GetRequirementsDescription(const FMassFragmentRequirements& Requirements);
    static MASSENTITY_API FString GetArchetypeRequirementCompatibilityDescription(const FMassFragmentRequirements& Requirements, const FMassArchetypeHandle& ArchetypeHandle);
    static MASSENTITY_API FString GetArchetypeRequirementCompatibilityDescription(const FMassFragmentRequirements& Requirements, const FMassArchetypeCompositionDescriptor& ArchetypeComposition);
 
    static MASSENTITY_API void OutputArchetypeDescription(FOutputDevice& Ar, const FMassArchetypeHandle& Archetype);
    static MASSENTITY_API void OutputEntityDescription(FOutputDevice& Ar, const FMassEntityManager& EntityManager, const int32 EntityIndex, const TCHAR* InPrefix = TEXT(""));
    static MASSENTITY_API void OutputEntityDescription(FOutputDevice& Ar, const FMassEntityManager& EntityManager, const FMassEntityHandle Entity, const TCHAR* InPrefix = TEXT(""));
 
    static MASSENTITY_API void SelectEntity(const FMassEntityManager& EntityManager, const FMassEntityHandle EntityHandle);
    static MASSENTITY_API FMassEntityHandle GetSelectedEntity(const FMassEntityManager& EntityManager);
 
    static MASSENTITY_API void HighlightEntity(const FMassEntityManager& EntityManager, const FMassEntityHandle EntityHandle);
    static MASSENTITY_API FMassEntityHandle GetHighlightedEntity(const FMassEntityManager& EntityManager);
 
    static MASSENTITY_API FOnBreakpointsChanged OnBreakpointsChangedDelegate;
    static MASSENTITY_API FOnEntitySelected OnEntitySelectedDelegate;
 
    static MASSENTITY_API FOnMassEntityManagerEvent OnEntityManagerInitialized;
    static MASSENTITY_API FOnMassEntityManagerEvent OnEntityManagerDeinitialized;
    static MASSENTITY_API FOnEnvironmentEvent OnProcessorProviderRegistered;
 
    static MASSENTITY_API FOnDebugEvent OnDebugEvent;
    
    static void DebugEvent(const FName EventName, FConstStructView Payload, const EMassDebugMessageSeverity SeverityOverride = EMassDebugMessageSeverity::Default)
    {
        OnDebugEvent.Broadcast(EventName, Payload, SeverityOverride);
    }
 
    template<typename TMessage, typename... TArgs>
    static void DebugEvent(TArgs&&... InArgs)
    {
        DebugEvent(TMessage::StaticStruct()->GetFName()
            , FConstStructView::Make(TMessage(Forward<TArgs>(InArgs)...)));
    }
 
    static MASSENTITY_API int32 RegisterEntityManager(FMassEntityManager& EntityManager);
    static MASSENTITY_API void UnregisterEntityManager(FMassEntityManager& EntityManager);
    
    static MASSENTITY_API bool IsEntityManagerInitialized(const FMassEntityManager& EntityManager);
 
    static MASSENTITY_API void RegisterProcessorDataProvider(FName ProviderName, const TSharedRef<FMassEntityManager>& EntityManager, const UE::Mass::Debug::FProcessorProviderFunction& ProviderFunction);
 
    static TConstArrayView<FEnvironment> GetEnvironments() { return ActiveEnvironments; }
    static MASSENTITY_API FEnvironment* FindEnvironmentForEntityManager(const FMassEntityManager& EntityManager);
 
    static MASSENTITY_API bool DoesArchetypeMatchRequirements(const FMassArchetypeHandle& ArchetypeHandle, const FMassFragmentRequirements& Requirements, FOutputDevice& OutputDevice);
 
    static MASSENTITY_API UE::Mass::Debug::FBreakpointHandle ShouldProcessorBreak(const FMassEntityManager& EntityManager, const UMassProcessor* Processor, FMassEntityHandle Entity);
 
    static MASSENTITY_API bool HasAnyProcessorBreakpoints(const FMassEntityManager& EntityManager, const UMassProcessor* Processor);
 
    static MASSENTITY_API UE::Mass::Debug::FBreakpointHandle ShouldBreakOnFragmentWrite(const FMassEntityManager& EntityManager, const UScriptStruct* FragmentType, FMassEntityHandle Entity);
 
    static MASSENTITY_API UE::Mass::Debug::FBreakpoint* FindBreakpoint(const FMassEntityManager& EntityManager, UE::Mass::Debug::FBreakpointHandle Handle);
 
    static MASSENTITY_API TArray<UE::Mass::Debug::FBreakpoint>& GetBreakpoints(const FMassEntityManager& EntityManager);
 
    static MASSENTITY_API void RefreshBreakpoints();
 
    static MASSENTITY_API bool HasAnyFragmentWriteBreakpoints(const FMassEntityManager& EntityManager, const UScriptStruct* FragmentType = nullptr);
 
    static MASSENTITY_API UE::Mass::Debug::FBreakpoint& CreateBreakpoint(const FMassEntityManager& EntityManager);
 
    static MASSENTITY_API void SetProcessorBreakpoint(const FMassEntityManager& EntityManager, TNotNull<const UMassProcessor*>, FMassEntityHandle Entity);
 
    static MASSENTITY_API void SetFragmentWriteBreakpoint(const FMassEntityManager& EntityManager, TNotNull<const UScriptStruct*> FragmentType, FMassEntityHandle Entity);
 
    static MASSENTITY_API void SetFragmentWriteBreakForSelectedEntity(const FMassEntityManager& EntityManager, TNotNull<const UScriptStruct*> FragmentType);
 
    static MASSENTITY_API void SetBreakpointEnabled(UE::Mass::Debug::FBreakpointHandle Handle, bool bEnable);
 
    static MASSENTITY_API void ClearProcessorBreakpoint(const FMassEntityManager& EntityManager, const UMassProcessor* Processor, FMassEntityHandle Entity);
 
    static MASSENTITY_API void ClearAllProcessorBreakpoints(const FMassEntityManager& EntityManager, const UMassProcessor* Processor);
 
    static MASSENTITY_API void ClearFragmentWriteBreak(const FMassEntityManager& EntityManager, const UScriptStruct* FragmentType, FMassEntityHandle Entity);
    
    static MASSENTITY_API void ClearAllFragmentWriteBreak(const FMassEntityManager& EntityManager, const UScriptStruct* FragmentType);
 
    static MASSENTITY_API void ClearAllEntityBreakpoints(const FMassEntityManager& EntityManager, FMassEntityHandle Entity);
 
    static MASSENTITY_API void BreakOnFragmentWriteForSelectedEntity(FName FragmentName);
 
    static MASSENTITY_API const UScriptStruct* GetFragmentTypeFromName(FName FragmentName);
 
    static MASSENTITY_API TSharedPtr<FStructOnScope> GetFragmentData(const FMassEntityManager& EntityManager, const UScriptStruct* FragmentType, FMassEntityHandle Entity);
 
    static MASSENTITY_API bool GetFragmentData(const FMassEntityManager& EntityManager, const UScriptStruct* FragmentType, FMassEntityHandle Entity, TSharedPtr<FStructOnScope>& OutStructData);
 
    static MASSENTITY_API const FMassArchetypeSharedFragmentValues& GetSharedFragmentValues(const FMassEntityManager& EntityManager, FMassEntityHandle Entity);
    
    static MASSENTITY_API TSharedPtr<FStructOnScope> GetSharedFragmentData(const FMassEntityManager& EntityManager, const UScriptStruct* FragmentType, FMassEntityHandle Entity);
 
    static MASSENTITY_API bool GetSharedFragmentData(const FMassEntityManager& EntityManager, const UScriptStruct* FragmentType, FMassEntityHandle Entity, TSharedPtr<FStructOnScope>& OutStructData);
    
    static MASSENTITY_API TSharedPtr<FStructOnScope> GetConstSharedFragmentData(const FMassEntityManager& EntityManager, const UScriptStruct* FragmentType, FMassEntityHandle Entity);
 
    static MASSENTITY_API bool GetConstSharedFragmentData(const FMassEntityManager& EntityManager, const UScriptStruct* FragmentType, FMassEntityHandle Entity, TSharedPtr<FStructOnScope>& OutStructData);
 
    static MASSENTITY_API void ClearAllBreakpoints();
 
    static MASSENTITY_API void RemoveBreakpoint(UE::Mass::Debug::FBreakpointHandle Handle);
 
    static void ShutdownDebugger();
    
private:
    // @todo: contain static data in an instanced struct and setup/teardown in startup/shutdown module
    static MASSENTITY_API TArray<FEnvironment> ActiveEnvironments;
    static MASSENTITY_API UE::FTransactionallySafeMutex EntityManagerRegistrationLock;
    static MASSENTITY_API TMap<FName, const UScriptStruct*> FragmentsByName;
    static MASSENTITY_API TArray<FName> CommandNames;
 
    static MASSENTITY_API FEnvironment& GetActiveEnvironmentChecked(const FMassEntityManager& EntityManager);
    static MASSENTITY_API FEnvironment* GetActiveEnvironment(const FMassEntityManager& EntityManager);
};
 
#else
 
struct FMassArchetypeHandle;
struct FMassFragmentRequirements;
struct FMassFragmentRequirementDescription;
struct FMassArchetypeCompositionDescriptor;
 
struct FMassDebugger
{
    static FString GetSingleRequirementDescription(const FMassFragmentRequirementDescription&) { return TEXT("[no debug information]"); }
    static FString GetRequirementsDescription(const FMassFragmentRequirements&) { return TEXT("[no debug information]"); }
    static FString GetArchetypeRequirementCompatibilityDescription(const FMassFragmentRequirements&, const FMassArchetypeHandle&) { return TEXT("[no debug information]"); }
    static FString GetArchetypeRequirementCompatibilityDescription(const FMassFragmentRequirements&, const FMassArchetypeCompositionDescriptor&) { return TEXT("[no debug information]"); }
};
 
#define MASS_IF_ENTITY_DEBUGGED(a, b) false
#define MASS_BREAK_IF_ENTITY_DEBUGGED(a, b)
#define MASS_BREAK_IF_ENTITY_INDEX(a, b)
#define MASS_SET_ENTITY_DEBUGGED(a, b)
 
#endif // WITH_MASSENTITY_DEBUG