Skip to content

The workspace

Storyletter has two panes, the navigator down the left and the document you’re editing in the centre. A problems bar appears along the bottom only when something needs fixing.

The Storyletter workspace: the back and forward arrows at the top left, the navigator on the left with the Story and Map rows and The Hamlet's Village box with its decks and hands, and the Arrival deck open in the centre with Group by set to Deck above four cards, each showing its title, its When condition, its purpose and its tags.
The navigator (left) and the document (centre): here, the Arrival deck from the example project, in its Cards view. The ▶ Play button in the top bar opens the Board.

The navigator is a tree of containers. Every row has a chevron (or a space where one would be), a label, and a count:

The Hamlet ← the project
Story 12 ← the @story properties
Map 2 ← the project map, and its zones
Village ← a box
Decks 5
Arrival 4
Gareth's Debt 3
...
Hands 4
+ New box

The tree stops at containers. Individual cards, hands, hand templates, and tag groups don’t appear as rows; you arrange and sort those in the centre, which is also where their “+ New” buttons live. The navigator keeps only + deck and + New box.

Story sits above the boxes and opens the story’s own state, the @story properties every designer shares, with the count showing how many are declared. It’s a document like any other, and edits save as you make them. Expand a property’s row to give it a purpose, one line saying what it’s for, which becomes the hover tip on that property’s pills wherever a condition or outcome names it. (Your game’s @world properties aren’t here; they’re a contract with the game and stay in Project settings.)

The Story document in Storyletter: the Story row selected in the navigator, and the Hamlet's seven story properties as rows. The first row, act, is expanded to show its Stages, in order (arrival, act-1, act-2), and its Purpose field; the rest show their name, type, starting value and a uses count. A note beneath points to Project settings, Game scopes, for the game's own state.
The Story document: the story's shared state as a page of its own. Expand a row for its Purpose and, for a list or quality, its values or stages.

A quality’s stages are chips in ladder order. Click a stage’s name to rename it, and every card, tag and condition naming that stage follows in the same edit, which one Undo takes back. Move a stage earlier or later and the row says how many gates compare against the ladder, since each of them now reads the new order.

Each row also carries a quiet uses chip (the count of everything in the project that reads or writes the property), and clicking it opens Find on exactly that list. Check it before you rename a property.

Map sits between Story and the boxes once the project has a map, with a count of its zones. It opens the project map, the one map every box on it shares. A box on the map wears a small map mark in its own colour.

A box expands to Decks and Hands. Its setup (the card template, hand templates, tags, and box properties) isn’t in the tree. It lives as tabs on the box’s own page.

The chevron expands or collapses a row and never navigates, and clicking a label opens that document. Only chevron clicks are remembered. The path to whatever you have open expands while it’s open, so the tree doesn’t ratchet itself open over a week of work. The open document’s row is highlighted strongly, and each ancestor softly. When the open document has no row of its own (a card, a hand, a tag group), its nearest ancestor takes the strong highlight, so you can always see which deck you’re in.

Right-click a box or deck row for Duplicate and Delete. A delete doesn’t ask first: a message names what went, and what went with it, and its Undo puts it all back. To reorder boxes, decks or hands, drag them on the project’s page, the box’s Decks page or its Hands page. Toggle the pane with View ▸ Show Navigator (Cmd+1).

Beside the toggle in the top bar sit a quiet ← → pair, Back and Forward through the documents you’ve visited, each greyed when there’s nowhere to go. They’re what rescues you after a jump (a Find hit, Go to definition, a warning click), and they’re on View ▸ Back / Forward (Ctrl+Cmd+← / Ctrl+Cmd+→; Alt+← / Alt+→ on Windows and Linux). The arrows retrace your steps. The chevrons and Up a Level move up and down the structure.

The centre is where everything is edited. There’s no inspector pane. A container’s document lists its children, and a card’s document holds everything the card owns.

Every page opens with two things above its tabs. The first is the way back: a button naming the level above (‹ Decks on a deck, ‹ Gareth’s Debt on a card), which Esc also takes. When you arrived from somewhere else, such as a map or a hand, a second button (↩ Map) takes you back there. View ▸ Up a Level (Cmd+[) goes up one level. Page-level controls, like the card/table/node switch and the card stepper, sit to the right.

The second is the identity heading, which holds the item’s type, its title, its gameId as a chip (worked out from the title until it’s first published, and shown faded until then; after that it’s pinned), and its purpose. An overflow menu beside the type holds Delete.

Each kind of document has a fixed set of tabs:

Document Tabs
Box Map (when the box uses the project map), Contents, Dealing, Card template, Hand templates, Tags, Properties
Deck Cards, Dealing, Properties
Card Dealing, Outcomes, Fields
Hand Cards, Dealing, Slots, Properties
Hand template Dealing, Bindings, Properties

Dealing always holds how the thing gets dealt. A tab shows a count where one makes sense (a 0 included, so a dimmed tab reads as empty rather than disabled), and a tab with nothing in it stays clickable, with the explanation inside.

Your tab choice follows you between pages of the same kind. Pick Outcomes on one card and the next card you open (from the navigator, a link, a coverage row) opens on Outcomes too.

Two words are kept apart. Fields means card fields, declared by the box’s card template and filled in on each card. Properties means the state declarations of a scope (@box, @deck, @hand).

Everywhere a condition is edited, the label is When, with a hint saying whose condition it is. On a card it reads “the condition to be dealt”, on a deck “the condition for any card in this deck”, and on an outcome “the condition for this outcome to be offered”.

Conditions and outcome changes are edited with a guided expression editor rather than free text, so the property names on offer are the ones your project declares.

Validation runs as you edit. When the project is clean there’s no bar at all, only a tick in the top bar.

When something is wrong, a one-line bar appears along the bottom, with the count and one problem at a time, named the way you think of it (“Burner Rig › Continue”, never a file path). The arrows step through, each step moving the view with it, and clicking the problem lands inside the thing itself. A problem about an outcome opens its card with that outcome expanded. Errors and warnings are told apart by colour, and a quick fix rides on the bar when one exists.

Coverage is a bigger job than validation, so it runs on demand (Review ▸ Coverage Test…) instead of live.

Edit ▸ Find… (Cmd+F) opens a small, pinnable Find window that floats over the editor. Type to filter every navigable thing in the project (the field’s placeholder says “Decks, cards, hands, tags…”). Picking a hit moves the editor underneath while the window stays put, so you can step through hits without losing your place. Esc closes it.

The window has four tabs across its top bar: Find, Replace, Property, and Field.

Replace (Edit ▸ Replace…, Cmd+Alt+F, or Ctrl+H on Windows and Linux) finds and replaces text across the whole project. That covers the titles and purposes of every box, deck, card, outcome, hand, hand template, and tag group, the project’s name, and the text fields on cards. Type what to find and what to replace it with, and the list previews every match as before → after, with where it lives. Replace all rewrites them all at once, and the message it shows has Undo; the Replace button on a row does just that one. It never touches conditions, changes, gameIds, or ids, and a replace is one step in Undo. If the card you’re editing is one of the matches, it shows the new text as soon as the replace lands.

Property (Review ▸ Find Property Usage…) answers “where is @x used?”. Type a property (@gold, @story.act, @world.time_of_day; a bare name matches it in any scope) and the list shows every place it’s read (a card’s condition, a deck’s gate, a hand’s condition, an outcome’s condition) and every place it’s written (an outcome’s change), each row saying reads or writes and naming the outcome that writes. Pick a row to go there. The Coverage window’s “gated on @x” links open this tab on that property.

Field (Review ▸ Find by Field…) answers “which cards have mood = tense?”. Type a field to list everything that has it, with its value, or add = value or != value to narrow the list. It covers the card template’s fields on cards, the outcome fields on outcomes, and an extension’s fields, written extension.field (probe.note). A value matches by the field’s type: text and choices ignore case, flags match when the flag is set, numbers compare as numbers, and a yes/no field takes true or false. A card that leaves a field alone holds its default, so mood = calm finds it too, and its row says default. Patterpad’s Find has the same tab for game data, and reads a query the same way.

Every key below is collected, along with the canvas and tool-window keys the menus can’t show, on Keyboard shortcuts.

Menu Items
Storyletter (macOS only) About Storyletter, User Information…
File New Project… (Cmd+N), Open Project… (Cmd+O), Open Storyletpack…, Open Recent, Close Project, Save (Cmd+S), Export as Storyletpack…, Merge Returned Storyletpack…, Resolve Clashes… (while a merge has left clashes), Connect to a Server…, New Card (Shift+Cmd+N), Project Settings… (Cmd+,), Share Scopes with Other Tools…, User Information… (Windows and Linux), Exit (Windows) or Quit (Linux)
Edit Undo (Cmd+Z), Redo (Shift+Cmd+Z), Cut, Copy, Paste, Select All, Duplicate (Cmd+D), Show Scene in Patterpad (when the project is paired with Patter), Find… (Cmd+F), Replace… (Cmd+Alt+F; Ctrl+H on Windows and Linux)
Play Play on the Board (Cmd+P), Live Link
Review Review Feedback (Shift+Cmd+R), Next Feedback (F8), Previous Feedback (Shift+F8), Coverage Test… (Shift+Cmd+C), Links…, Find Property Usage…, Find by Field…, Show Resolved Comments
Publish Publish Playable HTML…, Publish Spreadsheet…, Publish Bundle (Shift+Cmd+B), Auto Rebuild
View Command Palette… (Cmd+K), Project Overview, Up a Level (Cmd+[), Back, Forward, Show Navigator (Cmd+1), Reset View, Coverage Overlay, Colour Theme, Actual Size, Zoom In, Zoom Out, Toggle Full Screen (Windows and Linux; macOS adds its own)
Window the platform’s own window items
Help Open an Example ▸ (The Hamlet…, The Village…, Port Meridian…, The Hamlet (Patter Version)…), Storyletter Documentation, Storylet Studio Documentation Home, Check for Updates…, About Storyletter (Windows and Linux)

A few of these deserve a note. Undo and Redo reverse any edit to any kind of item, through the same version-control path a save takes, not just the text field you’re in. Each names the step it takes, such as Undo Rename deck. Connect to a Server… asks for an address and a code.

Publish Playable HTML… writes one self-contained .html file that plays the project in any browser, with no engine, server, or install. It’s the Board, with the player’s place saved in that browser, and it has a section of its own. Publish Spreadsheet… writes the whole project as an Excel workbook, one sheet per deck plus Outcomes, Hands, and Tag groups, for a review meeting or a producer’s filter. See a spreadsheet of the whole project. Auto Rebuild is off by default. Turn it on and the bundle re-exports a moment after your edits settle, so the .storyletsc on disk never goes stale.

Project Overview opens the project’s own page, and clicking the project name in the top bar does the same. Coverage Overlay tints the node canvas and the map by how much play reached each card or hand in your last coverage run (see Coverage testing). A ▶ Play button in the top bar opens the Board, the same as Cmd+P.

Live Link starts a loopback link to a running game. Saving pushes the fresh bundle into the game, and the game streams its run back for the Board to watch. A connect chip in the bottom-right corner shows the state (the menu item just toggles the same thing). See Live Link.

File ▸ Project Settings… (Cmd+,) opens a dialog with four sections.

  • General holds the project’s name and version, the Play setting (below), and one warning switch. Warn about unread state also flags state an outcome writes that no condition reads. It’s off by default, because cards are often written ahead of the content that will read them; a gate on state nothing writes always warns, whatever this says. It also holds Patter project, the Patter project this one is paired with (see Working with Patter).
  • Version control is the system the project is kept in: Git, Perforce, Plastic SCM, Subversion (SVN), or None. Storyletter checks a file out before writing where the system locks files, and writes straight away where it merges. Switching systems rewrites the project’s vcs-setup.md and ignore rules, in one step you can undo. A project made before the setting shows Not set, and Storyletter finds its system from the folders above it (see Version control).
  • Game scopes holds your game’s own state: @world first, then any other scope the game provides, such as @player, and the game values for coverage that stand in for them during a test run. + Add scope adds one; give it a name, and declare its properties, or turn on Any name, unchecked when the game decides what it holds. Read-only to the story on a scope makes every property in it one the story can read but not set. Renaming a scope carries the new name into every card and driver that uses it, so @player.hp becomes @hero.hp, in one step you can undo. @world is always there and can’t be renamed or removed. Where the game shares its scopes (below), these are the game’s: saving writes them to game-scopes/game.scopes.json first, leaving every other scope in that file as it was, and then copies them into the project.
  • Publish holds the bundle path (by default a storylet-dist/ folder beside the project, never inside it), whether metadata is full or stripped, Include the maps (whether the zone shapes and pictures ship with the bundle, for a game that draws its own map), and how many turns a play advances.

Sharing scopes with the game’s other tools

Section titled “Sharing scopes with the game’s other tools”

File ▸ Share Scopes with Other Tools… makes a game-scopes/ folder, the one place a game’s editing tools read each other’s properties from (see Running it with Patter). It asks where, starting at the root of your repository, and writes two files there: storylets.scopes.json with your @story declarations, and game.scopes.json with your @world. The project keeps its own copy of @world. If the folder is somewhere the tools wouldn’t find it by looking up from the project, the project file records where it is.

From then on, every save brings storylets.scopes.json up to date, the Game scopes settings edit game.scopes.json, the condition and outcome editors offer the other tools’ properties (with who declares each in the pill’s tip), and the Board plays cards that name them.

Most games are one player at a time, and most of the app should say so. Play is one setting with two rungs, and the second shows everything the first shows.

Play For What it adds
Solo one player, one playthrough nothing extra, this is the plain editor
Shared world several players over one world Shared on declarations and decks, a line on every property saying who shares its value, and the Shared choice and In the world on cards

Hidden means absent, not greyed out. A solo project has no Shared checkbox to read past. Nothing about the compiled bundle changes (both rungs run on the same engine), so this is only about what you’re shown. Nothing else is governed by it. A timed box and a hole filled from a property are engine features, and every project has them.

A project can also arrive carrying a third rung, set for it by the server it came from. The editor honours that rung, shows it in the field, and lets you move down from it; it isn’t one you can pick.

Moving down is refused while the project uses what the rung would hide, and the dialog says what is in the way (“3 declarations are shared”). Take those out first, or leave Play where it is. A shard hand-edited above its rung is a validation warning naming the rung, so the file and the setting can’t quietly disagree.

Every property list in the app is the same control, and the editor for a value follows its type. Boolean and enum values are pickers rather than free text.

(The @story properties aren’t in this dialog. They live behind the navigator’s Story row, as a document of their own.)

There are four palettes under View ▸ Colour Theme, plus Follow System. Chambray (light) and Indigo (dark) are the defaults, in blue-grey. Linen and Baize are their green-tinted predecessors, kept for anyone who prefers them. Follow System switches between Chambray and Indigo with your OS. Every window and dialog follows the theme, including the Board, Find, and Coverage, and switching between same-lightness palettes never recolours your tags, decks, or canvas furniture. Those colours are your content’s, not the theme’s.

Review ▸ Links… opens a lens on the card you have open. What can turn it on or off sits to the left, and what it turns on or off to the right, across every deck and box. It follows the editor, so it can sit open beside you. The Links window has the detail.

Open source under the MIT licence, made by .