/unreal-helper-library

UHL - unreal helper library, helps working with AI, GAS, customizing editor and so on

Primary LanguageC++MIT LicenseMIT

Unreal Helper Library [UHL]

UHL - unreal helper library, toolset to help developers working with AI, GAS and so on. Goal is to became a tool that insta-installed on new project creation. All tools are mostly tested on melee combat so if you have other background and think that something should work another way or have an idea on how to improve developer experience feel free to discuss

Support: tested UE5.4

Install

From source (recommended):

  • git submodule add https://github.com/Ciberusps/unreal-helper-library.git ./Plugins/UnrealHelperLibrary - add git submodule to your plugins folder
  • add code to file <ProjectName>.Build.cs
    // <ProjectName>.Build.cs
    public GameName(ReadOnlyTargetRules Target) : base(Target)
    {
        PublicDependencyModuleNames.AddRange(new string[] {
            // add "UnrealHelperLibrary" to use it in C++
            "UnrealHelperLibrary",
        });

        // OPTIONALLY add "UnrealHelperEditor" module to use custom unreal engine editor features
        if (Target.bBuildEditor)
        {
            PrivateDependencyModuleNames.AddRange(new string[] { "UnrealHelperEditor" });
        }
    }

Note

don't forget to update README.md with instructions on how to setup - git submodule update --init --recursive and how to update plugin(s) - git submodule update --remote

Note

and add Editor Preferences -> Force Compilation on Startup in Config/EditorPerProjectUserSettings.ini your team don't want to recompile plugin manually 😉

From marketplace:

later this year

Update

From source:

  • git submodule update --remote to update library from source

Modules

UHL consists of 3 modules:

  • UnrealHelperLibrary - main module with GAS helper classes, AI behavior tree nodes, Blueprint Function Libraries. Most functionality can be tested in Gyms(maps for testing atomic/single gameplay mechanic), all Gyms located in /Plugins/UnrealHelperLibrary/Content/Gyms
  • UnrealHelperEditor - optional module with editor customization, e.g. custom thumnails, custom class icons
  • UHL Utils (EditorUtilityWidget) - widget with tools helping you make trivial things, like ConvertToORM quite often task when you want to combine 3 textures Occlusion, Roughness, Metalic in one ORM texture

Documentation

UnrealHelperLibrary - main module

UnrealHelperEditor

UHL Utils (Editor Utility Widget)

GAS

AbilitySystemComponent

AbilitySystemComponent

UHLAbilitySystemComponent - for quick start with GAS. You can nest from it on start and than turn off its functions when you ready to replace them with your custom solution.

Features:

  • set InitialGameplayAttributes
  • give Abilities on start
  • activate InitialActiveAbilities
  • apply InitialGameplayTags
  • Lyra-like "InputConfig", GAS abilities input binding
InputConfig (GAS abilities input binding) [optional]

Binding InputActions to GameplayAbilities using tags, like in Lyra but enhanced and adopted for 3d action game.

image

Setup:

  • turn on bUseInputConfig on UHLAbilitySystemComponent
  • create InputConfig - DataAsset nested from UHLInputConfig
  • abilities should nest from UHLGameplayAbility for ActivationPolicy work correctly
  • in Project Settings -> Input -> Default Input Component Class -> set UHLInputComponent
  • in your PlayerCharacter class add lines in SetupPlayerInputComponent for binding actions from InputConfig
// Your PlayerCharacter class
void AUHLPlayerCharacter::SetupPlayerInputComponent(UInputComponent* PlayerInputComponent)
{
    Super::SetupPlayerInputComponent(PlayerInputComponent);

    UUHLInputComponent* UHLInputComponent = CastChecked<UUHLInputComponent>(PlayerInputComponent);
    UUHLInputConfig* UHLInputConfig = AbilitySystemComponent->InputConfig;
    TArray<uint32> BindHandles;
    UHLInputComponent->BindAbilityActions(UHLInputConfig, AbilitySystemComponent, &UUHLAbilitySystemComponent::AbilityInputTagPressed, &UUHLAbilitySystemComponent::AbilityInputTagReleased, BindHandles);

    // optional
    if (UHLInputComponent)
    {
        UHLInputComponent->BindAction(UHLInputConfig->NativeInputAction_Move.InputAction, ETriggerEvent::Triggered, this, &AUHLPlayerCharacter::InputMove);
        UHLInputComponent->BindAction(UHLInputConfig->NativeInputAction_Move.InputAction, ETriggerEvent::Completed, this, &AUHLPlayerCharacter::InputStopMove);

        UHLInputComponent->BindAction(UHLInputConfig->NativeInputAction_LookMouse.InputAction, ETriggerEvent::Triggered, this, &AUHLPlayerCharacter::InputLook);
        UHLInputComponent->BindAction(UHLInputConfig->NativeInputAction_LookStick.InputAction, ETriggerEvent::Triggered, this, &AUHLPlayerCharacter::InputLook);
    }
}
  • in your PlayerController class add
// Your PlayerController.cpp
void AUHLPlayerController::OnPossess(APawn* InPawn)
{
    Super::OnPossess(InPawn);

    CachedPlayerCharacter = Cast<AUHLPlayerCharacter>(InPawn);
}

void AUHLPlayerController::PostProcessInput(const float DeltaTime, const bool bGamePaused)
{
    Super::PostProcessInput(DeltaTime, bGamePaused);

    if (CachedPlayerCharacter.Get() == nullptr) return;

    if (UUHLAbilitySystemComponent* ASC = CachedPlayerCharacter.Get()->GetUHLAbilitySystemComponent())
    {
        ASC->ProcessAbilityInput(DeltaTime, bGamePaused);
    }
}



// Your PlayerController.h
UCLASS()
class UHL_API AUHLPlayerController : public APlayerController
{
  GENERATED_BODY()

protected:
    virtual void OnPossess(APawn* InPawn) override;
    virtual void PostProcessInput(const float DeltaTime, const bool bGamePaused) override;

private:
    TWeakObjectPtr<AUHLPlayerCharacter> CachedPlayerCharacter;
};

How to use:

  • every UHLGameplayAbility
AbilityInputCache

AbilityInputCache

How it works:

  • activate bUseAbilityInputCache in UHLAbilitySystemComponent (nest your own AbilitySystem from UHLAbilitySystemComponent)
  • in GameplayAbility activate bInputCache
  • add anim notifies to your attack animation
    • ANS_CatchToAbilityInputCache - to mark when its possible to cache ability - best practice - on 2nd frame of attack and until "BlockAction" end
    • ANS_CheckAbilityInputCache - when you want to check cache and activate ability best practice - on end of "BlockAction" with 5-10frames duration

Debug:

  • write in console ToggleAbilityInputDebug, don't forget to add ProcessConsoleExec to your BGameInstance or it won't work

InterpolateToPosition

AT_InterpolateToPosition - interpolate actor to specified position/rotation at a predetermined amount of time

image

UHLAIPerceptionComponent

AI

BTC_RandomSelector

Select random child node using weights

image

With cool validations

Warns if summary of weights > 1

image

Warns if chances array have more items then child nodes

image

Shows error if child nodes count > than chances count

image

CheckGASGameplayTagsOnActor

BTD_CheckGASGameplayTagsOnActor - checks that actor has GAS gameplay tags specified.

Warning

Don't mess with UBTDecorator_CheckGameplayTagsOnActor - its only checks GameplayTags on actor itself not on AbilitySystem.

Requirements:

  • actor should implement IAbilitySystemInterface to get AbilitySystemComponent

image

InAngle

BTD_InAngle - decorator to check is enemy in one of specified angle ranges. Useful in developing big enemies, for example we developing dragon we want to know is player under the right wing or leg, is player in front of dragon or behind and so on.

image

InRange

BTD_InRange - decorator to check distance between actors. Compliant with "MoveTo" node have same settings bIncludeSelfCapsuleRadius and bIncludeTargetCapsuleRadius to check distance excluding capsules radiuses

image InRange

LoopRandomCount

BTD_LoopRandomCount - randomized version of decorator Loop

image

TimeLimitRandom

BTD_TimeLimitRandom - randomized version of decorator TimeLimit

image

RandomChance

BTD_RandomChance - commonly used decorator to randomize actions. Fine for single child node, extra bad for multiple nodes due to chance regression, for randomization between multiple child nodes better to use RandomSelector

image

SetGameplayFocus

BTS_SetGameplayFocus - alternative for "Set default focus". SetGameplayFocus made right way - prevents rotation jittering while enemy rotation. One of most common problems that anybody stucks when starting developing AI - "focus dont work"/"focus works wrong".

image GameplayFocus

Requirements:

  • turn on UseControllerDesiredRotation
  • turn off
    • bOrientRotationToMovement
    • UseControllerRotationYaw
    • UseControllerRotationPitch
    • UseControllerRotationRoll

Troubleshooting:

  • check that nothing "ClearFocus"
  • check that MoveTo uses "AllowStafe"

SetBBValue

BTT_SetBBValue - helps settings values in blackboard, supports all blackboard types and for some values event provides opportunity to make calculations like int

image

DebugPrintBBValue

BTT_DebugPrintBBValue - prints BB value of any type

image

DebugPrintString

BTT_DebugPrintString - simple task for printing debug info on screen

image

InvokeGameplayAbility

BTT_InvokeGameplayAbility - activate/deactivate GAS Gameplay Ability by tag, with optional "wait for finishing"

image

PlayAnimMontage

BTT_PlayAnimMontage - play anim montage with option to customize PlayRate, Starting Position, Start Section Name and stopping montage on task abort

image

TurnTo

BTT_TurnTo - turn to enemy using turn animations Drop in replacement for "RotateToFaceBBEntry" but with option to "RotateTo" with animations To get settings from actor requires IUHLActorSettings to be implemented on character

UnrealHelperLibraryBPL

> RelativeAngles

RelativeAngleToActor

image

GetPointAtRelativeAngle

image image

GetPointAtRelativeDirection

image image

GetPointAtAngleRelativeToOtherActor

GetPointAtDirectionRelativeToOtherActor

DirectionToAngle

> GAS

CreateGenericGASGameplayEffectSpec

> Misc

GetProjectVersion

Get project version from "Project Settings"

image

image

GetNamesOfComponentsOnObject

Get names of actor components on object, usefull for GetOptions UPROPERTY

GetAssetsOfClass

> Other

GetHighestPoint

LoadingUtilLibrary

UHLLoadingUtilLibrary - loading utils from Lyra

TraceUtilsBPL

UHLTraceUtilsBPL - trace utils

UnrealHelperEditor

UnrealHelperEditor - optional module with editor customization, e.g. custom thumnails, custom class icons

Custom thumnails

image

Custom thumnails - to override thumbnail by your own, just implement IUHECustomThumbnail interface and define your own icon using GetCustomThumbnailIcon()

#if WITH_EDITOR
#include "UHECustomThumbnail.h"
#endif

// IUHECustomThumbnail not available in production build
#if !WITH_EDITOR
class IUHECustomThumbnail {};
#endif

class GAMECODE_API UInventoryItem : public UObject,
    public IUHECustomThumbnail
{
//  ...

 /** IUHECustomThumbnail **/
#if WITH_EDITOR
    UFUNCTION(BlueprintCallable, BlueprintNativeEvent)
    UTexture2D* GetCustomThumbnailIcon() { return Description.Icon; };
#endif
/** ~IUHECustomThumbnail **/

// ...

⚠️ for now works only with C++, TODO add support for blueprints

Thanks to this post and this

Custom class icon

Custom class icon - to override classes icons on your own, just implement set settings in UHESettings

List of default Unreal Engine Editor icons

⚠️ for now works only with C++, TODO add support for blueprints

Thanks to this post and this

UHL Utils (Editor Utility Widget)

ConvertToORM

Combines separate Occlusion, Roughness, Metalic textures into one ORM

TODO check ref - https://github.com/Atulin/ChannelMerger