Proposal: File-level tags

[TheMartianLife]

Introduction

File-level header fields which act as if they were repeated in the headers of each node in the file.

Rationale

Header tags are a really powerful tool for contextualising content. Tags which can specify which location this is taking place in, which act of the story, etc. are very helpful to readability, but whenever we see user projects we find header tags are less used than we would intend or expect. When it comes to saliency in Yarn 3 you can now ask "what node would run right now?" and it creates new opportunities to make use of Yarn tags to be used for dialogue-related state which applies at the conversation level. For example, to be able to ask "what is the start_pose: of the node that is about to be played?" so you can trigger the animation on the character model as the conversation starts.

But header fields within one file - where a Yarn file is often delineated by nodes which conceptually relate to each other in ways like being in the same scene, or by the same character, or set in the same day - get super repetitive and therefore are annoying to write. To be able to declare at the start of the file what properties are shared by the nodes in this file will also increase the information available to writers skipping around in large projects.

With the advent of node groups and when: headers, repetition is sure to increase further.

Proposed solution and design

File-level headers declared via a body-less node at the start of the file.

when: current_time() == .Day
// this is applies to each node in the file
===

title: DaytimeChat
// this will be constrained to daytime
---
Some content.
===

title: DaytimeChat
// this will be constrained to daytime
---
Some other content.
===

Backwards Compatibility

While this is technically a breaking change to the grammar, there should be no way that using this syntax was valid in the past. Therefore, no users should be affected.

[TheMartianLife]

Issues that arise is the readability of each node to easily tell what constraints apply to them, and considerations for how snippet previews should work in the editor when referencing node group nodes now that only partial information may be available in that snippet.