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:

1. The game must be set up (via the game setup flow)
2. The player action system must be enabled in the game's game-info configuration (gameActions.enabled: true)
3. The game must be marked as ready (gameReady: true)
4. Each player must be registered in game-info.playerInfo
5. 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

1. The bot validates the player is registered in the game
2. Any previous pending action for this player is cleaned up (old game log and player channel messages are deleted)
3. An action request is posted to the game log channel for moderators to review
4. 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).

Categories

A list of action types (e.g. ["Kill", "Investigate", "Protect"]). Each category has its own thread in the game log channel. An action can only belong to one category.

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:

1. Category Queue — Which category to execute
2. 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

1. Deletes all active and archived threads in the game log channel
2. Clears all stored thread IDs and count message IDs from the game configuration
3. Creates fresh threads for each configured category
4. Posts one embed per alive player in each thread, reflecting their current confirmed/unconfirmed state
5. 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.

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