This page describes how to set up the Dialogue System with Icebox Studios' Adventure Creator. (Adventure Creator is required.)
Adventure Creator copyright © ICEBOX Studios.
The support package adds these features:
Follow these steps to set up the Dialogue System with Adventure Creator:
Note: If you are updating the integration from a pre-AC 1.80 version, delete the folder Assets ► Pixel Crushers ► Dialogue System ► Third Party Support ► Adventure Creator Support before importing the updated Adventure Creator Support.unitypackage.
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 and click Assign managers. Then you can play the example scene in Assets ► Pixel Crushers ► Dialogue System ► Third Party Support ► Adventure Creator Support ► 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.
Add it to your Dialogue Manager object by selecting Component → Pixel Crushers → Dialogue System → Third Party → Adventure Creator → Adventure Creator Bridge. The Adventure Creator Bridge synchronizes Adventure Creator data with Dialogue System data.
There are two ways to synchronize data:
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. |
Force Cursor Visible During Conversations | Keep the mouse cursor visible during conversations. |
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.
Sync Settings
If the Sync Settings checkboxes are ticked, then 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
.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.
Details: Inventory Management
To manage AC inventory in conversations:
Copy DS Vars To AC
The inspector has a "Copy DS Vars To AC" button that can copy variables defined in your dialogue database to Adventure Creator's global variables list.
To manually synchronize data between Adventure Creator and the Dialogue System, use either of these two Lua functions:
SyncACToLua()
Syncs Adventure Creator's data into the Dialogue System's Lua environment. Specify what to sync using the checkboxes on the bridge component.
SyncLuaToAC()
Syncs Dialogue System's Lua environment into Adventure Creator's data.
Both Lua functions are available in the Script > "..." dropdown menu, in Custom > AC.
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 Adventure Creator Bridge component adds these Lua functions. They are also accessible from the "..." dropdown menus in Conditions and Script fields, in the Custom/AC submenu.
Lua Function | Description |
---|---|
acGetBoolean("variableName") | Returns a Boolean variable's value*. |
acGetInteger("variableName") | Returns an Integer variable's value*. |
acGetFloat("variableName") | Returns a Float variable's value*. |
acGetText("variableName") | Returns a Text variable's value*. |
acSetBoolean("variableName", value) | Sets a Boolean variable's value*. |
acSetInteger("variableName", value) | Sets a Integer variable's value*. |
acSetFloat("variableName", value) | Sets a Float variable's value*. |
acSetText("variableName", "value") | Sets a Text variable's value*. |
— | — |
acGetBooleanOnGO("gameObject", "variableName") | Returns a Boolean variable's value* from a GameObject's Variables component. |
acGetIntegerOnGO("gameObject", "variableName") | Returns an Integer variable's value* from a GameObject's Variables component. |
acGetFloatOnGO("gameObject", "variableName") | Returns a Float variable's value* from a GameObject's Variables component. |
acGetTextOnGO("gameObject", "variableName") | Returns a Text variable's value* from a GameObject's Variables component. |
acSetBooleanOnGO("gameObject", "variableName", value) | Sets a Boolean variable's value* from a GameObject's Variables component. |
acSetIntegerOnGO("gameObject", "variableName", value) | Sets a Integer variable's value* from a GameObject's Variables component. |
acSetFloatOnGO("gameObject", "variableName", value) | Sets a Float variable's value* from a GameObject's Variables component. |
acSetTextOnGO("gameObject", "variableName", "value") | Sets a Text variable's value* from a GameObject's Variables component. |
— | — |
acGetItemCount("itemName") | Returns the amount of an item in the player's inventory. |
acSetItemCount("itemName", value) | Sets the amount of an item in the player's inventory. |
acIncItemCount("itemName", value) | Increments the amount of an item in the player's inventory. |
— | — |
acGetObjectiveState(objectiveID, "playerName") | Gets an AC objective state**. |
The Lua functions look for a matching local scene variable first. If the function doesn't find a local variable with the specified name, it looks for a global variable. To use variables on a specific GameObject's Variables component, use the acGetXXXOnGO() Lua functions.
acGetObjectiveState:
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.
Property | Function |
---|---|
Conversation Title | The title of a conversation defined in the Dialogue Manager's dialogue database. |
Specify entry ID? | Tick to start from a specified entry ID instead of the START node. |
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.
Property | Function |
---|---|
Bark Conversation Title | The title of a conversation defined in the Dialogue Manager's dialogue database. See Barks 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.
Property | Function |
---|---|
Message | The message to show, which may contain 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.
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. |
Runs status and relationship Chat Mapper Functions in the Dialogue System's Lua environment.
Property | Function |
---|---|
Get Status | Stores the value of the GetStatus() Lua function into an AC variable. |
Set Status | Uses SetStatus() to set a status value. |
Get Relationship | Stores the value of the GetRelationship() Lua function into an AC variable. |
Set Relationship | Calls SetRelationship(), IncRelationship(), or DecRelationship() Lua functions to set a relationship value. |
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 condition to check. |
Sync Data | If ticked, Adventure Creator data is synchronized to the Dialogue System's Lua environment before running the Lua code. |
Checks the state of a quest or quest entry. The scene must have a Dialogue Manager.
Property | Function |
---|---|
Quest Name | The quest to check. |
Mode | Check main quest state or quest entry. |
Quest State | The required state. |
Sets the state of a quest or quest entry. The scene must have a Dialogue Manager.
Property | Function |
---|---|
Quest Name | The quest to set. |
Mode | Set main quest state or quest entry. |
Quest State | The new state. |
Shows or hides the quest log window.
Property | Function |
---|---|
Show? | Show or hide. |
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.
Property | Function |
---|---|
Direction | Sync from AC to DS Lua or DS Lua to AC. Calls the Adventure Creator Bridge component's methods to perform the sync. |
Property | Function |
---|---|
Mode | Pause or unpause the Dialogue System. |
To define an action list that's triggered by a change in a Dialogue System Lua variable, add about Lua Var Change Watcher component (Pixel Crushers → 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.Player
### instead of the player actor's name.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:
99999
.If the Dialogue Manager has a Save System component, it will use it. (See Save System) Otherwise it will only use the Dialogue System's PersistentDataManager, which saves the dialogue database runtime values and any persistent data components but not Savers.
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.