ScenarioFlow

Japanese README

Version History

Table of Contents

• ScenarioFlow
  • Table of Contents
  • News
    • Acknowledgement
  • Contacts
  • URLs
    • ScenarioFlow
    • External
    • Sample
• Introductory Topics
  • Introduction
    • What Is ScenarioFlow?
    • Why ScenarioFlow?
  • Getting Started
  • How to Play Dialogue Scenes
    • Command and Script
    • ScenarioScript and ScenarioBook
    • ScenarioBookPublisher
    • ScenarioBookReader
  • New Commands and Execution
  • Prameter Types and Decoders
• Practical Topics
  • New Async Commands
  • Token Code
  • SFText Script
  • Localized SFText
  • Composite Script
  • Scenario Progression Controls
  • Scenario Branching
  • The Skip Mode
• Advanced Topics
  • General Token Code
  • Advanced Scenario Progression Controls
  • Token Code in the System
  • The Structure of the Scenario Book

News

ScenarioFlow version 1.2.0 has been launched! It is available at the Unity Asset Store.

This update includes a new strong feature, localized SFText, which helps to make stories in multiple languages efficiently.

See the version history for the details of the update. If you have any issues or questions, feel free to create a new issue on the GitHub Issues, or you can send an email to contact@dotprologue.com.

Thank you for having interest in ScenarioFlow!

[!NOTE] ScenarioFlow.1.2.3 has been released for bug fixing.

Acknowledgement

We would like to thank Aki Uzuki (@aki_uzuki3 on X, Twitter), who designed and illustrated very attractive two characters, Sheena and Rio. They are the mascots of ScenarioFlow and appear on many samples (even in the movie below). Why don't you visit Aki Uzuki's X (Twitter) to see Uzuki's other works?

Contacts

Contact us by sending an email at the following email address, or you can send a message on Issues on GitHub.

contact@dotprologue.com

Any feedback is welcome. Feel free to contact us! (English or Japanese is fine)

URLs

ScenarioFlow

• ScenarioFlow
  • Link to the Unity Asset Store
• SFText Extension Pack
  • VSCode extensions for SFText
• ScenarioFlow Lab
  • Website for learning ScenarioFlow

External

• UniTask
  • ScenarioFlow uses UniTask to handle async operations
• Ayu Theme
  • Recommended VSCode theme for SFText

Sample

• ConsoleSFSample
  • A sample system using the debug console
• SimpleSFSample
  • A sample system with practical functions
• SavableSFSample
  • A sample system with functions for saving scenario data

Introductory Topics

Introduction

What Is ScenarioFlow?

ScenarioFlow is a library for Unity to implement scenes of characters conversing with each other effectively. This library provides the programmer-friendly and writer-friendly system by adopting novel architecture with the catchphrase "Suits for all projects."

Why ScenarioFlow?

There are big two advantages of ScenarioFlow. Firstly, thanks to its high extensibility, it works well in any project, and dialogue scenes are created effectivery. Secondly, thanks to a novel script format, writers can write scripts effectively.

First, for example, there are some libraries that have similar purposes to ScenarioFlow like Utage and Naninovel. However, ScenarioFlow is designed based on a completely different philosophy from them. It is the belief that "You have to build your dialogue system yourself." The dialogue system in this context means a set of functions needed for creating dialogue scenes like narrative directions, controlling the scenario progression, script parsing, and so on. Libraries mentioned as examples provide a dialogue system itself that has rich functions, so that users can create dialogue scenes without extra codes in most cases. On the other hand, ScenarioFlow provides "a system to create a dialogue system" by extracting essential elements needed for createing dialogue scenes. That is because if a library provides a dialogue system itself, functions of that system is often deficient, excessive, or unfit for some projects. So ScenarioFlow doesn't provides a dialogue system itself, but a highly extensible system to build a dialogue system that is suit for your project effectively.

Next, writers can use "SFText" which is a new script format when writing scripts. That format is designed based on real scripts for a play, so that it has simple grammar, and it is easy to write and easy to read. Writers can also edit it comfortably because extensions of VSCode are provided for editing support. As a side note, you can create a new script format to writers' preference because SFText is just one of script formats. And in most cases, adding or changing script formats doesn't have an impact on a dialogue system that has already been built.

Getting Started

Let's learn how to use ScenarioFlow. Create a new project in Unity, and set up the project by following the steps below.

• Import UniTask
  • ScenarioFlow uses UniTask to handle async operations
• Import ScenarioFlow
  • Download the asset on the Unity Asset Store
• Install Visual Studio Code
  • Recommended text editor
• Install SFText Extension Pack
  • Editing support for SFText
• Instal Ayu Theme
  • Recommended theme in SFText
• Import ConsoleSFSample
  • A sample of ScenarioFlow

In this tutorial, we use a sample of a dialogue system that uses the debug console for learning. After the set up, open ConsoleSFSample/ConsoleSFSampleScene, make sure that the sample scenario HideAndSeek.sftxt is bound to the ScenarioManager object, and enter the play mode. In this sample, characters' line will be displayed on the console, and you can move on to the next line with the enter key.

ScenarioManager:

Make sure that the scenario branches based on your choice.

Choice 1:

Choice 2:

How to Play Dialogue Scenes

Let's check how HideAndSeek.sftxt was runned and how the dialogue scene was played. Open the file Scripts/ScenarioManager.cs.

Dialogue scenes are executed by following the two steps below in ScenarioFlow.

1. Convert an instance of the ScenarioScript class to an instance of the ScenarioBook class with an instance of the ScenarioPublisher class
2. Run the instance of the ScenarioBook class with an instance of the ScenarioBookReader class

//Convert the scenario script to a scenario book
IScenarioBookPublisher scenarioBookPublisherInterface = scenarioBookPublisher;
IScenarioScript scenarioScriptInterface = scenarioScript;
ScenarioBook scenarioBook = scenarioBookPublisherInterface.Publish(scenarioScriptInterface);

//Start to read the scenario book
IScenarioBookReader scenarioBookReaderInterface = scenarioBookReader;
scenarioBookReaderInterface.ReadAsync(scenarioBook, this.GetCancellationTokenOnDestroy()).Forget();

Let's learn about classes and interfaces provided by ScenarioFlow, and terms in using them.

Command and Script

Any narrative directions in dialogue scenes like displaying dialogue lines and replacing character's images are invoked by executing "command". Command means a function that is called from a script like HideAndSeek.sftxt, and what type of direction is executed depends on the executed command.

In the example HideAndSeek, log dialogue async is a command to display a dialogue line, delay seconds is a command to make the system wait for the specified number of seconds, and branch on 2 selections async is a command to present two selections to the player and make the scenario branch based on the answer.

![](./Images/DialogueScene/ExScri