What's New in Squiffy v6

Squiffy v6 is a major update, representing a complete rewrite of the codebase since v5 was released in 2015. This page covers what’s new for story authors, plus guidance for those upgrading from earlier versions.

For Story Authors

Breaking Change: Text Processor

The most significant change in v6 is the replacement of the text processor. Squiffy v5 used a custom syntax for dynamic text, which has been replaced by Handlebars.

If your v5 story used dynamic text features like {if}, {else}, or text replacement, you will need to update your syntax. See the Dynamic Text and Helpers Reference pages for the new syntax.

Basic stories that only use sections, passages, links, and simple attributes should work without changes.

An Installable, Offline Editor

The editor at app.squiffystory.com is a Progressive Web App (PWA). It works offline, and you can install it to your device so it opens in its own window like any other app - with nothing to download first.

For the best experience, use Chrome or Edge. These browsers support the File System Access API, which lets the editor save directly to files on your computer. You can grant permission for the editor to access a file, and then save using the File menu or Ctrl+S (Cmd+S on Mac).

Squiffy 6 doesn’t include a downloadable desktop app. One is planned for Squiffy 7, built from the same code as the web editor.

No More Account Required

The previous web-based editor required you to log in with a textadventures.co.uk account and synced your stories to the server. This is no longer the case - the new editor works entirely with files on your own computer.

Your work is stored locally in your browser, so if you accidentally close the tab or your browser crashes, you won’t lose unsaved changes. When you return to the editor, you can pick up where you left off.

Editor Features

• Responsive design - Works on mobile devices and tablets
• Offline support - Install as a PWA and work without an internet connection
• Live preview - See your changes as you type
• New export options - Download as a single self-contained HTML file, or a ZIP with separate files
• Back button - Step backwards through your story while testing, without having to restart

New Helpers

v6 introduces some new Handlebars helpers:

Live text

Use {{live}} to display an attribute that automatically updates when its value changes:

@set score = 0
You have {{live "score"}} points.

+++Get points
@inc score 10
You found 10 points.

When the player clicks “Get points”, the score shown in the first paragraph updates in place.

Setting attributes in conditions

You can now modify attributes directly within {{#if}} blocks using {{set}}, {{inc}}, and {{dec}} - reducing the need to write JavaScript for conditional logic:

{{#if score > 100}}
    {{set "rank" "expert"}}
    You've reached expert level!
{{/if}}

See the Dynamic Text and Helpers Reference pages for more details.

Animation Effects

Text can now appear with animations using the {{#animate}} helper:

• typewriter - Text appears character by character
• toast - Text slides in from the bottom
• fadeIn - Text fades in smoothly
• continue - Clickable link that pauses the animation queue

Example:

{{#animate "typewriter"}}This text appears letter by letter.{{/animate}}

You can define custom animations using JavaScript in a @ui section. See the animate example for details.

Player Input

Players can enter text using HTML input elements with the data-attribute attribute:

What is your name?
<input type="text" data-attribute="name" placeholder="Enter your name...">

+++Continue...

Hello, {{name}}!

You can also use <textarea> for longer text, or any element with contenteditable="true".

Input Validation

Input fields support HTML5 validation attributes. Links are automatically disabled until all inputs in the current section are valid.

<input type="text" data-attribute="name" required minlength="2">

+++Continue...

Available validation attributes include:

• required - Field must not be empty
• minlength / maxlength - Minimum/maximum text length
• pattern - Regular expression pattern to match
• min / max - Minimum/maximum values for number inputs
• type="email" / type="url" - Built-in format validation

Single-File Export

You can now export your story as a single self-contained HTML file. This is ideal for:

• Easy sharing (just send one file)
• Platforms that only accept a single HTML file
• Offline distribution
• Email attachments

Use the “Export HTML (single file)” option in the editor’s File menu, or use --inline with the CLI:

npx @textadventures/squiffy-cli mygame.squiffy --inline

---

For Developers

The entire codebase has been rewritten in TypeScript. This provides full type safety, better IDE support and autocompletion, and improved maintainability.

Squiffy is now organized as a monorepo with separate npm packages:

Package	npm Name	Purpose
compiler	squiffy-compiler	Converts .squiffy files to JavaScript
runtime	squiffy-runtime	Browser library that runs compiled stories
packager	@textadventures/squiffy-packager	Bundles compiler output + runtime into deployable files
cli	@textadventures/squiffy-cli	Command-line interface

All packages use ES modules (import/export) instead of CommonJS (require).

---

Upgrading from v5

For Story Authors

Basic stories using sections, passages, links, and simple attributes should work without changes.

If your story uses dynamic text features, you’ll need to update to the new Handlebars syntax. Squiffy can do most of this for you:

• Editor: when you open a story that uses Squiffy 5 syntax in the editor at app.squiffystory.com, it offers to convert it. Review the changes afterwards, and use Undo if you want to go back.
• CLI: run with --convert-v5 to convert the file, keeping a backup of the original. See Converting from Squiffy 5.

Anything that can’t be converted reliably, such as an {else:...} that doesn’t directly follow an {if ...:...}, is left as it is and listed with its line number. Squiffy 6 also shows a warning when it compiles a story that still contains Squiffy 5 syntax.

The key differences:

v5 Syntax	v6 Syntax
{attribute}	{{attribute}}
{if gender=male:You are male.}	{{#if gender = "male"}}You are male.{{/if}}
{if score>100:High score!}	{{#if score > 100}}High score!{{/if}}
{if condition:text}{else:other text}	{{#if condition}}text{{else}}other text{{/if}}
{@b+=1}	{{inc "b"}}
{@b=5}	{{set "b" 5}}
{if seen intro:...}	{{#if (seen "intro")}}...{{/if}}
{passage name} (embedding)	{{embed "passage name"}}
{rotate size:small:large}	{{rotate (array "small" "large") set="size"}}
{label:1=text}	{{#label "1"}}text{{/label}}

To test your story:

1. Open your story in the new editor at app.squiffystory.com
2. Use “Open” to load your .squiffy file
3. Run it to verify everything works
4. Convert or update any dynamic text syntax as needed
5. Export using your preferred format

If you encounter any issues, please report them on GitHub.

For CLI Users

The npm package name has changed. Use npx to run the CLI:

# v5
squiffy mygame.squiffy

# v6
npx @textadventures/squiffy-cli mygame.squiffy

CLI options remain similar, with some additions:

Option	Description
-s, --serve	Start HTTP server after compiling
-p, --port	Port for HTTP server (default: 8282)
--scriptonly [filename]	Only generate JavaScript file
--zip	Create zip file
--inline	New: Create single self-contained HTML file
--convert-v5	New: Convert Squiffy 5 text processor syntax to Squiffy 6

---

Getting Help

• Documentation: Browse the other pages in this documentation
• GitHub Issues: Report bugs or request features
• GitHub Discussions: Ask questions and share ideas
• Discord: Join the community
• IntFiction Forum: Discuss at intfiction.org (use the squiffy tag)