This page describes how to set up the Dialogue System with Opsive's UFPS. (UFPS is required.)

UFPS Setup

This package adds functionality to start conversations using UFPS's interaction framework, suspend UFPS gameplay during conversations, synchronize UFPS data between UFPS and the Dialogue System, and load and save games containing UFPS and Dialogue System data.

Follow these steps to set up the Dialogue System with UFPS.

Import The UFPS Support Package

In your project, navigate to the folder Assets / Dialogue System / Third Party Support. Then import the package UFPS Support. This will unpack files into the subfolder Third Party Support / UFPS.

If you want to use the Dialogue System Menu Template with UFPS, see Set Up the Dialogue System Menu Framework.

Set Up The Dialogue Manager

Set up the Dialogue Manager GameObject normally as described in How to Set Up the Dialogue Manager. Then add these components:

Level Manager: (Component > Dialogue System > Save System > Level Manager) This component handles general synchronization of levels and Dialogue System data when changing levels and loading games.
FPSync Lua Player On Load Level: (Component > Dialogue System > Third Party > UFPS > Sync Lua Player On Load Level) This component applies the Dialogue System's Lua data to the UFPS player GameObject after loading a level.

The FPSync Lua Player On Load Level component allows you to have a different UFPS player GameObject in each level so you can test a level simply by playing it in the editor. When playing a game, before changing levels you can save the player's current UFPS data, such as health and inventory, into the Dialogue System's Lua environment. (An easy way to save the data is to use a Change Level Trigger, which is described further down on this page.) When the new level is loaded, FP Sync Lua Player On Load Level applies the saved data from the previous level to the player GameObject in the new level.

Set Up The Player

Automatic Player Setup

To set up the UFPS player in your scene, select menu item Component > Dialogue System > Third Party > UFPS > Add All Player Scripts. This will automatically configure your player with all of the scripts described below in the manual steps. If you use this menu item, you can skip all of the manual steps below.

(Some versions of Unity may not show this menu item. Its alternate location is Window > Dialogue System > Tools > UFPS.)

Manual Player Setup

Use these instructions if you want to pick and choose which scripts are added to your player.

This documentation assumes your player is a UFPS AdvancedPlayer GameObject. Similar steps apply if you're using any of the other UFPS player prefabs such as Camera&Controller or Hero.

Add these scripts:

FPPersistent Player Data: (Component > Dialogue System > Third Party > UFPS > Persistent Player Data) This component synchronizes the player's UFPS data – position, health, and inventory – with the Dialogue System's Lua environment for saved games and data persistence when changing levels. The options are:
- Override Actor Name: (Optional, defaults to "Player".) If not set, the component uses the GameObject's name as the name of the actor in the Lua Actor[] table. If your actor is named differently in the Lua Actor[] table (e.g., the actor has a different name in Chat Mapper or the Dialogue Database), then set this property to the Lua name.
- Record Position: Tick this checkbox to record the player's position when saving persistent data.
- Force Wield: Tick to force the player to wield the current weapon after loading a game and play the wield animation. Some custom weapons won't aim properly unless they go through the wield animation.
- Dont Apply Lua Next Load Level: Tick this to skip applying the player's saved info from Lua on the next level load. Normally you want to apply the saved info so the player's health, inventory, etc., persist across levels. However, if you're restarting the level with a fresh instance of the player (e.g., if the player died), set this true or the player will receive his old stats, such as zero health. This checkbox clears itself after loading the level. If you want the scene after to also apply this rule, add FP Don't Apply Lua Next Load Level to any active GameObject in your scene. This will re-tick the checkbox to make it take effect for the next load level also.
- When changing levels, you can also set a spawnpoint to start the player at. See Setting Spawnpoints for more information.
FPFreeze Player: (Component > Dialogue System > Third Party > UFPS > Freeze Player) This component freezes gameplay and shows the cursor during conversations. The component's Freeze() and Unfreeze() methods are also used by the example scene's main menu, and you can use them in your own scripts if you want. The options on this component are:
- Hide HUD: Tick to hide the UFPS HUD during conversations. (Default is ticked.)
- Freeze During Conversations: Tick to freeze the UFPS player during conversations. (Default is ticked.)
- Programmers: This component also has a CanShowCursor delegate that lets you provide a function to override when the cursor can be shown. For example, if you're using a joystick, you never want to show the cursor, so you could assign a function that always returns false.
FPSync Lua Player On Conversation: (Component > Dialogue System > Third Party > UFPS > Sync Lua Player On Conversation) This component synchronizes the player's health and inventory in UFPS with the inventory in the Dialogue System's Lua environment so conversations can check and manipulate it. This script relies on FP Player Lua Bridge to do the actual synchronization. You can use FP Player Lua Bridge separately from FPSync Lua Player On Conversation in your own scripts, too. The data that's synchronized is detailed further down this page.
FPPlayer Lua Bridge: (Automatically added by FPSync Lua Player On Conversation and FP Persistent Player Data.) This component synchronizes data between UFPS and the Dialogue System's Lua environment. Methods are virtual so you can override them if you want to create a subclass that does additional processing. Add all UFPS item types that will be synchronized with Lua to this component's Usable Items Types list. The bridge will also automatically add all item types listed in the Item Caps section of the player's inventory component. If you want to fill the Usable Item Types with all item types defined in the project, click the Find All Item Types button.
Show Cursor On Conversation: (Component > Dialogue System > Trigger > On Dialogue Event > Show Cursor On Conversation) UFPS hides the mouse cursor. This component shows the mouse cursor during conversations. You only need to add this component if you will use the mouse in conversations.

Additional Player Components

vp_FPInteractManager for UFPS Interaction Some UFPS player prefabs, such as Camera&Controller, don't start with a vp_FPInteractManager component. This component is required to use UFPS interaction, such as with FPInteractable Dialogue. If you want to use UFPS interaction, make sure your player has a vp_FPInteractManager.

GUILayer for Fade()

If you want to use the Fade() sequencer command, add a GUILayer to the player's FPSCamera. The Fade() command uses a GUITexture, so it relies on a GUILayer on the main camera.

Players with Bodies

Players with bodies, such as HeroHDWeapons, need an additional component. Add a Set Component Enabled On Dialogue Event and assign three components:

The body's vp_FPBodyAnimator
The body's vpRagdollHandler
The FPSCamera's vp_FPCamera

Set Up NPCs

On NPCs, add these components:

FPInteractable Dialogue: Derived from vp_Interactable, this component makes the NPC interactable within the UFPS framework. When the player interacts with the NPC, this component sends an OnUse message to the NPC. If the NPC has a Conversation Trigger configured to listen for OnUse, it will start a conversation.
Conversation Trigger: Starts a conversation when FPIteractable Dialogue sends an OnUse message to the NPC.
Set Enabled On Dialogue Event: Add this component and configure it to disable the FPInteractable Dialogue component during conversations.
Persistent Position Data: Add this component if you want to record the NPC's position in saved games or when changing levels.

If you want to use the Dialogue System's Selector functionality instead of UFPS's interaction framework, don't add FPInteractable Dialogue, and instead add a Usable component.

You can also set up barks and other Dialogue System features as normal, without having to configure any special UFPS versions.

Set Up Destructibles

On destructible objects such as crates, or killables such as enemies, add this component:

Dialogue System On Die: Performs various actions when the GameObject is "killed." The options are:
- Destroy: Tick if you want to destroy the object instead of just deactivating it.
- Sequence: An optional cutscene sequence to play. (See Sequences) For example, you can use KGFMapIcon() to change icons, Audio() to play audio, etc. The "speaker" is the Dialogue Manager GameObject, and the "listener" is the object that was killed.
- Lua Code: Any Lua code that you want to run.
- Variable To Record Death. If specified, this variable records that the GameObject was killed. This allows the GameObject to remember that it was killed when you load a game. You don't have to define this variable ahead of time in the dialogue database. You must provide a unique variable name for each GameObject so the GameObjects know which variable corresponds to which GameObject. Leave blank if you don't want to record death.
- Variable To Increment: If specified, this variable increments when the GameObject is killed. This is useful for kill quests and collection quests. You don't have to define this variable ahead of time in the dialogue database. Leave blank if you don't want to keep track.

Set Up Level Transitions

To set up a level transition trigger, create a GameObject with a trigger collider. Then add this component:

Change Level Trigger: This component synchronizes UFPS data with the Dialogue System's Lua environment, then loads a new level.
- New Level Name: The name of the destination level.

Set Up the Dialogue System Menu Framework

To use the Dialogue System Menu Framework (available on the Dialogue System extras page at www.pixelcrushers.com/dialogue-system-extras/), follow these steps:

Short Instructions

These instructions will get the Menu Framework running with UFPS with the least work.

Import the Menu Framework.
Add these scenes to your build settings in order:
- 0: Dialogue System / Third Party Support / UFPS / Example / Menu Framework Example / Start UFPS
- 1: Dialogue System Extras / Dialogue System Menu Framework / Example / Loading
- 2: Dialogue System Extras / Dialogue System Menu Framework / Example / Credits
- 3: Dialogue System / Third Party Support / UFPS / Example / Menu Framework Example / Gameplay UFPS
- (If you change the order of scenes or rename Gameplay UFPS, update the scene numbers/names on the Menu System's scripts and the Dialogue Manager's Level Manager script.)
Open the Start UFPS scene.
Inspect Menu System. At the bottom of the Input Device Manager component, click the Add Input Definitions button.

Play the Start UFPS scene to test it out. After you've confirmed that it's working, you can assign your own dialogue database, dialogue UI, etc. You can save the Start UFPS scene's Menu System and Dialogue Manager as prefabs and add them to your gameplay scenes for easy playtesting. In your gameplay scenes' copy of the Menu System prefab, deactivate the TitleMenuPanel child GameObject, as was done in Gameplay UFPS. When using the Menu Framework, in your gameplay scenes add the script FPLockCursorOnStart to your player.

Longer (Manual) Instructions

These instructions explain how to set up the Menu Framework from scratch to work with UFPS.

Import the Menu Framework.
You can use the scenes in Dialogue System Extras / Dialogue System Menu Framework / Example or create your own scenes with the same prefabs in them. The rest of these instructions use the scenes in the Example folder.
Add these scenes to your build settings in order:
- 1: Dialogue System Extras / Dialogue System Menu Framework / Example / Start
- 1: Dialogue System Extras / Dialogue System Menu Framework / Example / Loading
- 2: Dialogue System Extras / Dialogue System Menu Framework / Example / Credits
- 3: Dialogue System Extras / Dialogue System Menu Framework / Example / Gameplay
- (If you change the order of scenes or rename Gameplay, update the scene numbers/names on the Menu System's scripts and the Dialogue Manager's Level Manager script.)
Open the Start scene.
Add the script Dialogue System / Third Party Support / UFPS / Scripts / FPSyncLuaPlayerOnLoadLevel to the Dialogue Manager.
Inspect Menu System. At the bottom of the Input Device Manager component, click the Add Input Definitions button.
Add the script Dialogue System / Third Party Support / UFPS / Scripts / PauseUFPS to Menu System.
Expand Menu System and inspect the TitleMenuPanel child GameObject. Add the script Dialogue System / Third Party Support / UFPS / Scripts / ForceCursorVisible if you want the mouse cursor to be visible when returning to the title menu scene. (UFPS hides it by default.)
Inspect the PausePanel child GameObject.
- Add another element to On Open() and On Close() by clicking the "+" at the bottom of each section.
- Assign Menu System to both new elements.
- In On Open(), select PauseUFPS.DoPause.
- In On Close(), select PauseUFPS.DoUnpause.
In your gameplay scenes, add the script FPLockCursorOnStart to your player.
You can save the Start scene's Menu System and Dialogue Manager as prefabs and add them to your gameplay scenes for easy playtesting. In your gameplay scenes' copy of the Menu System prefab, deactivate the TitleMenuPanel child GameObject.

Example Scene

The example scene uses UFPS features to suspend UFPS gameplay and interact with an NPC to start a conversation, synchronizing UFPS data between UFPS and the Dialogue System.

In this example:

The player is configured for full UFPS/Dialogue System integration. (See Set Up The Player)
Private Hart is configured as an NPC with a conversation and a quest. (See Set Up NPCs)
There is a destructible crate. (See Set Up Destructibles)
There is full save and load functionality.

The example scene uses a script ExampleMainMenu.cs to provide a rudimentary main menu. For a more robust menu system, you can use the Dialogue System Menu Template with UFPS. See Set Up the Dialogue System Menu Framework.

Lua Bridge Data

The FPPlayer Lua Bridge component makes the following information available in the Lua environment during conversations:

Lua	Description
`Actor["Player"].Health`	The player's current health.
`Actor["Player"].TotalSpace`	The total capacity of the player's inventory. (read-only)
`Actor["Player"].UsedSpace`	The current used space in the player's inventory. (read-only)
`Actor["Player"].RemainingSpace`	The current remaining space in the player's inventory. (read-only)
`Actor["Player"].CurrentWeaponIndex`	The index of the player's currently-equipped weapon.
`Variable["Pistol"], Variable["Revolver"]`, etc.	(For all weapons defined in the player's vp_Inventory. If the value is `0` or nonexistent, the player does not have the item. If the value is `1` or higher, the player has the item, and the number indicates the amount of ammo. If you set a value during a conversation, the change will be reflected in the UFPS player at the end of the conversation.
`Variable["Pistol_Units"], Variable["Revolver_Units"]`, etc.	The amount of ammo loaded into each weapon.
`Variable["Bullet"], Variable["MachinegunBullet"]`, etc.	The amount of ammo held by the player (outside of weapons).

Notes:
- NOTE 1: The inventory system changed in UFPS v1.4.7. The variables above represent the values as used in UFPS 1.4.7+ using the new vp_Inventory system. To accommodate these changes, FPPlayerLuaBridge was changed to a MonoBehaviour. You must assign the valid inventory item types to the bridge component (see below).
- NOTE 2: FPPlayerLuaBridge assumes that the scene has a Dialogue Manager object. The easiest way to ensure this is to tick Dont Destroy On Load and Allow Only One Instance on the Dialogue Manager object to enable it to persist across scene changes. If there is no Dialogue Manager object, FPPlayerLuaBridge will set the player's health to 0. This will make the player unkillable because UFPS only checks for death if the player takes damage that changes his health from a positive number to 0 or less. Since his health is already 0, the death condition is never met.

General Interaction Guidelines

Sharing Additional Data

You may want to share additional data between UFPS and the Dialogue System. One way to do this is to put that information in the Dialogue System's Lua environment using the Lua.Run() method. If you set a user variable using PixelCrushers.DialogueSystem.Lua.Run(), then dialogue entries can check and/or change the value.

For example, NPC conversations can branch based on whom the player has killed, or what UFPS items the player has in his inventory (as is done in FPSync Lua Player On Conversation).

Saving and Loading

See the example menu script (ExampleMainMenu.cs) for a simple example of how to save and load. In brief, call PersistentDataManager.GetSaveData() to get the saved game data (including UFPS data). Call PersistentDataManager.ApplySaveData() to load a game by feeding previously-saved game data back into the Dialogue System and UFPS state.

If the player can switch between levels in your game, you may want to use the LevelManager script's methods as shown in the example menu script.

Pre-Game Level Selection Scenes

If the first scene of your game does not have a UFPS player object and a Dialogue Manager object, you'll have to take an extra step. This is the process:

Whenever a new level is loaded, the FPPlayer Lua Bridge applies the Lua data to UFPS data.

[New Level Loaded]
- Lua --> UFPS

When switching between gameplay levels, the FPPlayer Lua Bridge in the old level saves the UFPS data to Lua. Then the new level applies the Lua data to UFPS.

[Old Level]
- UFPS --> Lua
[New Level Loaded]
- Lua --> UFPS

If your level selection scene does not have an FPPlayer Lua Bridge, it will not save UFPS-->Lua.

To address this, you'll need to add some starting values to the dialogue database. These Lua environment will be initialized with these values.

On the Actors tab, add a field named "Health" to the Player. Change its Type to Number. Set the Value to the player's starting health. In the example below, the player starts with 42% health.

To set the player's current weapon, add a field named "CurrentWeaponIndex". Change its Type to Number. Set it to the weapon index (e.g., 1=Pistol, 2=Revolver, etc.). In the example below, the player's current weapon is 1 (Pistol).

To set the player's inventory, add variables on the Variables tab. In the example below, the player has a Pistol with 11 units loaded, and 38 extra bullets.

The names of the variables are defined above in the Lua Bridge Data section.

UFPS Mobile-Addon

Support for the UFPS Mobile-Addon is in the package UFPS Mobile Addon Support. When you import this package, it will add a Scripts folder and an example folder containing a two-level mobile demo.

IMPORTANT: To be able to switch between levels, you must add 'Mobile Level 1' and 'Mobile Level 2' to the build settings. For the example main menu's Restart Game button to work, you must make 'Mobile Level 1' the first scene in the build settings.

The example uses Unity GUI for the example menu and dialogue UI, but you could implement a dialogue UI using Unity UI, UFPS Mobile's vp_UI, or even NGUI.

The example menu is accessed through the mobile demo's menu. The Dialogue System Menu object (which contains the example menu script) is a child of the Dialogue Manager object.

Follow these steps to set up up the Dialogue System with the UFPS Mobile Addon:

Add an AdvancedPlayerMobile and RootUI to each scene. These objects don't seem to survive across scene loads very well.
Connect the AdvancedPlayerMobile's vp_SimpleHUDMobile fields to the RootUI as shown here:
Add these components to AdvancedPlayerMobile:
- FPFreezePlayer
- FPPlayerLuaBridge
  - Add all usable item types to the Usable Item Types list.
- FPSyncLuaPlayerOnConversation
- FPPersistentPlayerData (if you want to save the player's position)
Add these components to the Dialogue Manager:
- FPSyncPlayerOnLoadLevel (No need to add FPSyncPlayerOnLoadLevelMobile, as this is deprecated)

The FPPersistentPlayerData and FPSyncPlayerOnLoadLevel components are only necessary if your player will be switching levels or saving and loading games.

If you're using the Dialogue System's Menu Framework, add this script (ConnectPauseMenu.cs) to the RootUI GameObject, create a menu button, and configure it to call the script's OpenPausePanel method and the RootUI menu's Toggle method.

using UnityEngine;
 
namespace PixelCrushers.DialogueSystem.UFPS
{
 
    public class ConnectPauseMenu : MonoBehaviour
    {
 
        public void OpenPausePanel()
        {
            var pause = FindObjectOfType<MenuSystem.Pause>();
            if (pause == null)
            {
                Debug.LogError("Can't find Menu Framework PausePanel to open it.");
                return;
            }
            pause.pausePanel.Open();
        }
    }
 
}

<< Third Party Support

Table of Contents