Modding:Conversations: Difference between revisions
(methods for ConversationNode added) |
No edit summary |
||
Line 15: | Line 15: | ||
</object> | </object> | ||
</syntaxhighlight> | </syntaxhighlight> | ||
== ConversationScript configuration == | |||
Skipping over a small section of pre-conversation / checks / etc handled inside the "ConversationScript" part (for now, documentation TODO here). ConversationScript should definitely be used because it checks all sorts of parameters about wether or not the player is capable of speaking with the object. Telepathy, and other special conversation choices are considered when ConversationScript is the way into the ConversationUI.HaveConversation() | |||
== XRL.UI.ConversationUI.HaveConversation() == | |||
This is the main loop that handles the conversation start / end and setup. | |||
First, it deep copies the Conversation object as an original template, allowing mods and parts responding to the following events to mutate the nodes as much as they want. | |||
Then, it checks in order <code>Conversation.StartNodes</code> looking for the first node which passes the <code>ConversationNode.Test()</code> and sets it as <code>Conversation.NodesByID["Start"]</code> | |||
Then 3 events will fire in a row - all 3 will cancel the conversation if "false" is returned. | |||
=== Event: <code>BeginConversation</code> === | |||
Fired on: "Speaker" (not the player) | |||
Parameters: <Conversation>"Conversation" and <GameObject>"With" pointing to the player. | |||
=== Event: <code>PlayerBeginConversation</code> === | |||
Fired on: "Player" | |||
Parameters: <Conversation>"Conversation" and <GameObject>"Speaker" pointing to the person to be talked to. | |||
=== Event: <code>ObjectTalking</code> === | |||
Is fired on the speaker when asked to check object talking in the HaveConversation() parameters. This event would normally be checked before getting this far if you enter via ConversationScript, so before these other events, but can some time be fired after. | |||
=== Core Conversation Loop === | |||
After the pre-conversation events above, the conversation has started, and enters at the selected "Start" node. This could have been mutated during the previous events as well, so is checked once as we begin the loop. | |||
During each step of the loop, we call <code>ConversationNode.Visit(Speaker, Player)</code>, to trigger any "on visit" effects in the node. We then sort the <code>ConversationNode.Choices</code> using the <code>ConversationChoice.Sorter</code> which uses the Choices's "Ordinal" property to sort, but also automatically handles any "End" nodes with <code>ConversationChoice.END_SORT_ORDINAL</code>. To sort an option after an End node, you can set it to END_SORT_ORDINAL + 1. | |||
==== Event: ShowConversationChoices ==== | |||
Fired on "Speaker" | |||
Parameters: | |||
* <code><List<ConversationChoice>>Choices</code> - can set this parameter as well as read to "extend" the choices available in a node. | |||
* <code><ConversationNode>CurrentNode</code> - the current conversation node. | |||
* <code><ConversationNode>firstNode</code> - the start node for conversation. (lowercase f intentional) | |||
This event is passed the sorted choices and gets one last chance to pass back additional choices / resort / or whatever it wants to do. We suggest setting the response to a <code>new List<ConversationChoice>(Choices)</code> before mutating it as changes made to the original "Choices" here will persist throught the current conversation, but the choices used are not the Node.Choices, it is the response from this event's <code>Event.GetObjectParameter("Choices") as List<ConversationChoice></code>. | |||
==== Building the message ==== | |||
After this event fires, the current menu will render its text. The conversation itself has a <code>Conversation.Introduction</code> which will prepend the nodes message if it is set, and after it is displayed, the value will be reset to <code>""</code> - showing the "intro" only once. We take the <code>ConversationNode.Text</code> and select from it's random selections (<code>~</code> separated) and apply the Variable Replacement to it, then prepend intro, and affix a TradeNote (if enabled on the node) This is the conversation's content and the choices are displayed. | |||
=== Picking a Choice === | |||
==== Call: ConversationChoice.Visit(Speaker, Player) ==== | |||
When the choice is selected, we call ConversationChoice.Visit() -- it can to return false to abort following through with the choice. The default implementation handles checks for things like "GiveBook". | |||
==== Event: LeaveConversationNode ==== | |||
Fired on "Speaker" | |||
Parameters: | |||
* <code><ConversationNode>CurrentNode</code> - the current conversation node. | |||
* <code><string>GotoID</code> - the goto id of the node WE ARE LEAVING (not the one we are going to!!!) | |||
==== Call: ConversationChoice.Goto(Speaker) ==== | |||
<code>ConversationChoice.Goto(Speaker)</code> is responsible for telling us the next node in the conversation. By default it resolves GotoID or other special GotoIDs. | |||
==== Optional Event: GetConversationNode ==== | |||
In the default handling of ConversationChoice.Goto() it will resolve any GotoID starting with <code>*</code> into a ConversationNode by broadcasting a <code>GetConversationNode</code> on the speaker. | |||
Parameters: | |||
* <string> GotoID - Input the "GotoID" including a * - I.E. <code>*waterritual</code> | |||
* <ConversationNode> ConversationNode - This is "output" from the event - we read this to get the result node. Check the <code>GivesRep</code> part for an example of returning the water ritual. | |||
==== Exit loop if ConversationNode is null now ==== | |||
==== Event: VisitConversationNode ==== | |||
Fired on "Speaker" | |||
Parameters: | |||
* <code><ConversationNode>CurrentNode</code> - the new conversation node. | |||
* <code><string>GotoID</code> - the goto id of the node | |||
==== Call: ConversationNode.Enter(ConversationNode previous, GameObject speaker) ==== | |||
This virtual method can return even yet another new node if it wants, | |||
==== Exit loop if ConversationNode is null now ==== | |||
=== Exiting the Conversation Loop === | |||
==== Event: AfterConversation ==== | |||
Fired on: Speaker | |||
No Parameters | |||
== Conversation Classes and XML properties == | == Conversation Classes and XML properties == | ||
Line 20: | Line 105: | ||
The xml file for conversation consists of a single <conversations> node with multiple <conversation> nodes underneath. It does not currently support extending the base game dialog via <code>Load="Merge"</code> or the other similar tricks used for many of the XMLs. Creating a Conversation.xml file for your mod would be done when you want to add a new specific conversation / template to be used in the game. | The xml file for conversation consists of a single <conversations> node with multiple <conversation> nodes underneath. It does not currently support extending the base game dialog via <code>Load="Merge"</code> or the other similar tricks used for many of the XMLs. Creating a Conversation.xml file for your mod would be done when you want to add a new specific conversation / template to be used in the game. | ||
=== | === XRL.World.Conversation XML Node: <conversation> === | ||
{| class="wrapped wikitable tablesorter tablesorter-default stickyTableHeaders" role="grid" resolved="" style="padding: 0px;" | {| class="wrapped wikitable tablesorter tablesorter-default stickyTableHeaders" role="grid" resolved="" style="padding: 0px;" | ||
|- | |- | ||
Line 53: | Line 138: | ||
| colspan="1" class="confluenceTd"|ID | | colspan="1" class="confluenceTd"|ID | ||
| colspan="1" class="confluenceTd"|string / required / "key" | | colspan="1" class="confluenceTd"|string / required / "key" | ||
| colspan="1" class="confluenceTd"|The node ID used in other "GotoID" properties, etc. Can contain multiple "Start" nodes, one of which will be selected given the | | colspan="1" class="confluenceTd"|The node ID used in other "GotoID" properties, etc. Can contain multiple "Start" nodes, one of which will be selected given the boolean filter parameters. | ||
|- role="row" | |- role="row" | ||
| colspan="1" class="confluenceTd"|TradeNote | | colspan="1" class="confluenceTd"|TradeNote | ||
Line 62: | Line 147: | ||
| colspan="1" class="confluenceTd"|boolean | | colspan="1" class="confluenceTd"|boolean | ||
| colspan="1" class="confluenceTd"|Defaults to true, but <code>Closable="false"</code> in XML will set this to false, telling the conversation to not allow "escape" to get out of it. | | colspan="1" class="confluenceTd"|Defaults to true, but <code>Closable="false"</code> in XML will set this to false, telling the conversation to not allow "escape" to get out of it. | ||
|- role="row" | |||
| colspan="1" class="confluenceTd"|Text | |||
| colspan="1" class="confluenceTd"|string | |||
| colspan="1" class="confluenceTd"|The text content of the <code><text></code> node. Uses [[Modding: Text Replacement|Text Replacement]] strings. | |||
|- role="row" | |||
| colspan="1" class="confluenceTd"|Choices | |||
| colspan="1" class="confluenceTd"|List<ConversationChoice> (C# only) | |||
| colspan="1" class="confluenceTd"|The <code><choice></code> nodes below this node from the XML. | |||
|- role="header" | |- role="header" | ||
! colspan="3" class="confluenceTd"|Visit node triggers | ! colspan="3" class="confluenceTd"|Visit node triggers | ||
Line 145: | Line 238: | ||
* <code>IsMapNoteRevealed:MapNoteID</code> : <code>Qud.API.JournalAPI.IsMapOrVillageNoteRevealed( SpecialRequirement.Split(':')[1] )</code> | * <code>IsMapNoteRevealed:MapNoteID</code> : <code>Qud.API.JournalAPI.IsMapOrVillageNoteRevealed( SpecialRequirement.Split(':')[1] )</code> | ||
* <code>!IsMapNoteRevealed:MapNoteID</code> : NOT of the above | * <code>!IsMapNoteRevealed:MapNoteID</code> : NOT of the above | ||
|- role="header" | |- role="header" | ||
! colspan="3" class="confluenceTd"|C# Methods | ! colspan="3" class="confluenceTd"|C# Methods |
Revision as of 02:49, 1 June 2019
THIS DOCUMENTATION IS COMPLETELY IN PROGRESS AND GNARF IS COPY/PASTING OVER IT CONSTANTLY - PLEASE REFRAIN FROM WIKI EDITS UNTIL THIS NOTICE IS REMOVED THANKS!
Conversations are loaded as templates from Conversations.xml
- The base conversations can not be extended or modified through the XML, however there are events that will allow dynamically editing conversations as they happen.
Conversation Object Parts
In order to be conversable, an object should use the CovnersationScript
part and attach a ConversationID
which references a conversation template from Conversations.xml.
Snippet of ObjectBlueprints.xml that links Mehmet's Conversation to "JoppaMehmet"
<object Name="Mehmet" Inherits="NPC">
<part Name="ConversationScript" ConversationID="JoppaMehmet" />
</object>
ConversationScript configuration
Skipping over a small section of pre-conversation / checks / etc handled inside the "ConversationScript" part (for now, documentation TODO here). ConversationScript should definitely be used because it checks all sorts of parameters about wether or not the player is capable of speaking with the object. Telepathy, and other special conversation choices are considered when ConversationScript is the way into the ConversationUI.HaveConversation()
XRL.UI.ConversationUI.HaveConversation()
This is the main loop that handles the conversation start / end and setup.
First, it deep copies the Conversation object as an original template, allowing mods and parts responding to the following events to mutate the nodes as much as they want.
Then, it checks in order Conversation.StartNodes
looking for the first node which passes the ConversationNode.Test()
and sets it as Conversation.NodesByID["Start"]
Then 3 events will fire in a row - all 3 will cancel the conversation if "false" is returned.
Event: BeginConversation
Fired on: "Speaker" (not the player) Parameters: <Conversation>"Conversation" and <GameObject>"With" pointing to the player.
Event: PlayerBeginConversation
Fired on: "Player" Parameters: <Conversation>"Conversation" and <GameObject>"Speaker" pointing to the person to be talked to.
Event: ObjectTalking
Is fired on the speaker when asked to check object talking in the HaveConversation() parameters. This event would normally be checked before getting this far if you enter via ConversationScript, so before these other events, but can some time be fired after.
Core Conversation Loop
After the pre-conversation events above, the conversation has started, and enters at the selected "Start" node. This could have been mutated during the previous events as well, so is checked once as we begin the loop.
During each step of the loop, we call ConversationNode.Visit(Speaker, Player)
, to trigger any "on visit" effects in the node. We then sort the ConversationNode.Choices
using the ConversationChoice.Sorter
which uses the Choices's "Ordinal" property to sort, but also automatically handles any "End" nodes with ConversationChoice.END_SORT_ORDINAL
. To sort an option after an End node, you can set it to END_SORT_ORDINAL + 1.
Event: ShowConversationChoices
Fired on "Speaker" Parameters:
<List<ConversationChoice>>Choices
- can set this parameter as well as read to "extend" the choices available in a node.<ConversationNode>CurrentNode
- the current conversation node.<ConversationNode>firstNode
- the start node for conversation. (lowercase f intentional)
This event is passed the sorted choices and gets one last chance to pass back additional choices / resort / or whatever it wants to do. We suggest setting the response to a new List<ConversationChoice>(Choices)
before mutating it as changes made to the original "Choices" here will persist throught the current conversation, but the choices used are not the Node.Choices, it is the response from this event's Event.GetObjectParameter("Choices") as List<ConversationChoice>
.
Building the message
After this event fires, the current menu will render its text. The conversation itself has a Conversation.Introduction
which will prepend the nodes message if it is set, and after it is displayed, the value will be reset to ""
- showing the "intro" only once. We take the ConversationNode.Text
and select from it's random selections (~
separated) and apply the Variable Replacement to it, then prepend intro, and affix a TradeNote (if enabled on the node) This is the conversation's content and the choices are displayed.
Picking a Choice
Call: ConversationChoice.Visit(Speaker, Player)
When the choice is selected, we call ConversationChoice.Visit() -- it can to return false to abort following through with the choice. The default implementation handles checks for things like "GiveBook".
Event: LeaveConversationNode
Fired on "Speaker" Parameters:
<ConversationNode>CurrentNode
- the current conversation node.<string>GotoID
- the goto id of the node WE ARE LEAVING (not the one we are going to!!!)
Call: ConversationChoice.Goto(Speaker)
ConversationChoice.Goto(Speaker)
is responsible for telling us the next node in the conversation. By default it resolves GotoID or other special GotoIDs.
Optional Event: GetConversationNode
In the default handling of ConversationChoice.Goto() it will resolve any GotoID starting with *
into a ConversationNode by broadcasting a GetConversationNode
on the speaker.
Parameters:
* <string> GotoID - Input the "GotoID" including a * - I.E.*waterritual
* <ConversationNode> ConversationNode - This is "output" from the event - we read this to get the result node. Check theGivesRep
part for an example of returning the water ritual.
Exit loop if ConversationNode is null now
Event: VisitConversationNode
Fired on "Speaker" Parameters:
<ConversationNode>CurrentNode
- the new conversation node.<string>GotoID
- the goto id of the node
Call: ConversationNode.Enter(ConversationNode previous, GameObject speaker)
This virtual method can return even yet another new node if it wants,
Exit loop if ConversationNode is null now
Exiting the Conversation Loop
Event: AfterConversation
Fired on: Speaker No Parameters
Conversation Classes and XML properties
The xml file for conversation consists of a single <conversations> node with multiple <conversation> nodes underneath. It does not currently support extending the base game dialog via Load="Merge"
or the other similar tricks used for many of the XMLs. Creating a Conversation.xml file for your mod would be done when you want to add a new specific conversation / template to be used in the game.
XRL.World.Conversation XML Node: <conversation>
property | details | Description |
---|---|---|
ID | string / required / "key" | The conversation ID used to reference this conversation template via a <part Name="ConversationScript" ConversationID="....">
|
C# Properties | ||
StartNodes | List<ConversationNode> | C# only. Represents the children <node ID="Start"> (of which there can be multiple)
|
NodesByID | Dictionary<string, ConversationNode> | C# only. Represents the children <node> that are not "Start" - the "Start" node will be added here when conversation begins and it is chosen.
|
Conversation's have children <node>
nodes:
Nodes: <node> - Deserialized: XRL.World.ConversationNode
property | details | Description |
---|---|---|
ID | string / required / "key" | The node ID used in other "GotoID" properties, etc. Can contain multiple "Start" nodes, one of which will be selected given the boolean filter parameters. |
TradeNote | boolean | TradeNote="show" in XML will set this to true, it tells the conversation engine to display the [Press T or Tab to trade] after the conversation text.
|
bCloseable | boolean | Defaults to true, but Closable="false" in XML will set this to false, telling the conversation to not allow "escape" to get out of it.
|
Text | string | The text content of the <text> node. Uses Text Replacement strings.
|
Choices | List<ConversationChoice> (C# only) | The <choice> nodes below this node from the XML.
|
Visit node triggers | ||
CompleteQuestStep | string | A comma separated list of QuestID~StepID that will Complete the given quest step when the node is entered (awarding XP, etc)
|
GiveItem | string | A comma separated list of BlueprintID that will give items to the player whenever this node is entered.
|
Filter / Test properties for Start nodes | ||
IfWearingBlueprint | string | A single BlueprintID that the player must have equipped to see this start node.
|
IfHasBlueprint | string | A single BlueprintID that the player must in their Inventory to see this start node.
|
IfLevelLessOrEqual | string (of a number) | A string representation of the level the character must be less than or equal to to see this node.
|
IfHaveQuest | string | A string Quest ID the player must have to get this start node.
|
IfNotHaveQuest | string | A string Quest ID the player must *NOT* have to get this start node.
|
IfFinishedQuest | string | A string Quest ID the player must have completed get this start node.
|
IfNotFinishedQuest | string | A string Quest ID the player must *NOT* have completed get this start node.
|
IfFinishedQuestStep | string | A string Quest Step ID the player must have completed get this start node.
|
IfNotFinishedQuestStep | string | A string Quest Step ID the player must *NOT* have completed get this start node.
|
IfHaveObservation | string | A string Observation ID the player must have to get this start node.
|
IfHaveState | string | A string state flag the game must have to get this start node.
|
IfNotHaveState | string | A string state flag the game must *NOT* have to get this start node.
|
IfHaveItemWithID | string (C# ONLY) | A specific item ID that must be in the players inventory. This is a C# only property because Obejct ID doesn't exist until the object is created from the blueprint, making this option only useful on dynamic conversation nodes. |
SpecialRequirement | string | Other special requirements.
|
C# Methods | ||
Copy(ConversationNode source) | void | Copies all the properties and makes a copy of each Choice in the Choices list |
Test() | virtual bool | Tests the various If* and other requirements properties to see if the node should be chosen for a start node. |
Visit(GameObject speaker, GameObject player) | virtual void | Tells the node that it was visited, is used to handle GiveItem and CompleteQuestStep and tracking "Visited" status. |
Unused/Unimplemented properties | ||
Filter | string / deprecated | A potentailly unused property, it seems to have no code paths calling it |
GiveOneItem | string / deprecated | A seemingly unused string (on node), no code paths in base CoQ reference it |
StartQuest | string / deprecated | A seemingly unused string (on node), no code paths in base CoQ reference it |
RevealMapNoteId | string / deprecated | A seemingly unused string (on node), no code paths in base CoQ reference it |
TakeItem | string / deprecated | A seemingly unused string (on node), no code paths in base CoQ reference it |
ClearOwner | string / deprecated | A seemingly unused string (on node), no code paths in base CoQ reference it |
Snippet of Conversation.xml with Mehmet's script
<?xml version="1.0" encoding="utf-8"?>
<conversations>
<conversation ID="JoppaMehmet">
<node ID="Start" IfNotHaveQuest="What's Eating the Watervine?">
<text>
Live and drink, =player.formalAddressTerm=. May you find shade in Joppa.</text>
<choice GotoID="AboutJoppa1">What can you tell me about Joppa?</choice>
<choice GotoID="LookingForWork1">I am in search of work.</choice>
<choice GotoID="End">Live and drink.</choice>
</node>
<node ID="Start" IfHaveQuest="What's Eating the Watervine?" IfNotFinishedQuest="What's Eating the Watervine?">
<text>
Live and drink, =player.formalAddressTerm=. Have you tidings from Red Rock?
</text>
<choice GotoID="FinishExploringRedrock1" IfHasBlueprint="Girshling Corpse">Yes. I found bits of gnawed watervine and slew a white spiderling. I carry its corpse with me.</choice>
<choice GotoID="End">I'm working on it, =pronouns.personTerm=! Live and drink.</choice>
</node>
<node ID="Start" IfHaveQuest="What's Eating the Watervine?" IfFinishedQuest="What's Eating the Watervine?">
<text>
Live and drink, =player.formalAddressTerm=. May you find shade in Joppa.</text>
<choice GotoID="AboutJoppa2">What can you tell me about Joppa?</choice>
<choice GotoID="End">Live and drink.</choice>
</node>
<node ID="FinishExploringRedrock1">
<text>
What a hideous thing! I dread the horrors its presence portends. Bring the
corpse to Elder Irudad's hut for the Elder to examine.
</text>
<choice GotoID="End">As you say.</choice>
</node>
<node ID="LookingForWork1">
<text>
Some critters are eating our watervine. Faarooq claims he saw one slinking around a vine patch. Ugly little thing, he says; pale white, eight legs, an ear-splitting whine.
I noticed a bit of red dirt in the watervine pool, the same we find in the soil at a nearby &Ycave to the north&y we call &rRed Rock.&y
Travel to &rRed Rock&y and kill as many of these critters as you can. Bring back the corpse of one, too. &GElder Irudad&y will reward your efforts.
</text>
<choice GotoID="End" StartQuest="What's Eating the Watervine?">I will do as you ask.</choice>
<choice GotoID="Start">I will perform no such peasant's task.</choice>
</node>
<node ID="AboutJoppa1">
<text>
You would be wise to speak with &GElder Irudad.&y Look for his hut to the north.
</text>
<choice GotoID="LookingForWork1" IfNotFinishedQuest="What's Eating the Watervine?">I am in search of work.</choice>
<choice GotoID="End">Live and drink.</choice>
</node>
<node ID="AboutJoppa2">
<text>
You would be wise to speak with &GElder Irudad.&y Look for his hut to the north.
</text>
<choice GotoID="End">Live and drink.</choice>
</node>
</conversation>
</conversations>