mirror of
https://github.com/Ed94/Cog.git
synced 2026-06-13 08:02:23 -07:00
Arnaud Jamin
591 lines
21 KiB
Markdown
591 lines
21 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.
|
|
- 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), 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.
|
|
|
|
|
|
- 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
|
|
- Optionaly, 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
|
|
|
|
|
|
|
|
|
|
[Video](https://github.com/user-attachments/assets/aa1096d3-375d-4789-b274-923c36588a5b)
|
|
|
|
---
|
|
|
|
### 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 optionaly get the keyboard focus when the main menu bar is shown.
|
|
- Use the Keys Up/Down or Tab/Shift-Tab to nagivate in the command list.
|
|
- The console settings can be change 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.
|
|
|
|
---
|
|
|
|
### 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
|
|
|
|
|
|
|
|
---
|
|
|
|
### 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 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
|
|
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.
|
|
|
|
|
|
|
|
---
|
|
|
|
### 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 ordeing of the widgets appearing in the main menu bar
|
|
- Change Cog Shorctuts
|
|
- 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 povide a menu to force the stat to a reach a specific value.
|
|
- Right cliking 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 time scale.
|
|
|
|
|
|
- If changed on a client the time scale 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 cliking 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
|
|
|
|
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
|
|
- `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
|
|
- `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 shorcuts 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[]
|
|
{
|
|
"CogAbility",
|
|
"CogAI",
|
|
"CogAll",
|
|
"CogDebug",
|
|
"CogEngine",
|
|
"CogImgui",
|
|
"CogInput",
|
|
"CogWindow",
|
|
});
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
|
|
- In the class of your choice add a reference to the CogWindowManager (in the sample we use the GameState class):
|
|
```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
|
|
};
|
|
```
|
|
|
|
- In the cpp file, add the following includes:
|
|
```cpp
|
|
// ACogSampleGameState.cpp
|
|
#if ENABLE_COG
|
|
#include "CogAll.h"
|
|
#include "CogWindowManager.h"
|
|
#endif //ENABLE_COG
|
|
```
|
|
|
|
- Instantiate CogWindowManager and add some windows:
|
|
```cpp
|
|
// 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);
|
|
|
|
// Optionally, add more custom windows from your own project
|
|
// CogWindowManager->AddWindow<FCogSampleWindow_Team>("Gameplay.Team");
|
|
|
|
#endif //ENABLE_COG
|
|
}
|
|
```
|
|
|
|
- Shutdown CogWindowManager:
|
|
```cpp
|
|
// ACogSampleGameState.cpp
|
|
void ACogSampleGameState::EndPlay(const EEndPlayReason::Type EndPlayReason)
|
|
{
|
|
Super::EndPlay(EndPlayReason);
|
|
|
|
#if ENABLE_COG
|
|
if (CogWindowManager != nullptr)
|
|
{
|
|
CogWindowManager->Shutdown();
|
|
}
|
|
#endif //ENABLE_COG
|
|
}
|
|
```
|
|
|
|
- Tick 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.
|
|
```cpp
|
|
|
|
#if ENABLE_COG
|
|
#include "CogAbilityReplicator.h"
|
|
#include "CogDebugDraw.h"
|
|
#include "CogDebugReplicator.h"
|
|
#include "CogEngineReplicator.h"
|
|
#endif //ENABLE_COG
|
|
|
|
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
|
|
- CogEngineDataAsset
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- Reference the added Data Assets in the projet Asset Manager for them to be found in package mode:
|
|
|
|
|
|
|
|
|
|
|
|
## Screenshots
|
|
|
|
Cog integrated in Lyra:
|
|
|