It is important to note that the content of this document is subject to constant change, so it is recommended to refer to this document regularly when writing.
highlight.js does not support syntax for Yarn Scripts. So syntax highlight on for this page will be wrong.
Events
In Brinkmanship, we defined a special type of nodes –– Events. They are nodes that trigger when specific events happen in Unity. They act as starting points for their own series of dialogues, similar to the start node. An event will always named with a keyword "event" prefix.
In general, it is not recommended to jump to events from within other nodes in Yarn Spinner. This is because jumping to an event will bypass the associated logic that is usually triggered when Unity starts the event. However, if you wish to safely trigger events from the Yarn Spinner, it is possible to develop a method. Please inform the engineering team if want this.
When an event is triggered, the game will remember the node that led to it. This is so the game's where to resume dialogue when this event finished (see command <<resume>> and <<resume_stopped_node>> for more details). However, if a node's name contains the keyword "event", the game will not remember it. Therefore, avoid naming nodes with "event" if you want them to be remembered.
Events will always interrupt the current node and restart from themselves. If you need commands to disable and re-enable trigger detection for a specific event, please let us know.
Typically, a single event is consist of multiple related sub-events. Functions and variables are usually provided to separate them. A good practice is to create a node for each sub-event, and name them on_name_event, where name is the name of the sub event. The keyword "event" at the end will prevent the game from auto resume from this point.
Brinkmanship DialogueManager requires all events listed here exist in a project.
event-npc-death
Will trigger when a npc dies in the scene. This event should be used with is_all_npc_dead() and is_npc_dead(name : string) functions to determine which npc is killed.
// EXAMPLE
title: event-npc-death
---
<<if is_all_npc_dead()>>
<<jump on_captain_pilot_both_died_event>>
<<elseif is_npc_dead("Pilot")>>
<<jump on_pilot_killed_event>>
<<endif>>
===
event-gun-threat
An events that triggers when player tries to threaten npc(s) with their weapon. Please note, this event can be triggers when the player either raised, aimed, or holstered their weapon, or fired the weapon but missed, no ammo, or hit an object that can’t be killed (like a door). This event doesn’t trigger when the player hits a npc. Because that kills them and should be handled by event-npc-death. To separate what type of threat was made (or disengaged), use get_variable(var : string) function with variable gun-threat-state
// EXAMPLE
title: event-gun-threat
---
<<if get_variable("gun-threat-state") == "holstered">>
<<jump on_gun_stow_event>>
<<endif>>
===
event-resume
A special event triggered by <<resume>> command. This event is for adding logics to redirect conversation back to the correct node. However, you do not have to cover all resume scenarios. Command <<resume_stopped_node>> can automatically find the last node player stopped at before an event was triggered. Which is why you should always place a <<resumestoppednode>> at the end of this event to serve as a fallback.
// EXAMPLE
title: event-resume
---
<<if is_all_npc_dead()>>
<<jump on_captain_pilot_both_died_event>>
<<else>>
<<resume_stopped_node>> // This command should always-
// be placed at end of this nodeto catch scenarios-
// that's not covered by logics above and provide auto-
// resume as fallback.
<<endif>>
<<resume_stopped_node>>
===
Functions
In Yarn Spinner, functions are units of code that Yarn Spinner scripts can call to receive a value. Functions don’t always take parameters, but will always return a value. Yarn functions can return the following types of values:
stringintfloatbool
Functions can be used with events to separate them into more detailed sub-events. And can be used in any other nodes as well.
is_all_npc_dead() -> bool
Returns a bool. When all npc in scene is killed, this function will return true. This function doesn’t take any parameters.
//EXAMPLE
<<if is_all_npc_dead()>>
<<jump on_captain_pilot_both_died_event>>
<<endif>>
is_npc_dead(name : string) -> bool
Returns a bool. Return true when the passed in npc is dead. To check if an npc is dead, pass in parameter name as string,
//EXAMPLE
<<if is_npc_dead("Pilot")>>
<<jump on_pilot_killed_event>>
<<endif>>
get_variable(var : string) -> any
Can return either string, int, float, and bool. Takes a parameter var as string. This function retrieve data stored in game’s storage system. See variables section. A set_variable command can be implemented, please let us know if you need it.
Commands
Yarn commands allow you to trigger codes (functions) in Unity side from YS. Commands can take parameters but never returns. You use commands similar to how you use <<jump>> in YS. It is possible to add commands that trigger all kinds of things in Unity. Such as trigger an animation or walk a npc to a location. Please let us know if you need a specific commands.
<<resume>>
Jumps to event-resume. You may wonder why don’t just use <<jump event-resume>> Using <<resume>> will make your script more readable. And give us options to write Unity side logics that go with <<resume>>
<<resume_stopped_node>>
Jump to last stopped node that got interrupted by an event. The game will never resume to a node that contains keyword “event” in it.
Variables
Brinkmanship variables are used to retrieve value from Unity side through get_variable(var : string) -> any function. And should not be confused with yarn spinner’s built in variable. Right now only one variable exists, but almost all variables from Unity can be linked with YS in this way. Informations like ammo count or number of times raising the gun can all be variables. So let us know.
gun-threat-state
This variable returns a string that contains the state of gun threats. The returned states track following states: holstered, raised, aimed, firing-no-ammo, hit, missed, and hit-attackable-disabled. And with the last one meaning gun fired but hit a npc that can’t be killed (like a door). gun-threat-state should almost always used in the context of event-gun-threat.