The Seshat Adventure Engine is a text adventure engine written in vanilla JavaScript. It reads a JSON "storyfile" and allows you to play it in a classic "choose your own adventure" style.
Storyfiles are the way you program stories to play using Seshat. They follow the JSON (JavaScript Object Notation) format. The data structure for the Storyfiles is constantly changing during development, so this documentation may be out of date.
Events are the different "rooms" or "areas" that the player can navigate through. Each event is its own unique key in the storyfile. In order for an event to be functional, it must contain the following:
"events": {
"0": {
"locked": "0",
"image": "https://i.imgur.com/KLpd2I2.png",
"header": "Porch",
"description": "You come upon an abandoned house with a locked front door.",
"actions": {
"0": {
"special": "",
"text": "Kick the door.",
"response": "It won't budge.",
"warp": ""
}
}
}
}
locked
: only necessary if you want to have a locked action for this event (if you do, set to 0)
image
: contains a link to the header image you want to use for that event (will be resized to 400x200)
header
: title of event, usually used for displaying the name of a room or area
description
: a little blurb that describes the room or area
actions
: a list of actions the user can take during this event (see Actions below)
Actions are the different choices players can take during events. There are several types of Actions that have different outcomes.
Quick Response Actions display a message to the player. You can also add a warp
tag.
"actions": {
"0": {
"text": "Kick the door.",
"response": "It won't budge."
}
}
text
: option message to display
response
: message to display on click
Warp Actions are for when you want to move a player to another Event upon clicking an outcome. You can also add a response
tag.
"actions": {
"0": {
"text": "Go inside.",
"warp": "2"
}
}
text
: option message to display
warp
: event ID to warp to
Random Actions are a type of Special Event for when you want a user to have a customizable random chance of failing an outcome.
"actions": {
"0": {
"special": "random",
"text": "Pry it open.",
"meta": "50",
"warpSuccess": "2",
"successMsg": "It's extremely hard to move. It probably hasn't been opened in years. With a great burst of effort, you slide the window open.",
"warpFail": "0",
"failMsg": "It's extremely hard to move. It probably hasn't been opened in years. Unfortunately it appears the wood has rotted to the point that this window won't be opening any time soon."
}
special
: must be set to "random"
text
: option message to display
meta
: success rate in percent (out of 100)
warpSuccess
: event ID to warp to on event success
successMsg
: message to display on event success
warpFail
: event ID to warp to on event fail
failMsg
: message to display on event fail
Puzzle Actions are a type of Special Event for when you want a user to have to enter a password or puzzle answer to continue.
"actions": {
"0": {
"special": "puzzle",
"text": "Solve the puzzle.",
"response": "What goes up when the rain comes down? (all lowercase, one word).",
"meta": "umbrella",
"warpSuccess": "3",
"successMsg": "You got it. You pull out your umbrella and walk out into the rain.",
"warpFail": "5",
"failMsg": "Not exactly. You can't go out into the rain without one of these."
}
special
: must be set to "puzzle"
text
: option message to display
response
: puzzle or riddle for player to answer (shows in prompt)
meta
: answer to puzzle
warpSuccess
: event ID to warp to on event success
successMsg
: message to display on event success
warpFail
: event ID to warp to on event fail
failMsg
: message to display on event fail
These two special actions are used in conjunction with one another. Locked Actions require clicking a Key Action on another event to unlock them. For example, to open a door in one room you may need to find a key in another room.
"actions": {
"0": {
"special": "locked",
"lockCount": "1",
"text": "Open the front door.",
"response": "You insert the key into the door and twist. It pops open.",
"warp": "3"
}
}
special
: must be set to "locked"
lockCount
: how many Key Actions must be applied to this action to unlock it
text
: option message to display
response
: message to display when the Unlocked Action is clicked
warp
: event ID to warp to when the Unlocked Action is clicked
"actions": {
"0": {
"special": "key",
"keyValue": "1",
"text": "Pick up key.",
"response": "You picked up a key. It is labelled 'TOTALLY NOT FOR THE FRONT DOOR'",
"targetEvent": "0",
"obtained": "0",
}
}
special
: must be set to "key"
keyValue
: how many 'points' this Key Action counts for
text
: option message to display
response
: message to display when the Key Action is clicked
targetEvent
: event ID to apply the Key Action to
obtained
: must be set to "0" (this is changed programatically)