> [!IMPORTANT]
> The way Cog integrates in your project has been simplified. If you update Cog, please read the [integration guide](#Integrating-Cog-in-your-project).
# Cog
## FORK OF ORIGINAL
This fork is setup to build as an engine plugin (and most likely also work fine as a regular project plugin)
It depends on: [UE_ImGui](https://github.com/Ed94/UE_ImGui) which is a fork of [Vescodes's ImGui](https://github.com/VesCodes/ImGui) for Unreal.
This repo no longer has the Imgui libraries they are sourced from the latter's Thirdparty directory.
## Original Readme
Cog is a set of debug tools for Unreal Engine built on top of [Dear ImGui](https://github.com/ocornut/imgui)
- [Video](https://www.youtube.com/watch?v=ea5hz3cFcMM)
- [Sample Executable (Windows)](https://drive.google.com/file/d/1T7jQFoZ5rd6goBtDH-FCbjn6Kr1RzUCE/view?usp=sharing) (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
### 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.
https://github.com/user-attachments/assets/2497900e-d2d9-4af9-abef-44f7f31c2726
---
### 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.
---
### Build Info
Display the build information such as the build version, changelist, date, target, and so on.
---
### Cheats
Used to apply cheats to the selected actor.
- Cheats are replicated to the game server to be executed.
- 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
- Optionally, cheats applied to the local player character are automatically reapplied.
- Cheats can be defined in a Data Asset. Cog provide two default cheat execution (Apply Effect, Activate Ability).
- Cheat executions can be defined in blueprint.
---
### Collisions Tester
Used to test collision queries
---
### 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).
---
### Console
Used as a replacement of the Unreal console command.
- The console exist as a window and a widget (placed in main menu bar).
- The console widget can optionally get the keyboard focus when the main menu bar is shown.
- Use the Keys Up/Down or Tab/Shift-Tab to navigate in the command list.
- The console settings can be changed in the console window menu, or by right-clicking the widget.
---
### 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.
https://github.com/user-attachments/assets/56edc823-7130-4cfe-9af9-1c565f7286b9
---
### 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.
---
### Levels
Can be used to load specific levels
---
### 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:
```cpp
// Adding a metric
FCogDebugMetric::AddMetric(this, "Damage Dealt", MitigatedDamage, UnmitigatedDamage, false);
```
---
### Net Emulation
Used to configure the network emulation
---
### NetImgui
Handle connections to a [NetImgui](https://github.com/sammyfreg/netImgui) server.
The following image shows the editor running along a dedicated server. The NetImgui server displays the dedicated server imgui windows.
This can be used to debug the state of the game server. For example the behavior trees are only available on the game server.
---
### Notifications
Use to display and configure notifications
- Notification can be added by using the following macros: `COG_NOTIFY`, `COG_NOTIFY_WARNING`, or `COG_NOTIFY_ERROR`.
- Notification settings can be used to adjust the filtering, their location, their size, etc.
---
### 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:
```cpp
// 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());
```
---
### Scalability
Used to configure the rendering quality.
---
### 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.
- Configure how ImGui behaves
- Change the visibility and ordering of the widgets appearing in the main menu bar
- Change Cog Shortcuts
- Change the DPI Scaling. Use `[Ctrl][MouseWheel]` to change the DPI.
---
### 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.
---
### 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.
- Stats can be viewed as a widget in the main menu bar.
- Clicking on the stat provide a menu to force the stat to a reach a specific value.
- Right-clicking the stat display the settings, where the specific stat values can be defined.
---
### Tags
Displays the gameplay tags of the selected actor.
---
### Time Scale
Used to change the game global timescale.
- If changed on a client the timescale is also modified on the game server, and replicated to the other clients.
- Time Scale can be viewed as a widget in the main menu bar.
- Right-clicking the Time Scale display the settings, where the specific Time Scale values can be defined.
---
### 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.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 been simplified. 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.
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](https://github.com/segross/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:
```c#
// 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`
```cpp
#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 CogSubsystem;
};
```
`CogSampleConfigurationSubsystem.cpp`
```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();
#endif
}
void UCogSampleConfigurationSubsystem::PostInitialize()
{
Super::PostInitialize();
#if ENABLE_COG
UCogSubsystem* CogSubsystemPtr = Cast(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("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:
```cpp
// CogSampleCharacter.h
UCLASS(config=Game)
class ACogSampleCharacter : public ACharacter
, public ICogCommonDebugFilteredActorInterface
, public ICogCommonAllegianceActorInterface
```
```cpp
// 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:
