 |
|
This page explains how to use Hutong Games' Playmaker with the Dialogue System.
Playmaker copyright © Hutong Games.
To set up Playmaker support, import these two packages:
This will add:
The Dialogue System provides the following Playmaker actions, listed under Dialogue System in Playmaker's Action Browser.
| Action | Description |
|---|---|
| Is Conversation Active | Checks whether a conversation is currently active. |
| Start Conversation | Starts a conversation. |
| Stop Conversation | Stops the currently-active conversation. |
| Does Conversation Have Valid Entries | Checks whether a conversation currently has any valid entries branching from the start entry. (If all entries have conditions, it's possible that those conditions may all be false at the moment.) |
| Get Current Conversation Info | Stores the active conversation title, ID, entry ID, actor name, and/or conversant name in variables. |
| Get Last Conversation Started | Stores the title of the most recently started conversation. |
| Get Last Conversation Ended | Stores the title of the most recently ended conversation. |
| Update Responses | Updates the responses for the current state of the active conversation. If the response menu entries' conditions have changed while the response menu is being shown, use this to update the response menu. |
| Jump To Entry | Jumps to a specific dialogue entry. |
| Set Portrait | Similar to the SetPortrait() sequencer command, this action overrides an actor's portrait image. |
| Action | Description |
|---|---|
| Bark | Makes a character bark. |
| Action | Description |
|---|---|
| Is Sequence Playing | Checks whether a sequencer is currently playing. |
| Start Sequence | Starts a sequence. |
| Stop Sequence | Stops a sequence immediately. |
| Send Sequencer Message | Sends a message to the sequencer. |
| Action | Description |
|---|---|
| Show Alert | Shows a gameplay alert using the dialogue UI. |
| Action | Description |
|---|---|
| Add Quest | Adds a quest to the quest table. |
| Delete Quest | Deletes a quest from the quest table. |
| Get Quest Description | Gets the description text of a quest. |
| Get Quest State | Gets the state of a quest. |
| Set Quest State | Sets the state of a quest. |
| Get Quest Entry Count | Gets the number of quest entries (sub-quests) in a quest. |
| Add Quest Entry | Adds an entry to a quest. |
| Get Quest Entry | Gets the description of a quest entry. |
| Get Quest Entry State | Gets the state of a quest entry. |
| Set Quest Entry State | Sets the state of a quest entry. |
| Is Quest Abandonable | Checks whether a quest is abandonable. |
| Is Quest Tracking Enabled | Checks whether tracking is enabled on a quest. |
| Set Quest Tracking | Sets tracking on or off on a quest. |
| Get Quest Abandon Sequence | Gets the quest's Abandon Sequence (if defined). |
| Get Quest Count | Gets the number of quests in a specified state. |
| Action | Description |
|---|---|
| Set Status | Sets the status that is defined between any two assets, which is referred to as a mutual status. |
| Get Status | Gets the mutual status defined between any two assets. |
| Set Relationship | Sets the numerical relationship value between any two actors. Relationships can be useful for controlling NPC responses based on a relationship value. |
| Get Relationship | Gets the relationship value between two actors. |
| Inc Relationship | Increments the relationship value between two actors. |
| Dec Relationship | Decrements the relationship value between two actors. |
| Action | Description |
|---|---|
| Apply Persistent Data | Applies persistent data from the Lua environment to the objects in the scene. |
| Apply Savegame Data | Applies savegame data to the Lua environment and the scene. |
| Load Level | Loads a level with full Dialogue System persistent data awareness. |
| Load Game | Loads a saved game from a string variable. |
| Save Game | Saves a game to a string variable. |
| Record Persistent Data | Tells objects in the scene to record persistent data into the Lua environment. |
| Record Savegame Data | Records persistent data and extracts it as savegame data. |
| Reset Persistent Data | Clears persistent data in the Lua environment. |
| Level Will Be Unloaded | If you use Persistent Destructible or Increment On Destroy components, use this action before loading a new level. This tells the components to ignore their destruction due to the level change. |
Note: In most cases, you'll only need to use Load Level, Load Game, and Save Game.
To save Playmaker global variables, add a Playmaker Global Variable Saver component to your Dialogue Manager.
| Action | Description |
|---|---|
| Add Dialogue Database | Adds a dialogue database to the Dialogue Manager's master database. |
| Remove Dialogue Database | Removes a dialogue database from the Dialogue Manager's master database. |
| Reset Dialogue Database | Resets the Dialogue Manager's master database to an initial state. |
| Set Default Dialogue Database | Sets the default database to use for the Dialogue Manager's master database. |
| Preload Master Database | Normally the master database is loaded just before being used by the first conversation, bark, or quest update. Use this action to load it immediately. |
| Preload Dialogue UI | Normally the dialogue UI is loaded just before being used for the first time. Use this action to load it immediately. |
| Set Dialogue UI | Assigns a different dialogue UI to use for conversations and alerts. |
| Action | Description |
|---|---|
| Run Lua | Runs arbitrary Lua code. |
| Get Variable | Gets the value of a variable in the Lua Variable[] table. |
| Set Variable | Sets the value of a variable in the Lua Variable[] table. |
| Get Lua Field | Gets the value of a field of an element in a Lua table (Actor[], Item[], or Location[]). |
| Set Lua Field | Sets the value of a field of an element in a Lua table (Actor[], Item[], or Location[]). |
| Get All Lua Elements | Gets the names of all elements of a type (Actor, Item, Quest, Location, or Variable). |
| Sync type | Syncs the value of a variable between Playmaker and the Dialogue System's Variable[] table. (Similar to Get/Set Variable) |
| Action | Description |
|---|---|
| Set_Language | Sets the current language to use for localization. |
| Get Localized Text | Gets the value of a localized table table field using the current language. |
| Get Actor Name | Gets a GameObject's actor name or internal Lua index name. |
| Get Portrait Image | Gets the portrait image of an actor associated with a GameObject. |
See Localization for information about localized text tables. The asset type for Get Localized Text changed from 1.x's LocalizedTextTable to 2.x's TextTable. If you have a primary TextTable, you can assign it to the Dialogue Manager and leave the Get Localized Text actions' table fields blank. In this case, the actions will use the Dialogue Manager's table.
Below is a screenshot of an example FSM on an NPC that starts a conversation when the player enters the NPC's trigger collider:
The conversation title "Quick Start" should be present in your dialogue database.
Note that the player is assigned as the Actor. Since the FSM is on the NPC, you don't need to specify the Conversant; it will default to the NPC.
This section describes how to use actions to access data in the Dialogue System's Lua environment.
The Variable[] table is one-dimensional. That is, every variable (such as Variable["Actor"]) has only one value. Variable["Actor"].Age isn't valid. Variable["Actor"] and Variable["Conversant"] are string values. Variable["Actor"] contains the name of the actor in the current conversation, and Variable["Conversant"] contains the name of the conversant.
The Actor[], Item[]/Quest[], and Location[] tables are two-dimensional. Every entry, such as Actor["Player"] has a number of fields such as Actor["Player"].Age.
Let's say you know the name of an actor ("Fred"), and you want to get his age. In the Dialogue System's Lua environment, this is stored in Actor["Fred"].Age, and this is what you'll use in the Dialogue Editor in Conditions and Script fields.
In Playmaker, you can use the Get Lua Field action. Select the Actor Table and manually enter "Fred" as the element and "Age" as the Field. In the example below, the result is stored in a float variable named "Freds Age".
If you're in the middle of a conversation and you don't know ahead of time who the actor is, you can first get the value Variable["Actor"] by using the Get Variable action. In the example below, it's stored in a string variable named "Current Actor Name". Then you can provide the string variable's value to the Get Lua Field action.
The Set Lua Field and Set Variable actions work similarly but come with one important caveat. Lua is essentially typeless. You can assign a number to Actor["Fred"].Age, and then you can turn around and assign a string to it. Of course, a string probably wouldn't make sense in context, but in Lua you can still do it if you want. The Playmaker action will assign any/all values that you've specified. In the example below, to prevent the action from trying to assign a string or bool value, the string and bool properties have been set to "None" by clicking the little button to the right of each one.
If Bool Value had been left as false, Actor["Fred"].Age would have been assigned the value 99, and then it would have been assigned the value false.
Similarly, you should remember to set the unused values to None in the Set Variable action. Also note that "Variable Name" for the Variable[] table is equivalent to "Element" for the Actor[] table. It's the value inside the square brackets. These values are typically called indices, since they provide an index into the table. The action below sets Variable["Another Variable"] to 42.
There's one more thing to note about Lua in the Dialogue System: spaces (' ') and hyphens ('-') in indices are replaced by underscores ('_'). So in your Conditions and Script fields, you should use Variable["Another_Variable"]. (Note the underscore.)
If you want your FSM to receive Dialogue System events, add a Dialogue System Events To Playmaker component to a GameObject in your scene that will receive Script Messages & Events. This is usually the Dialogue Manager GameObject, but it can also be a conversation participant. To do add the component, select Component → Pixel Crushers → Dialogue System → Third Party → Playmaker → Dialogue System Events To Playmaker.
This component will pass Dialogue System notification messages such as OnConversationStart and OnConversationEnd to any FSMs that you've assigned to the component's FSMs list. The message events are:
| Event | Description |
|---|---|
| OnConversationStart | Sent at the start of a conversation. The event's GameObject data is the other participant in the conversation (or the primary actor if the component is on the other participant). |
| OnConversationEnd | Sent at the end of a conversation. The event's GameObject data is the other participant in the conversation. |
| OnConversationCancelled | Sent at the end of a conversation. The event's GameObject data is the other participant in the conversation. |
| OnConversationLine | Sent whenever a line is spoken. |
| OnConversationLineCancelled | Sent if the player presses the cancel key/button while a line is being delivered. Cancelling causes the Dialogue System to jump to the end of the line and continue to the next line or response menu. |
| OnConversationResponseMenu | Sent just prior to setting up the response menu with responses. If you specify a separator (e.g., ';') in the Event Data section, the event's String data will be the Menu Texts separated by that separator. |
| OnConversationTimeout | Sent to the Dialogue Manager object (not the participants) if the response menu times out. |
| OnLinkedConversationStart | Sent when the current conversation follows a cross-conversation link. The event's GameObject data is the other participant in the conversation. |
| OnBarkStart | Sent at the start of a bark. The event's GameObject data is the other participant. |
| OnBarkEnd | Sent at the end of a bark. The event's GameObject data is the other participant. |
| OnSequenceStart | Sent at the start of a sequence. The event's GameObject data is the other participant. |
| OnSequenceEnd | Sent at the end of a sequence. The event's GameObject data is the other participant. |
| OnQuestStateChange | Sent when a quest state or quest entry state changes. The event's String data is the name of the quest. |
| OnQuestTrackingEnabled | Sent when tracking is enabled for a quest. The event's String data is the name of the quest. |
| OnQuestTrackingDisabled | Sent when tracking is disabled for a quest. The event's String data is the name of the quest. |
| OnRecordPersistentData | Sent when the Dialogue System is recording persistent data into the Lua environment, usually when saving a game or before changing levels. |
| OnApplyPersistentData | Sent when the Dialogue System is applying persistent data to the scene from the Lua environment, usually when loading a game or after changing levels. |
| OnLevelWillBeUnloaded | Sent prior to unloading a level, usually before changing levels. |
| OnDialogueSystemPause | Sent when the Dialogue System is paused. |
| OnDialogueSystemUnpause | Sent when the Dialogue System is unpaused. |
You can also use the sequencer command FSMEvent() to send events from sequences to FSMs.
The Playmaker Support package adds the sequencer command below.
Syntax: FSMEvent(event[, subject|all[, fsm]])
Description: This sequencer command sends an event to a Playmaker FSM on a subject.
Parameters:
all for the subject, it will send the event to all FSMs on all GameObjects in the scene.Example:
FSMEvent(Updated Name Variable, Player) (Sends an event "Updated Name Variable" to the FSM(s) on the object named "Player".)The FSMEvent() sequencer command sends an event to an FSM. Here are the steps to set it up. These steps use the example scene in the Playmaker Support package to demonstrate. This scene has an FSM on the Dialogue Manager object.
FSMEvent(eventName, gameObject, fsmName). This will send an event named eventName to an FSM named fsmName on a specific gameObject.The example scene, the "Test Sequence" state does a little fade out/fade in sequence and, at the 2 second mark, calls FSMEvent(Test Sequence Ended). This sends the event "Test Sequence Ended" to all FSMs on the speaker, which in this case is defined to be the Dialogue Manager object itself.
In your project, you could do something like this:
TextInput(MyTextInputUI,Name,PlayerName)->Message(GotName); FSMEvent(SetName,PlayerManager)@Message(GotName)
The first command gets the text input. When it's done, it sends the message "GotName" to the sequencer.
The second command waits until it receives the message "GotName". Then it sends the "SetName" event to the PlayerManager.
In your PlayerManager FSM, set up a transition for the SetName event. When you receive this event, use the Get Variable action to get the value of PlayerName. Then use the Game Object Set Name action to set the game object's name to PlayerName.
Side Note: In practice, for this specific scenario, you could just put "[var=PlayerName]" in the Actor Override Name component to do the same thing.
Dialogue entry nodes' Script and Conditions fields accept Lua functions, as can the Dialogue System Trigger component. To make Playmaker-specific Lua functions available, add the component Dialogue System Playmaker Lua to your Dialogue Manager. This will add the functions below to Lua. In the '...' Lua wizard dropdowns, these functions are available in Custom > PM.
The FSMEvent() Lua function sends an event to FSM(s).
| Lua Function | Description |
|---|---|
| FSMEvent(eventName:string, objectName:string, fsmName:string) | Sends an event to an FSM. |
This Lua function sends the event eventName to the GameObject named objectName, and specifically to the FSM named fsmName.
If fsmName is blank, the event is sent to all FSMs on the GameObject. If objectName is "all", the event is sent to all GameObjects that have FSMs.
The Lua functions below allow you to get and set Playmaker global variables.
| Lua Function | Description |
|---|---|
| GetFsmFloat(variableName:string) | Returns the value of a global float variable. |
| GetFsmInt(variableName:string) | Returns the value of a global int variable. |
| GetFsmBool(variableName:string) | Returns the value of a global bool variable. |
| GetFsmString(variableName:string) | Returns the value of a global string variable. |
| Lua Function | Description |
|---|---|
| SetFsmFloat(variableName:string, value:float) | Sets the value of a global float variable. |
| AddFsmFloat(variableName:string, value:float) | Add to the value of a global float variable. |
| SubtractFsmFloat(variableName:string, value:float) | Subtracts from the value of a global float variable. (Specify positive number since it will be subtracted.) |
| SetFsmInt(variableName:string, value:int) | Sets the value of a global int variable. |
| AddFsmInt(variableName:string, value:int) | Adds to the value of a global int variable. |
| SubtractFsmInt(variableName:string, value:int) | Subtracts from value of a global int variable. |
| SetFsmBool(variableName:string, value:bool) | Sets the value of a global bool variable. |
| SetFsmString(variableName:string, value:string) | Sets the value of a global string variable. |
To include Playmaker's global variables in saved games, add a Playmaker Global Variable Saver to the Dialogue Manager or Save System GameObject.