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 theCog.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.
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.
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.
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.
Displays the behavior tree of the selected actor.
Displays the blackboard of the selected actor.
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
Used to test a collision query
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.
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
Used to tweak how the debug display is drawn.
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.
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.
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.
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.
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);
Used to configure the network emulation
Display the output log based on each log categories verbosity.
- The verbosity of each log category can be configured in the 'Log Categories' window.
Displays attributes of the selected actor as pools.
- The pools can be configured in a data asset.
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());
Used to configure the rendering quality.
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.
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.
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
Used to spawn new actors in the world. The spawn list can be configured in a Data Asset.
Displays engine stats such as FPS, Ping, Packet Loss.
Displays the gameplay tags of the selected actor.
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.
Used to read and set the selected actor transform.
- A gizmo in the viewport can also be used to change the transform.
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.
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.
You must have Unreal 5.1 or greater and Visual Studio to launch the sample
- Download the code
- Right Click
Cog.uproject
and clickGenerate Visual Studio project files
- Open Cog.sln
- Select the
DebugGame Editor
orDevelopment Editor
solution configuration - Make sure
Cog
is set as the startup project - Start Debugging (F5)
- Once in Unreal, press Play (Alt+P)
- Press the
[F1]
key or use theCog.ToggleInput
console command to open the Imgui Main Menu.
The Cog repository has the following structure:
CogSample
- A Sample that demonstrate various Cog functionalities. The project was saved in Unreal 5.1Plugins/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 modulesCogEngine
- 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 UnrealImGuiCogCommon
- 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:
// 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:
// 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:
// 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