Debugging Guide

Introduction

The combat system usually involves multiple aspects, such as input binding, skill activation, collision detection success, damage calculation accuracy, and combat result correctness.

The combat system is generally more difficult to debug and locate issues compared to other systems.

This article introduces the general debugging approach, which is applicable not only to GCS but also to most complex projects.

Enable Logs for Debugging

[Core.Log]
;Logs for generic input system(针对通用输入系统的日志。)
LogGIPS = Verbose 
;Logs for generic gameplay abilities (针对通用技能系统的日志。)
LogGGA_Ability = VeryVerbose
LogGGA_AbilitySystem = VeryVerbose
LogGGA_Tasks = VeryVerbose
;Logs for generic combat system (针对通用战斗系统的日志。)
LogGCS = VeryVerbose
LogGCS_Bullet = VeryVerbose
LogGCS_Trace = VeryVerbose
LogAbilitySystem = VeryVerbose

It's highly recommended to raise the log level of GCS related log categories in your project's DefaultEngine.ini

The system logs of this system will contain most useful informations to help you better identifying the problems/errors.

Use GameplayDebugger

Follow This doc to know how to debug the ability system via GameplayDebugger.

Debugging Process

Whenever you think a problem or bug has occurred, you can quickly locate which aspect it is by following the thought process below (from top to bottom).

Combat Result Correctness

If you hit someone but there is no effect.

You should directly set a breakpoint in CombatFlow.

If the breakpoint executes, then it can be determined that the problem lies in the handling of the combat result (check the configuration of AttackResultProcessor or check the logic correctness in CombatFlow, etc.).

If the breakpoint does not trigger at all, then the problem lies in one of the processes below.

Network Prediction and Result Replication (GCS 1.6)

When debugging network combat, distinguish GameplayEffect prediction from bullet visual prediction; their settlement boundaries are different.

Predicted GameplayEffects

If an instant GameplayEffect has UGCS_GEComponent_PredictivelyExecute, applying it on an AutonomousProxy adds a PredictionKey and predicting-context marker, then runs the local attribute callback. Check the local path at the AttributeSet's PostGameplayEffectExecute, UGCS_CombatFlow::HandleGameplayEffectExecute, and attack-result registration. Then check the server-authoritative path and result replication.

When the client receives an authoritative attack result, it matches the PredictionKey against an unconsumed local prediction. A match suppresses duplicate LocalPredicted processing; an unmatched authoritative result still runs according to the processor policy. Check that processors are configured as intended:

• Default skips predicting contexts and handles non-predicted results.
• LocalPredicted handles local predictions; it also runs for authoritative results that did not match a local prediction.
• ServerOnly handles only non-predicted authoritative results on the server.

Bullet Prediction

Only the first batch of a player-initiated bullet request predicts trajectory and visual effects locally, with the predicted presentation implemented in Blueprint. Predicted bullets do not apply GameplayEffects or trigger local attribute callbacks, predicted attack results, or LocalPredicted processors. Hits and effects are settled authoritatively on the server; chain and emitter follow-up bullets are server-only as well. Seeing a local trajectory without damage is expected at this boundary. Check server-side Trace hits, GameplayEffect application, and the subsequent CombatFlow callback.

Damage Calculation Correctness

Find the MMC/Execution breakpoint on the GE you ultimately want to apply (for example, the Execution that comes with GCS), and set a breakpoint there. The GE given to the target in GCS is generally configured in the attack definition table.

If the breakpoint triggers, you need to check that your Execution indeed provides valid numerical output. If the damage calculation does not cause effective numerical modification to the opponent, or if an attribute involved in the Execution does not exist (check whether the AttributeSet exists), then subsequent processes will not trigger (combat result, performance, etc.).

If the breakpoint does not trigger at all, then the problem lies in one of the processes below.

Collision Detection Success

In GCS, all collision detection related uses the Collision Trace System. You can learn how to debug/visualize collision detection by following it's doc.

If nothing is hit, you should check the bullet/weapon/Montage's currently activated/associated collision detection instance to see if it uses the correct Trace Definition configuration (further, it may be filtered due to the same faction, etc.).

If something is indeed hit, then the problem lies in one of the processes below.

Input Trigger

GIPS has debugging guidelines, and you can also set breakpoints in the referenced InputChecker/Processor blueprints to determine whether the input logic is executed.

If the input is indeed executed, then the problem lies in one of the processes below.

Otherwise, the problem lies in the input itself; check the input mapping configuration and the correctness of the input processing logic.

Skill Activation

Here lists the general means of debugging GAS.

First, ensure that the target skill has indeed been granted (open the corresponding blueprint and check if the skill instance is in the debug dropdown list).

Then set a breakpoint in the corresponding skill blueprint to see if it executes. If it executes, then generally there is an internal logic error in the skill that prevents subsequent processes from triggering.

If it does not execute, the first step in troubleshooting is to ensure that there is no custom logic blocking activation in the skill's internal CanActiveAbility.

Secondly, it comes to the most difficult part to troubleshoot: configuration errors.

If there are too many or disordered skill block/cancel tag configurations, it can also hinder skill activation. In such cases, it is best to raise the GAS log level and check the logs.

Many times, the inability to activate a skill is caused by Tags not meeting the conditions.

Debug entry points

Gameplay Debugger sections

Open the Combat category on the combat actor. Collection covers Shared, Combat, AttackResult, Trace, Bullet, Targeting, Weapon, and LocalPrediction. LocalPrediction conclusions land in the Shared prediction summary.

If Shared does not show the interface, return to Attach Combat Components before inspecting attack definitions.

Logs and Visual Logger

Source uses GCS_VLOG_* / GCS_VLOG_UELOG_* to write high-volume decisions to Visual Logger. Key events also hit the output log. Raise the matching channel to Verbose, then filter Visual Logger by actor.

Editor switches

• UGCS_DeveloperSettings.bDisableAffiliationCheck turns off affiliation filtering so you can tell whether “cannot hit an ally” is the Affiliation Filter. Keep it off in shipping configs.
• Processor bEditorDebugEnabled lets you disable one processor in the editor to see whether a cue, gameplay event, or project death path is the one that did not run.

Symptom to cause