 |
|
The Dialogue System defines the Lua variables and functions described below.
The following Dialogue System-specific Lua data is available to you in your Lua scripts. More details are available in Chat Mapper's online documentation.
A "table" in Lua is similar to an array or dictionary in C# or UnityScript. The Dialogue System creates these tables:
| Table | Description | Example |
|---|---|---|
Actor[] | Two-dimensional table containing all actors | Actor["Player"].Age |
Item[] | Two-dimensional table containing all items/quests | Item["Anvil"].Weight |
Quest[] | An alias for the Item[] table. | Quest["Kill_5_Rats"].State = "success" |
Location[] | Two-dimensional table containing all locations | Location["Starbase"].Description |
Conversation[] | Two-dimensional table containing all conversations | Conversation[9].Title (this table is indexed by ID) |
Variable[] | One-dimensional table containing user variables | Variable["Alert"] = "Hello, world" |
In this Lua code:
Actor["Player"].Age = 21
the string "Player" is called the key. The Actor["Player"] part is called the table element. This is sometimes called a record in Lua guides. The Age part is called the field. The code above sets the player's Age field to 21.
The Dialogue System also manages these variables in the Variable[] table:
| Variable | Description |
|---|---|
Variable["Alert"] | Set this variable to make the Dialogue System display an alert (see How to Display Alerts) |
Variable["Actor"] | The name of the actor in the current conversation (if any) |
Variable["Conversant"] | The name of the conversant in the current conversation (if any) |
Variable["ActorIndex"] | The actor's index in the Actor[] Lua table |
Variable["ConversantIndex"] | The conversant's index in the Actor[] Lua table |
The variables Variable["Actor"] and Variable["Conversant"] will be the display names of the participants. These names are shown to the player in the dialogue UI.
The variables Variable["ActorIndex"] and Variable["ConversantIndex"] will be the indices in the Lua Actor[] table. You can use them in your dialogue entries' Conditions and Script fields. For instances, to check if the current conversant is at least 21 years old:
Actor[ Variable["ConversantIndex"] ].Age >= 21Table keys and field names are generically called indices.
The Dialogue System follows a convention established by Chat Mapper:
Here are some examples:
| In the Dialogue Database | In Lua |
|---|---|
A variable named Kissed the Frog | Variable["Kissed_the_Frog"] |
An actor named Mister Big-Man | Actor["Mister_Big_Man"] |
The actor's Favorite Color field | Actor["Mister_Big_Man"].Favorite_Color |
These Chat Mapper functions are available in Lua to record statuses and relationship values. The descriptions of these functions come from the Chat Mapper documentation:
Chat Mapper can track a status that is defined between any two assets, which is referred to as a mutual status. To set or access a mutual status, use the following two functions:
SetStatus( Asset1, Asset2, "status value" )GetStatus( Asset1, Asset2 )Chat Mapper will also track numerical relationship values between any two actors. Relationships can be useful for controlling NPC responses based on a relationship value. The following four functions can be used to control relationship values:
SetRelationship( Actor1, Actor2, "relationship type", value )GetRelationship( Actor1, Actor2, "relationship type" )IncRelationship( Actor1, Actor2, "relationship type", incrementAmount )DecRelationship( Actor1, Actor2, "relationship type", decrementAmount )Please note that the Dialogue System does not implement the functions below, since they have no meaning outside Chat Mapper:
TrackVariable( Table, "variable name" )TrackStatus( Asset1, Asset2 )TrackRelationship( Actor1, Actor2, "relationship type" )This function shows an alert message:
ShowAlert( message )These functions return and set quest states and quest entry states:
CurrentQuestState( questTitle )CurrentQuestEntryState( questTitle, entryNumber )SetQuestState( questTitle, state )SetQuestEntryState( questTitle, entryNumber, state )While you can technically set quest states by setting the Quest[] Lua table directly, it's better to use these functions because they also update the quest tracker HUD and send OnQuestStateChange messages that your scripts can listen for.
The Dialogue System provides a Lua function GetLocalizedText() to retrieve localized versions of fields in the Actor, Item, Quest, or Location tables. For information about setting up localized fields, see Localization.
The syntax of GetLocalizedText is:
GetLocalizedText( tableName, elementName, fieldName )where:
Actor table), andGetLocalizedText() Example
Say your actors have a "Nickname" field. You've also added a Spanish-localized field named "Nickname es". To use the localized version in a conversation, use the [lua(...)] tag to call GetLocalizedText():
You must talk to [lua( GetLocalizedText("Actor", "Boss", "Nickname") )].The Dialogue System provides a Lua function RandomElement(). You can use this in combination with the [lua()] tag to insert a random element from a list into your dialogue text.
The syntax of RandomElement is:
RandomElement( string )where string is a string of elements separated by the horizontal bar character ('|').
RandomElement() Example
Say you have an NPC that greets the character with a random honorific title. In your dialogue database, click on the Variables tab and define a variable named Honorifics that contains this list:
- "Esteemed|Revered|Great|Magnificent"
Or, to set it in Lua code:
In the dialogue entry, set the text to:
Greetings, [lua(RandomElement(Variable["Honorifics"]))] One!The result is that the NPC will randomly use one of the element in the Honorifics list, such as "Greetings, Esteemed One!" or "Greetings, Great One!"
The source string doesn't have to be set at design time. You can generate it dynamically during gameplay. You can use RandomElement() for other purposes, too, such giving the player a random item upon completion of a quest, or even choosing a random quest out of a list.
The Dialogue System includes Lua functions that synchronize variables and quest states to all clients using Unity Networking's High Level API (UNET HLAPI). To make these functions available, add a Lua Network Commands component to your player prefab(s).
It will add these functions:
NetSetBool( variableName, value )NetSetNumber( variableName, value )NetSetString( variableName, value )Sets a variable locally and to all other clients. Use in place of Variable["foo"] = value when you want all clients to receive the value of the variable.
NetSetQuestState( questName, state )NetSetQuestEntryState( questName, entryNumber, state )Sets a quest state or quest entry state on all clients. Use in place of SetQuestState and SetQuestEntryState.
<< Lua in the Dialogue System | How to Use Lua in Scripts >>