mirror of
https://github.com/Ed94/Cog.git
synced 2026-06-13 08:02:23 -07:00
Arnaud Jamin
434 lines
17 KiB
Markdown
434 lines
17 KiB
Markdown
# Cog
|
|
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) (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:
|
|
```cpp
|
|
// 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:
|
|
```cpp
|
|
// 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](https://github.com/segross/UnrealImGui)
|
|
- `CogCommon` - Interfaces implemented by your project actor classes which cannot be excluded from a shipping build
|
|
|
|
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[]
|
|
{
|
|
"CogDebug",
|
|
"CogImgui",
|
|
"CogWindow",
|
|
"CogEngine",
|
|
"CogInput",
|
|
"CogAbility",
|
|
});
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
|
|
- 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:
|
|
```cpp
|
|
// ACogSampleGameState.cpp
|
|
void ACogSampleGameState::BeginPlay()
|
|
{
|
|
Super::BeginPlay();
|
|
|
|
#if ENABLE_COG
|
|
CogWindowManager = NewObject<UCogWindowManager>(this);
|
|
CogWindowManagerRef = CogWindowManager;
|
|
|
|
// Add windows
|
|
CogWindowManager->AddWindow<FCogEngineWindow_DebugSettings>("Engine.Debug Settings");
|
|
CogWindowManager->AddWindow<FCogEngineWindow_ImGui>("Engine.ImGui");
|
|
CogWindowManager->AddWindow<FCogAbilityWindow_Abilities>("Gameplay.Abilities");
|
|
CogWindowManager->AddWindow<FCogAbilityWindow_Attributes>("Gameplay.Attributes");
|
|
|
|
[...]
|
|
#endif //ENABLE_COG
|
|
}
|
|
```
|
|
|
|
|
|
- Tick the CogWindowManager:
|
|
```cpp
|
|
// ACogSampleGameState.cpp
|
|
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.
|
|
```cpp
|
|
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
|
|
[...]
|
|
```
|
|
|
|
```cpp
|
|
// 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
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|