Screenplays

When designing your game, you will need to add specific game functionality. For example when you open a treasure chest, step on a trap, or when you bump into a character. You want to be able to have conversations, receives items, etc. When a new scene starts, you might want to show a cutscene that reveals a part of the story. In any case, all of these things can be created with screenplays.

Screenplays are currently specified in plain text. But don’t worry, it is much easier than any programming or scripting language. Just take a look at the example screenplay below:

hero says "Hi mom!"
mom says "Hello sweetheart. Are you going into the forest?"
hero says "Yes"
mom says "Be carefull, alright?"
if hero lacks token "dagger"
    mom says "Take this dagger just in case."
    hero receives token "dagger"
dad says "And be home before supper!"

It reads just like a film script doesn’t it? Well, thats the whole purpose, to keep it simple and readable so anyone can work with it.

Remark that only a small subset of the complete screenplay features are currently implemented. More actions will be added soon. To get an idea on what will be supported in the future, take a look at the following script:

screen shows text "You enter the library" with icon book
professor says "Welcome my friend, if you have questions, you know where to find me"
continue
professor says "Hi again. The end of the world is near!"
when player chooses "How do you know this is the end of the world?"
    professor walks to tile 3, 4
    professor says "Take a look in this book, the prophecy is clear"
    if hero has token "prophecy book"
        hero says "I already have that book"
    else
        hero says "Let me see!"
when player chooses "This is not the end, it's just an earthquake."
    professor says "Unbeliever!"
    professor walks to tile 0, -6

Actions

A screenplay consists of a sequence of actions. An action is always of the form <actor> action, where <actor> is an actor that supports the given action.

Here is the list of actions that can be used inside a screenplay:

character says “your text

This action opens a conversation dialog displaying your text. See the example below

_images/conversation.png

Example screenplay:

hero says "Do you know the way to Lotheritus?"
merchant says "No, but maybe you can ask around in the Inn."

The formal specification of this action is:

<actor> says "<your text>"
<actor>
hero or any of the NPC’s
<your text>
The text you want to display in the conversation dialog. Make sure this is not too long so that it doesn’t fall outside of the dialog.

hero receives token “token

This action gives the hero a token, which can be checked in screenplays with if hero has token “token” or if hero lacks token “token”. Tokens work across different scenes, so you can set a token in one scene and check for it in another scene.

When playtesting, you can clear all tokens by selecting the hero entity and clicking the restart button next to the Tokens title. See Tokens Component for more info.

Example screenplay:

if hero lacks token "knows lisa"
    lisa says "Nice to meet you, I'm Lisa."
    hero says "Nice to meet you too, my name is Bart."
    hero receives token "knows lisa"
else
    hero says "Hi Lisa, nice to see you again"

The formal specification of this action is:

hero receives token "<your token>"
<your token>
The name of the token that the hero should receive. Might have already been received.

hero loses token “token

This action removes a token received by the hero with hero receives token “token”.

Example screenplay:

if hero has token "book of doom"
    hero says "Here is the book, I don't want it anymore."
    hero loses token "book of doom"
    lisa says "Thanks, I guess..."

The formal specification of this action is:

hero loses token "<your token>"
<your token>
The name of the token that the hero should lose. It might not be set yet.

if hero has token “token

Checks if the hero received a certain token, and if so, does the actions in the sub-block right after this action. An else action can be used after this action, which will run in case the hero didn’t have that token.

Remark that only the hero actor supports tags!

Example screenplay:

if hero has token "knows lisa"
    hero says "Hi Lisa, nice to see you again"
else
    lisa says "Nice to meet you, I'm Lisa."
    hero says "Nice to meet you too, my name is Bart."
    hero receives token "knows lisa"

The sub-block of the if is a list of actions that are run when the hero received the token. All actions in this sub-block must contain 4 extra spaces in front of each action.

The formal specification of this action is:

if hero has token "<your token>"
    <actions when true>
else
    <actions when false>
<your token>
The name of the token that is checked.
<actions when true>
A sequence of actions that are run when the hero has token your token. All these actions need to be proceeded with an extra 4 spaces relative to the if.
else
This else is optional and so can be skipped.
<actions when false>
A sequence of actions that are run when the hero doesn’t have token your token. All these actions need to be proceeded with an extra 4 spaces relative to the else.

if hero lacks token “token

Checks if the hero didn’t receive or lost a certain token, and if so, does the actions in the sub-block right after this action. An else action can be used after this action, which will run in case the hero does have that token.

Example screenplay:

if hero lacks token "knows lisa"
    lisa says "Nice to meet you, I'm Lisa."
    hero says "Nice to meet you too, my name is Bart."
    hero receives token "knows lisa"
else
    hero says "Hi Lisa, nice to see you again"

The formal specification of this action is:

if hero lacks token "<your token>"
    <actions when true>
else
    <actions when false>
<your token>
The name of the token that is checked.
<actions when true>
A sequence of actions that are run when the hero doesn’t have token your token. All these actions need to be proceeded with an extra 4 spaces relative to the if.
else
This else is optional and so can be skipped.
<actions when false>
A sequence of actions that are run when the hero has token your token. All these actions need to be proceeded with an extra 4 spaces relative to the else.

Errors

When typing screenplays, writing errors is pretty common. Therefore, any errors will be reported at the bottom of the screenplay edit dialog.

Below is a list of all errors, accompanied with a more detailed explanation.

Entity ‘...’ not found

Your entity name doesn’t exist in this scene. Check to see if the name is correct.

Entity ‘...’ has no action ‘...’

Your specified entity doesn’t have given action. See Actions for a list of all available actions.

An indent of X spaces is not allowed, use a multiple of 4 spaces

A single indent in the code is represented by adding 4 spaces in front of the action. Such indents are used for example with if or else actions. This error says that you don’t have a multiple of 4 spaces in front of your action.

Action ‘...’ needs to follow an ‘if’ action

You are probably using an else action without first specifying an if action. See the example in if hero has token “token” on how to use it properly.

Previous action doesn’t support an indent block

Using 4 spaces as indent is only allowed right after an if or else action.

Cannot indent more than 1 level

A single indent is 4 spaces, you are using too much spaces for this indent.