A List is a collection of numbers, variables, or text strings organized into a series of rows and columns. Lists may be one-dimensional arrays (a simple list of values), or two-dimensional arrays (a “spreadsheet” of rows and columns).
List entries are automatically interpreted as either numbers, variable names, or text. Lists can be authored within Story Machine or imported from a comma separated values file (CSV).
Lists are indexed starting at row and column 1.
Creating Lists
Lists are managed using the Lists pane, found under Window > Lists. To add a new list, enter its name as an Object, Scene, or Project list, or drag a CSV file from the project into one of those sections.
When dragging a CSV you will be prompted to optionally link the file to the list. If linked, the CSV will dictate the contents of the list, and changes made in Story Machine will be overwritten by the CSV when the scene loads. Note that like all assets in Story Machine, CSV files can be “live edited” while the Editor is open and changes made to the file will be reflected in the List pane automatically.
If a CSV file is copied instead of linked, its contents will be imported as a one-time operation and further changes to the file will not affect the list.
When importing a CSV, you have the option to treat the first row of data as column names.
Editing Lists
Clicking the Pencil icon next to the name of a list will bring up the List Editor pane. Here you can add and remove rows and columns, edit the values of individual cells, and set column names. Changes to lists can aso be made to lists as the game runs, via the Manipulate List action.
Using Lists with Indirect References
Throughout Story Machine you can refer to lists via the Indirect Reference syntax. This feature makes Lists a powerful way to organize data and code. For example, a list cell might contain a path to an image asset which is then referenced by the Replace Image action. Or it might contain the name of an action sequence from an Action Library, and can be referenced by the Send Trigger action. Using lists in combination with indirect references allows for the author to define a core set of features in their scene and then create many variants (e.g. levels, enemies, etc) based on list data.
Pro Tip
Lists can be used at runtime to manage complex collections of data that would otherwise be difficult to manage variables. For example, a group of enemies, each with their own health values, art, and status effects could be stored as rows in a list. Adding, removing, and modifying list content at runtime is a good way to store complex structures of game state.