documentation of the - advanced vr...

1Documentation of theAdvanced VR Framework 2.0

HumanCodeable

December 17, 2019

F

CONTENTS

1 PREFACE 4

2 The File Structure 5

3 Level Management 6

3.1 The Game Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

3.2 The Info-Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

3.2.1 Info-Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

3.2.2 Info-Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

3.2.3 Info-Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

3.2.4 Info-UI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

3.3 Levels And Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

3.4 Panel-based Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

3.5 Using the Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

4 The Component System 11

4.1 Custom Made Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

4.1.1 Actor Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

4.1.2 Scene Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

4.1.3 Child Actor Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

5 Actor Types 14

5.1 Interactibles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

5.2 Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

5.3 Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

5.4 Helpers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

6 Controllers, Pawns and Players 20

6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

6.1.1 Game Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

6.1.2 Game State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

6.1.3 Player Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

6.2 Pawns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

6.2.1 VR Pawn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

6.2.2 NonVR Pawn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

6.2.3 Spectator Pawn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

6.3 Controllers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

6.3.1 The Laser Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

6.3.2 The Pointer Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

6.3.3 VR Hands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

6.3.4 Pause Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

6.4 Motion Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

6.4.1 Hands Motion Component . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

6.4.2 Laser Motion Component . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

6.4.3 Pointer Motion Component . . . . . . . . . . . . . . . . . . . . . . . . . . 26

6.4.4 Radial Menu Motion Component . . . . . . . . . . . . . . . . . . . . . . . 26

6.4.5 Smartwatch Motion Component . . . . . . . . . . . . . . . . . . . . . . . 26

6.4.6 Teleporter Motion Component . . . . . . . . . . . . . . . . . . . . . . . . . 27

6.4.7 Movement Motion Component . . . . . . . . . . . . . . . . . . . . . . . . 28

6.5 Custom Controllers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

7 Advanced Controller Functionalities 29

7.1 Selecting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

7.2 Grabbing and Co . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

7.2.1 Grabbing With the Laser Controller . . . . . . . . . . . . . . . . . . . . . 30

7.2.2 Grabbing With the VR Hands . . . . . . . . . . . . . . . . . . . . . . . . . 31

7.2.3 Dragging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

7.2.4 Climbing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

7.3 Snapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

7.3.1 Snap To Surface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

7.3.2 Snap To Anchor (Attach) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

8 User Interfaces (UI) 34

8.1 Highlighting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

8.2 Pallets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

8.2.1 2D Minimaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

8.2.2 The Object Dropper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

8.2.3 Bookmarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

8.2.4 Data Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

8.2.5 Devices Pallet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

8.2.6 Menu Pallet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

8.3 Selection Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

8.3.1 Exchange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

8.3.2 Change material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

8.3.3 Show Info Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

8.3.4 Toggle light . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

8.3.5 Change light color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

8.3.6 Open/close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

2

8.3.7 Activate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

8.3.8 Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

8.4 Window object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

8.5 Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

8.5.1 3D Minimaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

9 Additional Features 42

9.1 Game Play Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

9.2 Internationalization (I18n) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

9.3 Achievement-System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

9.4 Character Stats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

10 Glossary 44

3

1 PREFACE

So why Version 2? Since the Advanced VR Framework has initially came to life it constantly changed

and evolved. This is even more true after the Advanced VR Framework V1 was released back in

Mai 2019. Since then a great community constantly contributed towards the Framework. We used the

countless feedback for a extensive rework of the whole Advanced VR Framework in which no piece

of code has been left untouched. Now more than ever the Framework is thriving towards becoming

a suitable solution for all VR applications (but of course for that we still have a bit to go ;)). Lets

have a short overview on the new features:

• Component based Functionality - The First Version was building upon a complex class hierarchy

to provide functionality and features to actors. This approach was not flexible enough to support

the versatile feature configuration that most applications required.

So we decided to replace it with a component based approach to make it more sleek and flexible.

We moved most of our functionality inside components and adding them to our actors to create

a perfect fit for every application. With this fundamental rework the Advanced VR Framework

2.0 provides now an easily accessible and flat class hierarchy.

All components of the framework were designed to be freely attachable to classes or even

instances and consequently provide a building set for a huge variety of different classes.

• Centralized Configuration - We have reworked the former experience object and are separating

the information into multiple more applicable info files and the Unreal in-build Game mode. The

former solution was just not flexible enough for complex level structures.

• Core - Finally, we included tons of core functionalities like a debug system, achievements or

internationalisation. Things that basically every project needs to have.

• Visuals and Gadgets - Furthermore, we expanded the framework with a rich amount of UI

Elements, like 3D minimaps, smartwatches, information windows, gaze selection, guided tour...

• And tons of improvements under the hood...

Finally, we hope our work will provide all of you with a reliable basis for your various projects and

that this Documentation will enable everyone to work with ease and enjoyment with the Advanced

VR Framework 2.0.

This is no Unreal Tutorial - To work effectively with the Advanced VR Framework 2.0 you need a basicknowledge on how the unreal engine works. The main objective of this documentation is to guide you onthe usage of the Advanced VR Framework 2.0 and provide solutions to the most frequent problems youmight encounter.

A Documentation is always out of date!!! - The Advanced VR Framework is in constant developmentand we are perpetually pushing new updates. The documentation will always try to keep up with thenewest version as much as possible but minor discrepancies are unavoidable.

4

2 THE FILE STRUCTURE AVRFrameworkAnimationsAnimBPBlueprintsCurvesDatatablesEnumsExperiences

ComponentsDemoDevicesEnviromentHelperInfoInteractablesNavigationTriggersUIVRWidgets

FrameworkIESInterfaceLibrariesMapsMaterialsMeshesMoviesParticlesSoundStructsTextures

The Advanced VR Framework 2.0 has a predetermined folder structure

which can be the basis for any VR project. Every new element of your

experience can be integrated unequivocally into the structure to keep

even large projects neat and easy to navigate. Most of the Folders are

self explanatory: Folders like Animations, Materials, Meshes, Particles,

etc will contain their respective filetype. Hereafter, you find a list of the

folders that are most important in this documentation and what they

contain.

Blueprints This folder contains most of the logic contained in the Frame-

work.

Components This folder contains the custom components newly intro-

duced to the Advanced VR Framework V2. Seperated in

Scene, Actor and Child Components.

Devices This folder contains all actors with the overwrite controls

function active.

Helper This folder contains all actors that we created to support

complex functionalities like snapping.

Navigation

Triggers This folder contains all actors with the ability to initiate events

concerning other actors.

UI

VR This folder contains the Motion Controller and the Motion

Components.

Widgets This folder contains everything to

Datatables Currently inside the Framework these are used mostly for

categories and internationalisation.

Experiences The Experiences folder should contain all of the unique files

concerning a certain experience.

Framework This folder contains all the essential Unreal Classes, Player

Controller, Game Mode, Game Instance Game State and the

Pawn class.

Libraries Libraries provide a set of universally accessible functions.

Maps All the for the Framework essential maps like intro, transi-

tion and pause. Experience specific maps should go in the

experience folder.

5

3 LEVEL MANAGEMENT

Figure 1. Menu Coordinator

For the Framework to properly function several key elements have to be

in place and linked. At the start of everything is the BP GameMode Main

which again is referencing several Info-Classes and a set of level classes.

The Level-Classes themselves then reference the levels which then ref-

erence the different maps that should be loaded. The Game Mode and

Info-Classes contain every reference relevant to the experience.

The only exception is the Game Instance. This class must be referenced inthe Project Settings under Maps & Modes separately.

3.1 The Game Mode

The Framework is using the BP_GameMode_Main to obtain all centrally

available information. Therefore, it is paramount that the Game Mode is

entered in the Project Settings. It contains general information about the

experience. The Game Mode contains following sections:

• Intro - This section of variables should define the look of the intro

map.

• Defaults - The Defaults define general global parameter like the

spectator screen size, the export path or a Version number.

• Info Classes - In the Game Mode you can define default Info-Classes The possibility to override Info-Classesallows to set Controls or UI on a per levelbasis.

for your project. Each level individually can override the used info

class if required.

• Pawns - In the Pawn section you have to set the default pawn classes

for the VR and nonVR Pawn. Similar to the Info-Classes these default

classes can be overridden on a per level basis.

• Levels - Under Levels you have to specify a menu level and a set of If you want your experience to just haveone level or want to handle the menu your-self you can leave the playable level setempty.

playable levels. The menu level is simply the first level that is being

loaded after the intro screen. The set of playable levels is being used

to populate the panel based menu described in section 3.4.

• Classes - These class definitions are made by Unreal and were inher-

ited from the original Game Mode. It is very essential that following

classes have been set or at least child classes of following classes.

– Game State Class - BP_GameState_Main

– Player Controller Class - BP_PlayerController_Main

Additionally the Game Mode is being extended by the Info-Classes.

For your experience we would recommend that you create a child of theBP_GameMode_Main and move it to your experience folder. So youcan quickly switch between different Experiences and to have everythingbelonging to the experience together in one folder.

3.2 The Info-Classes

The Info-Classes act as an extension of the Game Mode to keep data or-

ganized. Additionally Info-Classes can be overridden on a per level basis

6

facilitating a huge amount of flexibility while maintaining an organized

structure.

3.2.1 Info-Level

The Info-Level class represent a playable level or encapsulated play ex-

perience. The Info-Level file handles all the information concerning a

playable level. Contrary to the other Info-Classes there can be no default

Info-Level class because the Info-Level acts as a unique reference to a

playable level. In the Info Level you can enter the following information:

• Streaming Level - In this section you have to define which maps to You always need a world map and at leastone level to load.load. One world map and a set of maps inside the world map that

should be loaded for this level. Remember, the world map has to

contain all the maps to load. Make sure you referred to every map

you entered by its full name. Exact information on how to setup your

maps can be found in Section 3.3.

• Transition - Enter visuals of the transition map, that is shown during Set the minimum loading time to 0 if youwant the level to start as soon as it is loaded.the loading of the corresponding level, here. You can define the

skysphere around you and a minimum loading time.

• Panel - In the panel section you can define the entire visuals like The menu level does not need panel def-initions, unless you want the Menu-Levelitself appear in the menu.

Textures, Logo and Color of the panel created by BP_Menu for the

panel based menu. For further information on how to setup a menu

map have a look at Section 3.4

• Key - The Level-Key is a vital element and creates the link for all text If the Level-Key can not be found inthe datatables then all the text fields thatrequire this key will just show whatever youentered here.

fields directly concerning that level. The Panels, Transitions, Menu

and other elements use the Level-Key as a reference to search for

their respective content.

• Info - Here you can set Info-Classes like the Info-Controls or Info-UI Use this override to create custom controlsfor each level.

custom for this level. If no Info file is specified xx will fall back to

the default Info-Classes set in the Game Mode. See section 3.1

• Pawn - In the pawn section you can set a VR and NonVR Pawn used

by the level. The Framework automatically detects whether you are

in VR and chooses the Pawn accordingly.

To keep things simple you often want to have one map for one level. Butthere are scenarios where you need a more complex level structure. Forexample have multiple levels take place in the same map.

3.2.2 Info-Controls

Like the name suggests the Info-Controls defines all kinds of parameters

concerning the handling of the controllers, the movement options and

the haptics. Most of these settings are specific to the VR Pawn only and

do not apply to the NonVR Pawn.

• Controls - The controls section handles settings around the motion

controller. From the Visuals to assigning buttons.

– Controller Set - The Controller Set variable lets you define a pair You can define separate controllers for theleft and the right hand of the player.of Motion Controller classes, that the VR Pawn should spawn.

7

For more information on the Motion Controller classes please

refer to Section 6.3.

– Controller Mesh Override - The visuals of the Controller and Steam Valve Index Controllers can not beautomatically detected and would have tobe set here manually.

the Button Mapping are tied to the Controller Mesh. The Frame-

work is trying to detect the currently used HMD and set the

Controllers accordingly but you may want to force a specific

controller.

Figure 2. Function mapping

– Trigger Grip - The Trigger Grib option is a solution to emulate

Due to the limited usability of the grabbutton on the Steam VR Controllers thisoption is a popular workaround.

the grab button by holding the trigger.

– Holding Grab - The holding grab options let’s you set whether

the grab button has to be held in order to maintain grabbing an

object. If this option is unchecked it means that the player can

press the grab button once to grab an object and has to press it

again to release the object.

– Function Mapping - Using the function mapping you can assign

the button inputs for your controller. You only define the func-

tion that should be executed by the motion controller here, see

Figure 2. The Motion Controller then tries to map the function to

a certain Motion Component. The mapping has to be specific for

the used Controller Mesh and for the left and the right controller

respectively.

• Teleportation - This Section covers all different parameters on the

teleportation movement. The teleportation settings are discussed in

detail in section 6.4.6

• Movement - The Movement sections sets the parameters for the dif-

ferent direct movement options available. Have a look at section 6.4.7

for more information.

• Haptics - The haptics section offers the possibility to activate haptics If you want to adjust haptics for indi-vidual items you can simply do that in theblueprint of the respective item.

divided into four different groups: Haptics for Select, Grab, Devices

and Triggers. Additionally you can specify the strength of the haptics

for each controller type.

3.2.3 Info-Data

The Info-Data contains lists of characteristic information about Materials,

Categories and Actors. The information in this list can then be used by

entities in the Framework. For example the object dropper uses the actor

list to get Information about the actors it displays.

• Materials Info - A list that contains information about materials that

you have in pallets.

• Category Info - A list that contains information about Categories

used in the object dropper or the data browser (see sections 8.2.2

and 8.2.4).

• Actor Info - A list that contains information about actors appearing

in the object dropper and related pallets like the bookmarks and

devices pallet (section8.2).

8

3.2.4 Info-UI

The Info-UI’s task is to control the content of the UI elements. Currently

these cover the Pallets, Display and the Radial Menu.

• Pallets - Each variable in this section defines the content of its as-

signed Pallet. If the pallet requires additional information about the

item, like the image or category of an item, these have to be set

in the Info-Data. This section is solely for setting the items that

should be listed. A detailed description of the Pallets can be found

in Section 8.2.

• Display - Currently this section allows settings which content win- The Display and its options are still underdevelopment. Their content will be mas-sively increased in future updates.

dows should be available for the Display. For more information on

the display have a look at section 8.5.

• Radial Menu - This sections defines two sets radial menu buttons.

Each button has their own function assigned to it. A more indepth

description of the radial menu can be found in section 6.4.4.

3.3 Levels And Maps

The Maps folder contains 3 Maps being the Intro Map, Transition Map

and the Pause Map. The Framework needs these levels to do their re-

spective tasks.

Intro Map

Figure 3. Intro Map

The Intro Map is designed to be the initially opened map. It is build

similar to the Transition Map. It shows the Intro Animation and a button

that allows the player to start the Application. Upon pressing the button

the Intro Map loads the level specified in the Game Mode under Menu

Level. The Intro generates the skysphere according to the settings inside

the Game Mode in the intro section.

Transition Map

Figure 4. Transition Map

The transition map is displayed when entering a level. It’s designed to be

an extremely lightweight map that is displayed while the maps required

for the level are loading. The map merely contains:

• Starting Position - The position that initiates and places the player

pawn in the correct location.

• Sky Sphere - The look and feel of the skysphere is set in the Info-

Level file of the level the transition map corresponds to.

• Transition Text - The transition text contains two text fields. The text

fields are filled using the level key specified in the corresponding

info-level file and the datatables:

Figure 5. Pause Map

Datatable_I18n_Level_Name

Datatable_I18n_Level_Subtitle

Pause Map

When the BP_PlayerController_Main executes the Pause function it

loads the Pause Map and spawns a Pause Pawn which it then possesses.

While inside the Pause Map the game state is paused and will only

9

continue on exiting. The Pause Map simply consists of an text and a

logo showing Pause.

3.4 Panel-based Menus

Figure 6. Setup of a panel-based menu

The panel-based menu allows the player to enter all levels of the experi-

ence. The Framework provides the possibility to auto-generate customiz-

able menu maps using the BP Menu. The BP Menu constructs a panel

or tile for every level, when the menu map is loaded. These panels or

tiles have the ability to expand and show information. Additionally they

have a ”Start Level” button which loads the currently presented level.

Setup:

1) Put an instance of BP Menu into the menu map and scale it accord-

ing to your wishes.

2) Open BP_Menu and make the following adjustments:

• MenuType: Offers a selection between either panels (Figure 7)

or tiles (Figure 8)

• CenteredLevel: Indicates which level appears in the center upon

loading the menu level.

• ItemsPerRow: Defines how many tiles appear per row, tiles do All of the tiles need to fit in your scene.

not support a scrolling option.

• Levels: Contains a list all levels you want to show. Leave this field empty in case you wantto all levels in your game mode to appearas tiles or panels in the menu map.

Figure 7. Menu type: Panels

Figure 8. Menu type: Tiles

3) Open your GameMode and check that all Info-Level files you need

are listed there.

4) In each Info-Level you have to fill out the fields of the panel section,

both tiles and panels use the same parameters to generate their

content:

Each text field has it’s own datatable andtherefor the panel only requires one levelkey get all the texts for the level.

• The level key is required to search the following datatables or

the content of the Text fields:

Datatable_I18n_Level_Name

Datatable_I18n_Level_Details

Datatable_I18n_Level_AdditionalDetails

• The panel has three spaces for image fields. One larger image

with a resolution of 1600x975 and two smaller image of 800x585.

• A texture for the logo. Dimensions: 249x113.

• The background color. The Panel controls the alpha of the color

and will only apply the RGB value. The panel shift their trans-

parency value on selection.

The Image-Cover is designed to exceedthe dimensions of the panel to create anoverlapping effect.

• An Image Cover. This image will position itself over the back-

ground of the panel. The image as the dimensions of 650x650.

How It Works: BP Menu generates a tile or panel for each level according

to the information in the corresponding Info-Level file. Each tile or panel

is in itself an actor containing a widget displaying the information, images

and buttons.

10

3.5 Using the TemplateTemplate

InfoControls

BP_Info_Controls_...Data

BP_Info_Data_...Level

BP_Info_..._Level1BP_Info_..._Level1BP_Info_..._Menu

UIBP_Info_UI_...

MapsMap_Template_World_MenuMap_Template_MenuMap_Template_World_LevelMap_Template_Level1Map_Template_Level2

By now you should know everything to setup your own level struc-

ture. If you want to jump right in, we suggest you have a look at the

folder Experiences/Templates. Here you find the bare minimum

level structure already setup. Here we will basically show you how to

modify the existing files with your project data.

1) Set GameMode inside the Project Settings - BP GameMode Template

2) Customize your Game Mode and Info-Level Class

You can even store build multiple experiences in the Advanced VR Frame-work 2.0 by creating the appropriate folders in the experience folder andproviding each with the respective game mode and other essential files.However, be careful when moving from one experience to the other. Youhave to change the project settings by hand.

4 THE COMPONENT SYSTEM

Figure 9. Component System

Components are ”mini-classes” that typically cannot exist on their own.

Instead Components can be attached to classes as well as single instances

providing specific functionalities.

Components are freely exchangeable and enable you to create a multitudeof individually designed classes as well as modify single instances for specificfunctionalities. We chose the component system to avoid the deep andcomplicated class tree that previously detained some of you from using theAdvanced VR-Framework as effectively as possible.

How To Use: Components are added to actors to give them specific func-

tionalities like select, grab or toggle light. Thus, the component system

enables you as user of the Advanced VR Framework 2.0 to create your

own actor classes with ease.

Setup:

1) Create an child of the actor class

2) Add all components you need for the functionalities you want

3) Enter the necessary information the components need to function

4) Check for cross dependencies

Some components just cannot work with-out other components being added, too.Comp_SelectionMenu is a prominent ex-ample discussed in more detail in section 8.3

4.1 Custom Made Components

Some very essential components you can add to your actor class are

already provided by the Unreal Engine. But quite a number we created

ourself. We divided the components we created into 3 groups: actor com-

ponents, child actor components and scene components. And we will use

this section to make you acquainted with the differences between those

three groups and show you the variety of functionalities components

implement in the Advance VR Framework 2.0.

11

4.1.1 Actor Components

Actor components are the most basic component in the Advanced VR

Framework 2.0. Their basis class, Comp_Actor, contains only logic. They

need to be added to an actor to function, since they do not have a

transform. Neither can you add another component to them. You find

a list of all actor components below. Most of them are described in more

detail in other sections dealing with their application.

Attach Implements the event dispatcher for the attach functional-

ity and keeps account of all attached actors. For additional

information have a look at section 7.3

CharacterStats allows you to include character stats in your experience

or game. For more see section 9.4.

Exchange contains all necessary information to perform the exchange

functionality of the selection menu which is described in

more detail in section 8.3.

GazeView communicates with the forward trace of the camera within

the appointed distance to highlight in-game items or per-

form functions, see section 8.1.

Grab enables that instances of the class can be grabbed. For

additional information have a look at section 7 especially

7.2.

Highlight communicates with the controller (laser, pointer or hand)

to highlight in-game items, see section 8.1

LightColor contains all necessary information to perform the change

light color functionality described in section 8.3.5.

Material contains all necessary information to perform the change

material functionality described in section 8.3.2.

Select enables selection of an item with the trigger finger button

of the controller (see section 7.1).

WindowObject displays an information window upon activation by the

select component. The window object component also contains

all settings necessary to customize the information window,

see section 8.4.

4.1.2 Scene Components

In contrast to actor components, scene components have a transform mean-

ing they can appear on a map without being added to an in-game instance

of a class. However, scene components, too, cannot add another component

to themselves. Often the transform of a scene component is relative to its

corresponding actor to enable functionalities like attaching two in-game

items to each other.

Maplocation broadcasts the position and rotation of its actor so it

can be displayed on the minimap (see sections 8.2.1 and

8.5.1).

Selectionmenu enables the display of the selection menu in response to

the selection action of the motion controller. It manages

12

which options of the selection menu are displayed and

collaborates with other components to performed the

functionality chosen by the player (see section 8.3).

Anchor-connector enables an in-game item to attach itself to another in-

game item (e.g. the pipes attaching to each other or

the light bulb attaching to the battery). For more see

section 7.3.

Surface-connector enables the in-game item to attach itself to surfaces

(wall, floor or ceiling) as described in more detail in

section 7.3.

4.1.3 Child Actor Components

Child Actor Components are actually actors that we modified so they can

be used as components. The main reason for that was the fact, that com-

ponents are unable to add other components. Child Actor Components

however, can do that.

3D-Map displays the 3D minimap in-game. The setup of a 3D minimap

is described in detail in section 8.5.1.

Anchor Achors are added to an actor to define the position and ori-

entation at which another actor can be attached as well as the

tags of attachable items. For more information have a look at

section 7.3.

Figure 10. Using the canvas as a white board.

Canvas the canvas consists of a render target. Other Actors like the

Markers or Eraser draw lines on the canvas on overlap.

Edge component that defines the edge of a weapon between two

defined positions on the item. It also defines the direction in

which the weapon is supposed to be able to cut. Upon collision

the edge component notifies the item in question, but is not re-

sponsible for the processing of this information. For two-edged

Weapons add two edge components.

Widget modification of the widget component of the Unreal Engine that

includes additional functions handling the interaction with the

motion controller (laser, pointer or hand).

13

5 ACTOR TYPES

Practically every item you are going to put into your in-game experience

will be instances of an actor class. The actor class sits comfortably in the

middle of the class hierarchy and is extremely adaptable thanks to the

component system. The most important features of actors are...

• ... that they contain variables (e.g. the transform)

• ... that they contain logic (e.g. physics)

• ... that you can add more logic to them

• ... that you can add components to them

A pretty standard actor you are going to use in your experience has a

position, a mesh component and materials component(s) that determine

how it looks. However, the actor class can be adapted to all kinds of inter-

esting applications by attaching suitable components the most important

examples are interactibles, triggers and devices.

5.1 Interactibles

Interactibles arare at the heart of every experience including grab-able

items, lights, the tv screen and most other stuff the player sees and

interacts with inside the experience. Examples of the functionalities im-

plemented in components include:

• Grabbing, snapping, attaching and other means to move items

• The selection menu

• Presentation on the minimap

• Selecting, highlighting and information display

5.2 Devices

A device attaches itself to the VR controller when grabbed overwriting

specific controller functions like key inputs. Devices can be used within

the VR experience to help developers or enhance the experience by pro-

viding specific functionalities like taking photos, drawing or measuring

distances.

Devices and interactibles are actually quite similar in their implementation.The main difference consists in the snap and replace function functionalitythat allows devices to overwrite all of the controllers original functionalitiesexcept the grab functionality.

The framework includes following devices:

Figure 11. Measuring Device

• Measuring Device - The Measurement devices allows the placement

and connection of measurement markers. Connected Measurement

Markers draw a line and display their length.

• Gun - The gun is a very simple gun example. The gun can spawn

projectiles when pressing the trigger button.

• Flashlight - The Flashlight is also just a very simple example. The

flashlight can be activated and deactivated on the trigger pressed.

• Paintbrush - enables the controller to draw splines in the world.

When selecting the paintbrush on the pallet control interface the user

Figure 12. Paintbrush

14

has access to colour palette for switching between different spline

colours. The available colors have to be defined in the experience

object.

Figure 13. Camera

• Camera - The photo camera can take images on pressing trigger

and stores them as instances in the world. These images can be

accessed through a picture gallery in the pallet control interface. In

the picture gallery the player is able to browse and view their photos.

The picture gallery also has the ability to print their photos on actors,

export the photos to the hard drive or delete the photos.

Many of the Device examples are just meant to inspire. The possibilitiesfor devices are seemingly endless. Using the structure of the framework youcan implement any device imaginable.

5.3 Triggers

Figure 14.

Every trigger is paired to one in-game actor, that is suppose to react to its

input. For this to work the trigger instance contains the information which

in-game actor it is paired with and which type of trigger it provides.

On first glace the actor type class triggers seems to be quite similar to theinteractibles class. Like interactibles, they initiate an in-game event uponinteraction. In contrast to interactibles however, the event activated by atrigger is connected to a different in-game actor which quite often doesnot allow the player any other way to interact with.

The Framework implements 2 types of trigger signals:

• Single triggers - A single trigger signals only fires when different

state of the trigger has been reached.

• Constant triggers - The Constant Trigger signals his current state (po-

sition, movement delta, segment) every frame as long as the player

interacts with the trigger.

Within the Advanced VR-Framework we have created a set of pre-built

triggers, since they are much wider applicable than it seems. They can be

broadly categorized as buttons and drags. While buttons are work pretty

straight forward, drags need some additional explanations. Drags have

a movable element that can be grabbed. The movement is confined in

a predetermined fashion and the progress of this movement is send to

the paired actors. The paired actors receiving the progress input must

be implementing the ”ListenToTrigger” interface. This concept has been

implemented in 3 ways within the Framework to accommodate several

modes of application.

Buttons

Figure 15. Button

Buttons initiate an in-game event upon a single interaction.

Examples: button stand, pressure plate

Setup:

15

• button distance

• set

• holding button

• only trigger by mcomp

Linear Drags

Figure 16. Linear drag

With linear drags the player can move the dragged actor along one axis.

The transmitted signal to the paired actor consists in the position of the

drag on the axis.

Examples: drawers

Setup: Upon creating a linear drag class define:

1) drag type: the drag types mainly differ in what happens upon

release of the dragged actor. Choose on of three possibilities:

• free movement: if you let go the dragged actor stays where it is

• snap to segment: each drag is divided into a number of segments.

Upon letting go the dragged actor snaps to the nearest segment

• reset: after letting go the dragged actor resets to its original

position

2) current position: starting position of the drag the current position is updated automati-cally when the drag is used3) segments: For the trigger to work at least 2 segments are necessary

defining the beginning and the end of the drag. Every segment has

three elements:

• position: defines the beginning of the segment With linear drags you can enter any valueas position.• key: labels the segment unequivocally, so the paired actor recog-

nizes relevant signals

• boolian: can be used instead of a key for binary triggers.

Upon placing the trigger in the map:

1) assign paired actors: enter all actors in the map that are affected

by the trigger in the default-section of the trigger instance.

2) adapt paired actors: equip all paired actors with the listen-to-trigger

interface to receive the signal from the trigger. The interface does not process the signaljust receive it. You have to implement your-self how you want the paired actor to react.Spline Based Drags

Figure 17. Spline based drag

A spline based drag expands the concept of linear drags. Instead of along

one axis the dragged actor moves along a predetermined spline which

might be as curvy as you want them. In-game events are initiated as

described for linear drags.

Examples: sliders

Setup: Upon creating a spline based drag class define:







position

16



three elements:

• position: defines the beginning of the segment Values below 0 will be converted to 0 inspline based drags.• key: labels the segment unequivocally, so the paired actor recog-







interface to receive the signal from the trigger. The interface does not process the signaljust receive it. You have to implement your-self how you want the paired actor to react.Angular Drags

Figure 18. Angular drag

In an angular drag the dragged actor moves around central point. Here

the transmitted signal consists in the angle of the drag.

Examples: levers, valves, doors

Setup: Upon creating an angular drag class define:







position



three elements:

• position: defines the beginning of the segment Theoretically you can enter any value asposition for a segment in an angular drag.• key: labels the segment unequivocally, so the paired actor recog-







interface to receive the signal from the trigger. The interface does not process the signaljust receive it. You have to implement your-self how you want the paired actor to react.5.4 Helpers

Most helpers were created to solve prob-lems that can only be efficiently solved byoutsourcing them to another actor.

All helper classes inherit from the actor class and share the characteristic

of being used by other classes to fulfill their function. Instances of helper

classes are either created in the process of another classes functionality

or placed by the developer. Helpers that are automatically placed do not

need to be configured or adjusted. For an overview have a look at the

following list containing all helpers:

17

Debugging Helper The debug helper does not conflict, if youaccess this map through a level change, e.g.a menu. The Game Mode will only fall backto the debug helper if a Info-Level has notbeen set yet.

The debug helper helps associate a map with a level key. This is espe-

cially important when directly starting in a specific level for development

purposes.

Blueprint: BP_Helper_Debug

Placement: Manual.

Setup: Place the BP_Helper_Debug in the map that you want associated

with a specific Level-Info file. Enter the desired Level-Info in the default

section of the BP_Helper_Debug.

If you place a BP_Helper_Debug in a world map you can use it to setwhich level will be used when playing the in world map.

Group Helper

Figure 19. Group helper

The group helper helps managment and assembly of groups of actors

that are supposed to react collectively to an interaction. For example a

group of lamps that is turned on and off together when the player toggles

the appropriate button at one of them.

Blueprint: BP-Helper-Group

Placement: Manual.

Usage: Place the BP_Helper_Group in the scene. You need a different

group helper for each group that you want to set. In the group variable

set every instance that you want in the group.

Climbing Helper

Upon initiating a climb the climbing helper is generated from the motion

component to assists the communication between the climbing motion

component and the climbable actor, see section 7.2.4.

Blueprint: BP_Helper_Climb

Placement: Automatic.

Dragging Helper

The dragging helper is automatically created by a motion component

when interacting with a draggable actor (e.g. Trigger see section 5.3)

to handle the dragging process. Additional information is found in sec-

tion 7.2.3.

Blueprint: BP_Helper_Drag


Snapping Helper

When an actor is grabbed the grab component automatically creates a

snapping helper to assist snapping functionality. The Snapping Helper is

even created when no connector exist on the Actor. For further informa-

tion on the snapping process refer to section 7.3

Blueprint: BP_Helper_Snapping


18

Temporary Destination Helper

The temporary destination helper is created by the snapping helper as

destination for the snapping process. It references the position the ghost

is at, so the actor knows where to go when the snap function is being

executed. Have a look at section 7.3 for a more detailed description.

Blueprint: BP_Helper_TemporaryDestination


Map Actor Helper

The map actor helper is used by the 3D minimap to represent the actor

as an actor inside the 3D-Map (section 8.5.1).

Blueprint: BP_Helper_MapActor


Spline drawing Helper

The spline drawing helper represents the spline drawn by the paint brush

device, see section 5.2

Blueprint: BP_Helper_SplineDrawing


Photo Helper

The photo helper transfers the information on photos taken with the photo

camera device, see section 5.2

Blueprint: BP_Helper_Photo


19

6 CONTROLLERS, PAWNS AND PLAYERS

6.1 Overview

Figure 20. Establishing Control

Directly after game start Unreal is initializing the Game Mode specified

in the Project Settings. For the Framework it is absolutely essential that

the Game Mode in use is of type BP GameMode Main. The GameM-

ode defines a set of Unreal Classes to spawn one of them being the

PlayerController. The PlayerController used in the Framework has to be

of type BP PlayerController Main. The BP PlayerController Main checks

whether the current experience is in VR and the HMD is active.

• If it is: The BP PlayerController Main spawns and possesses a child

of a VR Pawn.

• If it is not: The BP PlayerController Main spawns and possesses a

child of a NonVR Pawn.

The default VR and NonVR pawn to be used has to be set in the game

mode in the Pawn section. Additionally the used pawns can also be set

on a per level basis in the Info-Level file, see section 3.

We suggest that you create child of the VR and NonVR Pawn to use andcustomize for each of your experiences.

The VR Pawn itself spawns one Motion Controller of type BP Base-

MotionController for each side. The Motion Controllers have to be spec-

ified in the Info-Controls. Motion Controllers themselves are simply con- For more information on how to estab-lish motion controllers have a look at sec-tions 6.3 and 6.5.

tainers for Motion Components which contain the functionality of the

Controllers.

Key inputs made by the player are handled by the player controller

and passed to the VR Pawn that either processes the key input directly

or forwards them to the respective Motion Controller. Subsequently the

Motion Controller checks the Info-Controls for the function assigned to

the button and then forwards the button input to the MotionComponent

which is responsible for this function.

6.1.1 Game Instance

Equally to the Game Mode the Game Instance has to be set inside the

MapsModes section of the Project Settings. The Framework requires the

Game Instance to be of the type: BP GameInstance Main. The Game

Instance has the unique ability to keep it state even after a level change.

Which makes it perfect for handling settings like graphics or language

settings.

6.1.2 Game State

The Framework uses the BP GameState Main as its Game State class.

Thus you have to make sure that it is entered in the classes section of

the game mode. The BP GameState Main’s task is to be an universally

accessible entity and as such handle keep track of elements like actor

groups or maps. Additionally it handles game events like loading and

executes the transition maps.

20

6.1.3 Player Controller

The Framework requires the Player Controller to be of type BP Player-

Controller Main. Similar to the Game State the BP PlayerController Main

has to be defined in the Game Mode. The BP PlayerController Main

spawns and controls the VR and NonVR pawn. It also handles the Pause

functionality.

6.2 Pawns

Figure 21. Pawn class hierarchy

Pawns are a Unreal class which have the ability to be controlled by the

Player Controller. The Frameworks most basic Pawn is the BP Pawn Base.

The VR and the NonVR pawn inherit directly from the BP Pawn Base

class. The NonVR class itself then is further inherits to a Normal and a

Spectator class as shown in Figure 21.

6.2.1 VR Pawn

The VR-Pawn represents the player within the VR experience.

Blueprint: BP Pawn VR

Functionalities: The VR pawn implements all necessary functionalities

for the player to interact and move around in the experience including:

Figure 22. VR pawn

• Virtual Body - The VR pawn provides the player with a virtual body

whose head movements and hand positions are follow the HMD

and controllers of the player. The position of the body adjusts itself

accordingly.

• Controllers - The VR pawn spawns a motion controller for each

hand upon starting the experience and transfers key inputs to the

corresponding motion controller.

• Spectator Mode - The VR pawn can also handle key input from

the keyboard. Upon activation of a spectator mode it spawns the For more info on the spectator mode seesection 6.2.3.spectator pawn and subsquently passes on any key input from the

keyboard to the spectator pawn.

• Bodyslots - The VR pawn provides seven anchors at different posi-

tions of its body where the player can attach objects in-game.

6.2.2 NonVR Pawn

Figure 23. NonVR pawn

The NonVR pawn was created to operate your experiences without a

HMD.

Blueprint: BP_Pawn_NonVR_Normal

Functionalities: The NonVR pawn has been constructed to emulate as

many functionalities of the VR pawn as possible:

• Movement - The NonVR Pawn moves with the wasd-keys, sprints

with shift, crouches with c and jumps with space.

• Select - The NonVR Pawn selects an object by clicking the left mouse

button.

• Grab - The NonVR Pawn grabs an object by holding the left mouse

button. Holding the right mouse button allows you to rotate the

grabbed object.

21

• Change Mouse Mode: With alt you can change the mouse mode.

You have two options:

– fps style - use the mouse to look around

– free mouse - the mouse moves independently within the current

field of view.

Setup: The main configuration you can make at the NonVR pawn regards

the movement style. You can choose:

• Walk - the NonVR pawn is affected by collision and gravity

• Fly - the NonVR pawn ignores collision and gravity

6.2.3 Spectator Pawn

Figure 24. Spectator Mode

The spectator pawn is of the NonVR pawn type. It serves as mobile

viewpoint for a second person watching the active player in the VR

experience from the monitor.

Blueprint: BP_Pawn_NonVR_Spectator

How To Use It: Activate the spectator mode by pressing any of the keys

1–4 on the keyboard. The spectator pawn is spawned automatically on

the nearest spectator location. Use keys 1–4 to change between spectator

modes:

1) Mode 01 - the monitor shows what the VR pawn sees

2) Mode 02 - the monitor shows what the spectator pawn sees

3) Mode 03 - the monitor shows what the spectator pawn sees with

an inlay of what the VR pawn sees

4) Mode 04 - the monitor shows what the VR pawn sees with an inlay

of what the spectator pawn sees.

Figure 25. Spektator mode 03

You can change between up to 10 viewpoints for the spectator pawn

using the numpad.

Setup:

1) Place up to 10 viewpoints for the spectator pawn in your map.

2) Tag each viewpoint with one digit from 0–9 to make them available

in spectator mode

The spectator pawn cannot be used in combination with the nonVR Pawn.

Pause Pawn

Replaces the VR or NonVR pawn upon pausing the experience.

How It Works: The input from the pause button is the only one, that is

processed by the player controller itself. Upon the player pressing the pause

button, the player controller intercepts the input and loads the pause level of

the corresponding world map. Subsequently the player controller spawns

and possesses the pause pawn. The pause pawn in turn spawns its own If in VR the player controller will spawnand possess an VR-Pawn with Pause MotionControllers.

motion controller . When repressing the pause button the player controller

will repossess the playing pawn. The pause pawn will be destroyed and

the Pause map unloaded. The Game will continue as before.

22

6.3 Controllers

Each controller is composed of a base motion controller and motion com-

ponents. The base motion controller mainly acts as a box for the motion

components. The motion components on the other hand can be attached

to each motion controller independently from each other like components

to actor classes. You can use this concept to create your own customized

controllers or use one of the 3 pre-built controllers the Advanced VR

Framework 2.0 provides. Each of them supports the functionalities high-

light, select and grab. However, depending on the controller type these

functionalities are implemented differently.

Different controller types have a profound effect on the play-style andfeeling provided by the experience. Also specific functionalities are moresuccessfully implemented in conjunction with specific controller types. Youcan of course mix and match as you like. However, your results will bemore accessible, if you stick to specific combinations.

6.3.1 The Laser Controller

Figure 26. Laser motion controller

The laser controller appears as an animated VR controller (matching

HMD) with a laser at one or both hands. The laser pointer is its main

means of interaction with the experience. The laser adopts all three main

functionalities of the controller (select, highlight and grab).

Blueprints: BP_MotionController_Controller_Laser

BP_MotionController_Controller_Laser_Single

The single laser controller has the laseronly at one hand. Consequently the lefthand and right hand controller are differentfor this setting.

Figure 27. Button map laser controller

Motion components included:

MComp_Controller

MComp_Laser Pointer

MComp_Teleporter

MComp_Movement

MComp_Radial Menu

Functionalities:

• highlights in-game items when the laser touches them

• selects suitable in-game items upon pressing of the pointer finger

button

• grabs suitable in-game items upon pressing the grip button

• teleports the pawn upon pressing the assigned button according to

the appointed movement options (for more see section 6.4)

• moves the pawn upon pressing the assigned button according to the

appointed movement options (for more see section 6.4)

• opens the radial menu upon pressing of the assigned button

6.3.2 The Pointer Controller

Figure 28. Pointer motion controller

The pointer controller is an animated VR controller (matching HMD) with

a pointer sphere at both controllers replacing a laser

Blueprint: BP_MotionController_Pointer


23

MComp_Controller

MComp_Pointer

MComp_Teleporter

MComp_Movement

MComp_RadialMenu

Functionalities:

Figure 29. Button map pointer controller

• highlights in-game items upon touch

• selects the in-game items the pointer touches upon pressing the trig-

ger button

• grabs in-game items within a defined distance upon pressing the grip

button

• teleports the pawn upon pressing the assigned button (for more see

section 6.4)

• moves the pawn upon pressing the assigned button (for more see

section 6.4)

• opens the radial menu upon pressing of the assigned button

The controller you see in-game is just a visual representation of the VR Mo-tion Controller. The Controller switches between the HTC Vive and OculusRift controller depending on which system is in use. Button mappings areincluded for both controllers in the Advanced VR Framework 2.0

6.3.3 VR Hands

Figure 30. VR Hands motion controller

The VR Hands Controller appears in-game as animated hands capable of

showing different hand gestures upon the corresponding key inputs by

touching or pressing the buttons of the controller.

Blueprints: BP_MotionController_Hands

BP_MotionController_HandWithWatch

Has the smartwatch only at one hand.Consequently the left hand and right handcontroller are different for this setting.


MComp_Hand

MComp_Teleporter

MComp_Movement

MComp_RadialMenu

MComp_SmartWatch

Functionalities:

Figure 31. Button map VR hands

• selects suitable in-game items by touching them with the pointer fin-

ger outstretched

• grabs suitable in-game items within a pre-defined distance upon press-

ing the grip button

• teleports the pawn upon pressing the assigned button.

• moves the pawn upon pressing the assigned button.

6.3.4 Pause Controller

The pause level has its own base motion controller, the motion controller

pause, which contains only the controller motion component.

24

This means during the pause the controller will always look like the oculusrift or vive controller regardless of the appearance of the controller withinthe level.

Within the pause level the motion controller and its component only

ensure the visual appearance of controllers, since all input from the pause

button is handled directly by the player controller.

6.4 Motion Components

Motion components work similar to actor components. Consequently, Find an in detail description of how tocreate custom made controllers at the endof this section.

you can custom design controllers in a similar fashion as you can create

new actor classes. Motion Components frequently interact with actor

Figure 32.

components to perform complex functionalities like grabbing or selecting

just like actor components cooperate among themselves, see Figure 32 for

a schematic example. The Advanced VR Framework 2.0 contains overall

9 custom made motion components.

Controller Motion Component

Figure 33.

The Controller Motion Component is a simple Mesh representation of the

Motion Controller.

Blueprint: BP_MComp_Controller

Functionalities:

• Select and display the controller´s mesh according to the current

HMD or Controller Mesh override.

• Highlight currently pressed buttons on the mesh.

Setup: Define the motion controller mesh under controller mesh override

in BP_Info_Controls if you don´t want to use the mesh of the current

HMD.

6.4.1 Hands Motion Component

The hands motion component gives the controller the shape of animated

hands with the corresponding animations representing the hands of the

pawn. Blueprint: BP_MComp_Hand

Functionalities:

• shows gestures and grab positions according to the animation blueprint

AnimBP_Hand_Left depending on the current key inputs. mirrored animations for the right hand aregenerated automatically.• highlights actors if they are facing the palm and within reach using

the following color code:

– blue: the object is grabable.

– red: the object is dragable

– white: the object can be used for climbing

• selects suitable actors by tapping with the outstretched index finger. Grabbing an actor prevents the selectionfunction on the motion controller executingthe grab.

• grabs and holds objects (see section 7.2).

• drags draggable objects (see section 5.3).

• climbs by interacting with climbing actors (see section 7.2.4).

25

6.4.2 Laser Motion Component

The laser motion component attaches a laser to the controller providing

the player with a possibility of remote interaction with in-game objects.

The laser is implemented as a colored trace emitted by the front of the

motion controller that is able to interact with in-game actors it falls onto.

Blueprint: BP_MComp_Controller_Laser

Functionalities:

• highlights actors the laser touches with the following color code:

– blue: object is selectable

– white: object is grabable

– red: object is draggable

• selects the objects the laser touches upon key input

• grabs suitable objects upon key input by attaching the laser to it

• drags suitable objects after grabbing

6.4.3 Pointer Motion Component

The pointer motion component attaches a spherical pointer to the con-

troller. The pointer implements all interaction possibilities of the laser,

but can be only used for interaction with objects in reach.

Blueprint: BP_MComp_Pointer

Functionalities:

• highlights objects the pointer overlaps with using the following color

code:

– blue: the object is selectable

– white: the object is grabable

– red: the object is dragable

• selects objects the pointer overlaps with upon key input

• grabs suitable objects when the pointer overlaps with them

• drags dragable objects after grabbing

6.4.4 Radial Menu Motion Component

Figure 34. Radial Menu

The radial menu motion component spawns a circular set of buttons (see

Figure34) that can be selected either by the thumbstick at the same hand

or the laser of the other hand.

Blueprint: BP_MComp_RadialMenu

Functionalities: Upon opening the radial will cause the radial menu to

spawn a selection of radial menu buttons. Upon triggering a radial menu

button the assigned function is executed. Possible functions can be used:

• spawn pallet

• was noch?

The radial menu automatically closes when a button has been triggered.

Setup: All buttons need to be added in the Info-UI file of the level.

6.4.5 Smartwatch Motion Component

Figure 35. Smartwatch

The smartwatch motion component attaches a smartwatch to the con-

troller which can display information and serve as UI.

26

Blueprint: BP_MComp_Smartwatch

How To Use It: The smartwatch navigates the display and serves to

display information permanently. Additionally, the smartwatch controls

the display offering the following functionalities:

• spawn/despawn display upon pressing the assigned button

• position display in eye level upon pushing the thumbstick to the

front

• position display over wrist upon pushing the thumbstick back

The radial menu and the smartwatch serve similar purposes. However,their different implementation makes the radial menu more suitable forvisualisations, while the smart watch is more appropriate for a diegetic UIin games.

6.4.6 Teleporter Motion Component

Figure 36. Teleport with rotation by hand

The teleporter motion component enables and controls teleportation

Blueprint: BP_MComp_Teleport

Figure 37. Teleport with area select

Setup:

1) assign a button in the info-control files to activate the teleporter

2) Add the teleporter motion component to your motion controller

3) Under teleport rotation type select how you want the pawn to be

rotated during teleport. You have the following options:

• None - Prevents any teleport rotation

• Rotate by hand - aligns the pawn´s rotation at the destination

of the teleportation with the vertical rotation of the controller

in the hand of the player after activating the teleportation (see

Figure 36).

• Rotate by Thumbstick - sets the desired rotation of the pawn at

the destination of the teleportation according to the thumbstick.

Figure 38. Straight laser for teleport

4) Under teleport search type define how the laser of the teleporter

looks like. You have the following options:

• Straight - the laser emerges as a straight line from the controller

as shown in Figure 41

• Trajectory - the laser forms a trajectory towards the floor as

shown in Figure 39

• Navigation - the laser forms a trajectory to the nearest position

on the navigation mesh

The navigation mesh is provided by Un-real, have a look at an Unreal tutorial formore information.

Figure 39. Trajectory laser for teleport

5) Under teleport movement assign the teleporting options:

• None - disables teleportation

• Teleport free - allows the player to teleport anywhere in the

map.

• Teleport Area Activate - the player will only be able to assigned

areas highlighted upon activation of the teleporter

• Teleport Select - allows teleportation to assigned area using the

select functionality (see Figure 37).

6) Under teleport time assign the total duration of the teleport

27

7) Under oculus teleport merges the oculuc teleportation settings into

your experience within the Advanced VR Framework 2.0

8) versteh ich nicht

9) was noch?

How It Works: The teleporter is activated by the assigned button. Upon

activation it spawns a laser and teleport mesh (see Figure 37). xx moves

the pawn instantly to the location selected by the laser.

6.4.7 Movement Motion Component

Figure 40. Ghost movement: walking

The movement motion component enables and controls all movement

options except teleportation

Blueprint: BP_MComp_Movement

Functionalities:

Setup:

1) Add the movement motion component to your motion controller

2) Under movement options select which type of movement you prefer

for the player.

• none - prohibits direct movement

• walk - allows only walking on the floor

• fly - allows free movement into all directions

3) Under movement style you can select how the movement is pre-

sented to the player.

• Fluent - translates the input directly into movement This option is very likely to cause motionsickness.• Stop Motion - similar to fluent movement the input is translated

directly into the movement of the pawn, however only certain

intervals are shown to the player. Set the interval in seconds for

stop motion movement in the movement iteration options.

• Ghost Movement - upon starting the movement a ghost is This movement option has the least riskof motion sickness along with teleport.spawned that moves instead of the player. At the end of the

How the ghost is represented in-gameis determined by the selected movementoption as follows:walk: the ghost looks like a mannequinfly: the ghost looks like a camera

movement action the player is teleported to the location of the

ghost. Under ghost movement behaviour select how the player

should control the ghost. You have three options:

– Direction - the ghost moves into the direction the controller

is currently facing.

– Move Relative to Origin - the ghost´s movements are con-

trolled by the position of the controller at any given moment

relative to the position of the controller at the start of the

movement.

– Position Relative to Origin - positions the ghost at the cur-

rent position of the controller relative to the position of the

controller at the start of the movement.

Figure 41. Ghost movement: fly

4) Set the speed of the movement under movement speed

5) Activate movement with fade in case you want to use fade in com-

bination with stop motion or ghost movement.

6) was noch?

28

We decided to not implement the movement using the thumb stick, sincethe vive controller for example does not facilitate this. In this way theAdvanced VR Framework 2.0 stays compatible with the maximum numberof HMDs.

6.5 Custom Controllers

The only thing that can interfere with the button mapping of controlers isthe snap and replace controls functionality that devices for example have.This function overwrites all function mappings except grab.

Setup

1) Create a child of the base motion control class

The base motion controller is fundamentally a box to put motioncomponents into. Base motion controller and a number of motioncomponent add up to a functioning controller within your experience.

2) Add the necessary motion components for the desired functionali-

ties

All motion components are designed to work regardless of your con-troller type or combination.

3) Connect your functions (like grab, select, ...) to the responsible mo-

tion component

4) Create a corresponding info class

5) Enter the button mapping of your new controller into its info class

All motion components are designed to function on both hands and allmodifications necessary to switch from left hand to right hand or viceversa are performed automatically. Thus, you can use one and the samemotion controller for both hands unless you want them to be different inthe experience like a smartwatch on one hand but not on the other.

7 ADVANCED CONTROLLER FUNCTIONALITIES

Advanced controller functionalities require the motion controller and its

motion components to interact with one or several components on the

actors the player chooses to interact with. Herein we present the most

important functionalities and show you how to set them up in your own

experience.

7.1 Selecting

The selection component makes an item selectable in-game. Its main func-

tion however, is information transfer. In consequence, the selection com-

ponent collaborates with other components depending what you want to

29

happen upon selection.

How It Works: reacts to input from the controller’s trigger finger button

either forwarding it to the selection menu component or to the window object

component or to a customary function of the actor.

Setup:

1) Add the selection component to your actor.

2) Under default/type enter what you want to happen upon selection.

You have the following options:

• None - Nothing happens.

• Custom - The input is directly transferred to the select interface

of the actor and all its processing has to be implemented on the

actor itself.

• Selection Menu - The input is transferred to the selection menu Requires the selection menu componentand possibly other components, see sec-tion 8.3

component which in turn opens the selection menu.

• Window - The input is transferred to the window object com-

ponent which in turn spawns a window object. Requires the window object component.For more information have a look at sec-tion 8.4

3) Additionally you can temporarily disable select under default/en-

able select.

4) Leave everything else untouched.

7.2 Grabbing and Co

Grabbing works quite differently depending on the controller used. The

VR Hands especially need close attention to make the grabbing look good

and feel natural for the player. For that reason we will go over grabbing

with different controllers separately starting with the simplest version

using the laser controller.

7.2.1 Grabbing With the Laser Controller

The laser controller grabs the interactible highlighted by the laser.

How it works: Upon being grabbed the actor attaches itself to the end-

point of the laser. However, the grabbed actors do not rotate with the

laser, when the controller is rotated. Instead the player can access the

transform of the actor using the thumbstick. By pressing the thumbstick

the player can cycle through 3 modi:

• distance + rotation: the thumbstick´s y-axis moves the object nearer

and farther from the pawn and the thumbstick´s x-axis rotates the

object around its z-axis.

• two axis rotation: the thumbstick´s x-axis rotates the object around

its z-axis. and the thumbstick´s y-axis rotates the object around its

y-axis.

• distance + scale: the thumbstick´s y-axis moves the object nearer and

farther from the pawn and the thumbstick´s x-axis scales the object.

Setup: Under Comp_Grab/Attributes enter:

1) grab type: normal (free placement, no collision) or physics handle

(collision is on, no free placement)

2) behaviour: free placement (upon release the item stays where it is)

or physics (upon release the item falls to the floor)

30

3) autoturn: rotates the z-axix of the item to point up

4) autopickup: no button press on the controller is necessary to pick

up an item

5) can be picked up: enables or disables the grab functionality

6) Snap and Replace Controlls: enables a device to attach to the

controller and overwrite its own functionalities to each button, see

section 5.2.

Regarding grabbing the pointer controller works practically like the lasercontroller. However, the pointer controller cannot grab items at a distanceunlike the laser controller. But it has the advantage, that the rotation ofthe controller is forwarded to the grabbed item.

7.2.2 Grabbing With the VR Hands

Figure 42. Grabbing a Vase with L_00

VR Hands grab the interactible within reach.

How it works: When the VR hands try to grab an item, the grab com-

ponent searches the mesh of the item for suitable sockets and relates the

most suitable socket to the controller. In general this will be the closest

compatible socket. This implementation allows the possibility for the

object to snap onto preferred locations without having to make specific

meshes with weird pivot locations.

Setup:

1) Enter settings under Comp_Grab/Attributes as described above.

2) Place a suitable number of sockets at the mesh of the object at places

where grabbing it with the VR hands would look naturally.

3) Enter a name for each socket following the naming conventions All characters following this first 4 charac-ters are ignored and can be used as required.

X NNIn this X is either the letter L or R assigning the socket to the leftVR Hand (L) or the right VR Hand (R). And N a number between0 and 3 assigning the posture of the VR Hand as:

• 00 generic grab, figure A• 01 controller grab, figure B• 02 pinch grab, figure C• 03 pingpong grab, figure D

So L_00 for example assigns a socket to the left controller in ageneric grab posture as shown in Figure 42 for the mug.

7.2.3 Dragging

The dragging functionality allows the player to drag an object (lever or

slide) according to predefined settings. Dragging can be executed with VR handsas well as laser or pointer motion controller.Setup:

1) Add the dragging interface to the actor you want to drag.

2) Additional setup for triggers might be necessary.

31

How it works: Upon grabbing a drag trigger, the controller interacts

with the dragging interface and spawns the dragging helper. During the

dragging the Controller holds onto the dragging helper. And the dragging

helper communicates its position to the drag trigger which follows the

dragging helper and triggers events according to its position.

7.2.4 Climbing

The climbing functionality enables the player to climb vertical surfaces. Climbing can only be executed with theVR hands as motion controllers.Setup: Add the climbing interface to the actor you want to be used for

Figure 43. Climbing

climbing.

How it works: Upon grabbing, the controller interacts with the climbing

interface and spawns the climbing helper. During climbing the climbing

helper is grabbed and moved by the controller and tells the pawn how

to move relative to the controller.

Note: still in development

7.3 Snapping

In a snapping process a grabbed actor moves into a suitable position

upon release instead of just falling or staying in place. This can either be

on a surface or attached to another actor depending on implementation.

7.3.1 Snap To Surface

Figure 44. Snap to surface

The snap to surface functionality allows a grabbed object to automatically

place itself on a suitable surface (wall, floor or ceiling) upon release (see

Figure 44).

How it works: Like the dragging functionality, snapping heavily relies on

the helper class to function. Two helper classes, namely BP_Helper_Tem-

poraryDestination and BP_ Helper_Snapping, provide necessary

assistance to enable objects to snap into place. The snapping helper is

always spawned when an item is grabbed and checks all connectors of

the item whether they detected a suitable surface for snapping. If they

did, it spawns the temporary destination helper to keep track of the position

and indicate it to the player. Subsequently, when the player releases the

object it, moves towards the position of the temporary destination helper

and stays there. The temporary destination helper itself is destroyed in the

process.

Setup:

1) Add the component Comp_Connector_Surface to the actor

Connectors are absolutely necessary for an actor to be able to snap toa surface. Without connectors the snapping helper cannot managethe snapping process.

2) Make sure the forward vector of the surface connector component

points in the direction you want the surface to be.

32

For visualisation add a vector component to the actor that is parallelto the forward vector of the surface connector component

3) Under xx enable rotate to surface if you want the actor to automat-

ically rotate into a suitable position towards the surface.

4) Under xx enter the distance in which you want the surface connector

to search for surfaces.

5) Check allow physics if you want physics to kick in after snapping. Physics and snapping to place may ex-clude each other. If the surface is a wall ora ceiling, the item might fall after snappingin case physics are activated. That’s whatthe allow physics setting on the connectorprevents.

6) Check should be active even with physics to prevent physics from

interfering with the snapping process

7.3.2 Snap To Anchor (Attach)

With the snap to anchor functionality the player can attach two objects

to each other or an objects to the pawn. The body slots act like anchors that at-tached to the pawn.How it works: For the attach functionality to work ingame, the anchor

and connector of two items must be aligned and the tags of both anchor

and connector need the same tag. Anchors can have multiple tags (in

contrast to connectors), so a variety of items can be attached to the same

anchor.

Setup: The attach functionality requires a dual setup to prepare the at-

Figure 45. Attach/Snap to anchor

tachable actor as well as the accepting actor. On the attachable actor:

1) Add the connector anchor component

Connectors and anchors are absolutely necessary for an actor to beable to attach to another actor. Without connectors and anchors thesnapping helper cannot manage the snapping process.

2) Align the forward vector of the snap to anchor component to be

perpendicular to the surface that is supposed to touch the accepting

actor.

3) On the snap to anchor component enter the search distance and

radius under xx to define the area in which the component searches

for an anchor.

4) Under xx enter the connector ID that determines which anchors the

actor is supposed to be attached to.

Figure 46. Anchor and connector of a pair of attachable actors

On the accepting actor:

1) Add an anchor to the accepting actor on the position you want other

actors to be able to attach to it

2) Adjust the anchor, so it is perpendicular to the surface other actors

should be attached at.

3) On the anchor enter the following settings:

• Under xx enter all connector IDs that should be allowed to

connect to this actor

• If you want physics to kick in after the snapping to anchor

process check allow physics.

• For short term deactivation of snapping to the anchor uncheck

connector should attach.

33

• Under sphere radius adjust the size of the zone where the an-

chor is active It´s beneficial not to set a very smallsphere radius, because then the anchormight be to small to be found easily by thecomponent.

In case of anchor vs surface the anchor is always preferred by the snappinghelper.

8 USER INTERFACES (UI)

The Advanced VR Framework 2.0 has several user interfaces to choose

from implementing information display as well as a plethora of possibil-

ities for the player to interact with in-game items including highlighting

as well as several menus and displays.

8.1 Highlighting

Highlighting is the simplest method to convey information and guide the

players attention to objects of interest. As many functionalities of the Ad-

vanced VR Framework 2.0 highlighting is implemented in components.

To enable highlighting of an in-game item simply add the corresponding

component either to the class or to the instance in question. You have two

components to choose from: the gazeview component and the highlight

component for normal highlighting.

We recommend finetuning your highlighting method to the kind of con-troller you want to use in your experience. The gazeview component is verywell suited to the VR hands. The highlight component works directly withthe laser of the laser controller, so it is more suited for the laser controller.

Highlight Component

Figure 47. Post Process Highlighting

The highlight component highlights an item, when the laser of the con-

troller touches it.

Blueprint: Comp_Highlight

Setup:

1) Add the highlight component to the actor you want to highlight.

2) Under Comp_Highlight/Default select the highlighting type:

• none: nothing happens

• post process: creates a bright frame around the highlighted item

as shown in Figure 47 The color of the post process highlightingfollows the reference entered in the con-troller blueprint. If you want to change ithave a look at the respective blueprints.

• mesh: spawns a ghost mesh around the item in question (still

under construction)

• size: the item in question increases its size temporarily (still

under construction)

• custom: customary reaction, that has to be entered into the class

blueprint.

3) Add a sound to notify the player that highlighting has started and

finished, if you find it necessary.

34

4) Adjust the timeout to the time you want the highlight to last after

the laser left the object.

5) All other settings leave as they are.

GazeView

Figure 48. Highlighting with Gazeview

GazeView is a different implementation of highlighting. Instead of de-

pending on the controller it traces where the player looks and highlights

interactibles accordingly.

Blueprint: Comp_GazeView

Setup:

1) Add the gazeviwe component to the actor in question.

2) Under Comp_GazeView/Default select the highlighting type:

• none: nothing happens

• button: the single button is created that can perform one of the

actions described in section 8.3.

• trigger with progress: spawns a progress bar which fills when

the player continues to look at the item. Upon reaching the

designated time the gazeview component communicates to the

trigger interface and a predetermined action is triggered.

• custom: customary reaction, that has to be entered into the class

blueprint.

3) Add a sound to notify the player that highlighting has started and

finished, if you find it necessary.

4) Adjust the timeout to the time you want the highlight to last after

the laser left the object.

5) All other settings leave as they are.

Gazeview is a great tool for players that are inexperienced with VR (orhandling controllers), since it highlights items of interest automatically. Itis an especially good match for the VR hand controller or the pointercontroller, because Gazeview is not dependent on a laser to highlightobjects out of reach of the player.

8.2 Pallets

Figure 49. 2D Minimap

Pallets are spawned by the radial menu to display information and im-

plement several functionalities. Each pallet consists in a widget and im-

plements the following functionalities:

• Display 2D Minimaps

• Spawn objects, bookmarks or devices

• Browse detailed data on objects

• Display the menu

8.2.1 2D Minimaps

The 2D Minimap pallet displays a 2-dimensional map using a widget.

How To Use It: Open the respective pallet or display to display the 2D

minimap. Select any position within the 2D minimap to teleport to it. In

35

case of multiple floors, a 2D minimap of each floor can be accessed via

the sidebar of the pallet.

Display Options: pallet or smartwatch

Setup:

1) Add the map location component to all actors that are supposed to

appear on the minimap. Walls, furniture or other items that shouldnot be moved are easier displayed in thetexture providing the background of theminimap.

2) Enter for each map location component:

• if the rotation and scale of the item should be transmitted

• if the item is supposed to appear on 2D or 3D minimaps or both

• which icon should display the item and the scale of the icon

3) Place the floor plan measurement helper at a appropriate position in

the map.

4) Insert the texture of the minimap in the floor plan measurement helper Please note that the picture you use astexture for the minimap should have theformat 2160x1500 and ensure that the ratiostays the same.

and scale it until the texture matches the relevant area of the map.

5) Place all necessary volume boxes on the area of the map that is

relevant for the minimap in question. And tag them as 2D volume

boxes.

The volume boxes determine the relevancy of items for the displayedmap. All items out side the assigned volume box or volume boxesare not displayed in the map notwithstanding their attached maplocation component

6) For minimaps with multiples stores you need to place and establish

one floor plan measurement helper for each store.

How it works: In the experience the absolute position of every item

is forwarded by the map location component to the 2D minimap widget.

To display the map, the 2D minimap widget calls upon the floor plan

measurement helper to check the relevance of the item for the map in

question and calculate the relative position of the item (see Figure 49)

8.2.2 The Object Dropper

Figure 50. Object Dropper

The object dropper is a pallet to display a predefined set of actors orga-

nized in categories. Additionally, the object dropper allows the player to

place objects like furniture or walls while being in game.

How To Use It: Upon selecting an item in the pallet, it is spawn as a

grabbed item in the experience. Place it at the desired spot by pressing

the grip button.

Setup:

1) enter into the info level file of the level a list of top categories and

actor classes you want to include into the object dropper

2) check for all top-categories that they are listed in your datatables

(see section ??).

3) enter details for each actor class into the info data file of the level

specifying the key of the actor, the overall category (including top

36

category and sub category) and a texture to be used in the object

dropper

4) you can place the pallet in your maps or spawn an object dropper

pallet from the radial menu.

8.2.3 Bookmarks

Figure 51. Bookmarks pallet.

The bookmarks pallet works similar to the object dropper. Bookmarks

are actors intended to mark the spots you have been working at last or

change request from your clients.

How To Use It: Upon selecting a bookmark in the pallet, it is spawn as

a grabbed item in the experience. Place it at the desired spot by pressing

the grip button.

Setup:

1) All necessary files are in the folder Blueprints/Info

2) In BP_Info_Pallet create an entry under ?? hitting the +-button

and fill in the name of the ??, picture, key word and category

3) In ?? (If you want this in all levels) or ?? create an entry under

Default Value/?? with the name of the class. Enter all other info

you already entered in step 2.

8.2.4 Data Browser

Figure 52. Data browser pallet.

8.2.5 Devices Pallet

Figure 53. Devices pallet.

Shows and spawns the devices assigned in the info-xx file of the level.

8.2.6 Menu Pallet

Figure 54. Menu pallet

The menu pallet displays a menu that allows the following functionalities:

reset resets the level to its original state. Removes splines drawn

by the xx device, ...

load menu loads the menu level, enabling the player to change level

without restarting the experience.

quit quits the experience

settings allows the player to adjust

• movement (see section 6.4)

• language (see section 9.2)

• graphic settings (under construction)

• audio settings (under construction)

8.3 Selection Menu

The selection menu manages a number of possible interactions of the

Do not get this mixed up with the radialmenu. The selection menu is a componentattached to an actor class or an instance ofan actor class. The radial menu on the otherhand is a motion component added to amotion controller.

player with an interactible with the necessary components.

Blueprint: Comp_SelectionMenu

How To Use It: Upon selecting a suitable interactible with the controller

the selection menu is spawned as a set of buttons arranged in a circular

fashion. Selecting one button may either trigger a functionality listed

below or spawn another set of buttons. Selecting the central button closes

the corresponding part of the selection menu.

Functionalities:

Figure 55. Selection Menu

37

• Change object, material or light color

• Toggle light, activate, delete, open or close

• Display an info window

Setup: You can modify the menu according to your wishes in the by

entering your pick of the following functions in the appropriate field of

the selection menu component.

1) Add the Comp-SelectionMenu component to the actor class.

2) Under selection type add all buttons you want to have in the

menu, that opens upon interaction. You can insert as many buttons here asyou need.

Please don´t neglect these steps. If you don´t define anything here, thereno buttons appear in your menu. And in a case of doubt, select the typeof selection menu that works best with your controller settings.

8.3.1 Exchange

Exchanges an object for an object of another class inside the experience.

How To Use It: Upon activation the button spawns a subgroup of buttons

for each actor class you want the in-game item to be exchangeable with.

Upon selecting one of the buttons the in-game item will be replaced by an

instance of the selected class with all functions defined therein.

Setup:

1) Add the Exchange-Comp to the actor class. Include the actor itself in the list.2) Under Comp-Exchange/Exchange enter all actors you want to

exchange this actor with.

3) Repeat the former steps at all objects you entered in the 2nd step.

Please remember, that in this case the whole instance will be exchangedincluding all functionalities. Consequently, every exchange will be a one-way street unless you establish the appropriate exchange-component on allactors you want to exchange with each other.

8.3.2 Change material

Exchanges the material, skeletal mesh or static mesh of an object in game.

How To Use It: On pressing the selection button spawns a set of material

selection buttons equal to the number of possible materials or meshes

defined in the actor class. Pressing a material selection button enables

you to change the appearance of an instance (of the actor-type) in-game

according to the matching definitions made in the respective actor class.

Setup:

1) Add Comp-Material to the actor class.

2) Under Comp-Material/ Assigned buttons assign the material This is mainly a cosmetic matter, since ma-terials look quite unattractive when pressedonto the buttons.

each button is to appear in.

3) Enter a tag for each button to match it to the intended material.

If you don´t add anything here, there willbe no button, so don´t forget it.

38

4) Under Comp-Materials/Possible Materials add one slot for

each button you created and enter the matching tags.

5) In each of the slots you created add a map element for every static

mesh that is part of your actor and that should be included in the

material exchange. Define fore each static mesh:

• the corresponding mesh component

• an individual tag of each mesh component

6) Add into each map element one of the 3 members:

• static meshs you want to exchange

• skeletal meshs you want to exchange

• materials you want to exchange

Please consider, that you have to choose one of these options.

7) Test the result of your effort using the Search Next Color button. It

will successively show you all tags you entered under Current

Material

8) State the tag of the material or mesh you want the instances to appear

with first when you add them to the level.

The exchange and change material functionality seem rather similar atfirst. Especially since you can exchange skeletal and static meshes as wellas materials. However, there are several important distinctions between thetwo functionalities mainly concerning the consequences of the execution ofone of the actions on the in-game item in question.

Exchange Change Material

changes the complete actoronly changes one specified traitof the actor (static mesh, skeletalmesh or material)

may change the class of the actordoes not change the class of theactor

functionalities of the item changecompletely

the item retains all its functionali-ties

8.3.3 Show Info Window

Shows predefined information on an object in a widget.

How To Use It: The button spawns a window showing various param-

eters of the in-game item. The window object updates the parameters in

real time and can also be grabbed and moved around and selected.

Setup:

1) Add the component WindowObject to the actor

2) Under xx enter all details you want to include in the info window.

8.3.4 Toggle light

Turns the light on and off.

How To Use It: Press the buttons to trigger the toggle light event on an

39

interactible. Lights have this functionality implemented with a timeline

which automatically targets all light components within the ??.

Setup:

1) Add the interface Light to the actor class.

8.3.5 Change light color

Changes the color of the light of an interactble. This function works quite Remember, this does not replace the ToggleLight-function.similar to the change material component.

How To Use It: This selection button spawns a number of material selec-

tion buttons which represent different colours the light can adopt. Upon

activation the light color is set directly to the respective colour parameter

of the light itself.

Setup:

1) Add the component Comp_xx to the light in question.

2) Under Possible Light Colors enter all colors you want for the

light. There is no need to include additionalcolors for the buttons, since this only affectsthe appearance in the menu which won´t bea problem in this case.

3) Under Current Light Color define the light color you want to

see first upon toggling the light.

8.3.6 Open/close

Opens or closes a door or similar interactible.

How To Use It: Select the button activate the toggle open event on the

interactable which handles a timeline based door movement.

Setup:

1) Add the Open/Close interface to the actor class.

8.3.7 Activate

activates a predefined event on the interactible.

How To Use It: Select the button to toggle the active event on the nter-

actable. It is intended for media objects likescreens or radios. The only object imple-menting this feature is currently the TVobject. It plays a demo media source file onloop.

Setup:

1) Add the interface named Activate to the actor class.

8.3.8 Delete

The delete selection button allows an interactable to be destroyed after a

short scaling animation.

Setup:

1) Add the interface named Delete to the actor class.

8.4 Window object

Figure 56. Window object

The window object serves as an alternative to the selection menu.

Blueprint:

Setup:

How It Works:

40

8.5 Display

Figure 57. Window object

The display is quite similar to the pallets, but it is designed to support a

more action oriented play-style. The display is an actor which includes

a widget to display texts and the 3DMap component to display the

3D minimap. As the pallet it is controlled by a specifically designed

motion component, the smartwatch. Like many elements intended for

more action-oriented experiences the display is still under constructions

in many respects. Right now it contains slides for:

• Stats (see section 9.4).

• Inventory (under construction).

• Minimaps (see section 8.2.1 or 8.5.1).

• Achievements (see section 9.3).

• Missions (under construction).

• Menu (under construction).

8.5.1 3D Minimaps

Figure 58. 3D Minimap

In the Advanced VR Framework the 3D-minimap is implemented as a

3-dimensional map displayed by a component.

Display options: smartwatch, level map of the experience

Setup:

1) Add the map location component to all actors that are supposed to

appear on the minimap.

2) Enter for each map location component:

• if the rotation and scale of the item should be transmitted

• if the item is supposed to appear on 2D or 3D minimaps or both

• if the item should be displayed with a substitute material or as

they appear in the map

3) Place the floor plan measurement helper at a appropriate position in

the map.

4) ??

5) Place all necessary volume boxes on the area of the map that is

relevant for the minimap in question. And tag them as 3D volume

boxes.

The floor plan measurement helper is flexible and can enable the2D minimap as well as 3D minimap of the same area of the map.However, it is not useful to use the same volume boxes for 3D and 2Dminimaps. Therefore, do not hesitate to add as many volume boxesas you need and don´t forget to label them appropriately.

6) Place or attach the 3D minimap component at the map position or

actor where it should be displayed.

How it works: In the experience the absolute position of every item is

forwarded by the map location component to the 3Dminimap component.

To display the map, the 3D minimap component calls upon the floor plan

measurement helper to check the relevance of the item for the map in

question and calculate the relative position of the item (see Figure 49) The

41

3D minimap component displays the map in the experience, often attached

to an in-game item.

9 ADDITIONAL FEATURES

The Advanced VR Framework additionally provides core functionality

that are just commonly required in interactive applications.

9.1 Game Play Tags

Figure 59. Setting up gameplay tags

Game Play Tags enable you to arrange information in categories and trees.

However, it can be quite tedious to establish the game play tag trees. Here

datatables will help by generating game play tag trees automatically if

so enabled in the project settings.

9.2 Internationalization (I18n)

The internationalization makes heavy use of the datatables and the level

keys. There are two kinds of I18n datatables:

• generic I18n datatables: contain a key that is specific for the trans-

lated word or phrase. They are used to translate generally used in the

experience on buttons like ”contiue” or ”no”. Each generally used

term has its own key that can be used universally.

• specific I18n datatables: contains level specific descriptions or phrases

like the level title. Each level specific text has its own data table for

example the Datatable/level titles and uses the level key to

assign the texts to the level.

It might seem redundant to have multiple datatables for different levelspecific texts. But the advantage of this system you only need onedistinct level key to allocate all level specific texts may they be thelevel title, level description or others.

The level key or key is used by the translate function to provide the set

text function with the text in the right language.

9.3 Achievement-System

Figure 60. Achievements as shown by the display

The achievement system is located in the game instance in form of a list

containing a key, an integer and a picture (texture2D).

• The key refers to the achievement datatable containing the title and

description of the achievement.

• The integer set the goal of the achievement which is a number.

• The texture contains the picture corresponding to the achievement.

Every action connected to an achievement needs the Add Achievement

Progress function attached to it which notifies the game instance to

increase the counter of the corresponding achievement by 1. The game

instance automatically checks if the goal of the achievement is met and

if it is unlocks the achievement.

42

9.4 Character Stats

The Character Stats are implemented as a component that enables the

definition, management and display of character stats

Component: Comp_CharStats

Setup:

1) Add the character stats component to the VR- or nonVR-pawn.

2) Add the character stats you need under xx

43

10 GLOSSARY

A

absolute position: position of an item in relation to the origin of the

map.

accepting actor: actor you can attach another actor to in the snap to

anchor process. The accepting actor needs at least one anchor.

actor component: component that can only exist added to an actor

anchor: component you add to the accepting actor of a snap to anchor

process to determine position and direction of the attached object.

attaching actor: actor you can attach to another anchor in the snap to

anchor process. The attaching actor needs the snap to anchor component.

B

body slot: anchor that has been placed on the pawn.

C

child actor component: component that can add other components to

itself

component: exchangeable functional element implementing a feature

D

datatables: datatables are Unreal internal tables that function like a database

in its simplest form. Each entry is identified by a key which allows

functions to return the entry of the corresponding cell.

default info class: The default info classes are the fallback for the game

mode when you do not enter an individual info-class for a level.

Devices can be used within the VR experience to help developers or

enhance the experience by providing specific functionalities like taking

photos, drawing or measuring distances.

E

event dispatcher: notification function to enable actors to react to changes

in other actors.

F

G

game instance: manages the information transfer (most importantly of

the level key) when the player changes the level

game mode: spawns the player controller and the game state upon starting

an experience.

game state: manages the transition maps when a level is loaded.

gazeview: highlighting of in-game items the player can interact with by

looking at them.

44

H

helper: mostly automatically created actors to support other classes in

executing their functionalities.

I

info classes: Four classes referenced in the game mode for each level, that

contain all information necessary to load and execute a selected level.

interactible: Interactible designates classes create instances the player can

interact with or the instances themselves according to context.

interfaces: are standards for information transfer. Do not confuse with

structs.

intro: First thing that happens when the experience is started. Usually it

shows a skysphere and a logo.

J

K

L

level key: Virtually the level’s ID.

level: a individually designed map the player visits during the experience

or a combination of them. Practically each construct you assign with a

level key.

M

menu map: map of the first level loaded in a play-through of your

experience, most probably containing a menu.

motion component: component implementing a controller functionality.

motion controller: container for motion components to create a controller

in the experience

N

O

P

paired actor: actor receiving and processing the signal from a trigger.

pause map: default map that is loaded, when the player presses pause.

pawn: visual representation of the player inside the experience

player controller: spawns and controls the pawns, manages the transition

to the pause map and back

Q

R

45

relative position: position of an item relative to a selected point that

coincide with the origin of the map.

S

scene component: component with its own transform, so it can exist in-

game without being added to an actor.

structs: Container holding selected variables that are usually transferred

together. For example you might include a struct containing all the po-

sitions in all three spatial directions.

T

transition map: default map that is loaded and displayed before and

while levels are loaded.

timeout (highlighting): time until the highlighting is removed from an

item.

U

UI: UI or user interfaces allow the player access to information and

selected functionalities

V

W

widget: System to create 2D Elements in-game

worldmap: Practically an empty container to put in all the maps you

need. Every worldmap contains 2 default maps (transition map and pause

map) and as many level maps as you like.

X

Y

Z

46

documentation of the - advanced vr...

Documents