tutorial

Hey guys,

We are going to continue our C++ Fundamentals lessons by creating a custom HUD using AHUD class, then adding a custom widget to the HUD using UUserWidget and finally rounding things off by adding some UWidgetAnimations to make the whole thing look a bit more pretty.

As usual you can find the starter project on our GitHub page.

Hold up, lets get some background on all this stuff first !

HUD – heads.up.display. this is a way of projecting various bits of information in the form of text, images, animations, etc to inform the player as to what is happening to him, other things, or his environment.

Alternatively a hud can also represent menu screens, credits, etc.

Essentially they are the large canvas on which various components and widgets will be displayed on.

For example:
– hud that show cases all the player attributes like health, mana and stamina
– options menu for configuring graphics properties
– scrolling credits

User Widget – a single purpose component that you can attach to various locations on the hud as well as the view port. this is normally either a single “ui thing” or a logical grouping of “ui things”.

For example:
– a cross hair in a FPS game
– health and mana bars on top of each other
– speed gauge in a car sim

Widget Animation – are user widget components responsible for handling the animation for all the various components added to the user widget.

This includes manipulation of states like transformation, visibility, color and opacity. Which allows designers to create various fun and exciting ways of presenting data and feedback to the player.

Example:
– health bar is actually red liquid that boils away as the player takes damage
– damage indicators that show up when a player hits something and proceed to fall to the ground while fading away

That’s better, now what ?

Well lets take a look at our HUD class and what we can do with it.

UCLASS()
class UE4FUNDAMENTALS08_API AInGameHUD : public AHUD
{
  GENERATED_BODY()

public:
  AInGameHUD();

  // Primary draw call for the HUD.
  virtual void DrawHUD() override;

  virtual void BeginPlay() override;

  virtual void Tick(float DeltaSeconds) override;

  UFUNCTION()
  void UpdateComboCount(int32 Value);

  UFUNCTION()
  void ResetCombo();

  UPROPERTY(EditDefaultsOnly, Category = "Interactive")
  TSubclassOf<UUserWidget> HitComboWidgetClass;

private:
  UHitComboWidget* HitComboWidget;
};

Similar layout to our player or prop classes but you get a few extra functions like DrawHUD() that allows you to control the various aspects of screen components and widgets.

We also include a TSubclassOf<UUserWidget> that allows us to include various custom widget components as part of this HUD.

void AInGameHUD::BeginPlay()
{
  Super::BeginPlay();

  if (HitComboWidgetClass)
  {
    HitComboWidget = CreateWidget<UHitComboWidget>(GetWorld(), HitComboWidgetClass);

    /** Make sure widget was created */
    if (HitComboWidget)
    {
      /** Add it to the viewport */
      HitComboWidget->AddToViewport();
    }
  }
}

The important method here is the one that instantiates the custom widget class and adds it to our view port.

void AInGameHUD::UpdateComboCount(int32 Value)
{
  if (HitComboWidget)
  {
    HitComboWidget->UpdateComboCount(Value);
  }
}

This is just an example of how we would call our user widget via our hud.

Great we have a HUD but what else do we need ?!

So let’s examine our user widget to see what makes it tick.

UCLASS()
class UE4FUNDAMENTALS08_API UHitComboWidget : public UUserWidget
{
  GENERATED_BODY()
public:
  UHitComboWidget(const FObjectInitializer& ObjectInitializer);

  virtual void NativeConstruct() override;

  UPROPERTY(EditAnywhere, BlueprintReadWrite, meta = (BindWidget))
  class UTextBlock* TXTCombo;

  void UpdateComboCount(int32 Value);

  void ResetCombo();

  void StoreWidgetAnimations();

  UWidgetAnimation* GetAnimationByName(FName AnimationName) const;

private:
  TMap<FName, UWidgetAnimation*> AnimationsMap;

  UWidgetAnimation* ComboFadeAnimation;
  UWidgetAnimation* ComboShakeAnimation;
};

As we can see in the header the deafult constructor for a UUserWidget is a bit different as it expects an ObjectInitializer to be passed in.

We also don’t have a BeginPlay but rather we expose NativeConstruct which esentially behaves the same way and loads stuff after the constructor is already loaded.

UPROPERTY(EditAnywhere, BlueprintReadWrite, meta = (BindWidget))
class UTextBlock* TXTCombo;

This bit here allows us to auto bind by name to a component on the user widget. In this case we are looking for a UTextBlock of name TXTCombo.

[ insert warning image ]

NOTE: You will get warnings if these attributes are not present.

And lastly we have our declared animations.

Ok, moving on the cpp file.

void UHitComboWidget::NativeConstruct()
{
  Super::NativeConstruct();

  StoreWidgetAnimations();

  ComboFadeAnimation = GetAnimationByName(TEXT("ComboFade"));
  ComboShakeAnimation = GetAnimationByName(TEXT("ComboShake"));
}

In the native construct we do a few things, we first use the StoreWidgetAnimations function to populate a map of animations keyed by name.

We then use that data to populate our animation variables by their names of ComboFade and ComboShake respectively.

void UHitComboWidget::UpdateComboCount(int32 Value)
{
  // only update if more than one hit
  if (TXTCombo && Value > 1)
  {
    if (TXTCombo->Visibility == ESlateVisibility::Hidden)
    {
      TXTCombo->SetVisibility(ESlateVisibility::Visible);
    }
    TXTCombo->SetText(FText::FromString((FString::FromInt(Value) + "x Combo")));

    if (ComboShakeAnimation)
    {
      PlayAnimation(ComboShakeAnimation, 0.f, 1, EUMGSequencePlayMode::Forward, 1.f);
    }

    if (ComboFadeAnimation)
    {
      PlayAnimation(ComboFadeAnimation, 0.f, 1, EUMGSequencePlayMode::Forward, 1.f);
    }
  }
}

In this method, we manipulate the state of the TXTCombo viability based on it being reset and set it back to visible.

We also take in the user provided combo count and add it to the text.

Once that is in place we play back the two animations, one to shake the text and the other to fade it away after a few seconds.

void UHitComboWidget::ResetCombo()
{
  GEngine->AddOnScreenDebugMessage(-1, 3.f, FColor::Orange, __FUNCTION__);

  if (TXTCombo)
  {
    TXTCombo->SetVisibility(ESlateVisibility::Hidden);
  }
}

In this method we reset the visibility of the TXTCombo back to hidden.

void UHitComboWidget::StoreWidgetAnimations()
{
  AnimationsMap.Empty();

  UProperty* Prop = GetClass()->PropertyLink;

  // check each property of this class
  while (Prop)
  {
    // only evaluate object properties, skip rest
    if (Prop->GetClass() == UObjectProperty::StaticClass())
    {
      UObjectProperty* ObjProp = Cast<UObjectProperty>(Prop);

      // only get back properties that are of type widget animation
      if (ObjProp->PropertyClass == UWidgetAnimation::StaticClass())
      {
        UObject* Obj = ObjProp->GetObjectPropertyValue_InContainer(this);
        // only get back properties that are of type widget animation
        UWidgetAnimation* WidgetAnimation = Cast<UWidgetAnimation>(Obj);
        // if casting worked update map with new animation
        if (WidgetAnimation && WidgetAnimation->MovieScene)
        {
          FName AnimName = WidgetAnimation->MovieScene->GetFName();
          GEngine->AddOnScreenDebugMessage(-1, 4.5f, FColor::Magenta, AnimName.ToString());
          AnimationsMap.Add(AnimName, WidgetAnimation);
        }
      }
    }

    Prop = Prop->PropertyLinkNext;
  }
}

This is the big method that allows us to process each property of the current user widget and evaluate them for widget animations.

When a widget animation is found we update our private map with those details.

UWidgetAnimation* UHitComboWidget::GetAnimationByName(FName AnimationName) const
{
  UWidgetAnimation* const* WidgetAnimation = AnimationsMap.Find(AnimationName);
  if (WidgetAnimation)
  {
    return *WidgetAnimation;
  }
  return nullptr;
}

This method allows us to retrieve our animation by the keyed name.

In addition to the video here is a bunch of additional reading material:

• User Interfaces & HUDs
• HUD Example
• AHUD
• UUserWidget
• UWidgetAnimation
• Widget Animations
• HUD Code Samples
• Widget Code Snippet