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

The first time you launch, Storyletter asks once for your name. 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 three worked examples. The Hamlet is small, with places, hands, and a deck to deal. The Village is the full demo. Port Meridian is the engine beside an action game. 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

File ▸ New Project… (Cmd+N / Ctrl+N) asks for a name, then where to put the folder. A new project isn’t empty. It lands one box, one place to deal to, and two cards that already work together, so it plays straight away. Add kits to it 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

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

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 gameId
storyletter my-game.storylets --at c_arrive             # anything, by its id
storyletter my-game.storylets --at "The Inn"            # anything, by its title
storyletter --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)

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.

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

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 maps carries them 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. 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

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, copies, 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

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

Two things you might go looking for aren’t there yet.

There’s no merge conflict view. Conflicts land as a .storyletconflict sidecar and validate refuses to ignore them, but reading one and picking sides is a command-line and text-editor job today.

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

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.

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

• The workspace: the navigator, the document and its tabs, the problems bar, Find, the menus and the themes.
• Designing cards: the deck, the card document, 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 starting a box from a kit.
• Maps: draw a tag group as zones and pin hands inside them.
• 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.
• 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.