Cog

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

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

Cog provides:

• ImGui windows to inspect and configure various Unreal systems (Core Engine, Enhanced Inputs, Gameplay Abilities, AI)
• Window mangement 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.

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), or Actor Selection, can be added in the main menu bar from the 'Window/Widgets" menu.

Cog Windows

Abilities

Displays the gameplay abilities of the selected actor.

[]()

• Click the ability checkbox to force its activation or deactivation.
• Right click an ability to remove it, or open/close the ability separate window.
• Use the 'Give Ability' menu to manually give an ability from a list defined in a Data Asset.

Actions

Displays the state of Input Action.

• Can be used to inject inputs to help debugging, as loosing window focus when breaking in the code doesn't affect the state of injected inputs unlike real inputs.
• The display input action are read from a Input Mapping Context defined in a Data Asset.

Attributes

Displays the gameplay attributes of the selected actor.

• Attributes can be sorted by name, category or attribute set.
• Attributes with the Current value greater than the Base value are displayed in green.
• Attributes with the Current value lower than the Base value are displayed in red.
• Use the options 'Show Only Modified' to only show the attributes that have modifiers.

Behavior Tree

Displays the behavior tree of the selected actor.

Blackboard

Displays the blackboard of the selected actor.

Cheats

Used to apply cheats to the selected actor.

• The cheats are gameplay effects configured in a data asset.
• Key modifiers can be used to change which actor should be affected by the cheat:
  • [CTRL] Apply the cheat to the controlled actor
  • [ALT] Apply the cheat to the allies of the selected actor
  • [SHIFT] Apply the cheat to the enemies of the selected actor

Collisions Tester

Used to test a collision query

Collisions Viewer

Used to inspect collisions in the world

• The query can be configured in the options.
• It can be used to better understand what object collisions are blocking a raycast.

Command Bindings

Used to configure the command bindings.

• Bindings are used to trigger console commands from a keyboard shortcuts, which are saved in Saved/Config/WindowEditor/Input.ini (in editor).
• Can be used to register the shortcuts Cog console commands:
  • Cog.ToggleInput
  • Cog.LoadLayout <LayoutIndex>
  • Cog.ToggleSelectionMode

Debug Settings

Used to tweak how the debug display is drawn.

Effects

Displays the gameplay effects of the selected actor.

• Mouse over an effect to see its details such as its modifiers, the gameplay tags it grants, the remaining time, etc.

Gamepad

Display the state of the gamepad

• Can be displayed as an overlay
• Can be used to inject inputs to help debugging, as loosing window focus when breaking in the code doesn't affect the state of injected inputs unlike real inputs.

Inspector

Used to inspect and modify an Object properties

• Inspect the selected actor by default
• Favorites can be added with a custom function defining what happens when the user press the Apply button (typically this can be used to modify and apply the Game User Settings)
• Manage a history of inspected objects.

Log Categories

Can be used to activate and deactivate log categories

• Activating a log category set its verbosity to VeryVerbose.
• Deactivating a log category set its verbosity to Warning.
• The detailed verbosity of each log category can be shown by using the Option menu.
• A client can modify the verbosity of the server.
• The log categories are used to filter both the output log and the debug draw.

Metric

Gather various values sent by the selected actor and compute their rate per second. This is typically used to compute the damage dealt or received per second.

• The following code shows how to add a metric:

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

Net Emulation

Used to configure the network emulation

Output Log

Display the output log based on each log categories verbosity.

• The verbosity of each log category can be configured in the 'Log Categories' window.

Pools

Displays attributes of the selected actor as pools.

• The pools can be configured in a data asset.

Plots

Plots values and events overtime. When applicable, only the values and events of the selected actor are displayed.

• The following code shows how to plot values and events:

  // Plotting a value
  FCogDebugPlot::PlotValue(this, "Speed", Velocity.Length());
  
  // Starting an event
  FCogDebugPlot::PlotEvent(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
  FCogDebugPlot::PlotEventStop(this, "Effects", RemovedGameplayEffect.Spec.Def->GetFName());

Scalability

Used to configure the rendering quality.

Skeleton

Display the bone hierarchy and the skeleton debug draw of the selected actor if it has a Skeletal Mesh.

• Mouse over a bone to highlight it.
• Right click a bone to access more debug display.
• Use the [Ctrl] key to toggle the bone debug draw recursively.

Selection

Used to select an actor either by picking an actor in the world or by selecting an actor in the actor list.

• The actor list can be filtered by actor type (Actor, Character, etc).
• The current selection is used by various debug windows to filter out their content.

Settings

Configure the settings of Cog Windows.

• Can configure the input key to toggle the input focus between the game and imgui
• Can change the DPI Scaling

Spawn

Used to spawn new actors in the world. The spawn list can be configured in a Data Asset.

Stats

Displays engine stats such as FPS, Ping, Packet Loss.

Tags

Displays the gameplay tags of the selected actor.

Time Scale

Used to change the game global time scale.

• If changed on a client the time scale is also modified on the game server, and replicated to the other clients.

Transform

Used to read and set the selected actor transform.

• A gizmo in the viewport can also be used to change the transform.

Tweaks

Used to apply tweaks to all the spawned actors

• The tweaks are used to test various gameplay settings by actor category
• The tweaks can be configured in a data asset.

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.1 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

The Cog repository has the following structure:

• CogSample - A Sample that demonstrate various Cog functionalities. The project was saved in Unreal 5.1
• 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
  • CogEngine - ImGui windows for the core unreal engine functionalities (Log, Stats, Time, Collisions, Skeleton, ...)
  • CogWindow - ImGui window management (Base Window, Layout)
  • CogDebug - Debug functionalities (Log, Debug Draw, Plot, Metric, ...)
  • CogImGui - Integration of Imgui for Unreal, inspired by UnrealImGui
  • CogCommon - Interfaces implemented by your project actor classes which cannot be excluded from a shipping build
• 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.

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[]
        {
            "CogAbility",
            "CogAI",
            "CogAll",
            "CogDebug",
            "CogEngine",
            "CogImgui",
            "CogInput",
            "CogWindow",
        });
    }
}

}

- In the class of your choice (in the sample we use the GameState class) add a reference to the CogWindowManager:
```cpp
// ACogSampleGameState.h
#pragma once

#include "CoreMinimal.h"
#include "CogCommon.h"
#include "GameFramework/GameStateBase.h"
#include "CogSampleGameState.generated.h"

class UCogWindowManager;

UCLASS()
class ACogSampleGameState : public AGameStateBase
{
    GENERATED_BODY()

    [...]

    // To make sure it doesn't get garbage collected.
    UPROPERTY()
    TObjectPtr<UObject> CogWindowManagerRef = nullptr;

#if ENABLE_COG
    TObjectPtr<UCogWindowManager> CogWindowManager = nullptr;
#endif //ENABLE_COG
};

• Instantiate the CogWindowManager and add some windows:

  
  // ACogSampleGameState.cpp
  void ACogSampleGameState::BeginPlay()
  {
  Super::BeginPlay();

if ENABLE_COG

CogWindowManager = NewObject<UCogWindowManager>(this);
CogWindowManagerRef = CogWindowManager;

// Add all the built-in windows
Cog::AddAllWindows(*CogWindowManager);

// Add a custom window
CogWindowManager->AddWindow<FCogSampleWindow_Team>("Gameplay.Team");

[...]

endif //ENABLE_COG

}

- Tick the CogWindowManager:
```cpp

// ACogSampleGameState.cpp
ACogSampleGameState::ACogSampleGameState(const FObjectInitializer & ObjectInitializer)
    : Super(ObjectInitializer)
{
    // Enable ticking
    PrimaryActorTick.bCanEverTick = true;
    PrimaryActorTick.SetTickFunctionEnable(true);
    PrimaryActorTick.bStartWithTickEnabled = true;

    [...]
}

void ACogSampleGameState::Tick(float DeltaSeconds)
{
    Super::Tick(DeltaSeconds);

#if ENABLE_COG
    CogWindowManager->Tick(DeltaSeconds);
#endif //ENABLE_COG
}

• In your PlayerController class, spawn the Cog Replicators. The Replicator are used to communicate between the client and the server, for example to apply cheats, spawn actors, etc.

  
  void ACogSamplePlayerController::BeginPlay()
  {
  Super::BeginPlay();

if ENABLE_COG

// Spawn the Replicator of each plugin
ACogDebugReplicator::Spawn(this);
ACogAbilityReplicator::Spawn(this);
ACogEngineReplicator::Spawn(this);

endif //ENABLE_COG

}

- Implement Cog Interfaces on your desired actor classes:
```cpp
// 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
  • CogAIDataAsset
  • CogEngineDataAsset
  • CogInputDataAsset

Currently, Cog does not properly work when running under a single process in multiplayer mode. You might want to disable the setting Editor Preferences - Run Under One Process: