Skip to content
An Electron-based testing platform for browser-based narrative games
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Passage Shell

Passage Shell is an Electron-based testing platform for browser-based narrative games. Using Express, Passage Shell can remotely "play" projects using a system of inter-process communication (IPC) channels to send information between its main and rendering processes.


The Express framework exposes the same routes across all loaders. However, not all functionality is available for all formats.

All routes return JSON-encoded values. Return objects are based on their route names except in the case of /click/X, which can also return an error object, and /file, which only returns the static file.

  • /: Information about the file
  • /text: The current text of the passage
  • /html: The current HTML of the passage
  • /links: Listing of all links (or link-like) elements in story area
  • /click/X: The numbered (starting from 0) of the entry of the link (from /links) to "click"
  • /undo: Attempts to "undo" based on file and loader
  • /redo: Attempts to "redo" based on file and loader
  • /error: The latest error (if any) to occur
  • /reset: Reloads the file (but maintains webserver)
  • /file: The file from settings.json


Passage Shell currently supports the following formats:

  • Twine2 (Harlowe, SugarCube, and Snowman story formats)
  • Ink for Web


The settings.json holds the options of port, loader, and file.

  • port: Port number for the webserver
  • loader: The type of files to load. Loader will attempt to open the 'index.html' file inside any directory matching its value
  • file: The static file to serve. Must be an absolute path.

Passage Shell will not run without proper settings and attempts to prevent invalid values.


Every other route but /file communicates with the renderer process. Therefore, it is possible to work with the other routes and "play" the file served by /file without interferring with each other.


Run npm install to prepare dependencies and then npm start to run.

Because of loading times and different formats using transitions, it is recommended to poll every 10ms or more.



You can’t perform that action at this time.