Storyletter
You design a Storylet Studio project in Storyletter, card by card and deck by deck. You set up the box the cards live in and declare the hands your game will deal. The real runtime, the same one your game ships with, runs inside the editor, so “would this card come up here?” is always one keystroke away, and “why did Arrive at the Village Gate get dealt?” has a line-by-line answer.
Storyletter runs on macOS, Windows, and Linux. Get it from the Download page.
This section is a full tour of the editor. If you only read one other page, make it Designing cards.
First run
Section titled “First run”The first time you launch, Storyletter asks once for your name, filled in with the
user.name git has for you, if it has one. That’s all. Your name signs your review
comments, and you can skip the prompt. Change it at any time from
User Information… (in the Storyletter app menu on macOS, or the File menu on Windows
and Linux).
From there you land on the welcome screen. Open a project… opens one you already have, and New project… makes one. Under Start from a kit are the game kits you can start a project from, and under Learn from a finished project are the four worked examples. The Hamlet is small, with a map, hands, and a deck to deal. The Village is the full demo. Port Meridian is the engine beside an action game. The Hamlet (Patter Version) is the Hamlet with a Patter scene for each card, its Patter project copied beside it. Click any of them to see what it holds and what pressing Play shows, before anything is made. A kit asks for a name; an example is copied somewhere you choose, so you can take it apart. Your Recent projects are listed too, and Help ▸ Open an Example reaches the examples from inside a project.
The example project is the quickest way to learn the model. Open it, press ▶ Play, and watch it deal.
Creating a project
Section titled “Creating a project”File ▸ New Project… (Cmd+N / Ctrl+N) opens the New project picker. Under
Start from a kit, pick Starter project, Starter project with Patter, Map-based
story or Action game, give it a Project name, choose its Version control (None
until you pick one), and choose where to put the folder.
The Starter project isn’t empty: it has one box, one hand to deal to, and two cards that
already work together, so it plays straight away. Under Learn from a finished project,
Open a Copy copies one of the examples instead. Add box kits to a project as you go (see
Setting up a box).
A Storylet Studio project is a real folder of files (see the format).
Keep it in whatever version control you use for your game, alongside your game files. You
won’t ship the project itself, only the .storyletsc bundle it publishes.
Opening a project
Section titled “Opening a project”Open Project… (Cmd+O), click a recent project on the welcome screen, or use
File ▸ Open Recent. Recent projects are listed by the name they call themselves,
with the folder path beside it. Double-click a .storylets folder, or run
storyletter <path> from a shell, and it opens where you left off.
Opening at a particular item
Section titled “Opening at a particular item”Launching from a shell, --at opens the project straight at an item instead of
where you left off:
storyletter my-game.storylets --at arrive-at-the-gate # a card, by its gameIdstoryletter my-game.storylets --at c_arrive # anything, by its idstoryletter my-game.storylets --at "The Inn" # anything, by its titlestoryletter --at arrive-at-the-gate # no path: reopen the last project there--at=<where> works too. <where> takes the same query as
storyletengine resolve. It tries an exact gameId first, then an id,
then a title, then a partial match. So a gameId copied out of your game code or a
runtime log pastes in and lands on the card it names, which is the quickest way to
answer “a tester reported a problem with this card”.
It can name a box, a deck, a card, a hand, a hand template, or a tag group, and opens that item’s document. An outcome opens its card with that outcome expanded. If nothing in the project matches, Storyletter prints that on the terminal and opens the project as it normally would, so a stale id in a bug report can’t stop you getting in. If Storyletter is already running, the same command jumps the open window rather than starting a second copy.
storyletter here’s the app’s own executable. On macOS that’s
Storyletter.app/Contents/MacOS/Storyletter, on Windows Storyletter.exe in the
install folder, and on Linux the AppImage.
Sending a project (Storyletpack)
Section titled “Sending a project (Storyletpack)”A project folder is perfect for version control but awkward to email or drop in a chat. A Storyletpack is the project squeezed into one file you can hand to someone.
- File ▸ Export as Storyletpack… writes the pack.
- File ▸ Open Storyletpack… unpacks one into a fresh project folder and opens it.
- File ▸ Merge Returned Storyletpack… takes a pack someone sends back and folds their edits into your project.
Where the game shares its scopes, the
pack carries a copy of them, so the person you send it to gets the other tools’ properties in
their pickers and on their Board. When it comes back, their copy is ignored, except that World
properties they changed are written to your game.scopes.json too. The merge’s confirmation
says so before anything is written.
See the send envelope for what travels and what doesn’t.
Resolving clashes
Section titled “Resolving clashes”Most of a merge combines on its own: different cards, or different fields of the same card, all survive. Where you and the other person changed the same thing differently, the merge keeps your side and records the clash in the file. A pull from a server does the same. Until each clash is settled, the project won’t validate, and a bar across the top of the window says how many there are.
Click Resolve… on that bar, or choose File ▸ Resolve Clashes…, to go through them. Each clash says where it is in words (“Card ‘Tavern Brawl’ in Opening deck: priority”, “@story.trust’s default”), what kind of clash it is, and both sides. For each one, choose:
- Keep mine keeps what’s there now, your side.
- Take theirs writes their side in its place.
- Edit takes you to the card, deck, box or setting, so you can combine the two by hand. Open the resolver again and that clash offers Mark resolved, which keeps what you’ve written.
A clash that isn’t a single value, such as a structural one, offers Keep mine and Edit only.
Every decision is one step you can undo. When a file’s last clash is settled, the
.storyletconflict record the merge left beside it goes too.
Publishing
Section titled “Publishing”Everything under the Publish menu turns your project into something you hand to others.
Publish Bundle (Shift+Cmd+B) is the everyday one. It compiles the .storyletsc your
game loads, to the path in your project settings. The first time a card, deck, hand or box goes
out, it also pins its gameId, so retitling it afterwards can’t change the name your game calls
(Auto Rebuild and Live Link don’t pin anything). The other two are for people, a page anyone
can play and a workbook anyone can read.
A playable page: one file, plays anywhere
Section titled “A playable page: one file, plays anywhere”You don’t need a game, an engine, or a programmer to put your project in front of people.
Publish ▸ Publish Playable HTML… writes a single .html file containing the whole
project and the same engine a shipped game would use. It needs nothing else, no internet,
no install, and no server. Anyone you give it to double-clicks it and plays, on a laptop or
a phone. It asks where to save, suggesting <project name>.html beside the project folder.
The page is the Board, the same one in the editor and in every runtime’s demo. Each hand is a labelled group of cards, clicking a card shows its outcomes, and clicking an outcome plays it and the board moves. There are three controls, Deal all hands, Next turn, and Restart, and a transcript of what happened. Titles and purposes always show (the page is for people), and the player’s place is saved in that browser, so closing the tab isn’t losing the game. Restart clears it.
A project with a map carries it into the page, pictures included, and the map takes the left of the screen with the cards in a column beside it, the same arrangement as the Board’s Map view. The map is drawn once, with the hands of every box on it. Zones are tinted, every placed hand is a pin wearing its live card count, and you can zoom with the wheel or the buttons and drag to pan. Tap a pin and the column jumps to that hand’s cards. On a phone the map sits on top with the cards below. The pictures ride inside the file as data. The Village and its five paintings publish to a single 5MB page that still opens from disk with no internet. A multi-box project gets a heading per box, so you can watch one box’s play light another box’s pin.
There are three ways to get it to people.
- Email it, drop it in a shared folder, or attach it to a message. It’s one file.
- Put it on itch.io. Name the file
index.html, zip it, and upload the zip as an HTML game. - Host it anywhere that serves files. Upload the file and share the link.
The same page from the command line is storyletengine export-html.
A spreadsheet of the whole project
Section titled “A spreadsheet of the whole project”Publish ▸ Publish Spreadsheet… writes the project as an Excel workbook (.xlsx), the
thing a lead reads in a review meeting and a producer sorts and filters. It asks where to
save, suggesting <project name>.xlsx beside the project folder.
One sheet per deck, a row per card: title, gameId, When, priority, redraw, weight, in one hand, across hands (each as the card deals with it, Card template defaults included), a column per tag group, a column per card field, purpose, and the outcomes with their changes. After the decks come an Outcomes sheet (one row per outcome), Hands (template, When, tags, slots), and Tag groups (every tag with its properties), with an Overview sheet in front carrying the project’s name, version, content hash, and counts. It’s read from the files, so any unsaved edit is saved first.
The same workbook from the command line is
storyletengine export-xlsx.
The same engine as your game
Section titled “The same engine as your game”Every operation Storyletter performs is the same one the CLI makes: load, validate, export, deal, coverage, merge. A CI gate and a designer’s Save see the same project, and what plays in the editor plays in your build.
Your edits are written straight back to the project files, in a fixed layout, with your version control’s locks respected. There’s no private database, and editing a file by hand in a text editor is a supported way to work.
The link runs both ways when you want it to. With Live Link connected, saving pushes the fresh bundle into your running game, and the game streams its run back so the Board watches what it deals and plays.
Not yet in the editor
Section titled “Not yet in the editor”One thing you might go looking for isn’t there yet.
There’s no writing status. Comments and the review walk exist, but there’s no per-card “draft / needs review / final” state to filter or report on.
Updates
Section titled “Updates”Storyletter keeps itself up to date. Help ▸ Check for Updates… looks for a new version, downloads it in the background, and asks to relaunch, saving your work first. It also checks by itself shortly after it starts. An update it finds that way downloads quietly and puts Restart to update in the top bar: click it to relaunch, saving your work first, or carry on and it installs when you quit.
On a Mac, a small helper installs the update once Storyletter has closed. The first time that happens, macOS may show a notice that Storyletter is running in the background. Nothing of Storyletter keeps running. The helper replaces the app and quits within a few seconds, and only runs when an update is waiting.
The helper is listed under System Settings ▸ General ▸ Login Items & Extensions, in Allow in the Background. If you switch it off, updates can’t install when you quit, and you’ll need to fetch new versions from the download page instead.
Where to go next
Section titled “Where to go next”- The workspace: the navigator, the document and its tabs, the problems bar, Find, the menus and the themes.
- Designing cards: the deck, Group by, the card document, where a card comes up, conditions, priority, tags and outcomes.
- The node canvas: a deck’s cards as nodes, with the arrows worked out for you.
- Setting up a box: the card template, hand templates, tags, hands and what can come up at each, and starting a box from a kit.
- The project map: draw the project’s zones once, put boxes on the map, and see what can come up at each hand.
- The Board: play the project on the real runtime, and see why a card was or wasn’t dealt.
- Working with Patter: pair the project with the Patter project that holds its dialogue, and let Storyletter check each card against its scene.
- The Links window: one card’s neighbours across the project, what can turn it on or off and what it turns on or off.
- Reviewing: comments on any item, markers on a canvas, and the walk through open feedback.
- Keyboard shortcuts: the full reference.
- Coverage testing: the coverage window is in the editor too, and it’s documented with the rest of the production workflow.
Open source under the MIT licence, made by Ian Thomas.