What is this template and what can I do with it?
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.
Who is this template designed for?
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.
What do I get with this template?
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
What type of interactive actors are included?
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.
Structure & Setup
We worked hard on making this template as easy to use as possible. However, there are things you should be aware of before you start bringing your story adventure to life with this. First, let’s talk about the template’s main components and how it’s all organized.
Feel free to mess around yourself if you feel confident, as this is always a reasonable way to get to know other developers work. Make sure you keep your work safe though!
Inside the folder Blueprints/Core we see a bunch of different actors (we ignore all subfolders for now). Let’s have a look at them one by one:
Game Instance Actor
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.
Starting a New Game
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.
Besides general camera settings, the player character inside this template contains functions for adjusting focal depth on the camera, player movement, head rotation and hand target location for picking up items using an IK chain. Also, the camera and movement settings are already set to fit the genre of the game. You can of course still use your own character or change the settings to match your design.
How can I use my own character?
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.
The interaction system of this template is based on a four-action-system, meaning players always have up to four possible interactions per interactive item. You can assign an interaction to one of the buttons, which are defined as Top-, Left-, Right- and Bottom Button Interactions. As the template is intended to work with gamepad, these buttons represent the face buttons of a gamepad (e. g. A, B, X, Y). The interaction system will send a different message for each button to the focused item, which can then respond to it individually.
Interactive Items & Item Data
How do interactive items work?
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.
What interactive actors are already there?
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:
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.
Basically, the same as BP_InteractiveObject but for skeletal meshes.
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.
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
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.
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.
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).
What about the other actors in the folder?
The other actors are used in specific cases. Therefore, I will mention dialogue NPCs, level transition actors and use actions in their individual topics.
Data from table – what does that mean?
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.
Items can be used from within the inventory. To use an item, we need to assign a use action to the items inventory data. A use action basically is a blueprint actor that will be spawned, execute an event and then destroy itself again once the linked object is being used. Your use action must always inherit from BP_Base_UseAction. Inside your own use action, override the function “RunScript” and keep the parent call, that will be generated together with the function node. Don’t forget to remove the actor after the required functionality has been executed. If an item has the “Discard when used” flag enabled, the item will be removed from the inventory when using it.
Dialogues & Conversations
Making the player talk
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.
How do the subtitles work?
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.
Talking to NPCs
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.
Level Transitioning & Streaming
You don’t need to care much about level transitioning and keeping your games state persistent. Get a reference to the story adventure game instance and call the function called “Level Transition” providing the level you want to move to. If you don’t want to open a new level and instead want to stream one or more levels in, and other levels out, use the function “Stream in and Out” which is part of the game instance as well.
To make it even easier for you, there’s a prepared master actor called BP_LevelTransitionActor which will handle all of that itself. All you need to do is provide the level or sublevel name. It will then load the defined levels when interacting with it. You can even provide a sequence that should be played in advance, for example leaving through a door.
Make sure to fill in your level details inside GameLevels_DataTable located under DataTables/GameSettings. Add a new row for each level and set its sublevels, initially visible sublevels and the chapter name used for save-game slots. The description is only meant as reference for yourself during development and is not used at any other point.
This template is prepared for localization, meaning all or most user interface texts are gathered in string tables. These string tables can then be used to simply create datasets for different languages. Switching the language in the menu will automatically switch the used dataset for these user interface strings.
Inside the folder Blueprints/Core/Settings, you’ll find structures and tables for easy customization of main elements inside this template. Here you can change the button images you’d like the template to display for gamepad and mouse & keyboard controls. This works that way, that respective actors fetch the default values of the given structures or the data provided inside specific data table row. This way you don’t have to click through all widgets and replace images, fonts and colors manually. Be aware that at some customization level you might still need to do that though.
There are some helpful functions implemented which can be used universally. The following list should help you find and use these universal functions in your projects.
Display a message on screen
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.
Following functions are part of the global function library and therefore are available within all actors:
Disable & Enable Interaction
Use “Enable Interaction” and “Disable Interaction” to temporarily hide interaction widgets and prevent players from interacting with objects.
Hide & show widgets on viewport
Use “Hide Active Widgets” and “Show Active Widgets” to temporarily hide widgets, for example while playing a sequence.
“Is Item in Inventory?”
As the name already says, this function will tell you if a specific item currently is inside the player’s inventory.
Get game mode, game instance & game controller
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.
Change Log & Update Help
To update the template to the newest version, it’s recommended to create a new project using the latest template version and migrating all changed files separately to your existing project. Keep the migration target project closed when migrating.
When migrating one file, the engine also tries to migrate other files as well. To prevent a mess, just hit “Replace” for the file you want to migrate and “No All” for all other files. Use the Update-Log to see which files have changed and need to be migrated.