 |
|
(Click Here for Video Tutorial)
This page describes how to set up the Dialogue System with Icebox Studios' Adventure Creator. (Adventure Creator is required.)
Adventure Creator copyright © ICEBOX Studios.
IMPORTANT: Please read the Adventure Creator Setup section for specific steps required to set up support.
The support package adds these features:
Follow these steps to set up the Dialogue System with Adventure Creator:
Third Party Support/Adventure Creator Support.Third Party Support/Adventure Creator.Adventure Creator/Scripts/Actions:ActionDialogueSystemAlert.csActionDialogueSystemBark.csActionDialogueSystemConversation.csActionDialogueSystemCheckConversationActive.csActionDialogueSystemLua.csActionDialogueSystemSequencerMessage.csActionDialogueSystemSaveData.csActionDialogueSystemRestoreData.csActionDialogueSystemVarCheck.csActions folder. If you have moved Adventure Creator from its default installation location, you must move these files into the new location, too.Next steps:
The example scene is a modified version of Adventure Creator's Demo scene. It contains the following modifications:
When you import Adventure Creator, the default manager settings are set to the Demo scene's managers. If you need to set AC's manager settings back to the Demo scene, inspect Assets/AdventureCreator/Demo/ManagerPackage. In the Inspector view, click on Assign managers. Then you can play the example scene in Assets/Dialogue System/Third Party Support/Adventure Creator/Example.
The example scene replaces the AC conversation "IntroConv" with a Dialogue System equivalent. The conversation uses the AC() sequencer command to start "IntroConv2" at the end of the conversation in "nowait" mode, which immediately releases control back to AC.
It also includes a simple quest titled "Find a Sword". This quest starts active. When the player picks up the sword by triggering the "Sword_Use" interaction, it runs a Lua action to update the quest state and refresh the quest tracker HUD. You can also use the quest log window system (not shown in this example scene), but you need to implement menus to open and close it.
There is also a simple interactive object, a Trash Can containing an obsolete model robot, Copper Pot. Copper Pot demonstrates barks (one-off lines of dialogue during gameplay) and a conversation that uses the sequencer command AC(TrashCanShake,nowait).
There's also a small utility script on Dialogue Manager that shows the current AC game state. You can watch the game state change when switching between Adventure Creator gameplay and Dialogue System conversations. You don't have to add this script to your own adventures.
The Adventure Creator Bridge synchronizes Adventure Creator data with Dialogue System data. Add it to your Dialogue Manager object by selecting Component > Dialogue System > Third Party> Adventure Creator > AC Bridge.
The inspector has these properties:
| Property | Function |
|---|---|
| Use Dialog State | Specifies what game state to put AC in during conversations. Set it to: *Never*: To never change AC's game state *If Player Is Involved*: To change to GameState.DialogOptions only if the player is involved in the conversation *Always*: To change to GameState.DialogOptions during every conversation |
| Take Camera Control | Specifies when to take camera control during conversations. Set it to: *Never*: Never touch the camera *If Player Is Involved*: Only if the player is involved in the conversation *After Stop If Player Involved*: Wait for AC to stop moving the camera, then take control *Always*: Always grab the camera from AC control |
| Max Time To Wait For Camera Stop | If Take Camera Control is set to After Stop If Player Involved, this specifies the maximum time to wait for the camera to stop. This is a safety net in case AC never stops the camera |
| Include Sim Status | Tick to include SimStatus in save data. See About SimStatus below |
| Prepend Global Variables | Tick to prepend 'global_' in front of global AC variables in Dialogue System's Variable[] table. Use if you need to distinguish global and local variables that have the same name |
| Save To Global Variable On Conversation End | Tick to save the Lua environment to an AC global variable at the end of every conversation |
| Save To Global Variable On Level Change | Tick to save the Lua environment to an AC global variable before changing levels; to use this, you must add Dialogue System Saver to the PersistentEngine prefab as described in Saving and Loading |
| Rerun Script After Cutscenes | Tick to resolve race conditions between AC() sequencer command and Lua Script on subsequent dialogue entry |
| Use Adventure Creator Language | Tick to automatically set the Dialogue System's Localization to whatever Adventure Creator is set to. This will set the Dialogue System's language to the language name defined in Adventure Creator (e.g., "French") |
| Use Adventure Creator Subtitle Settings | Tick to respect Adventure Creator's Subtitles toggle. |
Note about Subtitles
Adventure Creator's subtitles are off by default. If the Adventure Creator Bridge's Use Adventure Creator Subtitle Settings checkbox is ticked, then the Dialogue System will respect this and it will not show subtitle text.
How "If Player Is Involved" Is Defined
If sequencer camera commands aren't working on the MainCamera during conversations, AC is probably not in the DialogState game state, so it will retain control of the MainCamera. If can happen if a player character is not assigned to the Actor field. (An easy way to assign the player is to simply leave this field blank.) You can check the current game state by adding the ShowGameState script to a GameObject in your scene, such as the Dialogue Manager.
You can override the Use Dialog State and Take Camera Control settings for a specific conversation on the Third Party: Dialogue System Conversation action.
When a conversation starts, the bridge will set the game state as specified in the properties above. Then it will copy Adventure Creator's inventory and global variables to the Dialogue System's Lua environment. When the conversation ends, it restore the Adventure Creator game state and copy the Dialogue System's Lua environment back to AC's inventory and global variables.
In the Dialogue System's Lua environment:
Variable[] table. You can check the value in dialogue entry Conditions fields, and set the value in Script fields.Item[] table. The entry has fields for the AC ID number (AC_ID) and the item count (Count). To remove an item, set its Count to 0.| AC Data | Dialogue System Lua environment | Example |
|---|---|---|
| Variable | Variable[ variableName ] | Variable["Tipped_barrel"] == true (was barrel tipped?) |
| Item | Item[ itemName ']' | Item["Prop_sword"].Count = 0 (remove sword) |
If you don't want to sync either of these types of data, expand the bridge components Sync Settings foldout and untick what you don't want to sync.
You can manually synchronize data and/or freeze Adventure Creator by calling these methods:
The Sync methods respect the settings you've specified in the bridge component's Sync Settings foldout.
The Dialogue System's Adventure Creator Support package adds these new actions to Adventure Creator under Third Party:
Starts a Dialogue System conversation. The scene must have a Dialogue Manager object (see: How to Set Up the Dialogue Manager).
| Property | Function |
|---|---|
| Conversation Title | The title of a conversation defined in the Dialogue Manager's dialogue database |
| Actor | The main actor in the conversation, usually the player. Leave blank to default to the player |
| Conversant | The other actor in the conversation, usually an NPC |
| Override bridge control? | Tick to override the Use Dialog State and Take Camera Control settings on the Dialogue System - Adventure Creator Bridge |
| Wait until finish? | Tick to stay on this action, and not progress to the next action in the actionlist/cutscene, until the conversation ends |
| Stop on skip? | Tick to stop the conversation if the player skips the actionlist/cutscene |
Note that conversations can have multiple actors. The Actor and Conversant simply define the two primary actors.
If the scene has an Dialogue System - Adventure Creator Bridge, Adventure Creator data will be synced with the Dialogue System's Lua environment.
Checks if a Dialogue System conversation is active.
Starts a Dialogue System bark (a one-off line of dialogue). The scene must have a Dialogue Manager object (see: How to Set Up the Dialogue Manager).
| Property | Function |
|---|---|
| Bark Conversation Title | The title of a conversation defined in the Dialogue Manager's dialogue database. See Bark Conversations for an explanation of how bark lines are defined in conversations |
| Actor | The actor being barked at the bark. Leave blank to default to the player |
| Conversant | The barker |
| Sync Data | If ticked, Adventure Creator data is synchronized to the Dialogue System before barking and back to Adventure Creator after barking. Since this could have a small impact on performance if many barks occur at the same time, you have the option to leave it unticked if your barks don't need to access AC data |
Shows a gameplay alert message using the Dialogue System's dialogue UI. The scene must have a Dialogue Manager object (see: How to Set Up the Dialogue Manager).
| Property | Function |
|---|---|
| Message | The message to show, which may contain Dialogue Markup Tags |
| Duration | The duration in seconds to show the message |
| Sync Data | If ticked, Adventure Creator data is synchronized to the Dialogue System before showing the message |
Runs Lua code in the Dialogue System's Lua environment. This is often used to update the state of a quest, as demonstrated in the "Sword_Use" interaction in\ the example scene. The scene must have a Dialogue Manager object (see: How to Set Up the Dialogue Manager).
| Property | Function |
|---|---|
| Lua Code | The Lua code to run |
| Sync Data | If ticked, Adventure Creator data is synchronized to the Dialogue System's Lua environment before running the Lua code, and Lua is synced back to Adventure Creator after |
| Update Quest Tracker | Updates the quest tracker HUD, if one exists on the Dialogue Manager object |
| Store Result? | Optionally lets you specify the ID of a global string variable in which to store the result |
Evaluates a Lua expression and branches the action list based on whether the returned value is true or false. This action provides a shortcut rather than using the Lua action above, storing the result in an Adventure Creator global variable, and then checking the value of that variable.
| Property | Function |
|---|---|
| Lua Code | The Lua code to run |
| Sync Data | If ticked, Adventure Creator data is synchronized to the Dialogue System's Lua environment before running the Lua code |
Sends a message to the Dialogue System's sequencer. See Sequencer Command Syntax for information about using sequencer messages.
| Property | Function |
|---|---|
| Message | The message to send to the sequencer |
Saves the Dialogue System's data in an Adventure Creator global variable. Use this action just before any Change Scene actions. This allows Adventure Creator to carry the data through to the next scene.
Retrieves the Dialogue System's data from the Adventure Creator global variable. You will probably never need to use this action since it's handled automatically in most cases.
To define an action list that's triggered by a change in a Dialogue System Lua variable, add about Lua Var Change Watcher component (Dialogue System > Third Party > Adventure Creator > Lua Var Change Watcher.
Syntax: AC(cutscene[, nowait[, stepNum]])
Description: Plays an Adventure Creator cutscene or action list.
Parameters:
nowait: (Optional) If nowait is passed as the second parameter, the cutscene runs in the background, and control passes immediately to the next stage of the conversation. Anything else (such as wait) tells the sequencer to wait until the cutscene is done.Notes:
Example:
AC(Try lifting) (Plays the "Try lifting" cutscene.)AC(Dance, nowait, 3) (Plays the "Dance" cutscene starting at step 3 without waiting for it to finish.)Syntax: ACCam(on|off|idle|cameraName, [smoothTime])
Description: Enables or disables Adventure Creator's control of the camera. In most circumstances, you can just use the settings in the Dialogue System - Adventure Creator Bridge, but this sequencer command gives you additional control options.
Parameters:
on|off|idle|cameraName: The new control mode.on: Enables Adventure Creator's control of the camera.off: Disables Adventure Creator's control of the camera.idle: Waits until the camera has stopped, then disables Adventure Creator's control.Examples:
ACCam(off) (Lets the Dialogue System control the camera)ACCam(Stage Left, 2) (Smoothly moves to the Stage Left camera defined in AC over 2 seconds)Syntax: ACSpeech(lineID, [nowait])
Description: Plays the current dialogue entry through Adventure Creator's lipsync and subtitle system.
Parameters:
nowait: If specified, plays the dialogue entry in the background and doesn't wait for it.Notes:
entrytag to a line ID in Adventure Creator format.Resources folder(s) as described in the Adventure Creator documentation.ACSpeech(entrytag)
Example:
ACSpeech(Brain2) (Plays the audio, and possibly lipsync file, "Brain2")ACSpeech(entrytag,nowait) (Plays the audio, and possibly lipsync file, specified by the current line; play in background)Adventure Creator doesn't provide a way to temporarily relinquish its control of characters. This means the Dialogue System's LookAt() and MoveTo() sequencer commands won't work because AC will fight them for control.
Instead, create an Adventure Creator actionlist and use the AC() sequencer command to run it.
For example, say you've created an actionlist named "AdamWalksToDoor" with a single action that moves an NPC named Adam to the door. Use it in the Dialogue System like this:
The Dialogue System integration package provides two static functions in AdventureCreatorBridge that save the Dialogue System's state into an Adventure Creator global variable and retrieve it again when loading a game. These methods will automatically create the global variable if it doesn't already exist.
To hook the Dialogue System into Adventure Creator's Save System:
Adventure Creator/Resources/PersistentEngine.99999.If Include Sim Status is ticked on the Adventure Creator Bridge, the status of all dialogue entries will be included in the save data. This records whether an entry was offered in a response menu and/or whether it has been spoken by an actor. If you have a lot of dialogue entries, this can make the save data large. It's unticked by default since many games don't need to record this information. You must also tick Include Sim Status on the Dialogue Manager to maintain runtime sim status in the first place.
Adventure Creator pauses the game during player menus by setting Time.timeScale = 0. By default, the Dialogue System ignores Time.timeScale. This allows you to pause gameplay but still continue to run a conversation. If you want the Dialogue System to pause when Time.timeScale is zero, set the Dialogue System's time mode to gameplay mode:
using PixelCrushers.DialogueSystem; ... DialogueTime.Mode = DialogueTime.TimeMode.Gameplay;
Adventure Creator has an option to force the display into an aspect ratio. This puts black bars on the edges of the screen as necessary to make the visible area conform to the specified aspect ratio.
To make your Unity UI dialogue UIs adjust to the aspect ratio:
You can use this component for any Unity UI, such as AC Unity UI menus.