Getting started

Table of Contents

• Getting started
• Engine plugin or a game plugin? Which one do I need?
• Plugin structure
• Setting up the ThirdParty dependency
• Plugin core classes
• Adding the Hummingbird plugin to a blueprint game
• Hummingbird Views in the 3D world
• Sample game

Getting started

This tutorial will show you how to add the Hummingbird plugin into a project and create two types of UI elements - a HUD and an in-world UI view . Here are the steps to achieve this:

1. Install the Hummingbird plugin

First, you need to install the Hummingbird plugin using the installer wizard. The installer auto-detects the UE4 engine versions that are available on this computer and gives you the options to install a sample game

Installing Hummingbird plugin

2. Enable the plugin in your project

Then start the Unreal Editor, and choose either an existing project or create a new one via New Project -> Blueprint -> Blank, and save it in a folder of your choice.

The first thing you have to do is to enable the Hummingbird plugin in the editor. From the main menu click Edit -> Plugins, then navigate to the User Interface section and find the Hummingbird Plugin and click the checkbox Enable. You'll have to restart the editor and when you do a new drop-down menu will appear - Hummingbird.

Then create a new level and open the world settings. From the Game Mode section, click the + button to create a new GameMode override, let's name it MyGameMode.

Override the default game mode

Now, from the main menu choose Edit -> Project Settings, and navigate to Maps & Modes in the Project section, then set the Default GameMode to MyGameMode.

3. Add a HUD

From the Hummingbird menu, choose Add HUD. This will change the current GameMode's HUD class to HBGameHUDBP and will initialize it. Also, it will add a hb_hud.html page in YourProjectDir/Content/UIResources/ directory, if not already present; then this page will be opened in your default browser.

HBGameHUDBP for GameMode's HUD

For the HUD, you can add UI resources in YourProjectDir/Content/uiresources folder. As we previously mentioned, the HUD has been pre-setup for you and is ready to use, so you don't need to do any modifications to it, except for changing the view Page URL to coui://uiresources/YourHUD.html.

To see its content, open the HBGameHUDBP blueprint in the Blueprint Editor. If you experience difficulties locating HBGameHUDBP blueprint, you need to set Show Plugin Content and Show Engine Content checkboxes in the Content Browser View Options and search for HummingbirdPlugin Content. Here's a brief explanation of what happens:

• setting up the View - page, transparency, alpha threshold

Setup the View

• the UI input is initialized - this involves spawning and initializing a HummingbirdInputActor, and then setting Accept mouse input to true.

UI Input initialization

• setting up UI scripting (the two-way binding between JavaScript and Blueprints)

Setup UI Scripting

The only part that we cover in this tutorial, is the View setup. The UI Scripting and the input will be covered in upcoming tutorials.

The page is set to coui://uiresources/hb_hud.html by default, so the newly created page by Add HUD will be used if you skip changing it. However, you can change it whenever you want to a local page, placed in the uiresources folder and use the coui:// scheme.

4. Add in-world UI

Choose Hummingbird -> Add In-world UI. This will add a HBPlane to your scene, just in front of the player. You can change its transform via the World Transform in the Details tab of the HBPlane.

Click Edit HBPlane from the same tab and its blueprint will open. As you can see, it has a Hummingbird component and the UI scripting already set up for this view.

Follow these steps to setup the view:

1. Get a reference to the Hummingbird component in the EventGraph of the HBPlane blueprint.
2. Drag a pin from the reference and create SetURL node and set the URL to coui://uiresources/YourHUD.html
3. Add a Begin play and connect it with the URL setter.
4. Now go to the editor and click Play.

Lets do the same with one of our Hummingbird samples:

Setup in-world view

Here is the final result:

Final Result

Note

Hummingbird In-world UI by default is set to use HBMaterial that is not affected by scene lights. In case you want to have In-world UI that is affected by scene lights you just need to change the static mesh material of the HBPlane to HBMaterialLit. Both materials will still be affected by any post-processing in the scene, including light effects done via post-processing volume.

Difference between Unlit and Lit material for In-world UI

In order to showcase the difference between HBMaterial and HBMaterialLit materials let's compare them side by side with the same UI. In order to make it clearly visible, we can also add bright point lights that are also color tinted.

Material showcase - Scene Setup

On hitting the play button in the editor, the In-world UI using HBMaterial remains unaffected by the lighting, while the one using HBMaterialLit is properly lit and tinted.

Material showcase - Final Result

Engine plugin or a game plugin? Which one do I need?

Hummingbird can be installed as either engine plugin or a game plugin. Each of them having their own merit.

Engine plugin

This is the default option of installation. When you have Hummingbird installed as an engine plugin, the plugin will be available for all of the games that are created with that particular instance of the UE4 engine. This is useful when you are working on more than one game at the same time, or you are prototyping.

Note

The engine plugin option is only available when using a source built engine. This is due to limitations of the binary engine not being able to compile engine / plugin code.

Game plugin

Usually the game plugin option is used when using a binary engine. This is because this is the only way to build a plugin when using a binary engine. Another reason why you would like to use Hummingbird as a game plugin would be if you don't want the plugin to be visible to other games using the same engine.

Plugin structure

Hummingbird's plugin uses three modules:

• one for the actual Hummingbird C++ shared libraries (.dll, .dylib, etc.);
• an Engine module that sets up the dependency to the core Hummingbird library. It exposes several classes and Components specific for the development with UE4 and takes care of all the initialization and management of Hummingbird;
• an Editor module which eases your workflow with Hummingbird in the Unreal Editor.

Setting up the ThirdParty dependency

Hummingbird has to be added as a third-party dependency to UE4. This will make sure that all shared libraries (.dll, .dylib, etc.) are loaded when the game starts and they will be referenced by the engine correctly.

The Hummingbird installer will make sure that all the modules are installed correctly.

Install steps:

1. Run the provided installer.
2. When asked what to install, check UnrealEngine Plugin.
3. Select which UE4 version you'd like to install the plugin to. 3.1 If you've selected a binary distribution, Hummingbird will be installed as a game plugin and you will be asked for the path to the game. 3.2 If you've selected an compiled from source distribution, Hummingbird will be installed as an engine plugin.
4. Click install.

The installer provides some other useful items such as a sample game and a collection of ready-to-use HTML5 kits.

Add Hummingbird to your game

After you've installed the plugin, you need to enable it from the UE4 editor:

1. Open the Unreal Engine Editor.
2. Click on the Window menu.
3. Click Plugins.
4. Find the Hummingbird in the list of plugins.

If you are only going to use Hummingbird through the UE4 Editor / Blueprints, you are done. If you going to to use Hummingbird through C++ code, make sure your game references our plugin in its Build.cs file. Doing so is trivial - open YourGame/Source/YourGame/YourGame.Build.cs. Add the following lines to the constructor of the class YourGame:

PrivateDependencyModuleNames.Add("HummingbirdPlugin");
PrivateDependencyModuleNames.Add("Hummingbird");

Note

If you've installed the plugin as a Game plugin to an existing game, the previous step has already been done for you by the installer.

In case than you can not activate the plugin from the editor, you can also activate it by adding the following lines in the .uproject file of your game.

"Plugins": [
    {
        "Name": "HummingbirdPlugin",
        "Enabled": true
    }
]

Hummingbird will look for resources loaded through custom protocols (such as coui://) in YourGame/Content folder.

Plugin core classes

Hummingbird consists of several core classes:

• UHummingbirdBaseComponent is an abstract class, actor component, which contains the necessary code to hook Hummingbird up with UE4.
• UHummingbirdComponent is derived from the BaseComponent and can be used to add UI in the 3D world. It's one of the core Hummingbird classes and represents a single HTML page that is rendered. Also holds methods for manipulating the view.
• UHummingbirdHUD is derived from the base component and can be added to a AHUD actor to add HUD.
• AHummingbirdGameHUD is A HUD class that is derived from AHUD and is the easiest way to use Hummingbird - you can just replace your AHUD class with this one. It's a wrapper around UHummingbirdHUD with fairly simple implementation. This should be your main starting point if you want to have a Hummingbird View attached on your view.
• AHummingbirdInputActor is the input actor is responsible for capturing and forwarding mouse and keyboard input to the currently focused Hummingbird View. It must be spawned and initialized in the game world.
• SHummingbirdWidget is a slate widget capable of running Hummingbird.
• UHummingbirdWidget is an UMG widget capable of running Hummingbird.

Adding the Hummingbird plugin to a blueprint game

Using the installer

1. Run the provided installer.
2. When asked what to install, check Add Hummingbird to an existing game and uncheck Generate Project Files.
3. Browse to the root directory of your game.
4. Click install.

These are almost the same steps as in the previous section but generating project files will fail if your game has no C++ code.

One last step

Open the editor and enable the Hummingbird plugin for your game using the Window -> Plugins dialog. Hummingbird plugin is in the Installed / User Interface section.

Note

Without C++ code, you won't be able to distribute your game. See the next section for details.

Hummingbird Views in the 3D world

Attaching a Hummingbird View to a 3D object in the game world is actually a very easy thing to do - all you have to do is:

1. Add a UHummingbirdComponent to the object
2. In the Static Mesh component of the object, change the material used to HBMaterial.

Sample game

To quickly try out Hummingbird - try the provided HummingbirdFPS game.

HummingbirdFPS sample game requires UE 4.19.0 or later, which is also the requirement for the Hummingbird plugin.

The first thing you have to do is to install the Hummingbird plugin using the installer wizard. The installer auto-detects the UE4 engine versions that are available on this computer and gives you the options to the Hummingbird sample game.

1. Build the UE4 Engine.
2. Build the HummingbirdFPS game.
3. Run the UE4 Engine.
4. Click Projects -> Browse and browse to the HummingbirdFPS.uproject file.
5. Open the game.

There you can see a few samples we are distributing with the sample game. There you will find a few UE4 maps, where we are using a mixture of C++ code and blueprints to show the ways to integrate Hummingbird Views in your UE4 game.