Special Lua Variables & Functions

Table of Contents

The Dialogue System defines the Lua variables and functions described below.

Data

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.

Tables

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.

Variables

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:

  • Conditions: Actor[ Variable["ConversantIndex"] ].Age >= 21

Important Note About Table Indices

Table keys and field names are generically called indices.

The Dialogue System follows a convention established by Chat Mapper:

  • In Chat Mapper tables, replace all space characters and hyphens with underscores in indices.

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

Chat Mapper Functions

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:

Status Functions

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 )

Relationship Functions

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 )

Chat Mapper Functions Not Implemented

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" )

Other Useful Functions

Alert Functions

This function shows an alert message:

  • ShowAlert( message )
    • Shows a string as an alert message.

Quest Functions

These functions return and set quest states and quest entry states:

  • CurrentQuestState( questTitle )
    • Returns the current quest state as a string.
  • CurrentQuestEntryState( questTitle, entryNumber )
    • Returns the current state of a quest entry as a string.
  • SetQuestState( questTitle, state )
    • Sets a quest to a state.
  • SetQuestEntryState( questTitle, entryNumber, state )
    • Sets a quest entry to a 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.

GetLocalizedText() Function

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:

  • tableName is "Actor", "Item", "Quest", or "Location",
  • elementName is the name of an element in the table (e.g., "Player" for the PC in the Actor table), and
  • fieldName is the name of the field.

GetLocalizedText() 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():

  • Dialogue Text: You must talk to [lua( GetLocalizedText("Actor", "Boss", "Nickname") )].

RandomElement() Function

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:

Variable["Honorifics"] = "Esteemed|Revered|Great|Magnificent"

In the dialogue entry, set the text to:

  • Dialogue Text: 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.

Lua Network Synchronization Functions

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:

Set Variables Over Network

  • 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.

Set Quest State Over Network

  • 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 >>