Debug Commands
Debug commands are powerful tools designed for testing and resolving issues. To prevent accidental use, these commands are hidden and disabled by default.
Enabling Debug Mode
Section titled “Enabling Debug Mode”Before you can use these commands, you must enable debug mode in your config.yml. This toggle acts as a safety gate for advanced administrative operations.
# Enabling debug mode allows administrators to access advanced troubleshooting commands.debug: true
# Enables profiling for SantaSays events to measure execution time.# Recommended for identifying lag or slow external plugins.event-profiling: enabled: true # If enabled, logs every event execution with timing details to the console. verbose: falseTimer Command
Section titled “Timer Command”Administrators with the santasays.debug.timer permission can manually override the active game timer. This is particularly useful during testing to skip long waiting periods.
If used without an arena name, the command targets the arena you are currently in. Providing an arena name allows you to adjust the timer for a specific match remotely.
/santasays debug timer [arena] <time>Example
Section titled “Example”/santasays debug timer winter-arena 60State Command
Section titled “State Command”Administrators with the santasays.debug.state permission can force a match into a specific game state (e.g., WAITING, STARTING, IN_GAME, ENDING, RESTARTING). This allows you to manually progress the game lifecycle for debugging purposes.
Similar to the timer command, this targets your current arena unless a specific arena name is provided. Use this command with caution, as forcing states can disrupt active gameplay logic.
/santasays debug state [arena] <state>Example
Section titled “Example”/santasays debug state winter-arena ENDINGTasks Command
Section titled “Tasks Command”Administrators with the santasays.debug.tasks permission can access an interactive registry of all tasks available in the plugin. This is the primary interface for exploring, searching, and testing individual challenges.
The list is fully interactive and paginated (15 tasks per page). Clicking on any task ID within the chat triggers a Context-Aware Execution:
- If you are NOT in an arena: The plugin will automatically join you to the first registered arena and force the selected task to start immediately.
- If you ARE already in an arena: The selected task will be queued as the very next round in your current game.
You can also use the search flag to filter the list by task name.
/santasays debug tasks [page] [--search=<keyword>]Example
Section titled “Example”/santasays debug tasks 1 --search=parkourRun Task Command
Section titled “Run Task Command”While primarily functioning as a background utility for the /santasays debug tasks command, administrators with the santasays.debug.tasks permission can also trigger this command manually for specific testing scenarios.
If you are currently in an arena, it sets the specified task as the next one to be played. If you are not in an arena, it will automatically join you to the first registered arena and force the specified task to start immediately.
/santasays debug runtask <task_id>Example
Section titled “Example”/santasays debug runtask 12Join Command
Section titled “Join Command”Administrators with the santasays.debug.join permission can use this powerful command to instantly set up a test environment. Unlike the standard join command, this version bypasses the usual waiting phases and allows you to simulate a full game scenario with specific players and tasks.
When executed, it forces the specified arena’s state directly to IN_GAME. You can optionally bring other players with you and pre-define which tasks should be played in what order.
The task selection also supports numeric ranges, making it easier to queue sequential blocks of challenges.
/santasays debug join <arena> [--players=p1,p2,...] [--tasks=1,5,8-12,20]Options
Section titled “Options”--players=name1,name2: Automatically pulls the specified online players into the arena with you.--tasks=id1,id2,range: Forces the game to run specific tasks in the given order. Supports individual IDs (e.g.,5) and ranges (e.g.,8-12).
Example
Section titled “Example”/santasays debug join winter-arena --players=mrdespi,mSquid_ --tasks=1-3,5,8-10Next Command
Section titled “Next Command”Administrators with the santasays.debug.next permission can manually queue the upcoming tasks for their current arena. This command is perfect for testing specific task transitions or chaining challenges together to see how they flow.
This command supports both individual task IDs and numeric ranges, allowing you to bulk-queue sequences of tasks efficiently. When specified, the plugin will provide a confirmation message listing the names of the successfully queued tasks.
/santasays debug next <task_1 task_2 ... | 1-5 8 10-12>Example
Section titled “Example”/santasays debug next 1-5 8 10-12Round Command
Section titled “Round Command”Administrators with the santasays.debug.round permission can manually set the current round number of the match. This is a critical tool for testing round-specific logic or jumping directly to the final round to verify winner calculations and rewards.
The command requires a valid integer. Once executed, the match’s internal round counter will be updated instantly to the specified value.
/santasays debug round <number>Example
Section titled “Example”/santasays debug round 15Max Round Command
Section titled “Max Round Command”Administrators with the santasays.debug.maxround permission can manually override the total number of rounds for the current match. This allows you to shorten or extend a game dynamically without changing the global configuration.
This is particularly useful if you want to trigger game-end conditions earlier than expected or prolong a test session.
/santasays debug maxround <number>Example
Section titled “Example”/santasays debug maxround 20Component Command
Section titled “Component Command”Administrators with the santasays.debug.component permission can use this command to preview chat formatting and component parsing in real-time. Instead of constantly reloading configuration files to see how a message looks, you can test colors, hex codes, and placeholders directly in-game.
The plugin will parse the input using its internal chat manager and send the resulting component back to you, exactly as it would appear in a game message or announcement.
/santasays debug component <message>Example
Section titled “Example”/santasays debug component <gradient:red:gold>Test Message!</gradient>Dump Command
Section titled “Dump Command”Administrators with the santasays.debug.dump permission can generate a comprehensive performance report of the plugin’s internal events. This command is directly tied to the Event Profiling system in the config.yml.
When executed, the plugin will send a timings report to the sender, detailing how long various event listeners took to process. This is the primary tool for diagnosing “server lag” or identifying conflicts with slow external plugins.
/santasays debug dumpExample
Section titled “Example”/santasays debug dumpDetails
Section titled “Details”- Prerequisite:
event-profilingmust be enabled inconfig.ymlfor meaningful data.