-
Notifications
You must be signed in to change notification settings - Fork 172
Game : Txt Guide
A guide to writing the .txt read by the Source Academy game engine.
Table of Contents
- Getting Started
- What's in a Checkpoint?
- Key Concepts
- Txt Naming Convention
- Txt Format Guide
- Main .txt
- Location Guide
- Dialogue Guide
- Action Guide
- Entity Guide
Writing your own checkpoint? You've come to the right place.
-
Refer to Source Academy Game Storywriter guide to know more about tools to write your txt file.
-
Refer to the following Sample Checkpoint or download some deployed checkpoints from
Story Simulator > Simulate Checkpoint > S3for reference as you read this guide. -
You may download the following Source Academy Game Txt Syntax highlighter vs code extension to highlight your txt under the Sa language
Definition and structure of a checkpoint
As you may already know, checkpoint is a part of chapter, which are played in progression once the previous one has finished.
A checkpoint is made up of (1) set of objectives and (2) a game map.
Objectives 📝
Refers to a set of goals that a player must achieve in order to clear the checkpoint.
It can be a simple list such as
talkToHartin
goToClassRoom
Explanation: We define two objectiveIds, talkToHartin and goToClassroom. As the player interacts with various entities in the game, these objectives may be fulfilled through actions. Once both these tasks are fulfilled by the player, the player can proceed to the next checkpoint.
Game Map 🗺️
Refers to all the locations in the checkpoint and how each location is configured. Storywriters have great control when it comes to customising locations, such as which other locations it is connected to, what objects are present in it, or even game modes available, just to name a few customiseable aspects of a location.
Entities
Entity refers to an element in the game, such as a specific location, object, or dialogue. Refer to Entity Guide to learn more about types of entities and what they mean in the game.
Actions 🎬
Actions are the main drivers of a story. They are the storywriters' tool or "Source"😉 to enable the game to progress based on player choices.
- How actions are triggered: Storywriters can attach actions to entities. For example, attaching action to a location causes the action to be performed when location is visited while attaching actions to objects causes action to be performed when object is clicked. Look out for 🎬 to see whether objects can have actions.
- What actions do: Using actions, storywriters can cause new objects and dialogues to be added to the map, move the player to a different location, mark objectives as "complete" and much more.
- Storywriters can specify whether the action occurs just once or many times.
- See Action Guide for more information.
Ids
Each entity such has its own id. Storywriters typically provide these in order to refer to a specific entity.
- Example:
mainDoor1could refer to one particular instance of a door image that is located in the center of the Hallway. - Typically written in camelCase.
- Ids can have types such as locationId, objectId, etc. depending on the type of entity it is referring to.
- Warning❗ Ids are unique across the entire checkpoint. Even though id's have different types, you cannot have a character with characterId of
carand an object with objectId ofcartoo.
All checkpoints inherit the /stories/defaultCheckpoint.txt in S3.
https://source-academy-assets.s3-ap-southeast-1.amazonaws.com/stories/defaultCheckpoint.txt
This reduces the need to redeclare locations and items that are present throughout the game.
You may overwrite this by uploading with the defaultCheckpoint.txt filename.
A little guide on the unique .txt syntax
There are two types of listing
Vertical listing of items separated by newlines
Example:
item1
item2
item3
Horizontal listing of items separated by commas
Example:
item1, item2, item3
The .txt uses Python-like paragraph format
A paragraph is made up of a header and a body.
header
body
body
body
Storywriters can create paragraph bodies by indenting with 4 spaces or 1 tab
Example:
header1
line3
line4
header5
line6
line7
line8
line9
line10
line11
line12
In the above example, there are two main headers, header1 and header5, each containing a body of text underneath.
-
header1's body is a point-listing made up of just 2 points:line3andline4 -
header5's body is a point-listing 4 points:line6,line9,line10, andline12 - We can also nest further things underneath one point.
line6's body is a point-listing of 2 points:line7andline8, whileline10's body is a point-listing of 1 points:line11.
Lines refer to all non-empty lines in the text file, whichever paragraph they are in. A txt line is typically one of the following:
- An id such as
studentRoom - A category such as
characters - A CSV (see CSV format)
- A configuration line (see Configuration Line)
This format specifies properties for an entity.
Examples:
cheiftain, Chieftain, happy, left
myChair, /objects/chair.png, 100, 100
CSV's describes an entity (e.g. character or object)'s properties. The order of properties matters. The proper CSV format must be followed in order to accurately describe an entity.
This format specifies the value(s) for a certain key, using a : symbol.
Examples:
startingLoc: studentRoom
modes: talk, move, explore
This line describes the value for a particular configuration such as the value of startingLoc (starting location) or the list of game modes in a location. In case the value is a comma-listing, the order of values typically don't matter.
The following must be specified in the main outermost layer of the .txt
| Key | Value(s) | Requirements for value |
|---|---|---|
startingLoc |
The starting location of the player upon entering the chapter | Must be an existing location id |
The following are paragraphs present in the outermost layer of .txt
Point-listing of objectiveIds that players must accomplish to complete the checkpoint.
Example:
objectives
talkToHartin
solveThePuzzle
Explanation: We define that players must accomplish the tasks talkToHartin and solveThePuzzle to proceed to next checkpoint.
Point-listing of CSVs to declare locations present in the checkpoint.
CSV format: locationId, location asset path, location name
| Property | Meaning |
|---|---|
| locationId | Declaration of new location with that locationId
|
| location asset path | The path to an image file to be used in painting the background of the location |
| location name | display for that location when players click on "Move" |
Example:
locations
studentRoom, /locations/room.png, Student Room
hallway, /locations/hallaway.png, Hallway
Explanation: We create two locations, one with locationId studentRoom that uses /locations/room.png as background and has the display name Student Room, and another with locationId hallway that uses /locations/hallway.png as background and has the display name Hallway
Use one of the locationIds you defined previously under locations paragraph
Nested paragraph describing a specific location
Example:
studentRoom
modes: ...
objects
...
characters
...
Refer to Location Guide for more information on writing location paragraphs.
Point-listing of dialogue (paragraphs) that can be brought up
Example:
dialogues
uninhabited, The Uninhabited Planet
...
newBegin, A new beginning
...
Refer to Dialogue Guide for more information on writing dialogues.
How to write paragraphs describing a certain location.
Each location paragraph is headed by the locationId of the location that you want to describe.
The following must be specified in the body of a location:
| Key | Value(s) | Requirements |
|---|---|---|
modes |
Comma-listing of the game modes available in the chapter | Every mode must be one of the following: talk, explore, move
|
talkTopics |
Comma-listing of talk topics available in a location, i.e. dialogues that players can choose from when click on "Talk" | Must be valid dialogueIds |
nav |
Comma-listing of other locations that this location is connected to. | Must be valid locationIds |
Paragraphs in the body of the location paragraph.
Point-listing of actions 🎬 that occur when location is visited.
Example:
actions
show_dialogue(youveArrived)
make_object_glow(pen)
Refer to Action Guide for more details on how to describe an action.
Point-listing of CSVs of objects in the location.
CSV format: +objectId, object asset path, x, y, width(optional), height(optional)
| Property | Meaning |
|---|---|
| + | Presence of object at the start of the checkpoint. Put a plus sign if you want the object to appear initially when checkpoint begins, drop the plus sign if you'd like to add it later. |
| objectId | Declaration of new object with objectId of objectId
|
| object asset path | The path to the image file to be used in rendering the object in the location |
| x | x-coordinate of centre of the image |
| y | y-coordinate of centre of image |
| width | width of the image |
| height | height of the image |
Example: +mainDoor1, /objects/door.png, 10, 20, 30, 40
Explanation: In the location, we display an object with objectId mainDoor1 that uses /objects/door.png as its texture and is rendered using the coordinates (10, 20) with size 30 by 40 pixels.
Each object CSV line may have nested point-listed actions 🎬 underneath, specifying what actions are triggered when object is clicked.
Point-listing of CSVs of bounding boxes in the location.
CSV format: +bboxId, x, y, width, height
| Property | Meaning |
|---|---|
| + | Presence of boundingbox at the start of the checkpoint. Put a plus sign if you want the bounding box to appear initially when checkpoint begins, drop the plus sign if you'd like to add it later. |
| bboxId | Declaration of new boundingBox with bboxId of bboxId
|
| x | x-coordinate of centre of the rectangle |
| y | y-coordinate of centre of rectangle |
| width | width of the rectangle |
| height | height of the rectangle |
Example: +bbox1, 10, 20, 30, 40
Explanation: In the location, we draw an invisible, possibly clickable rectangle with bboxId bbox1 with coordinates (10, 20) and size 30 by 40 pixels.
Each object CSV line may have nested point-listed actions 🎬 underneath, specifying what actions are triggered when boundingBox is clicked.
Point-listing of CSVs of characters in the location.
CSV format: +characterId and assetPath, character name, default expression, default position
| Property | Meaning |
|---|---|
| + | Presence of character at the start of the checkpoint. Put a plus sign if you want the character to appear initially when checkpoint begins, drop the plus sign if you'd like to hide the character or add him later. |
| characterId and assetPath | Declaration of new characterId. Since characters are unique and cannot have multiple instances, the id has to match the asset path (which is the folder name inside /characters folder) |
| character name | The display name to show in the dialogue speaker box if ever that character has dialogues |
| default expression | The expression for this character initially. Must match one of the filenames |
| default position | Position to render the character originally. May be one of left, right, or center
|
Example: +chieftain, Chieftain, happy, left
Explanation: In the location, we display Chieftain with characterId chieftain that uses /characters/chieftain folder as source of images, with happy.png being his original expression and is rendered on the left side of the screen.
Point-listing of CSVs of bgm in the location.
CSV format: bgmId, bgm asset path, volume
| Property | Meaning |
|---|---|
| bgmId | Declaration of new bgmId |
| asset path | The path to the background music to be used in rendering the object in the location |
| volume | Volume of this background music |
Example: heavyHitter, /bgm/HeavyHitter.mp3, 0.5
Explanation: We declare the background music with bgmId heavyHitter that uses /bgm/HeavyHitter.mp3 as source of background music and volume of 0.5.
Note: The first background music declared is made default for the location.
Point-listing of CSVs of sfx in the location.
CSV format: sfxId, sfx asset path, volume
| Property | Meaning |
|---|---|
| sfxId | Declaration of new sfxId |
| asset path | The path to the sound effect to be used in rendering the object in the location |
| volume | Volume of this sound effect |
Example: card, /sfx/card.mp3, 0.5
Explanation: We declare the sound effect with sfxId card that uses /sfx/card.mp3 as source of background music and volume of 0.5.
Crafting individual dialogue paragraphs under the dialogues paragraph
The header for a dialogue is a CSV with format: dialogueId, title(optional)
Example:
planetXrk, What happened to the planet, Scottie?
<dialogue body goes here>
Explanation: We define a dialogue with the dialogueId planetXrk. It has the title What happened to the planet, Scottie?. The title is will appear under the "Talk" menu if the dialogue is a talk topic under a location.
Note: Although this is a CSV, you can put commas in the title, this is fine.
Writing dialogue bodies are quite simple, much like writing a script for a play.
Example:
@scottie, happy, left
It has been a while since you last set foot on the ship.
I'm so happy you've arrived.
@you
Thanks, Scottie! It was my pleasure.
The simplest body is just a point-listing of lines to be spoken in the dialogue.
You may nest point-listed actions underneath any line in the dialogue. This causes the actions to be triggered when dialogue line is spoken.
❗You may not perform the following actions during a dialogue.
-
change_location- This can only be used at the end of a dialogue. The workaround is to usechange_backgroundandclear_objectsduring dialogue. -
show_dialogue- Dialogue is already playing. Use goto's instead.
You can change the speaker by writing a change-speaker CSV which starts with an @ symbol
CSV Format: @characterId, expression(optional), position(optional)
| Property | Meaning |
|---|---|
| characterId | characterId of the speaker |
| expression | Expression of the speaker. Has to be one of the expressions in the folder. Defaults to speaker's default expression if not specified |
| position | Position of speaker on the map. One of left, right, center. Defaults to speaker's default position if not specified. |
Example: @beat, happy, left
Explanation: This line changes the speaker to a beat as described in any location's characters list, whose expression is happy and rendered on the left of the screen.
❗Make sure you have the character somewhere on the map first before making him a speaker, even if he's hidden or in another location.
Note: You may use the following special speakers in place of the speaker CSV
-
@you- will make students' name appear -
@narrator- will speaker box and speaker avatar disappear
You can specify parts of a dialogue by numbering lines using integers.
Example:
9
Welcome to Source Academy
goto 2
1
You will never reach this part.
2
You have reached part two.
Explanation: This dialogue has three parts. Part 9, being listed first, will be played first. After playing Welcome to Source Academy, it reaches goto 2. This means the dialogue will now play part 2 - You have reached part two. That's the end. Part 1 will never be reached.
Currently, there is no good use for it besides segmenting your dialogue into parts. However, this feature is put in place to pave the way for "choices" which can show a different part depending on what response a player clicks on when prompted.
You may interpolate student's name into the script using {name} which gets replaced with their Luminus names.
As we've seen, actions can be performed by various entities, such as locations, objects, bounding boxes, and even during dialogues.
If there is a listing of many actions, they are performed sequentially.
| Entity | How to specify/attach action | When action is triggered |
|---|---|---|
| Locations | Nest point-listed actions under the location paragraph's action header |
When location is visited |
| Objects | Nest point-listed actions under an object CSV line | When object is clicked during Explore mode |
| BoundingBoxes | Nest point-listed under a boundingBox CSV line | When boundingBox is clicked during Explore mode |
| Dialogue | Nest point-listed actions under any line in a dialogue body | Right after dialogue line is played |
Marks task with taskId in the checklist as accomplished
Example: complete_objective(talkToChieftain)
Explanation: When this action is executed, the task talkToChieftain in Objectives is marked as completed
Changes players' location on the map
Example: change_location(crashsite)
Explanation: When this action is executed, players will be placed in the crashsite location.
Adds or removes an item with id entityId of category category from a location with id locationId
List of possible categories and corresponding entity id.
| Category | Entity Id |
|---|---|
objects |
objectId |
talkTopics |
dialogueId |
boundingBoxes |
bboxId |
navigation |
locationId |
Changes the background of the scene to the background of a particular locationId as specified under main .txt's locations paragraph.
Brings up the dialogue with dialogueId dialogue as specified under the main dialogues paragraph.
Adds or removes a game mode from a location with locationId locationId.
Adds a popup showing the image of objectId on a position (left, right, or middle) for a duration of duration milliseconds.
If an object with objectId objectId is visible on screen, then it will glow yellow to draw players' attention.
If an object with objectId objectId is visible on screen, then it will blink to draw players' attention.
Changes background music to bgmId bgmId.
Plays background music with sfxId sfxId.
By default, actions are only performed once the first time they are triggered. Say, you want show_dialogue(hi) to occur every time an object is clicked. You can use the asterisk symbol to mark them as repeatable *
Example: show_dialogue*(hi)
Explanation: The action show_dialogue*(hi) will be performed every time object is clicked.
Action Conditions are used to specify under which precondition an action can performed. They can be written as if clauses right next to the actions.
Example: show_dialogue(welcome) if checklist.talkToChieftain
Explanation: The action will be the first time it's triggered and talkToChieftain is completed.
Example: show_dialogue*(welcome) if checklist.talkToChieftain
Explanation: The action will be performed every time it's triggered as long as talkToChieftain task has been completed.
You may chain multiple conditions using the keyword AND
Example: show_dialogue*(welcome) if checklist.talkToChieftain AND userState.collectibles.cookie
Explanation: The action will be performed only if talkToChieftain task has been completed, and user has the cookie under his collectibles list.
What do we mean when we refer to...?
One of the tasks the player has to complete to finish the checkpoint
One of the places players can to navigate to
Choices of what activities players can do upon visiting a location.
One of the following: talk, explore, move
A list of lines containing speaker and sequence of spoken lines.
An image that is drawn in a certain location. This may or not be interactive in Explore Mode.
A character (avatar) present in a certain location. May also be used as speaker in the dialogue.
An invisible rectangle that players may possibly be able to interact with in Explore Mode.
One of the topics the player can talk about in Talk Mode. Specified using a dialogue.