Flows

A flow is a saved chain on the StageHand dashboard: something happens in Discord, StageHand checks it if you ask, then it runs the steps you wired. Open stagehand.quest/dashboard, pick your server, and open Flow Builder under Server Setup. Turn the flow on. A flow that is off does not run.

How a flow is wired

Each flow has one trigger. That is the start. Filters on the trigger itself decide whether this run happens at all: which forum, which command name, which role was added, and so on.

From a step, drag a wire to the next step.

Several wires leaving one step all run.
When two wires later meet on the same step, that step runs once.
A check has two outs. The green side is yes. The red side is no. Leave a side unwired when you do not need it.
Wait for button click, Pick muses in thread, and Pick muses with server tag pause until someone answers. The flow continues from there, including after a restart.
Wait (delay) pauses this branch. Up to an hour stays in the moment. Longer waits finish the first hour, then resume the next step when the time is up.

Text on a later step can use values from earlier steps. Type the token, or insert it from the variables list on that field. A token is empty until the step that creates it has run.

Variables that travel

These are the tokens most chains use. A later message, thread title, tag name, or claim field can include them.

Token

What it is

{user}

The person who started this run. {member} is the same.

{command_args}

The text after a custom command.

{user_input}

What someone typed in a modal on an earlier Wait for button click.

{selected_muses}

Names chosen in a muse menu, joined the way that menu is set.

{selected_muse_owners}

Mentions of the people who own those muses.

{selected_muse_key}

The stable id of the first muse picked. Use this when a claim should belong to that muse.

{selected_muse_keys}

Every picked muse id, separated by |.

{selected_muse_household}

One muse’s id, or a shared id when more than one muse was picked. Use this when a household shares a claim.

{choice}

The button or menu option someone picked on Wait for button click.

{number}

The latest number Generate number rolled.

{phone}

The latest phone number from that step. A custom save name on the step, such as cell, is also {cell}.

{street}

A line drawn by Draw from list when that step’s save name is street. The default save name is {draw}.

{claim_value}

The thing just saved, found, or released.

{claim_label}

The name stored with that claim.

{claim_state}

How the claim step ended. See Claims.

{claim_count}

How many rows were in a posted list.

{claim_list}

The directory text from Post claim list.

Other tokens appear when that kind of trigger is upstream: thread link and name, scene name and date, channel name, challenge winner and {winner_key}, checklist title and task label. The variables list on a field shows what this step can already see.

Example chains

Roll a phone and keep it on a muse. Custom server slash command → Pick muses with server tag (one muse) → Generate number. Pattern (###) ###-####, skip prefixes 555, skip numbers already claimed, Save on a subject with pool phone and Belongs to {selected_muse_key}. The next message can say {selected_muses} — {phone}. The same muse gets the same number the next time.

Give a thing from the command text. Custom command → Pick muses with server tag (one muse) → Assign claim. Pool item (or apartment, callsign, locker). Belongs to {selected_muse_key}. Value {command_args}. Someone runs the command with the thing after the name, picks the muse, and that muse keeps it. Use {user_input} instead when a Wait for button click modal collected the text.

Post a living phone book. Custom command or Lore panel button → Post claim list. Title Phone book, pool phone, delivery set to a channel. That message stays up. Later assigns and releases edit it. Right-click the message and choose Refresh to rebuild it. Turn on Post as an embed and set a sidebar color when the phone book should be an embed. Refresh keeps that embed. A private reply is a one-time copy and stays plain text.

Give a household a street address. See Street address. You can wire it yourself or import the example.

Link a muse to a thread. See Link a muse to a thread. Run that command inside the muse’s thread. Reputation is not required.

A claim does not have to be the last step. Leave the claim step’s delivery on “leave it for a later message,” then Rename thread or Create forum thread with {selected_muses} · {claim_value} in the title. Send channel message can post {claim_label} — {claim_value}. Add / remove forum thread tags can use {claim_value} when that text is a tag name on the forum.

Import an example

In Flow Builder, Import sits next to New. Choose a flow file. It is the same kind of file you get when you right-click a flow and choose Export to file. The flow appears in the list. Save it, then turn it on.

Give a household a street address uses the custom command address. Link a muse to this thread uses linkthread. Those names have to be on under Custom slash commands, the same as any other custom command on this page.

Street address

This chain gives one muse, or a pair, a street address and can post that address into each muse’s thread.

Custom server slash command, named address.
Pick muses with server tag. One muse, or two who share a home.
Wait for button click, shown as a menu. Each option is a neighborhood, such as Old Market and The Docks. Wire each option to its own next step.
Draw from list on each of those wires. Old Market has its own lines, such as Willow Lane and Baker Street. The Docks has its own, such as Harbor Road and Net Alley. Save as street on every one of those steps, so the next step can use {street}. The lines stay on the step. The same line can be drawn again. The neighborhood nobody picked does not run, and its list is not used.
Both draws meet on one Generate number. Roll a number and leave Save on a subject off, so {number} is ready and nothing is stored yet.
Assign claim. Pool address. Value {number} {street}. Household, belongs to {selected_muse_household}. One claim for the pair. Either muse can look it up or give it back. Post claim list shows both names on that one row.
On that assign step, turn on Post to the muse’s thread and set the message to Address: {claim_value}.

When two wires meet on the number and the claim, those steps run once. Only the chosen neighborhood’s list is drawn.

Link a muse to a thread

Link muse thread remembers the thread you run the command in. It does not need reputation. Reputation still supplies a thread later if you already link muses that way and this step was never used.

Import Link a muse to this thread, or wire it: custom command linkthread → Pick muses with server tag (one muse) → Link muse thread. Run it inside the muse’s thread, then pick the muse. The reply includes the muse’s name. A normal channel does not save a link. The reply asks you to run it inside the muse’s thread.

One muse is linked per run. Choose Every selected muse only when a household should share that same thread. Remove the link on the same step clears it. Unlink does not need to be a second flow.

Claims

A claim is one saved thing in a pool, on a subject.

Pool is the kind of thing. Each server has its own pools. The name is a short word you choose: phone, apartment, item, locker, callsign, or another name made of letters, numbers, hyphens, and underscores. phone and apartment do not share values. Generate number, Assign claim, Release claim, Look up claim, and Post claim list all use the same pools.
Subject is who it belongs to. After a muse menu, that is {selected_muse_key} (the first muse). Household uses {selected_muse_household} so the muses that were picked share one row. Either name can look it up or give it back, and the directory shows both names on that one row. After Challenge recorded, {winner_key} is that muse’s id, so a prize or a locker can be saved on the winner. One subject holds one value in a pool.
Value is the thing: a rolled number, {command_args}, {user_input}, or words you type.

The first assignment sticks. The next time that subject is saved in the same pool, they keep what they already have. The same value cannot be given to someone else in that pool. For numbers, (555) 010-1212 and 5550101212 count as the same value. To give a muse something new, Release claim first.

Generate number rolls a number or a phone. In a phone pattern, # is one random digit and the other characters stay, so (555) ###-#### keeps the area code. Skip prefixes such as 555, 000, or 911 keeps the roll from starting with those digits. Skip numbers already claimed in this pool will not roll a taken number. Save on a subject stores the roll in the pool.

Assign claim stores a specific value you already have. If that exact value belongs to someone else, it stays with them. Household stores one shared value for the muses that were picked. Lookup and release work from either muse. The directory shows one row, with both names.

Draw from list picks one random line from a list you type on that step. One line per row. Blank rows are skipped. The lines stay on the step, and the same line can be drawn again. Save as street makes {street} available on the next step. Leave it as draw to use {draw}. Give the list a short name, such as old-market. A draw on a branch that did not run is not used.

Post to the muse’s thread is a checkbox on Assign claim, and on Generate number when Save on a subject is on. Any pool can use it. The message can be Address: {claim_value} or Phone: {claim_value}. Leave the message blank for a simple line with the saved value. {claim_value}, {claim_label}, {selected_muses}, {number}, {street} (or whatever you saved the draw as), and the household name all work in that line.

The claim is saved first. StageHand then looks for a thread in this order: the thread from Link muse thread, then the muse’s reputation thread if you already use reputation. It posts that line there. The next time this pool posts in that same thread, it edits the message instead of adding another. A household posts the same line once in each muse’s thread. A muse with no thread is skipped. Releasing the claim takes that line down, so the old address or phone does not stay in the thread. Clearing a household whose owners have all left does the same.

If nobody is linked, the claim still saves and nothing is posted. The reply names the muse and says the message was not posted. It tells you to run the link-thread command inside their thread, or link them in reputation. One muse with a thread and one without still updates the linked thread, and the reply names only the muse who had none.

Look up claim finds one row. Search by muse name, part of a name, the muse id, or the value. One match fills {claim_label} and {claim_value}. Several matches list the names and ask for a closer search.

Release claim frees a row so the subject and the value can be used again. Name the muse and leave the value blank to release whatever they have. Leave the muse blank and set the value to free that exact thing. Fill both to release only when that muse has that thing.

Post claim list posts the pool, sorted by name. A channel post is living: a new claim or a release edits that message, and a long list continues in the following messages. {claim_count} is how many rows were posted. Turn on Post as an embed to put the directory title and the claim lines in an embed with a sidebar color. Each continued page uses that same color. Refresh and later claim changes keep the embed. A private reply does not stay in sync and stays plain text.

/ifttt purge-claims is for people with Manage Server. It lists claims whose muse owner is no longer in the server. Leave the pool empty to check every pool, or name one pool. Turn confirm on to release those claims. A claim stays when StageHand cannot tell who owns it. A household stays while any owner is still in the server, and it is cleared when every owner has left. Clearing it also removes the line that was posted in those muses’ threads.

{claim_state} on the next step is a short word for how the claim step ended:

Word

Meaning

new

Saved for the first time.

kept

This subject already had a value. That value was kept.

taken

This value already belongs to someone else.

full

No free number was left with those exclusions.

found

Lookup matched one row.

empty

Nothing matched, or the pool had nothing to release or list.

released

The claim was cleared.

ambiguous

Lookup matched more than one name.

listed

A directory was posted.

The claim step can show a different reply for those cases (already has one, already assigned, nothing matched). The wires after that step still run. There is no check yet that sends the green wire one way and the red wire another based on {claim_state}. Put the word in a message if you want people to see it.

Triggers

The trigger is the start. It does not run the actions by itself. Wire the next step from it.

Panels

Lore panel button — Runs when someone presses a lore panel button set to this flow. The person who clicks is {user}. The panel’s channel or thread is where later steps post. On the panel, set the button action to Flow and pick this flow.

Members

Member joined — Runs once when someone joins. Later steps can give roles, send a DM, or open a ticket for that person.
Member left — Runs when someone leaves. Their roles at leave time are still available to Member has role(s).
Role added to member — Runs when roles are added. Leave every role unchecked to run on any add, or pick roles and choose whether any one of them or all of them must be in the update.
Role removed from member — The same idea when roles are removed.

MIA & hiatus

Marked MIA (inactive list) — Runs when the daily inactive check adds someone.
Cleared MIA — Runs when someone leaves that list.
Hiatus started — Runs when a hiatus becomes live, on the start date. A future-dated hiatus waits for the nightly check.
Hiatus ended (inactive) — Runs when a dated hiatus passes its end date on the nightly check.

Channels & forums

Forum thread created — Runs when a new forum post is created. Optionally limit it to one forum. The new thread is the place later steps use. Pair it with Thread is under this forum when one flow should split two forums.
Channel or category created — Runs when a channel or category is created. Context channel type can split text channels from forums.

Scenes

Scene opened — Runs after StageHand opens a scene: a new thread or a header in a persistent hub. The opener is {user}. Later messages can use {scene_name}, {scene_date}, {muse_names}, and {time_of_day}.
Scene closed — Runs after a scene is closed, including when a flow uses Close scene. The person who closed it is {user}.

Messages

Reaction added to a message — Runs when someone reacts. Set the channel and message, and optionally one emoji. The person who reacted is {user}.

Slash and prefix

Custom server slash command — Runs when someone uses your server’s custom slash command. The name has to match a subcommand under Custom slash commands on the Flow Builder page. The text they add is {command_args}.
Custom !command — Runs when someone types !name in chat. Trailing text is {command_args}. You can limit it to one channel.

Checklists

Checklist task added — Runs when an admin adds a task to a posted staff checklist. Later text can use {checklist_title} and {task_label}.
Checklist task completed — Runs when an admin marks a task complete. {completed_by} is who marked it.
Checklist fully completed — Runs when the last open task is completed and the checklist collapses to its finished message.

Games

Challenge recorded — Runs when a dice challenge result is saved. Later steps can use {winner}, {loser}, {winner_key}, and the owners’ mentions when those muses are linked in Reputation.
Challenge approved — Runs when staff approve a pending challenge. Challenge recorded follows it on the same approval.

Checks

A check does not change the server. It chooses the next wire.

Member has role(s) — Green when {user} has the roles you pick (any of them, or all of them). On a leave, the roles are the ones they had when they left. Put this in front of Assign claim or Add / remove roles when only some people should continue.
Member left (this run) — Green when this run started from Member left.
Thread is under this forum — Green when the thread in this run belongs to the forum you pick. Use it after Forum thread created or a scene trigger.
Context channel type — Green when the channel in this run is a text-style channel or a forum, whichever you pick. Use it after Channel or category created.

Actions

An action does the work, then the next wired step runs. Tokens it creates are available after it.

Member & roles

Add / remove roles — Adds and removes roles on {user} in one step. StageHand’s role has to sit above those roles.
DM member — Sends {user} a DM now, or queues the same text as a pending reminder. Earlier Wait steps add to that delay.

Messages & channels

Send channel message — Posts in the channel this run is using, or in a channel you pick. The text can include any token from earlier steps. It can post now or queue a reminder.
Generate number — Rolls a number or a phone and can save it on a subject. See Claims. With delivery left for a later message, {number} and {phone} are ready for the next step. Post to the muse’s thread is available when the roll is saved.
Draw from list — Picks one random line from a list you type on the step. The lines stay reusable. Save as street to use {street} later. See Street address.
Assign claim — Saves a specific value in a pool. Household shares one row across the muses that were picked. Post to the muse’s thread writes it into a linked thread and keeps that message up to date.
Link muse thread — Links the selected muse to the thread this command is run in. Run it inside that thread. Reputation is not required. Remove the link clears it. See Link a muse to a thread.
Release claim — Clears one saved value in a pool.
Look up claim — Finds one saved row and fills {claim_label} and {claim_value} for the next step.
Post claim list — Posts the pool as a directory. Post as an embed uses the directory title and a sidebar color. A channel post keeps that embed when the list changes.
Send static image (file on bot host) — Posts an image you have placed for StageHand to use, with an optional caption that can include {user}.

Timing & flow

Wait for button click — Posts a button or a menu and pauses until someone picks. One option uses the usual outgoing wire. Each extra option has its own wire, so a neighborhood can draw its own list before those wires meet again. After it, {choice} is the option they picked, {user_input} is the modal text, and {gate_clicked_by} is who clicked.
Wait (delay) — Pauses this branch, then continues to the next step.
Schedule reminder — Older way to ping a channel after a delay. For a new flow, use Wait plus Send channel message as a pending reminder.
Cancel reminder(s) — Cancels pending reminders that share the reminder key you set.

Channels & forums

Create forum thread — Opens a thread in a forum you pick. The title, first post, and tags can use tokens such as {selected_muses}, {claim_value}, and {user}. After it, {created_thread_link} and {created_thread_name} are available.
Add / remove forum thread tags — Adds tags, or replaces the thread’s tags with the names you list. A token such as {command_args} or {claim_value} works in the name list when that text matches a tag on the forum.
Pick muses in thread — Posts a menu of muses who have already posted in the thread through MultiMuse, and waits. Then {selected_muses} and {selected_muse_key} are available. Wire Rename thread after it to title the thread from the selection.
Pick muses with server tag — Posts a menu of public muses that carry this server’s MultiMuse tag, and waits until Continue. Lists longer than 25 use Previous and Next. Turn off Allow more than one muse when the next step should see a single {selected_muse_key}.
Rename thread — Sets the thread title from a template. Leave the thread id blank to use the thread this run is in. An archived thread is reopened so the title can change. {claim_value} and {selected_muses} work here.
Lock / unlock thread — Locks the thread so only people who can manage threads can send messages, or unlocks it.
Set thread slowmode — Sets the seconds between messages. 0 turns slowmode off.
Archive / unarchive thread — Archives the forum thread from this run, or a thread id you paste.
Add mailbox (index) — After Forum thread created, adds that thread to a mailbox index you already set up with /mailbox set channel. The thread title is the character name.

Scenes

Post scene setup button — Posts a button that opens the scene wizard for whoever clicks it.
Close scene — Ends the scene the way /scene end does, then Scene closed flows can run. Do not wire Close scene directly after Scene closed on the same flow unless you mean for it to loop.
Open scene in persistent hub — An older step. Use the Scene opened trigger for new flows.

Integrations

Run Rules & Watchers rule — Runs one rule you already saved under Rules & Watchers, with the same person in context.
Post dice preset buttons — Posts a dice preset into the thread or channel.
Post dice preset by forum tag — Reads the new thread’s tags and posts the matching preset. Put a Wait before it when the profile is more than one message.
Link reputation (pending) — Posts and pins a muse reputation card in the new forum thread. Put a Wait before it so a multi-post profile can finish.
Track birthday from profile — Reads a birthday from the MultiMuse card, then from the profile or form, and tracks it the same way /birthday does. Put a Wait before it on a new character thread.
Refresh forum index — Rebuilds the index for a forum. Wire it after new threads when the index should catch up.
Open support ticket — Opens a ticket for {user} from a ticket preset.

Checklists and tasks

Post staff checklist preset — Posts a staff checklist. Admins edit it in the channel. Completing the last task can start Checklist fully completed.
Post My list — Posts a member’s personal list (/task). The owner defaults to {user}.

World & display

Refresh info display — Renames your info-display voice channels now. Leave the slot blank to refresh every enabled slot.
Push next ticker line — Posts the next line from a ticker feed. Leave the feed blank for the main feed. Wire it after Scene closed when a scene should advance the feed.

Server

Create server emoji — Adds a custom emoji from emoji markup (<:name:id>) or a Discord emoji image link. {command_args} is the usual source. You and StageHand both need Manage Expressions.