Revision as of 11:00, 15 June 2017

In Staxel, there are two files which are used to specify all villager dialogue in game. These files are the *.dialogue files which point to an associated .json file that was created using Yarn.

*.dialogue File

Creating a *.dialogue File

Creating this file is very simple with only two properties. The full file looks like;

{
  "code" : "mods.modname.village.character.dialogue.CecileFond",
  "dialogue" : "staxel/village/character/dialogue/CecileFond.json"
}

Both properties are self-explanatory. Make sure the dialogue property points to a file that is created by Yarn otherwise some issues can arise.

Config Options

"code"

Valid options (String): A unique string which dialogue what this object is.

Default Value: No default value is specified. Always need to provide your own.

A string containing the unique identifier of this dialogue. This is commonly only used in Dialogue Pools.

"dialogue"

Valid options (String): A string which contains the path to a Yarn .json file.

Default Value: Null or nothing specified.

A string containing the path of the item the blob will be referring to.

The Yarn *.json file

Yarn is the program which creates the dialogue files for Staxel. It utilises it's own scripting language which can make choices and also use conditional statements in order to provide the right dialogue. They also include an editor which helps visualise these files.

Look at the documentation around Yarn, particularly sections such as this. Do not Yarn is changing frequently and documentation might not line up with the implementation used in Staxel.

Additional Functions

These are additional functions that Staxel offers to integrate the dialogue into the game. They range from functions that do decision making to functions which give and take items and money from the player.

acceptQuest

Usage: <<acceptQuest>>

If the speaker has a quest, then give the quest to player. Also if the quest has a start item then give the player that item.

adjustReputation

Usage: <<adjustReputation 20>>

Parameter 1: Amount to adjust by.

Adjust the player's reputation by the amount specified.

branchAchievementNotCompleted

Usage: <<branchAchievementNotCompleted staxel.achievement.PlantCrop PlantingWait>>

Parameter 1: Achievement code to look for. (e.g. staxel.achievement.PlantCrop)

Parameter 2: Title of the Node to move to.

When this function is hit, it will check if the selected achievement has been completed. If it has been not completed it will continue on normally. If it has been completed, then it will move to the specified node. Useful for checking for completed actions, such as the uses in the tutorial.

branchBuildingHasExisted

Usage: <<branchBuildingHasExisted staxel.totem.workplace.Patisserie Existed>>

Parameter 1: Totem code to search for.

Parameter 2: Title of the Node to move to.

When this function is hit, it will check if the specified totem has been completed at some point (i.e Has been built). If it hasn't then continue on normally. If it has been completed, then move to the specified node. This is useful for making sure you only talk about buildings that exist or have existed. (Note: Building does need to have been built before. Just placing totem doesn't count.)

If you require that it does exist then check #branchValidStructureExists.

branchHasUnclaimedAchievementRewards

Usage: <<branchHasUnclaimedAchievementRewards AchieveRewards>>

Parameter 1: Title of the Node to move to.

When this function is hit, it will check if the player has unclaimed rewards. If they do, then it will head to the specified node, otherwise continues on normally.

branchPlayerCantAffordItem

Usage: <<branchPlayerCantAffordItem item staxel.item.crafting.MugOSap 1 CantAfford>>

Parameter 1: Can be item, tilePlacer or plant. Use item for items. Use tilePlacer for TileObjects or Tiles. Use plant for Seeds.

Parameter 2: Item/Tile/Seed code. (e.g. staxel.crop.tomato)

Parameter 3: Title of the Node to move to.

When this function is hit, it will check if the player can afford the item. If they can then continue on normally. If they can't then move onto the specified node. This is useful for only giving an option if the player can afford it.

branchPlayerDoesntHaveItemOfCategory

Usage: <<branchPlayerDoesntHaveItemOfCategory seed PlantingGive>>

Parameter 1: Category to look for.

Parameter 2: Title of the Node to move to.

When this function is hit, it will check if the player has an item with the specific category. If they do, continue on normally and if they don't, move to the specified node.

branchPlayerDoesntHavePlayerItem

Usage: <<branchPlayerDoesntHavePlayerItem staxel.item.FarmRegistrationLetter GoodBye>>

Parameter 1: Item code. (e.g. staxel.crop.tomato)

Parameter 2: Title of the Node to move to.

When this function is hit, it will check if the player has an item of a specific code. If they do, continue on normally and if they don't, move to the specified node.

branchQuestActive

Usage: <<branchQuestActive CheckCompletion>>

Parameter 1: Title of the Node to move to.

When this function is hit, it will check if the player has this person's specific quest. If the speaker has no quest, the player doesn't have the quest, or the player does have the quest but it's for the wrong day, continue on normally. Otherwise go to the node.

branchQuestCompletable

Usage: <<branchQuestCompletable CompleteQuest>>

Parameter 1: Title of the Node to move to.

When this function is hit, it will check if the player has completed this person's specific quest. If the speaker has no quest, the player does have the quest but it's for the wrong day, or if the quest is not completeable then continue on normally. Otherwise go to the node.

branchQuestTarget

Usage: <<branchQuestTarget TargetDialogue>>

Parameter 1: Title of the Node to move to.

This is specifically for delivery type quests. When this function is hit, it will check if the player has a quest for the villager and if so, check to see if the the person is the target of the quest. If the speaker has no quest for the villager or the villager is not the target then continue on normally. Otherwise go to the node.

branchNoVillagerWithPersonality

Usage: <<branchNoVillagerWithPersonality staxel.village.personality.Tomboy NoTomboy>>

Parameter 1: Code of the personality to search for. (e.g staxel.village.personality)

Parameter 2: Title of the Node to move to.

When this function is hit, it will search to see if a villager with the specified personality exists in the world. If they do, continue on normally and if they don't, move to the specified node. This is useful for when you want to talk about another type of villager that may or may not be in the village.

branchNoVillagerWithName

Usage: <<branchNoVillagerWithName Leif TellRumour>>

Parameter 1: Name of person to look for.

Parameter 2: Title of the Node to move to.

When this function is hit, it will search to see if a villager with the specified name exists in the world. If they do, continue on normally and if they don't, then move to the specified node. This is useful for when you want to talk about another specific villager that may or may not be in the village.

branchValidStructureExists

Usage: <<branchValidStructureExists staxel.totem.AirshipLanding AirshipAvailable>>

Parameter 1: Totem code to search for. (e.g. staxel.totem.AirshipLanding)

Parameter 2: Title of the Node to move to.

When this function is hit, it will search to see if a valid totem of the type specified exists. If it does, then head to node continue on normally otherwise it continues on normally. Useful for checking that a building actually exists before going to it/ talking about it.

If you want to know that the building existed at some point then head to #branchValidStructureExists.

cancelQuest

Usage: <<cancelQuest>>

If the player has a quest for the current speaker, then cancel that quest. Otherwise do nothing.

completeQuest

Usage: <<completeQuest>>

If the speaker has a quest, and it is completable then set the quest complete. Also give the quest reward.

emote

Usage: <<emote staxel.emote.ScratchHead>>

Parameter 1: Emote code to play. (e.g. staxel.emote.ScratchHead)

Play a specified emote and wait until it is finished.

giveItemToPlayerIfDoesntHave

Usage: <<giveItemToPlayerIfDoesntHave item staxel.item.tool.Hoe>>

Parameter 1: Can be item, tilePlacer or plant. Use item for items. Use tilePlacer for TileObjects or Tiles. Use plant for Seeds.

Parameter 2: Item/Tile/Seed code. (e.g. staxel.crop.tomato)

Give an item to the player if they do not have the item already.

giveItemToPlayerIfCantAfford

Usage: <<giveItemToPlayerIfCantAfford plant staxel.crop.Tomato>>

Parameter 1: Can be item, tilePlacer or plant. Use item for items. Use tilePlacer for TileObjects or Tiles. Use plant for Seeds.

Parameter 2: Item/Tile/Seed code.

Give an item to the player if they can't afford to buy that item.

givePlayerPetals

Usage: <<givePlayerPetals 42>>

Parameter 1: Amount of Petals to give.

Give the amount of petals specified to the player.

givePlayerPetalsIfInsufficient

Usage: <<givePlayerPetalsIfInsufficient 42>>

Parameter 1: Amount of Petals to check for. Amount of Petals to give.

Give the amount of petals specified to the player if the player does not have the amount or more. (If player has less than 1000 petals, give 1000 petals)

giveUnlockedAchievementRewards

Usage: <<giveUnlockedAchievementRewards>>

Give all the unclaimed items from achievements to the player.

loadItemBuyPrice

Usage: <<loadItemBuyPrice item staxel.item.crafting.MugOSap 1 $sap>>

Parameter 1: Can be item, tilePlacer or plant. Use item for items. Use tilePlacer for TileObjects or Tiles. Use plant for Seeds.

Parameter 2: Item/Tile/Seed code.

Parameter 3: Quantity

Parameter 4: Target Variable.

Calculates the cost of the specified item and places the value into the variable specified.

loadVillageActiveQuestsInfo

Usage: <<loadVillageActiveQuestsInfo>>

Loads all the current quest givers. Each consecutive quest giver is stored in the variable "$quest_giver_i" where i is the number of the quest giver starting at 0. Also stores the number of quests in the variable "$quest_count". For use of these variables look at the barkeep's dialogue.

loadVillagerName

Usage: <<loadVillagerName Cecile $c_name>>

Parameter 1: Name of character to search for.

Parameter 2: Target Variable.

Searches for a villager with the specified name. If that villager does exist, then it places their code name into the target variable. This is specifically for loading the right translation for the character.

loadVillagerNameForPersonality

Usage: <<loadVillagerNameForPersonality staxel.village.personality.Mayor $mayor_name>>

Parameter 1: Code of the personality to search for. (e.g staxel.village.personality)

Parameter 2: Target Variable.

Searches for a villager with the specified personality. If that villager does exist, then it places their name into the target variable.

lockPlayerInConversation / releasePlayerFromConversation

Usage: <<lockPlayerInConversation>> and <<releasePlayerFromConversation>>

LockPlayerInConversation forces the player to enter into conversation mode. Conversation mode does several things;

• Stop the player from moving.
• Brings in the black bars
• Focuses player focus onto the NPC

ReleasePlayerFromConversation removes conversation mode from the player. Allowing them to move off and end the conversation. A <<typewriterMode off true true>> should be placed with this command if <<typewritermode on>> was present.

playerPurchaseItem

Usage: <<playerPurchaseItem item staxel.item.crafting.MugOSap>>

Parameter 1: Can be item, tilePlacer or plant. Use item for items. Use tilePlacer for TileObjects or Tiles. Use plant for Seeds.

Parameter 2: Item/Tile/Seed code. (e.g. staxel.crop.tomato)

Purchases the item if the player can afford the item.

pickRandomLine

Usage:

<<pickRandomLine>>

This is line 1.

This is line 2.

<<flushRandomLine>>

Choose a single line, from a number of text only lines, randomly up either up to the end of the node or up to the command <<flushRandomLine>>. Used to select either a random section of text so that it doesn't repeat the same text too often.

pickRandomPath

Usage:

<<pickRandomPath>>

<<NodeName1>>

<<NodeName2>>

<<flushRandomPath>>

Choose a single line, from a number of node names, randomly up either up to the end of the node or up to the command <<flushRandomPath>>. Used to select a random node to go to so the same section of text isn't repeated often. Less clutter than #pickRandomPath when dealing with larger conversations.

moveTo

Usage: <<moveTo TavernEntrance>>

Parameter 1: Waypoint Kind to find. Can be one of: Any, ChillSpot, Tutorial Spawn, NearShippingDock, NearCatalogue, Fields, Totem, Pathing, MayorsOffice, Shop, TavernEntrance, BarArea, TownSquare, ShopEntrance

Move the NPC to the nearest node of the kind specified.

leadTo

Usage: <<leadTo TavernEntrance>>

Parameter 1: Waypoint Kind to find. Can be one of: Any, ChillSpot, Tutorial Spawn, NearShippingDock, NearCatalogue, Fields, Totem, Pathing, MayorsOffice, Shop, TavernEntrance, BarArea, TownSquare, ShopEntrance

Move the NPC to the nearest node of the kind specified. Stops to wave at player if they are too far away.

removePlayerItem

Usage: <<removePlayerItem staxel.item.FarmRegistrationLetter>>

Parameter 1: Item code to remove.

Remove the item specified if the player has it. Do nothing if there is no item.

resumeProgress

Usage: <<resumeProgress>>>>

Resume the last node that was saved for the current player. If there is no saved value or if saved value is the "Start" node then continue on the current node.

saveProgress

Usage: <<saveProgress>> or <<saveProgress NodeA>>

Parameter 1: The title of the node to save. (Skipping means the last node is saved.)

This saves the current node to a variable which is then stored. Useful for when a conversation needs to be completed. (e.g. It is used in the tutorial to save the last location Farm Fan was in.)

shuffleNextOptions

Usage: <<shuffleNextOptions>>

Make the next set of options be in a random order.

typewriterMode

Usage: <<typewriterMode on>> or <<typewriterMode off true true>>

Parameter 1: Turn on or off typewriter mode.

Parameter 2: (If Parameter 1 is off) Clear the message so it doesn't stay around. (Set to False to keep messages after this value)

Paremeter 3: (If Parameter 1 is off and Parameter 2 is True) Setting to True lets the current node immediately end without the need to click. (e.g Ending conversation immediately.)

Setting the typewriter to on makes it so text is filtered out a single character at a time instead of the entire message appearing at once. Should be turned off at the end of a conversation (i.e. <<typewriterMode off true true>>) before releasing from conversation.