This guide covers common issues, debugging techniques, and solutions for OmniShift problems. Use the systematic approach below to identify and resolve issues efficiently.
Start
├── Character not responding? → Check Input System
├── Camera not working? → Check Camera System
├── Animation issues? → Check Procedural Animation
├── Performance problems? → Check Optimization Settings
├── Network issues? → Check Network Configuration
└── Other issues? → Check Component Status
Symptoms:
Causes & Solutions:
Incorrect Plugin Directory
✅ Correct: YourProject/Plugins/OmniShift/
❌ Wrong: YourProject/OmniShift/
Missing Dependencies
Compilation Errors
# Regenerate project files
Right-click .uproject → "Generate Visual Studio project files"
# Clean build
Delete Binaries/ and Intermediate/ folders
Rebuild project
Version Compatibility
Symptoms:
Debugging Steps:
Check Character Class
// Verify GASPAC_CharacterBase is available
// Look in C++ Classes → OmniShift → GASPAC_CharacterBase
Validate Data Assets
// Check if required data assets are assigned
if (!CharacterConfig)
{
UE_LOG(LogTemp, Error, TEXT("Missing Character Config Data Asset"));
}
Check Default Pawn Class
Project Settings → Maps & Modes → Default Pawn Class
Should be set to your OmniShift character Blueprint
Symptoms:
Debugging Steps:
Check Input Mapping Context
// Verify Input Mapping Context is applied
if (APlayerController* PC = GetController<APlayerController>())
{
if (UEnhancedInputLocalPlayerSubsystem* Subsystem = ULocalPlayer::GetSubsystem<UEnhancedInputLocalPlayerSubsystem>(PC->GetLocalPlayer()))
{
Subsystem->AddMappingContext(InputMappingContext, 0);
}
}
Validate Input Actions
Input Editor → Check that all required Input Actions exist
Verify IA_Move, IA_Look, IA_Jump, IA_Crouch are created
Check Key Bindings
Project Settings → Engine → Input
Verify action mappings are correctly bound
Debug Input System
// Enable input debugging
console: ShowDebug EnhancedInput
console: EnhancedInput.Debug 1
Common Input Issues:
| Issue | Cause | Solution |
|---|---|---|
| No movement | Input Mapping Context not applied | Apply context in Player Controller |
| No camera look | Mouse input not bound | Check mouse bindings in Project Settings |
| Jump doesn't work | Input Action not bound to Jump | Verify IA_Jump is bound to Jump function |
| Crouch not working | Input Action not configured | Create IA_Crouch and bind to Crouch function |
Symptoms:
Solutions:
Reduce Input Buffer Time
// In Input Profile Data Asset
InputBufferTime = 0.05f; // Default: 0.1f
Disable Input Buffering (if not needed)
bEnableInputBuffering = false;
Check Performance
High CPU usage can cause input lag
Monitor frame rate and optimize if needed
Symptoms:
Debugging Steps:
Check Camera Manager Component
// Verify component exists and is enabled
if (CameraManagerComponent)
{
CameraManagerComponent->SetComponentEnabled(true);
}
Validate Camera Profile
// Check if camera profile is assigned
if (CameraProfile)
{
ApplyCameraProfile(CameraProfile);
}
else
{
UE_LOG(LogTemp, Warning, TEXT("No Camera Profile assigned"));
}
Check Camera Mode
// Force camera mode
CameraManagerComponent->SetCameraMode(EGASPAC_CameraMode::ThirdPerson_OverShoulder);
Symptoms:
Solutions:
Adjust Collision Settings
FGASPAC_CameraSettings Settings;
Settings.bEnableCameraCollision = true;
Settings.CameraCollisionRadius = 15.0f; // Increase for better collision
Settings.CameraCollisionHeight = 50.0f;
Configure Spring Arm
// In Blueprint or C++
SpringArm->bEnableCameraLag = true;
SpringArm->CameraLagSpeed = 10.0f;
SpringArm->bDoCollisionTest = true;
Debug Camera Collision
console: ShowDebug CameraCollision
console: gaspack.DebugCamera 1
Symptoms:
Debugging Steps:
Check Animation Blueprint
Verify AnimBlueprint is assigned to Skeletal Mesh
Check Event Graph for proper animation updates
Validate Locomotion Profile
// Check if locomotion profile is assigned
if (LocomotionProfile)
{
ProceduralAnimationComponent->ApplyLocomotionProfile(LocomotionProfile);
}
Debug Animation State
// Check current locomotion state
EGASPAC_LocomotionState CurrentState = ProceduralAnimationComponent->GetCurrentState();
UE_LOG(LogTemp, Warning, TEXT("Current Animation State: %d"), (int32)CurrentState);
Symptoms:
Debugging Steps:
Check Body Processing Component
// Verify IK systems are enabled
BodyProcessingComponent->SetIKSystemEnabled(EGASPAC_IKType::FootIK, true);
BodyProcessingComponent->SetIKSystemEnabled(EGASPAC_IKType::HeadIK, true);
BodyProcessingComponent->SetIKSystemEnabled(EGASPAC_IKType::HandIK, true);
Validate Rig Configuration
Check Rig Config Data Asset for correct bone names
Verify IK chains are properly configured
Debug IK Visualization
console: gaspack.DebugIK 1
console: gaspack.ShowIK 1
Common IK Issues:
| Issue | Cause | Solution |
|---|---|---|
| Foot IK not working | Foot bones not in rig config | Add foot bones to rig hierarchy |
| Head IK not tracking | Look-at target not set | Call SetLookAtTarget() with valid location |
| Hand IK not reaching | Hand bones not configured | Configure hand IK chains in rig config |
Symptoms:
Diagnostic Steps:
Profile Components
// Enable performance profiling
console: gaspack.Profile 1
console: gaspack.ShowStats 1
Check Update Frequencies
// Reduce update frequencies if needed
ProceduralRigComponent->SetUpdateFrequency(60.0f); // Down from 120.0f
BodyProcessingComponent->SetUpdateFrequency(30.0f); // Down from 60.0f
Enable Distance LOD
BodyProcessingComponent->SetDistanceLOD(true);
ProceduralRigComponent->SetDistanceLOD(true);
Symptoms:
Debugging Steps:
Monitor Memory Usage
// Check memory stats
FPlatformMemoryStats MemoryStats = FPlatformMemory::GetStats();
UE_LOG(LogTemp, Warning, TEXT("Physical Memory: %.2f MB"),
MemoryStats.UsedPhysical / (1024.0f * 1024.0f));
Check Object References
Use "Objects" command in editor
Look for orphaned objects
Force Garbage Collection
// Test for memory leaks
GEngine->ForceGarbageCollection(true);
Symptoms:
Debugging Steps:
Check Replication Settings
// Verify character is set to replicate
bReplicates = true;
SetReplicateMovement(true);
Validate Network Settings
Project Settings → Engine → Network Settings
Check Default Server Net Driver
Verify Max Client Update Rate
Debug Network Traffic
console: Net.Dormancy 0
console: ShowDebug NET
console: net.ShowCorruptDormancy 1
Symptoms:
Solutions:
Optimize Replication
// Set appropriate net update frequency
SetNetUpdateFrequency(30.0f); // Down from 100.0f
MinNetUpdateFrequency = 10.0f;
Reduce Replicated Properties
// Only replicate essential properties
DOREPLIFETIME_CONDITION_NOTIFY(This, CurrentHealth, COND_SkipOwner, REPNOTIFY_Always);
// Don't replicate expensive properties like full IK data
Symptoms:
Debugging Steps:
Check Ability System Component
// Verify ability system is initialized
if (AbilitySystemComponent)
{
// Check if abilities are granted
TArray<FGameplayAbilitySpec>& Abilities = AbilitySystemComponent->GetActivatableAbilities();
}
Validate Attribute Set
// Check attribute set exists
if (AttributeSetCore)
{
float CurrentHealth = AttributeSetCore->GetHealth();
UE_LOG(LogTemp, Warning, TEXT("Current Health: %f"), CurrentHealth);
}
Debug Gameplay Ability System
console: ShowDebug AbilitySystem
console: ga.Debug 1
Symptoms:
Debugging Steps:
Check Interaction Range
// Verify interaction range is set
InteractionHandComponent->SetInteractionRange(200.0f);
Validate Target Objects
Ensure target objects have interaction interface
Check collision channels for detection
Debug Interaction System
console: gaspack.DebugInteraction 1
console: ShowDebug Interaction
Symptoms:
Solutions:
Aggressive Optimization
OptimizeForMobile(Character);
// Reduces update frequencies, disables expensive features
Reduce Quality Settings
Project Settings → Engine → Rendering
Lower settings for mobile devices
Symptoms:
Solutions:
Console-Specific Settings
OptimizeForConsole(Character);
// Applies console-optimized settings
Validate Console Requirements
Check platform-specific requirements
Ensure proper packaging for consoles
# General Debugging
gaspack.DebugMode 1 # Enable debug visualization
gaspack.DebugMode 0 # Disable debug visualization
gaspack.ShowStats 1 # Show performance stats
gaspack.Profile 1 # Enable profiling
gaspack.Profile 0 # Disable profiling
# Component-Specific
gaspack.DebugRig 1 # Debug procedural rig
gaspack.DebugBodyIK 1 # Debug body IK
gaspack.DebugCamera 1 # Debug camera system
gaspack.DebugInteraction 1 # Debug interaction system
gaspack.DebugAnimation 1 # Debug animation system
gaspack.DebugAbility 1 # Debug ability system
# Performance
gaspack.PerformanceMode <level> # Set performance level (0-3)
gaspack.DumpPerformanceToFile # Export performance data
gaspack.ResetStats # Reset performance counters
Component Status Widget
Create UMG widget to display component status
Show current state, performance metrics, errors
Debug Visualization
Use debug draw functions
Visualize IK targets, collision spheres, ray traces
Event Logging
Log major component events
Track state changes and transitions
Logging
UE_LOG(LogTemp, Warning, TEXT("OmniShift Debug: %s"), *DebugMessage);
Asserts
check(Component != nullptr && "Component should not be null");
Breakpoints
Set breakpoints in component update functions
Track component initialization and state changes
Error: 'GASPAC_CharacterBase' type not found
Solution: Ensure plugin is enabled and project is rebuilt
Error: Missing include files
Solution: Check #include paths and rebuild project files
Warning: Missing Character Config Data Asset
Solution: Assign Character Config in Blueprint Details panel
Error: Procedural Rig Component not found
Solution: Ensure component is created in character constructor
Warning: Camera Profile not assigned
Solution: Assign Camera Profile Data Asset to character
GitHub Issues
Report bugs at: https://github.com/MountainLabsDE/OmniShift/issues
Include system specs, error messages, and steps to reproduce
Documentation
Check this wiki for detailed documentation
Look for specific component guides
Review examples for reference implementations
Community
Join Discord/Slack community
Ask questions in forums
Share solutions with other developers
**Description**: Brief description of the issue
**Steps to Reproduce**:
1. Step 1
2. Step 2
3. Step 3
**Expected Result**: What should happen
**Actual Result**: What actually happens
**System Specs**:
- Unreal Engine version:
- Platform:
- Hardware specs:
**Additional Info**:
- Screenshots/Videos
- Log files
- Project files (if applicable)
Monitor Performance
Regularly check frame rate and memory usage
Use profiling tools to identify bottlenecks
Optimize before issues become critical
Validate Configurations
Check data asset assignments
Verify component settings
Test with different configurations
Testing
Test on target platforms
Validate network functionality
Check performance under load
Error Handling
// Always check pointers before use
if (Component != nullptr)
{
Component->DoSomething();
}
else
{
UE_LOG(LogTemp, Error, TEXT("Component is null"));
}
Validation
// Validate inputs and configurations
check(InputValue >= 0.0f && "Input must be non-negative");
Cleanup
// Proper cleanup in destructors
virtual void EndPlay(const EEndPlayReason::Type EndPlayReason) override
{
// Cleanup resources
Super::EndPlay(EndPlayReason);
}
For additional help:
Still having issues? Check the GitHub issues page or ask for help in the community forums.