Story syntax

The story.json file is a JSON object containing the whole story structure. The engine reads the file and renders the site on a PHP server. This documentation page will detail how to define pages, options, actions, metadata, and more. The examples shown might not be the best for understanding without context, so you might want to look at the story.json file in the repository.

Metadata Object

The metadata object contains auxiliary information about the story. This can include the title, author, and story version. It's currently not used by the engine directly, but should be included for future compatibility.

{
	"metadata": {
		"title": "My Story",
		"author": "John Doe",
		"version": "1.0"
	}
}

Story Object

The main component of the story.json file is the story object. It contains every page, option, and variable used by the engine.

{
	"story": {
		"pagename": {
			"heading": "Page Heading",
			"text": "Page Text",
			"options": {
				"optionname": {
					"text": "Text that will be displayed",
					"action": ["set-KEY: VALUE", "goto: pagename1"],
					"requirements": {
						"KEY": ["VALUE", "VALUE"]
					}
				}
			}
		}
	}
}

Pages

To define a page, create a new key-value pair in the story object. The key is the name of the page, and the value is an object that contains the page's heading, text, and options.

{
    "story": {
        "pagename": {
            "heading": "Page Heading",
            "text": "Page Text",
            "options": {
                "... options ..."
            }
        }
    }
}

Options

To define an option, create a new key-value pair in the options object. The key is the name of the option, and the value is an object that contains the option's text and action.

{
	"options": {
		"optionname": {
			"text": "Text that will be displayed",
			"action": ["set-KEY: VALUE", "goto: pagename1"],
			"requirements": {
				"KEY": ["VALUE", "VALUE"]
			}
		},
		"optionname2": {
			"text": "Text that will be displayed",
			"action": ["set-KEY: VALUE", "goto: pagename2"],
			"requirements": {
				"KEY": ["VALUE", "VALUE"]
			}
		}
	}
}

Requirements

To define requirements for an option, add a requirements object to the option. The requirements object contains key-value pairs where the key is the name of the variable and the value is an array of possible values. If the user's state does not match the requirements, the option will not be displayed. Multiple keys for different requirements are combined with an AND operator, whereas multiple values for a single requirement are combined with an OR operator.

{
	"requirements": {
		"KEY": ["VALUE", "VALUE2"],
		"KEY2": ["VALUE", "VALUE2"]
	}
}

In the above example, we can simplify the requirements to KEY == VALUE || KEY == VALUE2 and KEY2 == VALUE || KEY2 == VALUE2.

Actions

Actions are written in a simple, human-readable format. They are separated by semicolons and are in the form of action: argument. The engine will read the actions and perform them in the order they are written.

The following actions are currently supported:

• set-KEY: VALUE: Sets a key-value pair in the story's state. This can be used to store the user's progress or to change the story's behavior.
• goto: pagename: Jumps to the specified page.
• end: Ends the story.

Variables

To use variables in the story, use the {{KEY}} syntax. The engine will replace the variable with the value stored in the story's state.

{
	"story": {
		"start": {
			"heading": "Welcome to the story",
			"text": "What is your race?",
			"options": {
				"human": {
					"text": "Human",
					"action": ["set-race: human", "goto: next1"]
				}
			}
		},
		"next1": {
			"heading": "Next Page",
			"text": "You are a {{race}} now.",
			"options": {
				"next": {
					"text": "end the story",
					"action": ["end"]
				}
			}
		}
	}
}