User guide

Getting started

Open tailstock.achery.dev and sign in with an Achery account — the same one you use for other Achery apps, or a new one.

The first time you use Tailstock in a browser or on a phone, it asks whether you'd like to share usage and crash reports. Either answer is fine — see Privacy.

Then create a project. A project is one game.

Finding your way around

Inside a project, the pages are grouped into:

  • World — a list for each kind of thing in your game (Locations, NPCs, Factions, Items, Conversations, Scenes, Quests, Recipes, Bestiary, Encounters, and any types of your own), plus World setup
  • Rules — Flags, Player model, Enemy stats, Named conditions and Custom events
  • Playback — Play
  • Insights — Dashboard and Lint

On the web they're in the sidebar; in the app, on the project's screen.

To jump to anything in a project by name, press ⌘K (or Ctrl+K) on the web, or tap the search button in the app. Search finds every entity by name or alias, every rule definition by label or key, and every page. It doesn't search inside descriptions or dialogue.

A first loop

A good first hour: add a stat and a flag, make a place and a character who lives there, write them a short conversation with one choice that needs the stat and one that sets the flag — then play it and watch the flag change. That's most of Tailstock in miniature.


Projects

The projects page lists your projects, most recently changed first. Opening one makes it your current project on that device.

Each project has a name, a description and an accent colour, which tints the app while you're working in it.

Duplicating a project makes a copy with one of two options:

  • Setup only — the rules and structure (player model, flags, custom events, custom fields and types, your lists, the enemy stat schema and lint settings), without any content. Handy for starting a new game with an old one's rules.
  • Everything — all of it, images included.

Deleting a project moves it to Trash, where you can restore it for 30 days. After that it's permanently deleted, images and all. Delete permanently… in the trash deletes it for good straight away.

Export

On the web, a project's page has Export: Download export saves the project as your game reads it — a zip of project.json (one versioned JSON file: your definitions, every entity, conversation, scene and quest, and their text) and its images. Notes, presets, playthroughs and lint settings stay out.

New token… makes a token the Godot addon can pull the export with. It's shown once, so copy it then; Revoke… stops one working at once. The app lists your tokens and can revoke them too.

Once something has been exported, game code may refer to it by name: its slug no longer changes when you rename it, and changing a slug or a key by hand asks first.

The Godot addon

The Export card has Download the Godot addon. Unzip it into your Godot 4 project, turn it on under Project Settings › Plugins, then paste an export token and the export URL into its Tailstock dock and press Pull: the latest export lands in your project.

In your game, the Tailstock singleton plays conversations and scenes exactly as playback does — the same rules, the same dice for the same seed — and tells your game what to show: lines, choices, directions, rolls, your custom events and quest changes. Your game decides how they look; the addon draws nothing. It reads and sets state by key, saves and restores the whole game, and comes with an example dialogue box to start from. Its README has the details.

Backups

On the web, Download backup on a project's page saves the whole project — content, notes, definitions, lists, images, presets, playthroughs, lint settings and dismissals, map pins and its history — as one zip file. A project in the trash can be backed up too, from the Trash list.

Restore from backup… on the projects page brings a backup back as a project, exactly as it was, with the same IDs — so saves and exports made from it keep working. Because of that, a backup can't be restored while its project still exists (even in the trash): delete the project permanently first. Backups made by a newer version of Tailstock can't be restored until this one catches up; older ones are brought up to date as they're restored. A backup file can be up to 500 MB.


The world

Everything you write about — places, characters, factions, items, and the conversations, scenes, quests, recipes and bestiary entries described later — is an entity, and they all share the same basics:

  • a name, and aliases (other names it goes by — search and @ mentions find these too)
  • a slug, a code-friendly name made from the name, which follows renames until you set it yourself
  • a status: stub, draft or complete — new things start as stubs
  • tags, shared across the whole project
  • a description (the content) and notes (for you)

Every list can be searched, filtered by status, tag or custom field, and sorted.

Locations

Places nest inside places to any depth: a tavern in a town in a region. Browse them as a tree; move one by dragging it on the web or choosing a new parent in the app. A location's page lists the NPCs, conversations, scenes and encounters there — optionally including everything in the places inside it.

NPCs

Characters have a primary location and any number of secondary ones, a role, and memberships of factions with an optional rank.

Give an NPC a portrait for each mood — neutral, happy, angry and so on — and a default for any mood they don't have. Dialogue lines pick a mood, and the right portrait shows beside them.

Mark an NPC as a companion to let them join the party. A companion can carry their own stats, skills and attributes.

An NPC's page lists their conversations, the scenes they're in, and the lines they speak elsewhere.

Factions

Each faction has a colour, a list of ranks, and the player's reputation with it: a number with bounds and a starting value. Reputation reads through named tiers — Hated, Hostile, Neutral, Friendly, Revered, or your own — so logic can say "reputation with the Guild is at least Friendly". Factions can also record how they feel about each other, as lore.

Items

Items have a category and are stackable or not, with an optional maximum stack. The party shares one inventory; each item starts at a count you set. An item's page shows every effect that gives or takes it, every condition that checks it, the recipes that make and use it, and the enemies that drop it.

Your own types and fields

Open World setup to shape a project to its game:

  • Custom types — new kinds of entity, such as spells, deities or historical events. They get their own list, can nest if you like, and can be mentioned with @ like anything else.

  • Custom fields — typed facts per entity type: text, rich text, whole or decimal numbers, yes/no, a choice from a list, or a link to other entities. Required fields must be filled before something can be marked complete. Number, yes/no and choice fields can be read by your game logic.

  • Lists — the options Tailstock offers elsewhere: flag categories, NPC roles, moods, reputation tiers, image kinds, item categories, travel methods and voices. New projects start with sensible defaults.

Images

Any entity can hold a gallery of images, each with a kind and an optional caption. Each kind draws as pixel art — kept crisp at the largest whole-number scale that fits, never smoothed — or smooth, for concept art and references.

Upload PNG, GIF, WebP or JPEG images up to 20 MB each: on the web by picking, dragging or pasting; in the app from your photo library or camera.

Declare an image a sprite sheet by giving its frame size and count, then name animations with a frame range and speed to preview them. A sheet shows its chosen frame wherever a single picture is needed, such as a portrait or thumbnail. Images can also go inline in any rich-text field.

Mentions

Type @ in any rich-text field — descriptions, notes, dialogue, scene beats, journal text — to mention an entity. A mention links to the thing, not the spelling: rename the character and every mention shows the new name. Mention someone by an alias and it shows that alias. Each entity's page lists everything that mentions it.


Rules

Keys

Everything your game logic can read or change has a key — a lower-case name like met_mira or gold. Keys share one namespace across flags, stats, skills, attributes, reputations, item counts and quests, so no two can clash. Renaming a key never breaks anything that uses it.

Player model

The Player model describes what a player character has:

  • stats — numbers, with optional bounds and a default
  • skills — ranks from 0 up to a maximum
  • attributes — options such as a class (one at a time) or traits (any number)

Flags

Flags are your world's variables: story progress, choices made, counters, remembered text. A flag is true/false, a whole number (with optional bounds — values are kept inside them), one of a list of options, or text.

A flag can be global, or held per entity: one met flag gives every NPC their own value, instead of a hundred hand-made met_ flags. You can override the default for particular entities.

A flag's page shows every effect that sets it and every condition that checks it. You can also create a flag on the spot while building a condition or effect.

Tailstock also tracks some state for you, which logic can read but you can't set: how many times each conversation has started, each dialogue node been visited, each choice been picked and each scene played, and where the player is.

Named conditions

Write a condition once, give it a name — "Can afford the ferry" — and use it anywhere. Change it, and every use changes.

Custom events

Custom events are how Tailstock talks about things only your game knows — play a sound, shake the camera, open a shop. Declare an event with typed parameters; effects and scene cues fire it, and playback lists it as it happens.

Enemy stats

The bestiary has its own stat schema, separate from the player's: declare stats like hp or armour here and give every enemy a value.


Conditions and effects

Conditions decide whether something can happen: whether a conversation starts, a choice shows, a scene plays or a quest moves on. Build one from menus out of tests — a flag's value, a stat, a skill, an attribute, reputation, an item count, a quest's progress, who's in the party, whether a recipe can be crafted, the built-in state, a named condition, a percentage chance or a dice roll — combined with and, or and not as deeply as you like.

Stat checks can name the protagonist, a particular companion, anyone in the party or everyone in it. A dice check rolls something like d20 plus modifiers against a target; it's rolled once each time the condition is checked.

Effects change things: set or adjust a flag, stat or reputation, give or take items, add or remove companions, move the player, start a conversation, scene or quest, advance a quest, craft a recipe, or fire a custom event. They run in order, and each can have its own condition.

Every condition and effect reads back as a single line — "met Mira AND persuasion ≥ 3", "give 2d6 gold" — and the builders only offer values that fit, so a broken one can't be saved.


Dialogue

Conversations

A conversation belongs to whatever the player interacts with to start it — an NPC, a location, an item — or to nothing. When several could start, they run in the priority order you set, and the first whose trigger conditions pass is the one that plays. A conversation that belongs to nothing starts only when something else starts it.

Anyone can speak in a conversation, not just its owner: any NPC, the player, the narrator, or a voice from your project's list.

What a conversation is made of

  • Lines — a speaker, their mood and what they say. A line can have variants that play in sequence, cycle, or shuffle, so a repeat visit doesn't hear the same thing. Write {gold} to show a value from the game's state.

  • Choice sets — the player's options. A choice can have a condition (and be hidden, or shown locked with an explanation, when it fails), be offered only once, run effects, and lead somewhere. If nothing can be picked, the set can fall back to somewhere else.

  • Checks — a choice can roll for success, with a different outcome for each, and show something like "[Persuasion 15]" in its label.

  • Branches — go one way or another depending on conditions, with no choice shown.

  • Jumps and calls — go to another part of the conversation or another conversation. A call comes back when the other conversation ends, so shared exchanges can be written once.

  • Ends.

The script view

The Script view shows a conversation as a screenplay, from the start: lines, then choices indented beneath them. Write and edit in place, insert anything after anything, and change every detail of a node from there. A part reached from more than one place appears once in full, and elsewhere as a link to it.

This is the whole dialogue editor in the app, and often the quicker one on the web.

The graph (web)

On the web, Open the graph to see the conversation as a canvas of cards and connections, with a minimap. Drag from a card to make the next one, drag connections to rewire them, and click a card to edit it in the side panel. Arrange lays out the whole graph or a selection. Copy and paste works between conversations, and undo and redo cover everything you've done since opening it.

Anything written in the app turns up in the graph, placed near where it belongs.


Scenes

Scenes are scripted sequences — intros, cutscenes, events — made of beats:

  • lines, like dialogue
  • directions — stage directions, in prose
  • effects
  • conversations, which play and then hand back to the scene
  • cues — your own custom events, for camera moves, sounds, fades and whatever else your game does

Any beat can have a condition. A scene set somewhere plays when the player arrives, if its trigger conditions pass — once only, unless you make it repeatable. Effects can also start a scene, either straight away or after whatever's playing finishes.


Quests

A quest has stages, each with journal text, objectives and effects that run on entering it. Objectives are required or optional, and complete through an effect or by themselves when a condition becomes true; they can show progress, like "wolf pelts 3 / 5".

When a stage's required objectives are done, the quest moves on to the first next stage whose condition passes — so a quest can branch and end more than one way, completing or failing.


Crafting

A recipe turns input items into outputs. Inputs are used up or kept as tools; outputs can have a chance; a recipe can need a condition and a station — a place or an item. An item's page shows a tree of everything needed to make it, down to base materials, and what it can be made into. Dialogue and scenes can craft with an effect, and a condition can ask whether a recipe can be crafted right now.


Bestiary and encounters

Bestiary entries have a value for each of your enemy stats, a list of abilities, and a loot table of items, chances and quantities. Encounters group enemies, with counts, a location and a condition for your game to check. Tailstock doesn't simulate combat — this is design data for your game's own systems.


Maps and travel

Any location can have a map of the places inside it, on a background image if you like. Place pins by dragging them on the web.

Connections join places, one way or both, with an optional cost (in a unit you choose, such as hours), a travel method and a condition — a locked gate, say. The route planner finds the cheapest way between two places, with or without conditions.


Playback

Play lets you play through your game's story without a game. Start from a conversation, a scene or a location — or press ▶ Play from here on any line in either dialogue editor.

  • World mode: starting from a location, you see where you are, who and what you can talk to, and where you can travel. Arriving somewhere plays its scenes.

  • Starting state: start from the defaults or a preset — saved values for the state you want to test from. Save as preset… keeps the current state for next time.

  • Inspector: every variable, the built-in state, the party, the inventory and every quest, live — and editable mid-play.

  • Show unavailable choices: see hidden choices with their condition, the part that failed highlighted.

  • Rolls: every roll is shown with its result. Redo as pass or Redo as fail to force the other outcome; set a seed to make rolls repeatable.

  • Transcript: every line, choice, roll, effect and event so far. Back to here rewinds to any earlier point.

  • Events: the custom events that have fired, with their values.

  • Saved playthroughs: Save playthrough… keeps it by name, to open on any device. If the project has changed since, Tailstock says what changed and carries on from the nearest point that still makes sense.


Lint

Lint checks the whole project for things that are probably mistakes: dialogue that goes nowhere or can't be reached, choices with no destination, calls that loop, broken mentions, flags that are set but never checked (or the reverse), conditions that can never pass, missing portraits, recipe loops, quest stages you can't reach, conversations and scenes nothing starts, and things marked complete with required fields empty.

Lint lists every finding by severity, rule and area, each linking to where it is, and the editors show markers too. A deliberate dead end isn't a bug: dismiss a finding with a reason and it stays hidden until that content changes. Each rule can be turned off or have its severity changed for the project.


Dashboard

The Dashboard shows how far along a project is: how many of each type are stubs, drafts and complete, and how that's changed over time; how big and deep each conversation is; how much each NPC has to say; how much each flag is used; lint counts; and how much time you've spent editing, by day, week and area. Everything links to the list behind it.


Deleting things safely

Tailstock won't let your game's logic point at nothing.

  • If something is used by logic or flow — a flag a condition checks, an item a recipe needs, a conversation a scene plays — it can't be deleted. Tailstock lists every place that uses it.
  • If it's only mentioned — in a description, a custom field, a cast list — Tailstock lists the mentions and asks first. Afterwards they show as broken, and lint reports them.
  • Deleting a dialogue node that others lead to asks first, and leaves those links unconnected for you to fix.

Web and iPhone

Tailstock works in any modern browser and in the iPhone app, with the same projects on both. The app does everything except:

  • the dialogue graph — use the script view, which edits everything
  • placing map pins — maps are viewable, and connections editable, in the app

Working on more than one device

Edit the same thing in two places and Tailstock won't silently overwrite either. If you save something that's changed elsewhere since you opened it, you'll see Changed on another device with both versions: Keep mine, or Use the other version. Coming back to a screen picks up changes from your other devices.

Offline

Tailstock needs a connection. Without one, it says so and stops new edits; anything you hadn't saved stays on screen and is saved when you're back online.


Settings

  • Appearance — Light, Dark, or follow the device. Saved per device.

  • Privacy › Share usage and crash data — see Privacy.

  • Account › Sign out

  • Delete account… — below Sign out

Deleting your account

Settings › Delete account… permanently deletes every project (including any in the trash), image and saved playthrough, then signs you out. It can't be undone. Your Achery sign-in isn't deleted, because other Achery apps use it; to delete that too, email [email protected], as Your Achery account explains.


Privacy

Your projects are private to your account; nobody else can open them. Tailstock doesn't store your name or email address.

Sharing usage and crash reports is up to you, per device or browser, and you can change your mind in Settings. Either way, what you write — names, text, keys, images — is never sent. The privacy policy has the details.


Getting help

See Support, or email [email protected].