DebateCraft Mafia Host Bot Guide

This guide covers the new dashboard-hosted Mafia system. It is ready for manual games and optional clock-assisted phase transitions. It does not yet resolve night actions automatically.

1. What the host bot handles

The system currently handles:

1. Game drafts, rosters, hosts, and co-hosts
2. Preset and custom role PMs
3. Cryptographically secure role randomization
4. Private role-PM delivery
5. Game-thread creation
6. Scheduled or immediate Day 1 starts
7. Player posting permissions
8. Vote tracking, thresholds, plurality, and ties
9. Day and Night transitions
10. Thread locking during Night
11. Player elimination and restoration
12. Player substitutions
13. Temporary or indefinite player muting
14. Pausing and resuming games
15. Winner announcements
16. Timed postgame discussion
17. Vote history and Day navigation
18. Host and administrator audit logs

It does not currently:

1. Accept private night actions through a dedicated action form
2. Understand or resolve Cop, Doctor, or Mafia actions
3. Determine night-action priority
4. Send investigation results automatically
5. Choose Mafia’s kill
6. Detect win conditions
7. Reveal roles automatically
8. End the game automatically
9. Trigger an immediate hammer when majority is reached

For manual games, players should send night actions privately to the main host. The host resolves those actions and enters the resulting eliminations and announcements through the dashboard.

Part I: Access and responsibilities

2. Getting permission to host

In order to access the mafia host dashboard you need to have permissions to do it. This is to prevent spam and abuse by potential bots. As such, if you want access to utilizing and testing this feature please DM an administrator and we can grant you access.

3. Host roles

Main host

The main host is the canonical game operator. They can:

1. Change the setup
2. Randomize and finalize assignments
3. Send role PMs
4. Launch the thread
5. Schedule Day 1
6. Advance phases
7. Resolve votes
8. Eliminate and restore players
9. Substitute or mute players
10. Pause, complete, or cancel the game

System-generated public posts and private role PMs are sent using the main host’s account.

Co-host

Co-hosts receive read-only dashboard access in the current manual-game release. They can review secret assignments and game state, but cannot change or send them.

Administrator

Administrators can normally inspect and recover hosted games. However, an administrator or moderator who is or was a participant in an unfinished game is blocked from its dashboard to prevent cheating. This includes eliminated and substituted players.

4. Opening the Host Dashboard

Go to:

Mafia → Resources → Host Dashboard

The dashboard is divided into:

1. Continue hosting: active responsibilities
2. Games you run: games where you are the main host
3. Games you co-host: read-only co-host assignments
4. Pregame drafts: games that have not launched
5. Game history: completed and cancelled games
6. Other hosts: administrator-only history grouped by main host

Active hosting responsibilities are placed ahead of historical games so they are easier to find.

Part II: Creating a game

5. Create a draft

Select New game draft.

Enter:

1. Game name
2. Main host username
3. Player usernames
4. Co-host usernames

Player and co-host usernames can be entered one per line or comma-separated.

The person creating the draft becomes the main host by default. An administrator can create a game for a different approved main host.

You may create an empty draft and add the roster later.

Select Create draft.

6. Understand the pregame workflow

The dashboard presents the launch sequence in this order:

1. Roster
2. Roles
3. Randomize
4. Finalize
5. Role PMs
6. Run game

Complete these in order. Later steps remain unavailable until their prerequisites are satisfied.

Part III: Roster and roles

7. Enter the roster

Under Roster and role set, enter one player username per line.

The displayed order becomes the stable slot order. Randomization changes which role occupies each slot; it does not unpredictably rearrange the underlying player records.

Make sure:

1. Every username is valid
2. The main host is not accidentally included as a player
3. Co-hosts are entered separately
4. No player appears twice
5. The final player count matches the total role quantity

8. Add preset roles

The initial proof-of-concept role library includes:

1. Vanilla Town
2. Town Cop
3. Town Doctor
4. Mafia Goon

Select Add preset role, choose the role, and set the number of players receiving it.

Preset descriptions can still be reviewed and edited before assignments are finalized.

9. Create a custom role

Select Create custom role PM.

Configure:

1. Role name
2. Alignment
3. Quantity
4. Known team, when applicable
5. Private role-PM body
6. Optional advanced voting rules

Alignment choices include:

1. Town
2. Mafia
3. Independent
4. Custom alignment

When using a custom alignment, enter the alignment’s public or internal name.

Known teams

Players with the same non-empty team key are treated as teammates. For example, every ordinary Mafia role might use the team key mafia.

Their teammates can then be included in the role PM.

Do not reuse a team key between unrelated groups.

10. Write the role PM

Supported placeholders include:

1. {player} — assigned player
2. {role} — assigned role
3. {teammates} — players sharing the role’s team key

The game name, role, alignment, and known team information are also included by the system.

Use the PM preview to verify the finished message. Secret role data must stay in the role-PM editor; do not paste it into the public opening-post editor.

Images are not yet supported as first-class PM attachments. Hosted images could be linked manually, but native private-message uploads remain future work.

11. Configure advanced voting rules

Each assigned role can change how its player interacts with voting.

Vote weight

Examples:

1. 0: vote does not add to a wagon
2. 1: ordinary voter
3. 2: double voter
4. Higher values: custom weighted voters

Lynch-threshold modifier

This changes the number of votes required to eliminate that specific player.

Examples:

1. +1: loved or popular player who requires one extra vote
2. -1: hated player who requires one fewer vote
3. 0: ordinary threshold

Visibility

Vote weight and threshold modifiers each have separate visibility settings:

1. Everyone
2. Assigned player and hosts
3. Hosts only

This allows the same mechanic to be public in one setup and hidden in another.

Host-only mechanics are deliberately omitted from generated player PMs and public game information.

Advanced modifiers can also be changed during a game when a role or event changes a player’s voting status.

12. Save the setup

Select Save setup.

The total role quantity must exactly equal the roster size before randomization is allowed.

Once assignments have been finalized and delivered, the setup becomes locked. This prevents the roster, role set, and private assignments from becoming competing sources of truth.

Part IV: Randomization and role PMs

13. Randomize assignments

Select Randomize assignments.

The system securely shuffles the configured role packages across roster slots. A package includes:

1. Role
2. Alignment
3. Team
4. Role-PM content
5. Vote weight
6. Threshold modifier
7. Visibility rules

These fields move together; alignment is not separately shuffled away from its role.

Review the secret assignment table carefully. Only authorized hosts and administrators who are not game participants can see it.

Current behavior allows rerandomization before finalization. Each reroll creates a new assignment version. A future release may make the first randomization permanent, but that restriction does not exist yet.

14. Finalize assignments

When satisfied, select Finalize assignments.

Finalization locks the assignment version. After this point:

1. The roster and role set cannot be reopened casually
2. Assignments cannot be rerolled
3. Role-PM delivery can begin
4. Substitutions must use the dedicated substitution workflow

Do not share or stream the dashboard while assignments are visible.

15. Send role PMs

Under Role PM delivery, select Send role PMs.

Each message is sent from the designated main host. Player replies therefore return to the main host’s private-message conversation.

Delivery statuses include:

1. Pending
2. Sent
3. Failed

The system assigns each recipient and assignment version a stable message identifier. Retrying a partially failed batch cannot intentionally create duplicate role PMs.

If some messages fail:

1. Read the recorded error.
2. Correct the account or permission problem.
3. Select Retry unsent role PMs.

Every role PM must be delivered successfully before the game can launch.

Part V: Launching the thread

16. Prepare the opening post

Under Launch game, enter:

1. Thread title
2. Opening post

The opening post supports rich-text formatting. Use it for:

1. Rules
2. Player list
3. Public setup information
4. Vote syntax
5. Phase lengths
6. Activity expectations
7. Replacement and moderation policies

Do not include secret assignments.

The dashboard creates one canonical game thread. Do not separately edit its host list, roster, or phase state through legacy thread-embedded controls.

17. Choose when Day 1 begins

You have two options.

Start Day 1 immediately

The bot:

1. Creates the thread
2. Posts the opening material
3. Opens Day 1
4. Allows eligible players to reply and vote
5. Starts the applicable deadline

Schedule Day 1

Choose an exact local date and time.

The bot creates the public thread immediately but keeps player replies and voting locked. At the scheduled time it:

1. Posts the Day 1 announcement
2. Opens player discussion
3. Activates the Day 1 deadline

Before the scheduled start, the dashboard provides:

1. Start Day 1 now
2. Change schedule
3. Day 1 deadline controls
4. Scheduled-start status and recovery information

Scheduling uses server-backed work, so closing the browser does not cancel it.

18. Choose a phase-control mode

Manual

Manual mode is recommended for manual games.

Deadlines can be displayed, but reaching one does not advance the game. The host must explicitly resolve the Day or begin the next Day.

Use Manual when:

1. Night actions are submitted privately
2. The host must calculate results
3. Flips require review
4. The next Day needs a custom opening message
5. The host wants complete control over timing

Automatic phase clock

Automatic mode performs time-based phase transitions.

At a Day deadline, it:

1. Reads the canonical vote state
2. Applies threshold, plurality, and tie rules
3. Resolves the Day
4. Opens Night
5. Locks player discussion

At a Night deadline, it opens the next Day.

It does not resolve private night actions or send role results. If a host needs to process actions and compose a detailed morning announcement, Manual mode remains safer.

Automatic mode also does not cause an immediate hammer when a player reaches majority. The normal automatic transition occurs at the configured deadline. A host can manually resolve the Day earlier.

Manual controls remain available in either mode.

19. Configure phase lengths

For automatic mode, select preset Day and Night lengths or choose exact deadlines where offered.

For Day 1, choose:

1. The normal mode behavior
2. An exact end time

In Manual mode, the default can be no deadline. In Automatic mode, a future deadline is required.

20. Configure deadline voting rules

Choose what happens if the Day deadline arrives without a threshold elimination.

No player reaches threshold

Choose:

1. No Lynch
2. Plurality: eliminate the player with the highest vote total

Multiple top wagons are tied

Choose:

1. No Lynch
2. Random player among tied wagons
3. Player who reached the final tied total first
4. Eliminate all tied players

A No Lynch wagon does not compete as an ordinary player wagon in sub-threshold plurality resolution.

21. Launch safely

Select the launch button.

Launching is resumable. If the request is interrupted, reload the dashboard and select Resume game launch. The recovery process reuses the reserved thread and post records rather than creating duplicates.

Only the designated main host can initiate the normal launch. Administrators can assist with recovery when permitted.

Part VI: Running the game

22. How voting works

During an open Day, eligible living players see the Vote to Lynch controls above the reply editor.

A player can:

1. Choose a player or Unvote
2. Select Insert vote
3. Submit the reply normally

The bot recognizes the canonical vote command in the post and updates the game’s vote state.

Players may also select Post vote count to request a public count.

Votes are rejected when the player is:

1. Eliminated
2. Muted
3. Replaced
4. Not on the roster
5. Posting at Night
6. Posting while the game is paused
7. Posting before scheduled Day 1
8. Posting after automatic deadline closure
9. Posting in a completed or cancelled game

23. Monitor the Day

The dashboard’s Day-resolution section displays a current snapshot with:

1. Each wagon
2. Effective vote total
3. Individual elimination threshold
4. Voters
5. Source posts
6. Players not voting
7. Detected result
8. Any ambiguity requiring host intervention

Vote weight and player-specific threshold modifiers are applied to the canonical calculation.

24. Resolve the Day

When ready, use the Day-resolution panel.

If the bot detects one unambiguous result, choose Use detected vote result.

If the result needs host judgment, choose Record a host override and select:

1. No Lynch
2. A living player

A host override requires an explanation. That explanation becomes part of the public result announcement.

Then choose the Night deadline and select:

Resolve Day and open Night

The bot will:

1. Record the canonical Day result
2. Mark the applicable player or players eliminated
3. Post the public result
4. Open Night
5. Immediately lock ordinary player discussion and voting

Hosts and authorized moderators can still post at Night.

25. Process Night manually

For a manual game:

1. Have players send actions privately to the main host.
2. Confirm action deadlines.
3. Resolve protection, investigation, kill, and other effects outside the bot.
4. Enter resulting eliminations through the dashboard.
5. Prepare the public next-Day announcement.
6. Begin the next Day.

Do not rely on the automatic clock to calculate these actions.

26. Begin the next Day

While the game is in Night, the dashboard displays a rich-text field for the next Day’s public opening message.

Use it to announce:

1. Who died during the Night
2. Alignment or role flips
3. Investigation-independent public results
4. Rule clarifications
5. Replacements
6. A concise game recap

Choose the new Day deadline and select Begin Day N.

The bot:

1. Posts the host’s public opening message
2. Opens the new Day
3. Unlocks eligible player replies
4. Starts the new deadline
5. Starts the Day on a fresh forum page

All Days remain in one thread, but each new Day begins on a new page.

27. Navigate between Days

Once multiple Days exist, the public thread shows a Day navigation bar with:

1. Previous Day
2. Next Day
3. Jump-to-Day selector

Ordinary page-number navigation remains available alongside Day navigation.

28. View vote history

Open the public game thread and select Vote history in the Game Info panel.

Vote history shows:

1. Voter
2. Target
3. Vote or unvote
4. Effective wagon total
5. Day number
6. Time
7. Link to the source post

Vote history is public to players and spectators. It is not restricted to hosts.

Eligible legacy games with the old vote system can use the temporary compatibility route, but the full canonical integration belongs to dashboard-hosted games.

Part VII: Host controls

29. Change the phase deadline

Use Current phase deadline to update the running deadline.

In Manual mode, the deadline can be cleared.

Automatic mode requires a future deadline because the worker needs a valid execution time.

30. Override the base threshold

Leave the threshold field blank to use strict majority.

Entering a value changes the game’s base threshold. Individual role modifiers are applied afterward.

For example:

1. Base threshold: 5
2. Hated modifier: -1
3. That player’s effective threshold: 4

Use role-level modifiers for player-specific mechanics instead of repeatedly changing the whole game’s base threshold.

31. Eliminate or restore a player manually

The roster table provides Eliminate and Restore controls.

Use these for:

1. Night kills
2. Moderator-resolved effects
3. Revivals
4. Corrections
5. Nonstandard mechanics

Day eliminations should normally go through the dedicated Day-resolution workflow so that votes, history, and announcements remain consistent.

32. Pause and resume

Use Pause game for:

1. Host emergencies
2. Rule disputes
3. Replacement searches
4. Technical problems
5. Moderation intervention

You may enter a public pause reason.

Pausing preserves the current phase but blocks ordinary player discussion, voting, and automatic advancement.

When resuming:

1. Choose Manual or Automatic control.
2. Set the appropriate deadline.
3. Select Resume game.

33. Substitute a player

Active games must be paused before substitution.

Under Player substitutions:

1. Select a living outgoing player.
2. Enter the replacement username.
3. Enter the required private reason.
4. Select Send PM and replace.

The replacement inherits:

1. Stable roster slot
2. Role
3. Alignment
4. Team
5. Private role card
6. Voting modifiers

The outgoing player remains canonical until the replacement PM succeeds.

If delivery fails, use:

1. Retry replacement PM
2. Safely cancel, but only when no replacement PM was created

During a paused Day, completing a substitution clears the current vote state. Players must vote again after resumption.

34. Mute a player

Muting applies only to the hosted game thread. It does not suspend the account or prevent private messages elsewhere.

Select the player and choose:

1. Remainder of the current Day
2. Until manually unmuted

Enter the required private reason.

A muted player cannot:

1. Reply
2. Vote
3. Unvote
4. Request a vote count

The bot does not automatically announce the mute publicly. The host decides whether the setup requires disclosure.

35. Change the public thread title

Use Thread title in the dashboard.

Changing the title changes the readable slug, but the permanent thread identifier stays the same. Old links redirect to the canonical URL.

This changes the public thread title only; it does not rename the private dashboard record.

Always use this control instead of trying to reconstruct or manually edit the URL.

Part VIII: Ending a game

36. Complete the game

Use Complete game when a win condition has been met.

Choose:

1. Winning faction or team
2. Or Other result with a custom label
3. Optional completion note
4. Postgame-discussion length or exact closing time

Then select:

Complete game, announce winner, and open postgame

The bot will:

1. Stop the phase clock
2. Stop vote processing
3. Post the winner announcement
4. Open ordinary postgame discussion
5. Schedule the thread to close at the selected time

After completion, the dashboard can:

1. Change the postgame closing time
2. Reopen discussion
3. Close discussion immediately

The host must determine when the win condition has been met; the bot does not yet detect it.

37. Cancel a game

Use Cancel game only for abandoned or invalid games.

Cancellation is permanent and closes the linked thread. It is not the normal way to end a successfully completed game.

For unlaunched drafts, cancellation preserves setup and assignment history for auditing but prevents further changes.

Part IX: Safety and recovery

38. Use the dashboard as the source of truth

Do not separately maintain conflicting copies of:

1. Roster
2. Host list
3. Living players
4. Phase
5. Deadline
6. Threshold
7. Vote state
8. Assignments

Make canonical changes through the dashboard.

Legacy embedded host controls should not be used on dashboard-hosted games.

39. Audit history

The dashboard includes recent activity and a full audit page.

Audit categories include:

1. Dashboard views
2. Host actions
3. Automated actions

Each event records information such as:

1. Actor
2. Time
3. Access basis
4. Outcome
5. Source
6. Relevant non-secret metadata

Secret role assignments and role-PM bodies are not copied into audit metadata.

40. Recover pending operations

Role PM delivery failed

Correct the underlying account problem, then select Retry unsent role PMs.

Launch was interrupted

Select Resume game launch. Do not create a second draft.

Announcement is pending

Select Retry announcement.

Use Dismiss announcement only when you intentionally accept that the public post will never be created. Dismissal cannot be undone.

Thread synchronization is pending

Select Retry thread synchronization before attempting other phase changes.

Scheduled start failed

Use Start Day 1 now or correct the schedule and save it again.

“Game changed in another tab”

Reload the dashboard. The stale form is being rejected to protect newer state.

Authorization or CSRF error after deployment

Reload the page before resubmitting. A form opened before deployment may contain an expired security token.

Administrator cannot access a game

Check whether that administrator is or was a participant in the unfinished game. Participant blocking is intentional.

Host controls are missing

Confirm that:

1. The user has Mafia Host permission
2. They are the designated main host
3. Their approval has not been revoked
4. The game is not in a terminal state
5. No pending synchronization or announcement is blocking changes

Thread remains locked unexpectedly

Check:

1. Current game phase
2. Pause status
3. Scheduled-start status
4. Pending thread synchronization
5. Moderator-level locks

A moderator lock overrides ordinary host phase behavior and must be intentionally removed through moderation controls.

Recommended live-game procedure

Before launch

1. Confirm the main host and co-hosts.
2. Verify every player username.
3. Match the role quantity to the roster.
4. Preview every custom role PM.
5. Confirm team keys and teammate lists.
6. Review hidden voting modifiers.
7. Randomize only when the setup is final.
8. Review assignments privately.
9. Finalize assignments.
10. Deliver every role PM successfully.
11. Use Manual phase control for the first live games.
12. Preview the opening post and Day 1 schedule.

During each Day

1. Confirm the thread is open.
2. Monitor vote history and current wagons.
3. Address substitutions or moderation problems through Pause.
4. Resolve the Day through the Day-resolution panel.
5. Use an override only when host judgment is genuinely required.
6. Confirm Night is open and player discussion is locked.

During each Night

1. Collect actions privately.
2. Resolve actions manually.
3. Update living-player status.
4. Write the next-Day public message.
5. Set the new deadline.
6. Begin the next Day.
7. Confirm the new Day starts on a fresh page and replies are open.

At game end

1. Confirm the actual win condition.
2. Choose the winning faction or custom result.
3. Add an optional final note.
4. Set the postgame-discussion period.
5. Complete the game.
6. Verify the winner announcement.
7. Allow postgame discussion to close automatically or adjust it as needed.

Most important warnings

1. Keep assignment screens private.
2. Do not rely on the bot to resolve night actions.
3. Do not assume reaching majority causes an instant automatic hammer.
4. Do not use Cancel for an ordinary game ending.
5. Pause before substituting a player.
6. Do not manually duplicate a failed launch or PM batch.
7. Use the dashboard—not legacy thread controls—as the canonical game record.