Project Overview
This project is an educational Virtual Reality (VR) simulation for nursing students, built in Unreal Engine. It allows students to interact with a MetaHuman character named Charlie.
Engine Version
The project was created using Unreal Engine 5.3. It's recommended to stick with this version to avoid potential issues.
Project Name
The project folder is named VRDialogueTemplate.
Key Files and Folders
The most important project files are located in the Content > MyStuff folder. This is the main hub for the project's custom logic and assets.
BP_Charlie
The blueprint for the main NPC, Charlie, the MetaHuman students interact with.
Content\MyStuff\DialogueSystem\NPCs\BP_Charlie.uasset
VRPawn_Dialogue
The player character blueprint, containing interaction logic for the dialogue UI.
Content\MyStuff\DialogueSystem\VRPawn\VRPawn_Dialogue.uasset
AC_CharlieDialogueTree
Actor Component holding the entire branching dialogue tree for Charlie.
Content\MyStuff\DialogueSystem\DialogueTrees\AC_CharlieDialogueTree.uasset
BPI_Interactable
Blueprint Interface for communication between the VRPawn and Charlie.
Content\MyStuff\DialogueSystem\BPI_Interactable.uasset
ABP_MH_Charlie
Animation Blueprint that controls all of Charlie's body animations via a state machine.
Content\MyStuff\DialogueSystem\Animations\BodyAnims\A_MH_m_med_nrw_final\ABP_MH_Charlie.uasset
Face_AnimBP
Modified MetaHuman face blueprint with an idle animation. Only edit to disable idle during Mo-Cap.
Content\MetaHumans\Common\Face\Face_AnimBP.uasset
Core Systems
Dialogue System
The heart of the project, based on the Ultimate Dialogue System tutorial. Logic is split between AC_DialogueBase and AC_CharlieDialogueTree. To edit dialogue, open the `AC_CharlieDialogueTree` blueprint.
Animations
Body animations are controlled by the ABP_MH_Charlie state machine. Facial animations are played as "Animation Montages" and assigned in the dialogue tree; simply convert a recorded animation to a montage and select it in the 'Add Dialogue' node.
Level Transitions
The project uses a fade-to-black effect for level transitions, adapted from a tutorial by GDXR. The BPI_Interactable interface triggers this fade on the player pawn.
Motion Capture & Audio
Facial Mo-Cap Setup
Facial animation and audio are recorded simultaneously using the Unreal Live Link app (iPhone only).
- Ensure PC and iPhone are on the same Wi-Fi.
- Find PC's IPv4 address with
ipconfig. - Add IP address in the Live Link app settings.
- Enable "Head Rotation" in the app settings.
Using Recorded Mo-Cap Files
Recordings are saved outside the main project folder. Aim for clean takes to use the files directly.
File Location:
C:\Users\Public\UnrealEngine\VRDialogueTemplate\Content\Cinematics\Takes\[DateOfRecording]\
- To Use Audio: In the `AC_CharlieDialogueTree`, select the
.wavfile from the 'NPC Audio' dropdown in the 'Add Dialogue' node. - To Use Animation: Right-click the animation sequence file in Unreal, 'Convert to Anim Montage', then select it from the 'Body animation' dropdown in the 'Add Dialogue' node.
Troubleshooting & FAQ
Q: The player is spawning in the wrong place. How do I fix this?
This can happen if the Quest 2 headset has stored spatial information about the physical room you're in. This saved data can interfere with the simulation's intended spawn point. It is an issue with the headset's memory, not the Charlie VR app itself.
To fix this, you need to clear the headset's stored spatial data:
- In the Quest 2, go to Settings (cog symbol).
- Scroll to find and select Privacy and Safety, then go to Device Permissions. Turn OFF the "Enhanced Spatial Services" toggle. Meta can sometimes re-enable this during updates, so it's worth checking if the issue occurs.
- In the same "Privacy and Safety" menu, find the option to clear physical space history and activate it.
- Also find and activate the option to clear data stored on servers to ensure all spatial information is removed.
- Relaunch the Charlie VR app. The player should now spawn in the correct location in front of Charlie.
If the issue persists, try taking the headset to a completely different room, creating a new boundary there, and then returning to the original room to create the boundary again. This can force a reset.
Packaging & Deployment
Packaging for Quest Headsets
To package the project as an .apk file for Android/Quest, you must first run the setup batch file located at:
C:\Program Files\Epic Games\Unreal Engine 5.3\Engine\Extras\Android\SetupAndroid.bat
Run this file before every packaging attempt.
Installing the APK on a Headset
University headsets are in developer mode, which is required for local installation.
- Connect the Quest to the PC via USB-C. You must be wearing the headset when you plug it in to accept the "Allow USB detected" permission prompt.
- Navigate to the folder:
C:\Users\Public\UnrealEngine\VRDialogueTemplate\Build\Android\Build050825v8 - Double-click the
Install_VRDialogueTemplate-arm64.batfile. A command prompt will show the installation progress.
Running the App on the Headset
The installed app will not appear in the main library. You need to find it in Unknown Sources (look for a folder icon with a question mark on the headset's menu).