Counting Minigame

Relevant source files

The following files were used as context for generating this wiki page:

• src/util/counting/countingManager.ts
• src/util/counting/helpers.ts
• src/commands/fun/counting.ts
• src/util/counting/types.ts
• src/util/counting/constants.ts
• config.example.json

The Counting Minigame is a core community engagement feature within the Poixpixel Discord Bot. It facilitates a collaborative environment where users count sequentially in a designated channel. The system enforces strict rules to ensure game integrity, including preventing a single user from counting twice in a row and implementing a sophisticated mistake-tracking system that can lead to temporary or permanent bans from the minigame.

The module is built with a focus on persistence and fault tolerance, utilizing Redis for real-time state management and a background rehydration process to ensure that temporary bans and system states are maintained across bot restarts.

System Architecture and Data Flow

The counting system operates through a centralized manager that interfaces with Redis for state persistence. When a message is sent in the counting channel, it is processed to evaluate if the number is correct, if the user is authorized, and if any milestones have been reached.

Message Processing Logic

The message processing flow handles input validation, rule enforcement (no double counting), and mathematical evaluation (supporting basic expressions via sanitization).

State Management

Counting data is stored in Redis under the key counting. The data structure tracks the current progress, historical highs, and moderation metadata.

Field	Type	Description
currentCount	number	The current number in the sequence.
lastUserId	string | null	Discord ID of the last successful counter.
highestCount	number	Historical peak reached in the guild.
totalCorrect	number	Cumulative count of all successful entries.
bannedUsers	string[]	List of user IDs prohibited from counting.
mistakeTracker	Record	Mapping of user IDs to their mistake/warning statistics.
bannedMeta	Record	Metadata for bans, including expiry timestamps.

Sources: src/util/counting/types.ts:16-24, src/util/counting/constants.ts:5

Moderation and Mistake Tracking

The system implements an automated "three-strike" style policy. Mistakes (wrong numbers or double counting) are tracked per user. Reaching specific thresholds triggers warnings, and excessive warnings result in automated bans.

Mistake Escalation Workflow

1. Mistake Recorded: Increments the user's mistake count.
2. Warning Issued: When MISTAKE_THRESHOLD is reached, a warning is issued and the mistake count resets.
3. Automated Ban: When MAX_WARNINGS is reached, the user is automatically banned for a duration defined by AUTO_BAN_DURATION_MS.

Administrative Commands

Administrators and Moderators can manage the game state through the /counting slash command.

Subcommand	Permission	Purpose
status	None	Displays current count, high score, and last counter.
setcount	Administrator	Manually overrides the current count.
ban	BanMembers	Prohibits a user from participating (temp or perm).
unban	ModerateMembers	Restores a user's access to the minigame.
resetdata	Administrator	Wipes all counts and clears everyone's mistakes.
listwarnings	ModerateMembers	Displays a paginated list of users with active strikes.

Sources: src/commands/fun/counting.ts:26-104

Implementation Details

Mathematical Evaluation

The bot does not just look for raw integers; it uses sanitizeAndEval to allow users to use simple math. However, it applies strict sanitization to prevent code injection or unsafe execution. If evaluation fails, it is treated as a mistake.
Sources: src/util/counting/helpers.ts, src/util/counting/countingManager.ts:187-201

Rollback Mechanism

To prevent griefing in high-number sequences, the bot employs a rollback strategy instead of a total reset to zero for counts above 100.

• If count > 100: The count is rolled back to the nearest power of 10 (e.g., if a mistake happens at 1,250, it might rollback to 1,000).
• If count <= 100: The count is reset to 0.

Sources: src/util/counting/countingManager.ts:162-185, src/util/counting/countingManager.ts:222-253

Milestone System

The system automatically reacts to specific milestones to celebrate progress. These are defined in MILESTONE_REACTIONS.

export const MILESTONE_REACTIONS = {
  normal: '✅',
  multiples25: '✨',
  multiples50: '⭐',
  multiples100: '🎉',
} as const;

Sources: src/util/counting/constants.ts:40-45, src/util/counting/countingManager.ts:316-328

Configuration

The minigame behavior is highly configurable via the config.json file under the counting object.

Option	Default	Description
warningPeriod	3600	Duration (seconds) before mistakes/warnings decay.
mistakeThreshold	5	Number of mistakes before a formal warning is issued.
maxWarnings	3	Number of warnings before an automated ban.
autoBanDuration	86400	Duration (ms) for an automated ban (24 hours).

Sources: config.example.json:115-128, src/util/counting/constants.ts:13-37

The Counting Minigame provides a robust framework for community interaction, combining simple gameplay with complex automated moderation to ensure a fair and persistent experience for all server members.