SceneText Documentation

SceneText is a system for story scenes with text. It is intended for the classic style of game dialog but could be used many ways and modified to suit many tasks. It can have choices that the user clicks and other branching possibilities.

SceneText was made by Noah Beamer (moniker BCETracks) because these tools were being created for the game "The Blackbird of Amor", http://blackbirdoa.com, a game with a visual novel format. Other information about SceneText is available on the official download site/page.

SceneText can be used for many types of games. The game can be primarily story based or have between gameplay scenes. SceneText can be inserted into a game as a GameMode. Once your story scene is done it can load a level and return to the gameplay. This is shown in the example, it will go to the top down mode at the end. The example project is available on the official download site/page.

-The flow of the system is as follows:

1. Load the story data. You can load it from JSON (text) files. With c++ you could also have it hardcoded or use another method. The JSON is intentionally not loaded until play start so you can change it without a re-import. To change the text source file look at the GameMode blueprint BeginPlay. The data will become Screen objects. Each screen represents a box of text but has other optional features.

2. Begin with Screen zero. Show text, wait for any animation, wait for user to click, then decide what to do.

3. Usually it will decide to go to the next screen, [0] goes to screen [1]. Things like prompts and commands can be used to skip screens or exit the story.


-The functions called go like this:
[Begin Process (BeginScreen())] > [ImUpdateMainItems] > [TypeWriteM] > Wait for user click or a timer > [user Advance (SubmitAdvance()+SaveState())] >[Begin Process (BeginScreen())]


The Begin function(s) prepare to show something on screen, ImUpdateMainItems sets the main text, TypeWriteM is a macro to animate the text with adjustable speed, User Advance is when the user clicks. SubmitAdvance may reject the click, if it does not then we save the sate and of course begin again with the next Screen object. The last screen object should tell us to load a level or something to get out of the story.


As stated, a screen is an object (a c++ only object) that holds a box of text and has optional extra things it does. It can:
1. Ask the user a multiple choice question. Each answer can do a command and the answer is saved too.
2. Play a sound, or many sounds ie. music and a SFX.
3. Move a character(A blueprint Actor with a skeletal mesh component) or hide them.
4. Set character animation, or just pose.
5. Go to another Screen, Game Mode, or whatever.

You can usually use an unlimited number of these features as they are in an array of blocks where each block is a prompt answer, command etc.

In a finished project you will have a json game data file (unless you enter the data with c++). The GameData.json file(s) in the "data" folder are required, make sure they are added in project settings -deployment section when publishing. These files contain the screen settings and text that will be used. There is an editor for those files (it should be in the example project)


More Details on Prompts:
Prompt blocks represent an answer to a question or a choice or any number of things. The doPrompt flag tells the screen to stop and show buttons instead of continuing normally. Prompts have several important parameters:

Body - The button text, what the user sees

Id - The user does not see this, it is an internal unique identifier.

Group - The unique identifier for the prompt. All answers should have the same group.

Command - What to do on this choice. GoToScreen~6 for example goes to screen index 6. For all types of blocks that use commands, commands are a list of values separated by ~.


Actors:
To move an actor around the scene you have to get it, and you need to use a string, or possibly an array index to identify. The best function I found was get actor by tags. Look at the example actor, she has her name as a tag.


Animations:
An Actor block can specify an animation and play, loop, or neither. It also has a number for the starting position. To animate an Actor you need to not only find an animation but load it. The first method I used was a mistake, it did not load the animation but appeared to work if the animation was loaded earlier. This means that you can use LoadAsset if it is an asset loaded by the level. The second method was to have the animations in an Array (a Map in the GameMode Blueprint) which works... but you should find a way to dynamically load them based on the type of game you want.


Sounds: Like animations a sound must be loaded not just fetched from disk when needed. They have an array in the GameMode Blueprint. The setting variable of a sound block is the volume, if blank it should go to 1 which is what you would normally use.


Special Commands: Command blocks can work in different ways but the normal use is for them to trigger when the screen is over unlike actor and sound blocks. They can have the same commands as the prompt commands like GoToScreen~6.