SGS-A

Player Interface

As with all SGS versions, SGS-A is written with two key features in mind:

1. It should run using the Shortcuts app and built-in integrations only.
2. It should be entirely playable from the Shortcuts widget.

Using iOS 13 or earlier, this means that no graphics can be shown to the player, and the only way to interact is to select an option from a pre-determined list. (Future versions of SGS will take advantage of iOS 14's changes.) So, SGS-A serves as a game engine that creates a text adventure game out of a plain text file written by the game developer. SGS-A takes advantage of Shortcuts' integration with dictionaries to store information and present the game to the player. A dictionary is a particular formatting of plain text which allows the computer to to match up a list of player-presentable options ("Go North") with computer-readable results ("You Walk North~~N!~Stone Ring"). The most useful part is that the value of any given option can be another dictionary. A dictionary inside a dictionary. Add a couple layers of nesting, and now SGS-A can read through an organized hierarchy of data. Shortcuts allows you to pull a list of all the player-presentable options (called "keys") which can then be shown to the player to pick from. So the game writer can build a location, give it a description, and make a list of all the possible actions and their results. While playing the player sees the description and is presented with the Action Menu:

The Action Menu serves as a splash page for the given location. It provides the two main types of actions "Move" and "Interact", and also gives access to the player's inventory and the game menu. 

The "Move" and "Interact" menus are effectively the same. Pressing one open up a list of possible actions at the given location. The movement menu lists places to go that will leave the location (go north, enter door, etc.), while the interaction menu covers actions within a location (pull lever, examine window, etc.). Either menu shows the player the description of the location and has has a back button for returning to the Action Menu.

The player can check their inventory at any location by pressing the "Inventory" option. It will list all of their items below the description of the location. Selecting an item will give a description of the item and present the option to "use item". This way, the player can use a key to open a door or a fishing rod to catch some food. If the item does not have any use at the current location, a standard "You can't use that item here" message will appear.

The "Menu" option gives access to all the meta-game actions. It shows the player's percentage of completion and allows them to save the game, load a save, and exit. SGS-A has support for 3 save files, stored locally in text form to the iOS Notes app. Selecting either of the save-related options will present them with the current status of the 3 save states, including their percentage of completeness. They can always overwrite an existing save slot.

The Checkpoint System

The real key to how the Shortcut Game System works is its checkpoint system. This is invisible to the user but is the vital method for the game writer to communicate with the game engine. The checkpoints are tags that the writer attaches to a player after they have completed specific tasks. They can then specify different versions of a location based on what the player has accomplished. For example, a player can be in a room with a locked door and a shelf full of books. If the player pulls on the correct book, suddenly the locked door becomes an exit! To the player they haven't moved at all, but the game sees two different rooms. One with a locked door and one with an open exit. Pulling on the book had given the player a checkpoint that the writer used to denote versions of the room. There are no limits to how many checkpoints a player or a location can have. Additionally, the previous location the player was in is also treated as a checkpoint. That way, if it is relevant to a room which way the player entered, that can be taken into account. 

Checkpoints also double as a method of keeping track of how much of the game the player has completed. Adding an exclamation mark to a checkpoint denotes it as important, and the player's percentage of completion is calculated by how many "!" there are in their list of checkpoints compared to the total number possible. There is no limit to how many "!" can be added to a given checkpoint.

The Game File

The game itself, as noted above, is contained within a text file formatted so the computer can read it. for a more in-depth description of the formatting, take a look at the post called "SGS-A Game File"