Player Action Commands Documentation

Overview

The player action system provides a structured workflow for players to submit night actions (or any game action) to moderators, with a two-party confirmation handshake before actions are logged.

Two commands drive this system:

/playeraction - Used by players to submit their action for the current round
/modaction - Used by moderators to review, manage, and execute player actions

Prerequisites

Before either command can be used, the following must be in place:

The game must be set up (via the game setup flow)
The player action system must be enabled in the game's game-info configuration (gameActions.enabled: true)
The game must be marked as ready (gameReady: true)
Each player must be registered in game-info.playerInfo
A game log channel must exist (created automatically if not present)

Moderators must hold the configured moderator role. Players must be registered participants in the active game.

`/playeraction` Command

Submits a player's action to the moderator queue.

Required Arguments

┌───────────────────┬────────┬─────────────────────────────────────────────────────┐
│ Argument          │ Type   │ Description                                         │
├───────────────────┼────────┼─────────────────────────────────────────────────────┤
│ playeractionstring│ String │ The player's action text (free-form description)    │
└───────────────────┴────────┴─────────────────────────────────────────────────────┘

What Happens

The bot validates the player is registered in the game
Any previous pending action for this player is cleaned up (old game log and player channel messages are deleted)
An action request is posted to the game log channel for moderators to review
An informational embed is posted to the player's current channel showing their submitted action

Examples

/playeraction playeractionstring:I want to investigate Alice tonight

/playeraction playeractionstring:I use my ability on Bob to protect him

Note: Players can re-submit a new action at any time before a mod confirms it. The previous action and its messages are automatically cleaned up.

Note: If a player already has a fully confirmed action (in a previous category), re-submitting will note the previous action in the game log so moderators are aware.

`/modaction` Command

Provides moderator tools for managing the player action queue.

Required Arguments

┌─────────────────┬────────┬─────────────────────────────────────────────────────┐
│ Argument        │ Type   │ Description                                         │
├─────────────────┼────────┼─────────────────────────────────────────────────────┤
│ modactionoptions│ Choice │ The action to perform (LIST, PING, EXECUTE, REPOST) │
└─────────────────┴────────┴─────────────────────────────────────────────────────┘

Action Options

┌─────────┬────────────────────────────────────────────────────────────────────┐
│ Option  │ Description                                                        │
├─────────┼────────────────────────────────────────────────────────────────────┤
│ LIST    │ Display all confirmed player actions, grouped by priority          │
│ PING    │ Ping players who have not yet submitted or confirmed their action  │
│ EXECUTE │ Post confirmed actions to the game log and clear the action queue  │
│ REPOST  │ Delete and recreate all category threads in the game log channel   │
└─────────┴────────────────────────────────────────────────────────────────────┘

Examples

/modaction modactionoptions:LIST
/modaction modactionoptions:PING
/modaction modactionoptions:EXECUTE
/modaction modactionoptions:REPOST

The Confirmation Handshake

The core of the player action system is a two-party handshake between moderators and players. An action is not finalized until both a moderator and the player have confirmed it.

Flow Diagram

Player submits /playeraction
        │
        ▼
Game log channel receives action request message
  (with classification dropdowns if configured,
   Accept/Deny buttons)
        │
        ▼
Player's channel receives informational embed
  (shows submitted action, no buttons yet)
        │
        ▼
Moderator reviews in game log channel ─────────────────────────┐
        │                                                      │
  [Classification required?]                              Mod clicks Deny
        │                                                      │
   Yes ─┤                                              Action cleared,
        │                                              denial sent to
   Mod selects Priority dropdown                       player's channel
   Mod selects Category dropdown                               │
        │                                              Notified in game log
   No ──┤                                                      │
        │                                                     End
        ▼
  Mod clicks Accept/Confirm
        │
        ▼
Game log message deleted
Player's channel message updated:
  "Action Approved by Moderator" embed
  + [Confirm] [Deny] buttons
Player is pinged to confirm
        │
        ▼
Player reviews in their channel ───────────────────────────────┐
        │                                               Player/Mod clicks Deny
        ▼                                                      │
  Player clicks Confirm                                 Action cleared,
        │                                               denial sent to both
        ▼                                               channels
Action stored in categoryGameActions                           │
Category thread updated in game log                           End
Count message updated
"Action Fully Confirmed" embed sent to player
Mods notified with link to category thread

Step-by-Step Detail

Step 1 — Player submits action

The player runs /playeraction with their action text. The bot:

Posts an action request to the game log channel, mentioning the mod role
If classification is configured (both priorities and categories are defined), the game log message includes dropdown menus for selecting priority and category, plus Accept and Deny buttons
If no classification is configured, the game log message shows Confirm and Deny buttons directly
Posts an informational "⚔️ Player Action Request" embed to the player's channel (no buttons at this stage)

Step 2 — Moderator reviews

A moderator sees the action request in the game log channel:

With classification enabled:
- Select a priority from the Priority dropdown
- Select a category from the Category dropdown
- Click Accept (the button validates that both selections have been made)
Without classification:
- Click Confirm directly

If only one priority or one category is configured, it is auto-assigned and the corresponding dropdown is omitted.

Step 3 — Awaiting player confirmation

After mod approval:

The game log message is deleted
The player's channel message is replaced with a new "✅ Action Approved by Moderator" embed showing the action text and its assigned category
Confirm and Deny buttons are added to the player's channel message
The player is pinged to confirm

Step 4 — Player confirms

The player clicks Confirm in their channel:

The action is stored in categoryGameActions under the assigned category
The player's channel embed message is deleted
A "✅ Action Fully Confirmed" embed is sent to the player's channel, showing the action text and category
If a category thread exists in the game log channel, the player's embed in that thread is updated to show the confirmed action with Reclassify and Remove buttons for mods
The category's count message is updated (e.g. "3/8 player actions submitted")
A temporary ping is sent to the mod role in the game log channel with a link to the category thread

Denial Behavior

Either party can click Deny at any point during the handshake.

In all cases, the player's action state is fully cleared (category message IDs are preserved for thread continuity).

Classification System

Priorities

A configured, ordered list of priority labels (e.g. ["High", "Medium", "Low"]). Priorities determine the order in which actions are processed when EXECUTE is run. Actions within the same priority are further ordered by submission time (or randomly, at mod's choice).

When Classification is Active

Classification dropdowns appear in the game log message when both priorities and categories are configured with at least one value each. If only priorities or only categories are defined (but not both), classification is skipped and the action goes directly to the player confirmation step.

Category Threads

When categories are configured, the game log channel maintains one thread per category. Each thread contains:

One embed per alive player (showing either "No Action" or their confirmed action with priority)
A count message at the bottom (e.g. 3/8 player actions submitted)

Player embeds in a category thread are updated in place as actions are confirmed or removed.

After confirmation, each player embed in a category thread includes two moderator buttons:

[📝 Reclassify]  [🗑️ Remove]

Reclassify — Opens classification dropdowns to reassign the action's priority and/or category
Remove — Clears the player's confirmed action from this category and resets their thread embed to "No Action"

`LIST` Option

Displays all confirmed player actions grouped by priority.

With categories configured: Shows a category selection UI first. Select a category to view its actions.

Without categories: Lists all actions directly.

Output Format

📋 Actions: [Category]
Category: Kill | Summary: 5 submitted, 3 pending

⚡ High
✅ Alice
└─ I want to kill Bob

⚡ Medium
✅ Carol
└─ I want to kill Dave

❌ No Action Submitted
Eve, Frank, Grace

Players are sorted by priority (in the configured priority order), then by submission timestamp within each priority group.

`PING` Option

Sends a reminder message to each alive player who has not yet fully submitted an action for the selected category.

With categories configured: Shows a category selection UI with a dropdown and a Ping button. Select the category, then click Ping.

Without categories: Pings all players without any confirmed action.

Ping Message Types

Players receive different reminder messages depending on their current action state:

No action submitted — "You have not submitted an action yet. Please submit your action!" Action submitted, awaiting mod review — "Your action is pending moderator review. Mod approved, awaiting player confirmation — "Please confirm your game action.

Ping Shortcut Buttons

Ping reminder embeds include action shortcut buttons:

No action yet: A 📝 Submit Action button — clicking opens a text modal for the player to type and submit their action directly without using /playeraction
Awaiting player confirmation: ✅ Confirm Now and 📝 Change Action buttons — allowing the player to confirm or replace their action from the reminder embed

`EXECUTE` Option

Posts all confirmed actions for a selected category to the game log channel, then clears those actions from the queue.

With categories configured: Shows a UI to select:

Category Queue — Which category to execute
Execution Order — Random or Submission Order

Without categories: Executes all confirmed actions in random order by default.

Execution Order

Within each priority group, actions are ordered by:

Random Order — Actions are shuffled randomly before being listed
Submission Order — Actions are listed earliest-submitted first

Output Format

The execution results are posted directly to the game log channel as embeds:

⚔️ Executed: Kill
Category: Kill | Actions: 5
Actions executed by priority, in random order within each priority level.

⚡ High
1. Alice
└─ I want to kill Bob

2. Carol
└─ I want to kill Dave

⚡ Medium
3. Eve
└─ I want to kill Frank

After Execution

The executed category's actions are cleared from all players' categoryGameActions
The category thread is reset: all player embeds are updated to "No Action"
The category count message is reset to 0/N player actions submitted
Players' in-progress action state is cleared for that category

`REPOST` Option

Completely regenerates all category threads in the game log channel. Use this to recover from thread corruption or to reset the thread view mid-game.

What REPOST Does

Deletes all active and archived threads in the game log channel
Clears all stored thread IDs and count message IDs from the game configuration
Creates fresh threads for each configured category
Posts one embed per alive player in each thread, reflecting their current confirmed/unconfirmed state
Posts a count message at the bottom of each thread

⚠️ Warning: REPOST deletes all threads in the game log channel, including any threads not created by this bot. Use only when needed.

Note: REPOST does not affect existing confirmed actions — it only rebuilds the visual thread display.

Full Example Walkthrough

Setup

Game configured with:

Categories: ["Kill", "Protect"]
Priorities: ["High", "Medium", "Low"]

Night Phase

1. Player Alice submits her action:

/playeraction playeractionstring:I want to investigate Bob

Bot posts to game log:

@Moderators ⚔️ Player Action Request from Alice (#alice-channel)
> I want to investigate Bob

[Select Priority ▼]  [Select Action Category ▼]
[Accept]  [Deny]

Bot posts to Alice's channel:

⚔️ Player Action Request
Player: @Alice
Action: I want to investigate Bob

2. Moderator classifies and accepts:

Mod selects High from Priority dropdown, Kill from Category dropdown, then clicks Accept.

Game log message is deleted.

Alice's channel message is replaced:

✅ Action Approved by Moderator
Please provide a final confirmation for your action.

Action: I want to investigate Bob
📂 Action Category: Kill

[Alice - Confirm]  [Deny]

Alice is pinged: "@Alice Please provide a final confirmation for your action."

3. Alice confirms:

Alice clicks Confirm.

Alice's channel shows:

✅ Action Fully Confirmed
Your action has been confirmed by both you and a moderator.

Action: I want to investigate Bob
📂 Action Category: Kill

Kill category thread in the game log is updated:

Alice's embed: ✅ confirmed — "I want to investigate Bob" (Priority: High)
Count message: 1/8 player actions submitted

Mod role is pinged: "@Moderators ✅ Alice's action confirmed → #kill"

4. Moderator checks status:

/modaction modactionoptions:LIST

Returns a list of all submitted actions grouped by priority for the selected category.

5. Moderator pings players who haven't submitted:

/modaction modactionoptions:PING

Category selection UI appears. Mod selects Kill, clicks Ping.

Each alive player without a confirmed Kill action receives a reminder in their channel.

6. Moderator executes at end of night:

/modaction modactionoptions:EXECUTE

Category selection UI appears. Mod selects Kill, selects Random Order, clicks Execute.

Execution results are posted to the game log. Kill actions are cleared from the queue and the Kill thread is reset to "No Action" for all players.

Location Tracking

Location tracking is a second, independent system that shares the game log channel and /modaction with player actions. It can be on while the action system is off. Locations are plain strings a moderator defines on the game setup page (Track player locations in the 🎯 Player Action System section); the first location is the default and every player starts there. Each location has a Travel flag: when unticked, players cannot pick it as a destination, but moderators can still place players there.

Discord roles for locations (optional)

Tick Show locations as Discord roles under the location list at game setup to make whereabouts public. The bot creates one role per location on the game server, named 📍 <location> (hoisted so the member list groups players by place, and mentionable so players at a place can ping each other), and keeps every player — alive or dead — on the role of their current location. Accepted travel, dashboard moves (notified or silent), list edits, swaps and death all keep the roles in step; REPOST re-syncs them if they drift.

Before the game starts, the setup page checks the would-be role names against the server's existing roles and refuses to start while any 📍 <location> name is already taken (rename the location or untick the option). The bot never moves roles in the hierarchy, so a player who also holds a higher hoisted role is listed under that role instead. The roles are deleted by /cleanupgame, and when tracking is turned off from the dashboard.

The `📍 Locations` thread

One thread in the game log channel, mirroring the category threads:

One embed per alive player, edited in place. The title is the player's current location (📍 Forest, or 📍 Crypt 🔒 when closed for travel) and a Travel line shows their current request state.
A summary message at the bottom: player counts per location, and while a travel round is open, answered/prompted with how many requests await a moderator.

REPOST rebuilds it along with the category threads. Death removes a player's embed and cancels their pending request; resurrection re-adds the embed where they fell. /swapplayer redraws the embed under the new name.

`/travel` (players)

Replies ephemerally with a dropdown of open destinations other than where the player stands. Picking one sends a Travel Request to the game log for a moderator to Accept or Deny, and posts a status embed in the player's channel that is updated with the outcome. The dropdown stays attached to that status message until a moderator decides, so a player can change their mind.

/travel

Preconditions: location tracking on, game ready, the caller is an alive registered player, and at least one other location is open.

`/modaction TRAVEL` (moderators)

Pushes the dropdown to every alive player with a channel, plus a 🏠 Stay at <current> option that needs no approval. A confirm step shows who will be prompted and the open destinations:

Prompt all starts a new round. Pending requests from the previous round are cancelled (their log messages are edited to say so) before the new prompts go out.
Prompt unanswered (shown while a round is open) re-asks only players who have not answered, were denied, or had a request cancelled.

The travel handshake

Player picks a destination (dropdown from /travel or TRAVEL)
        │
        ▼
Game log: 🧭 Travel Request from Alice — Town Square → Forest   [Accept] [Deny]
Player's channel: ⏳ Travel request sent — waiting for a moderator (dropdown still attached)
        │
        ├── Accept ──► Alice is moved; log line edited to "✅ Accepted by @Mod";
        │              player's channel: "✅ Travel accepted — you are now at Forest"
        │
        └── Deny ────► log line edited to "❌ Denied by @Mod";
                       player's channel: "❌ Travel denied — you remain at Town Square"
                       with the dropdown re-offered

There is no final player confirmation: a dropdown pick is already unambiguous. Every request posts exactly one game log message, and a decision only counts if that message is still the player's current request. If the player re-picks while a moderator is clicking, the click on the old message is refused with "This request was replaced or already resolved." and nothing changes.

Request states you may see in the thread:

State	Meaning
⏳ Awaiting an answer	prompted, no pick yet
⏳ Requested: X	waiting for a moderator
✅ Request accepted	granted; the player moved
❌ Denied	refused; the dropdown was re-offered
🏠 Staying	the player chose to stay
⤫ superseded	a moderator moved the player while the request was pending
⤫ cancelled	the destination was removed or closed, a new round started, the player died, or tracking was turned off

Note: Moderator moves from the dashboard are silent by default; travel acceptances, denials and cancellations always tell the player.

Tips

Classification is optional — If priorities and categories are not configured, the handshake skips directly from mod confirmation to player confirmation without dropdowns
Players can change actions freely — Until a moderator has confirmed an action, the player can re-run /playeraction to replace it
PING is category-aware — Players who have a confirmed action in one category but not another will only be pinged for the category they're missing
EXECUTE clears only the selected category — Running EXECUTE for Kill does not clear Protect actions
REPOST is a recovery tool — Only use it when threads are broken or out of sync; it does not affect confirmed action data

Player Action Commands Documentation

Overview

Prerequisites

/playeraction Command

Required Arguments

What Happens

Examples

/modaction Command

Required Arguments

Action Options

Examples

The Confirmation Handshake

Flow Diagram

Step-by-Step Detail

Denial Behavior

Classification System

Priorities

Categories

When Classification is Active

Category Threads

LIST Option

Output Format

PING Option

Ping Message Types

Ping Shortcut Buttons

EXECUTE Option

Execution Order

Output Format

After Execution

REPOST Option

What REPOST Does

Full Example Walkthrough

Setup

Night Phase

Location Tracking

Discord roles for locations (optional)

The 📍 Locations thread

/travel (players)

/modaction TRAVEL (moderators)

The travel handshake

Tips

`/playeraction` Command

`/modaction` Command

`LIST` Option

`PING` Option

`EXECUTE` Option

`REPOST` Option

The `📍 Locations` thread

`/travel` (players)

`/modaction TRAVEL` (moderators)