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 navigator
Section titled “The navigator”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 boxThe 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.)
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 document
Section titled “The document”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).
Conditions
Section titled “Conditions”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.
The problems bar
Section titled “The problems bar”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.
The menus
Section titled “The menus”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.
Project settings
Section titled “Project settings”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.mdand 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:
@worldfirst, 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.hpbecomes@hero.hp, in one step you can undo.@worldis always there and can’t be renamed or removed. Where the game shares its scopes (below), these are the game’s: saving writes them togame-scopes/game.scopes.jsonfirst, 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 isfullorstripped, 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.
Play: how much of the app you see
Section titled “Play: how much of the app you see”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.)
Themes
Section titled “Themes”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 Ian Thomas.