SGS-A Game File

Top Level Overview

The text file for SGS-A games uses Shortcuts' standard dictionary formatting, seen below. Where the values are strings of text, they are surrounded by the quotes. Where they are sub-level dictionaries the quotes are not necessary. 

{"Key 1":"Value 1",

"Key 2":"Value 2",

"Key 3":"Value 3",

"Key 4":"Value 4"}

SGS-A uses keys at the top level to match up game-specific information with variables inside the system. The top level keys are:

• Title
• Starting Position
• Checkpoint! Count
• Save File Tag
• Menu Message
• Intro Messages
• Credits
• End Game Dictionary
• Item Dictionary
• Location Dictionary

The first 7 in the list are straightforward items that have to do with setting up the game for new players. "Title" is the name of the game. "Starting Position" is the starting state for a new game (formatted as described farther down). "Checkpoint! Count" is the total number of "!" that a player can have, and is used to indicate how much of the game has been completed. The "Save File Tag" is used when storing saved data locally. The tag allows the system to easily find the relevant data in the Notes app. "Menu Message" is the description shown to the player when they are prompted to either start a new game or load an old save. Finally, "Intro Messages" are the texts shown to a player at the start of a new game. There can be multiple messages in here, so it can be used as a tutorial or atmosphere setting or anything the game writer wants. Different messages are separated by "$$$". "Credits" are displayed to the player after they have successfully completed the game.

The last 3 contain sub-dictionaries that contain the information of the bulk of the game.

End Game Dictionary

This is a dictionary that contains all of the different possible endings a player can encounter. the title of the ending is the dictionary key and the description for the player is the value associated with it. By default, endings will show the message, then prompt the player to load a save. However, if the ending's title contains "WIN", SGS-A will recognize this as a completion of the game. Rather than loading a save, the player sees the description, then the credits, then the shortcut is ended.

Item Dictionary

Similar to the End Game Dictionary above, the Item Dictionary matches all of the items a player can have in their inventory with descriptions. When the player selects an item, they will be presented with the description from this dictionary above the option to use the item.

Location Dictionary

This is the heart of the game. This dictionary contains the descriptions of each location, all the actions the players can take, and what the results are. Location names form the top level keys, and their values are dictionaries that contain the different version of that location (see post about the checkpoint system). Using the relevant checkpoints as the keys gives a dictionary that contains the description for the location and sub-dictionaries for the "Move", "Interact", and "Inventory" menus. The player sees the keys from those dictionaries at their possible actions, and when they select one, it is used as a key to give the result. A hierarchy of the Location Dictionary is shown below:

Results Format

The result of any action is formatted as a text string that is read by the system and alters the player's current state. Each section is separated by a "~". The format is below:

[Messages]~[Items]~[Checkpoints]~[Location]

Multiple messages can be shown to the player by separating them with a "/". Items and checkpoints can be lists, with each unit separated by a comma. By default, items or checkpoints are added to the player's status. But by prefixing the desired item or checkpoint with a "/", they will instead be deleted from their status. The location section will provide the location dictionary with a new key to use to determine where the player is. Leaving any of these sections blank will result in no action to that part of the player's status.

Save State Format

To save the game, SGS-A just needs a text string that represents the current state of the player (since the game itself does not change). The primary state variables are combined into lists and stuck together using various symbols. The player's location and previous location are separated by a "/". The inventory and checkpoint lists use commas to separate items. Lastly, the player's percentage of completeness is rounded to the nearest whole number and saved at the end. Each section is separated by a "%". 

SGS-A supports 3 save states. To store this information, the save data text strings are combined with the Save File Tag as noted above, and appended to a note in the built-in Notes app. Below is the format of the single save state and the full combined save file:

Single save file - 

[Location]/[Previous Locations]%[Inventory1,Inventory2]%[Checkpoint1,Checkpoint2]%[percent complete]

All 3 save files – 

[Save File Tag]&[SAVE 1]&[SAVE 2]&[SAVE 3]

Special Choices

If there is a choice that needs to be made that does not fit inside of the structure of the location-based system, SGS-A provides an alternate mechanism. Inside of an otherwise normal action, the game writer can provide the player with a set of choices that lead to different results. The result of those choices can be another set of choices, for a maximum of 10 levels of nesting. When encountering such a choice, the player is presented only with the description and the options provided, rather than seeing the Action Menu and having access to the full range of meta-game actions.

This is represented in the game file by a dictionary located where the results text string would normally be for a given action. The special choice dictionary has two values. The first is "Description", who's value is the text presented to the player. The second is "Options", which points to a dictionary of the player's choices (the keys) and their results (corresponding values). The results of their choice can be a text string of the result like any normal action, or it can be another special choice dictionary. SGS-A supports up to 10 consecutive special choices.