The Story Machine Interface


The Stage is where scene composition takes place. Objects can be selected, resized, dragged, and deleted. New objects can be dropped from the Project window. A valid Scene is required to manipulate objects on the Stage.

The Project is a file list containing all of the files used in a Story Machine project. It maps directly to a folder on the disk. Files may be dragged from the Project window to the Stage, or to other fields (e.g. a file reference in the Inspector).

The Inspector is a context-sensitive game object parameter inspector. It contains information intrinsic to all game objects (such as position and scale), but can also contain a list of components that are unique to the selected object.

The Tools Pane displays editor tools (such as the selection tool, region tool, and text box tool), as well as a list of all the game objects in the scene. Game Objects can be displayed in layer order, or as a parent/child hierarchy. Dragging and dropping moves the game object’s layer or changes its parent, depending on the view. Game Objects can also be dragged and dropped onto fields in the Inspector or Action List.

An Action List is a sequence of commands to be executed in order. Each action is simple: change text in a text field, select a snapshot, animate an object. A list of these commands represents an Action Sequence, which may be executed when an event is detected (e.g. clicking on an object). Multiple Action List windows may be open at once, representing different action lists. Actions can be dragged to change the order of execution, and between action lists.

The Snapshots Pane displays snapshots saved in this scene. Snapshots are layouts of the game objects in the scene: their position, orientation, scale, and layer. Snapshots can be selected to instantly move objects into position, and animation between one snapshot and another is possible.

The Variable Editor allows variables to be named and initialized with values. Variables can drive nearly any numerical value field in the editor, and can be manipulated with Actions. When running the Player in the editor, variable updates can be viewed in real time. The Variable Editor can edit both Scene-Local Variables and Project Variables.

The Project Preferences window allows project-wide settings to be set, including the native resolution of the game. Window scaling behavior and the origin location (bottom-left or center) can also be selected here.

The AI Generation Pane allows AI-generated images to be inserted into the scene, either by authoring a direct prompt, or by using Story Machine’s generation interface.

The Achievement Pane allows creation and editing of achievements.

Core Story Machine Concepts

The Editor is the main Story Machine application that Story Machine games are built in.

The Player is a thin Story Machine client that can open and run Story Machine game packages. The Player can be ported to many platforms.

A Scene is a self-contained collection of assets and action lists that make up a single scene in a game. Scenes contain Game Objects and Snapshots, as well as Scene-Local Variables. Often a Scene will describe a single game location, e.g. a hallway or classroom. A complete game is made by linking Scenes together.

A Game Object is an object within a scene: an image, a sound, a clickable region, etc. All Game Objects have a name and a transform: a position, an orientation, a scale, and a layer. On its own, a Game Object does nothing, but Game Objects can also contain one or more Components that provide functionality.

A Component is a unit of functionality in a game object. For example, the Image Component allows the Game Object to display an image in the scene. The Region Component allows the Game Object to receive clicks within a predefined space. The Animation Component allows a Game Object to move, rotate, scale, or change color over time. Game Objects may have multiple components, but most will only have one.

An Image is a 2D graphic displayed on the stage. It supports transparency, and can have an additional tint. An image may optionally be set to “nine slice” mode, so that it can be stretched without the corners changing size. Images can be repeated and scrolled by adjusting their Custom Mapping parameters. Images support multiple blend modes.

A Region is a polygon that represents an area of the screen. Regions may be any shape as long as they have at least three points. Regions can be used to designate a clickable area, or to constrain a game object to a particular part of the screen. They can also be used for basic collision detection.

An Action is an instruction to change something in the scene. Actions are usually simple, such as setting the color tint of an image, or changing the text in a text box. Sometimes Actions can have complex effects, like animating an image over the course of several seconds. Actions are organized into an Action List, each action firing in the order it appears in the list. Most Actions have the option to continue immediately to the next Action in the list (even if the current Action’s effects are still operating), or wait until the Action has fully completed before moving on. Some Actions (such as the Wait Action), must complete before the next Action in the list can be executed.

A Text Box is a rectangular region that contains text. Text boxes can only display text that is stored in the Text Database. Text Boxes are assigned a TrueType font, and can display any characters that the font supports. Text Boxes can optionally type out their contents like a typewriter. Text Boxes also support simple HTML-like tags within the text itself to change color, size, and typing speed of the text.

The Text Database is a library of text used in the game project. Every text entry is given a name, and the Text Database is stored as a simple text file in the Project Folder. The purpose of the Text Database is to enable simple localization: by replacing one text file with another, the entire game can be changed to another language.

An Event is an condition that can cause a Action List to execute. Today there are three events: START (fired when the Game Object is created), IDLE (fired every frame), and TRIGGER (fired when some other Game Object sends a message). The user can also define their own named events and trigger them from Actions.

A Variable is a number with a name that can be referenced in any part of the UI that accepts numbers. Variables are stored in the Variable Database and automatically saved when the player saves their game. Variables store only numbers, but these can be manipulated with Actions. Variables may be stored in the Project (and referenced throughout the entire game), or in the Scene (and therefore exist only when that scene is active), or in specific objects. The system also provides several built-in variables.

A Flipbook is an animated sequence designed for short, high-resolution animation video clips. It is created from a series of still frame images, supports transparency, and can provide lossless storage and playback (as well as lossy compression if desired). It differs from Frame Animation in that it is designed for high quality full screen lossless video playback, particularly for cell-style animation sequences. A Flipbook might be used, for example, to play a dramatic full-screen interstitial when a character makes an important discovery, or to drive very high resolution animated character animation. It is not appropriate for general purpose video playback.

A Frame Animation is an animated sequence created out of a series of cells stored within a single “sprite sheet” image. It is appropriate for most in-game animations (“sprites”) of characters, UI, and effects. A Frame Animation may be made up of one or more sprite sheet images, and supports frames of varying size and pivot.

A Snapshot is a record of a particular layout of Game Objects in the scene. It records the location, orientation, layer, and scale of each Game Object, as well as whether or not each object is active. Snapshots do not record settings within individual Game Object Components. Snapshots have a variety of uses: they can be used to quickly reorganize the scene to represent a UI change (for example, the appearance or disappearance of a menu), to change the staging of the scene (for example, a character in the background comes forward to speak), or for simple animation. Snapshots can be selected by Actions, which can further animate from one Snapshot to the next (by moving objects into their new location over time or with a fade). Snapshots do not alter Game Objects that were added to the scene after the Snapshot was taken.

A Sound is an audio file (mp3, wav, flac) that can be assigned to a GameObject or played via a Command. Up to 32 sounds can play simultaneously. Sounds can be stopped, started, and cross-faded. Music is a special kind of sound that has its own volume and automatically cross-fades when a new track is started.

A Snippet is a collection of Game Objects that can be saved outside of the scene and used in multiple scenes. If the Snippet is changed, all scenes containing the snippet are updated as well.