Third Person Story Adventure Template – Documentation

This template is intended to serve as a core framework for a story-based type of game with environmental interactions. The main inspiration for this template is, among others, the Life is Strange series as well as Telltale Games´ The Walking Dead.

Not only is it designed for artists and designers who want to realize their ideas without extensive programming knowledge, it is also meant to save valuable development time for experienced programmers. As the main features are already in place, you can focus on the main content of your game.

A summary of what the template contains:

• A fully functional third person player controller, pawn and animation blueprint
• Cinematic interactions using sequences
• An integrated interaction system with interactive actor blueprints
• An interaction widget rendered in virtual 3D space with object occlusion
• System and interface for collecting and reviewing journal entries and inventory items
• Full mouse & keyboard and gamepad support with dynamic input detection system
• A sophisticated main and ingame menu with options for graphics, audio and gameplay
• Saving and loading your game into 3 different slots with additional progress information
• Integrated functions for easy level transitions with level streaming support
• Prepared localization support with language selection in options menu
• Helpful extra features like footstep effects based on surface type

There is a variety of predefined master actors integrated which you can use out of the box. All these actors display their name and interaction icons when the player is close. A monologue can be assigned to all actors which will be played on interaction. Additional, predefined mechanics are:

• Simple focus on actors: Focus the player view on actor location
• Inspection actors 2D: Show 2D widget with pictures to flip through
• Inspection actors 3D: Move actor close to player camera with free item rotation in 3D space
• Collectables: Collect an item with animation sequence or simple take animation with or without previous inspection
• Collect item and add to inventory. Items can be shown on screen if desired or only show up in inventory
• Add journal entries by inspecting or collecting actors
• Sequence loop actors: Play predefined sequences, start with intro, play a looping sequence until player leaves, switch to end sequence and continue gameplay when done. (Can be used to interact with a bench or play guitar, listening to music, etc.)
• Interactive NPCs with dynamic dialogues: Predefine a dialogue based on sequences and let players talk to NPCs with branching dialogues.

We’re using a custom game instance blueprint called BP_StoryAdv_GameInstance. Values set in the game instance persist during level changes. That’s why we use the game instance to control user settings, level streaming, saving and loading. It’s also important to know, that we can access this game instance from every other actor so we can use its functions if we need them.

The actor called BP_StoryAdv_GameController is a particularly important actor which contains the template’s interaction system and handles various mechanics, such as the ingame menu, the players backpack or updating the active input device. The game controller is one of the most crucial actors of this template. There must always be one instance of it inside a persistent level unless it’s a menu level or similar. Be aware though that you don’t have to place this actor inside a level manually as it will be spawned automatically by our game mode!

As you might already know, the game mode is commonly used to handle the game rules and main mechanics. Also, the game mode controls which pawn or controller classes are used, etc. In addition to that, we’re using our custom class called BP_StoryAdv_GameMode to call functions used to control game settings and input device changes. There’s also another game mode actor we’re using for the game menu, which is basically the same as it’s derived from our main game mode. It only spawns another pawn for the menu since we need a specific one and not or main game character in there.

The menu pawn is used inside the main menu level only. It controls the player input and passes it over to the user interface widget to react to it.

There’s a lot communication happening in this template. We’re using interfaces for this sake most of the time. BP_InteractionInterface is used to fetch information from interactive actors as well as for the actual interaction. To keep all our widgets up to date we’re using an interface called BP_WidgetInterface. The functionality of both should explain itself. If you’re not familiar with interfaces, please have a look at how they work first before you try to dig deeper into the template’s mechanics.

The function library BP_StoryAdv_FunctionLibrary contains multiple helper functions used in a lot of different actors in this template. It’s often used to get a reference to a specific controlling actor and can be used to toggle widget visibility. I would recommend not to add to this and rather creating an individual library, should you need one to prevent possible conflicts on future updates.

The default map which will be loaded when starting a new game is set inside BP_StoryAdv_GameInstance by changing the value of the variable called “NewGameLevel”. This variable is not put in a category so you will easily find it once you opened up the blueprint. Make sure added your level with all information to the game levels data table (DataTables/GameLevels_DataTable) first. More information about level setup can be found further down at Level Transitioning & Streaming.

To keep the functionality provided with the template, it’s recommended to create a new actor based on BP_StoryAdv_Character, or reparent your existing character to this actor. This way you would keep your changes even after updating the parent class after a future template update.

In addition to that, you need to set up the animation blueprint for your new character mesh. If the skeleton is the same, you could simply retarget the integrated one and it’ll be all fine. If the skeleton is different it is of course still possible to retarget, however you need to remove the animations from it and replace them with your own ones.

There’s not much happening in AnimBP_StoryAdv_Character so it should be quite easy to bring it over to your own animation blueprint if you like to do it that way around as well.

All interactive objects inherit from either BP_Master_InteractiveObject or BP_Master_InteractiveCharacter based on whether they’re using static or skeletal meshes. These actors control the main interaction functionality, read their data from the provided table, handle outline and UI widget visibility.

The interaction system can detect them since the meshes are set to object type “Interactive”. Having one of these actors (or child actor of course) in focus will read their data and display the UI widget. Interacting with them will send an interface message to the focused actor which will execute one of the predefined interaction events.

There are several master blueprints which you can use to create your own interactive actors. All these actors fetch their data from data tables, so you only provide the table and row to set up the item in the game world. Let’s go through the existing master actors one by one:

BP_Master_InteractiveObject
This is the root of all interactive objects based on a static mesh. Create a blueprint which inherits from this actor to create your own interactive actor without caring about the basic functionality.

BP_Master_InteractiveCharacter
Basically, the same as BP_InteractiveObject but for skeletal meshes.

BP_Master_SimpleInspection
Based on the functionality from its parent, this actor focusses the player camera on it on top button interaction and play a defined dialogue if desired.

BP_Master_InspectionCloseUp_2D
Interacting with this actor will show a predefined full screen user interface widget. This widget can have multiple pages players can flip through. While presenting the widget, a predefined dialogue is played if desired

BP_Master_InspectionCloseUp_3D
Interacting with one of these actors will move the item close to the player camera where the mesh can be rotated around 3D space. The item can be put back or picked up and put in the inventory. While interacting, a predefined dialogue can be played as well.

BP_Master_LoopingSequence
This actor allows you to provide 3 level sequences, one as intro, one looping and one ending sequence. On interaction the intro sequence plays. After it’s done, it’ll seamlessly start playing the loop animation which can then be interrupted by the player. At that point, the ending sequence plays. The gameplay resumes after it’s done. You can provide a music track or player dialogue to play while the sequence is playing as well. This is an atmospheric feature which can be used in multiple ways. For example, as a resting spot with background music, to give the player and character time to reflect.

BP_Master_SimpleCollectible
This actor can be picked up on interaction. There are multiple options for picking up the item. It can be picked up by playing a predefined level sequence (which is the intended way) or by playing a simple take animation with IK bone adjustment to get the characters hand closer to the item in world space. Also, you can have the item only show up in the inventory or show a predefined icon on screen as long as the player has the item (useful for when you have a key item you need to use shortly after picking it up).

The other actors are used in specific cases. Therefore, I will mention dialogue NPCs, level transition actors and use actions in their individual topics.

To help you organize your games items, all item properties are stored in data tables. The table and row name are then assigned to the actors’ instance in the game world. In these tables you set up the object name, the interaction labels, dialogue data, other inspection properties and more. This is extremely helpful to keep track of all your items and to maintain a non-destructive workflow.

Dialogues are prepared in data tables. All player monologues and object descriptions can be found under DataTables->Dialogues->ObjectDescriptions by default. The table contains rows for each item with information for dialogue wave to be played and subtitles to show. Note, that this data is provided as array elements, so you can have multiple lines of text played in a row.

Subtitles in this template are not based on the default subtitle system of the engine. Instead, a user interface widget will display the text provided to the given wave file. The duration of one subtitle line depends on the letter count so a short sentence will automatically fade way earlier than a long sentence. The visual implementation can be changed in WBP_Subtitles.

For a conversation between the player and an NPC, you need two separate data tables. One data table contains all lines the player can choose from while the other table contains the parts the NPC can choose from. Every conversation part has a level sequence assigned to it. This sequence contains the talking character with the correct audio file so you can easily bring it in sync. The data table also contains the next data table row for each part. If the next part is located in the players data table, the option widget will automatically show up giving the player the opportunity to decide for an answer and vice versa. This way, conversations are not necessarily linear and can have different outcomes based on the players decisions.

To add a consequence to a player’s dialogue option, create a new actor based on BP_Base_ConsequenceScript and override the function called “Run Script” inside of your new actor. Put the code of your consequence, for example locking a door, enabling another conversation etc. to this function. Since you don’t need this actor after the function has been called, don’t forget to destroy the actor at the end of the function. This will allow you to create whatever consequence you need. To add a consequence script to a dialogue option, add a reference to your consequence class to the option structure inside the players dialogue data table. Please have a look at the example conversation and BP_ExampleConsequenceScript as reference.

Get a reference to BP_StoryAdv_GameController for example by using “Get Game Controller” and call the function called “Display Message”. The message you type in will automatically fade in and out on screen.

Use “Enable Interaction” and “Disable Interaction” to temporarily hide interaction widgets and prevent players from interacting with objects.

Use “Hide Active Widgets” and “Show Active Widgets” to temporarily hide widgets, for example while playing a sequence.

As the name already says, this function will tell you if a specific item currently is inside the player’s inventory.

These handy functions help you get a reference to the story adventure game mode, the game instance or the game controller to call functions or get information from them.