[!IMPORTANT] The way Cog integrates in your project has changed. If you update Cog, please read the integration guide.

Cog

Cog is a set of debug tools for Unreal Engine built on top of Dear ImGui

• Video
• Sample Executable (Windows) (500 MB)

Cog provides:

• ImGui windows to inspect and configure various Unreal systems (Core Engine, Enhanced Inputs, Gameplay Abilities, AI)
• Window management with persistent configuration and layouts.
• C++ and Blueprint functions to log and debug draw within Log Categories.
• Control over the server regarding debug draw, logging, spawning, cheats.
• NetImgui support to ease the debugging of game server.

General Info:

• Cog can be used both in editor and package builds. It is disabled by default on shipping builds.
• Press the [F1] key or use the Cog.ToggleInput console command to open the ImGui Main Menu.
• Many windows display their contents based on a selected actor. The selector actor can be chosen using the Engine/Selection window or widget.
• Widgets such as Stats (FPS, Ping), Time Scale, Actor Selection, Console, can be added in the main menu bar from the Window/Widgets menu.

Cog Windows

Cog comes with the following windows:

// Adding a metric
FCogDebugMetric::AddMetric(this, "Damage Dealt", MitigatedDamage, UnmitigatedDamage, false);

    // Plotting a value
    FCogDebug::Plot(this, "Speed", Velocity.Length());

    // Starting an event
    FCogDebug::StartEvent(this, "Effects", GameplayEffectSpec.Def->GetFName(), GameplayEffectSpec.GetDuration() == 0.0f)
                    .AddParam("Name", AbilitySystemComponent->CleanupName(GetNameSafe(GameplayEffectSpec.Def)))
                    .AddParam("Effect Instigator", GetNameSafe(GameplayEffectSpec.GetEffectContext().GetInstigator()))
                    .AddParam("Effect Level", GameplayEffectSpec.GetLevel())
                    .AddParam("Effect Duration", GameplayEffectSpec.GetDuration());

    // Stopping an event
    FCogDebug::StopEvent(this, "Effects", RemovedGameplayEffect.Spec.Def->GetFName());

Debug Functionalities

Cog provides C++ and Blueprint functions to log and debug draw within Log Categories.

Log and debug draw functions can be filtered by the selected actor.

Setup

Testing the sample

You must have Unreal 5.5 or greater and Visual Studio to launch the sample

1. Download the code
2. Right Click Cog.uproject and click Generate Visual Studio project files
3. Open Cog.sln
4. Select the DebugGame Editor or Development Editor solution configuration
5. Make sure Cog is set as the startup project
6. Start Debugging [F5]
7. Once in Unreal, press Play [Alt+P]
8. Press the [F1] key or use the Cog.ToggleInput console command to open the Imgui Main Menu.

Integrating Cog in your project

[!IMPORTANT] The way Cog integrates in your project has changed. If you didn't modify Cog sources, you should remove all your existing Cog source files before updating. If you did modify Cog sources and still have a CogWindow folder, consider deleting it before updating. Previously Cog was integrated from your project GameState class. Now it is integrated from UWorldSubsystem in your project as described in the integration guide below.

The Cog repository has the following structure:

• CogSample - A Sample that demonstrate various Cog functionalities. The project was saved in Unreal 5.5
• Plugins/CogAbility - ImGui windows for the Gameplay Ability System (Abilities, Effects, Tags, ...)
• Plugins/CogAI - ImGui windows for AI (Behavior Tree, Blackboard)
• Plugins/CogInput - ImGui windows for the Enhanced Input library (Input action, Gamepad)
• Plugins/Cog - The main Cog plugin which contains the following modules
  • Cog - Cog Subsystem (Manage windows, menu, settings, layout, ...)
  • CogCommon - Interfaces implemented by your project actor classes which cannot be excluded from a shipping build
  • CogDebug - Debug functionalities (Log, Debug Draw, Plot, Metric, ...)
  • CogEngine - ImGui windows for the core unreal engine functionalities (Log, Stats, Time, Collisions, Skeleton, ...)
  • CogImGui - Cog own integration of Imgui for Unreal, inspired by UnrealImGui
• Plugins/CogAll - Only contains a utility function to easily add all the built-in windows from all the Cog plugins. Useful for projects that do not need to exclude some plugins.
• Plugins/CogCommonUI - Contains an implementation of CommonUIActionRouterBase to let the Cog shortcuts work while in a CommonUI menu. Only use this plugin if you use CommonUI.

Cog has multiple plugins to ease the integration for projects that do not use the Ability System Component or Enhanced Input. For the next steps, it is assumed all the plugins are used.

• Setup up module dependencies:

// CogSample.Build.cs
using UnrealBuildTool;

public class CogSample : ModuleRules
{
    public CogSample(ReadOnlyTargetRules Target) : base(Target)
    {
        PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;
        PublicDependencyModuleNames.AddRange(new string[] 
        { 
            "CogCommon",  // CogCommon is required on all target configuration
            "AIModule",
            "Core",
            "CoreUObject", 
            "Engine", 
            "EnhancedInput",
            "GameplayTasks",
            "GameplayAbilities",
            "GameplayTags",
            "InputCore", 
            "NetCore",
        });

        // Other Cog plugins can be added only for specific target configuration
        if (Target.Configuration != UnrealTargetConfiguration.Shipping)
        {
            PublicDependencyModuleNames.AddRange(new string[]
            {
                "Cog",
                "CogAbility",
                "CogAI",
                "CogAll",
                "CogDebug",
                "CogEngine",
                "CogImgui",
                "CogInput",
            });
        }
    }
}

• Add a world subsystem to your project to configure which windows to add in the main menu. Use CogSampleConfigurationSubsystem as a template.

CogSampleConfigurationSubsystem.h

#pragma once

#include "Subsystems/WorldSubsystem.h"
#include "CogSampleConfigurationSubsystem.generated.h"

UCLASS()
class UCogSampleConfigurationSubsystem : public UWorldSubsystem
{
    GENERATED_BODY()
public:
    
    virtual bool ShouldCreateSubsystem(UObject* Outer) const override;
    virtual void Initialize(FSubsystemCollectionBase& Collection) override;
    virtual void PostInitialize() override;

private:
    UPROPERTY()
    TWeakObjectPtr<USubsystem> CogSubsystem;
};

CogSampleConfigurationSubsystem.cpp

#include "CogSampleConfigurationSubsystem.h"

#include "CogCommon.h"

#if ENABLE_COG
#include "CogAll.h"
#include "CogSampleWindow_Team.h"
#include "CogSubsystem.h"
#endif

bool UCogSampleConfigurationSubsystem::ShouldCreateSubsystem(UObject* Outer) const
{
    if (Super::ShouldCreateSubsystem(Outer) == false)
    { return false; }

#if ENABLE_COG
    return true;
#else
    return false;
#endif
}

void UCogSampleConfigurationSubsystem::Initialize(FSubsystemCollectionBase& Collection)
{
    Super::Initialize(Collection);
#if ENABLE_COG
    CogSubsystem = Collection.InitializeDependency<UCogSubsystem>();
#endif
}

void UCogSampleConfigurationSubsystem::PostInitialize() 
{
    Super::PostInitialize();

#if ENABLE_COG
    UCogSubsystem* CogSubsystemPtr = Cast<UCogSubsystem>(CogSubsystem.Get());
    if (IsValid(CogSubsystemPtr) == false)
    { return; }

    // Add all the built-in windows. You can copy and paste this function code to organize the main menu differently.
    Cog::AddAllWindows(*CogSubsystemPtr);
    
    // Add a custom window
    CogSubsystemPtr->AddWindow<FCogSampleWindow_Team>("Gameplay.Team");
#endif
}

[!NOTE] The reason you need to manually add this code is because you can customize which windows are displayed in the main menu, and because all Cog code appart from the CogCommon module is stripped in Shipping build.

• Implement Cog Interfaces on your desired actor classes:

// CogSampleCharacter.h
UCLASS(config=Game)
class ACogSampleCharacter : public ACharacter
    , public ICogCommonDebugFilteredActorInterface
    , public ICogCommonAllegianceActorInterface

// CogSamplePlayerController.h
UCLASS(config=Game)
class ACogSamplePlayerController 
    : public APlayerController
    , public ICogCommonPossessorInterface

• In Unreal Editor create and configure the following Data Assets:
  • CogAbilityDataAsset
  • CogEngineDataAsset

• Reference the added Data Assets in the project Asset Manager for them to be found in package mode:

Screenshots

Cog integrated in Lyra: