SimonSays Documentation

Introduction

SimonSays is a feature-rich Minecraft plugin that runs multiple chat and in‑world minigames. Players compete to type fastest, solve puzzles, answer trivia, complete action challenges, and earn points (with optional economy rewards via Vault). Includes an auto‑run scheduler, PlaceholderAPI support, and a GUI leaderboard.

Built against Spigot API 1.16.5 targeting Java 8; designed to run on modern Spigot/Paper servers (1.13+ content).

Installation

1. Place SimonSays-*.jar into your server plugins/ folder.
2. (Optional) Install Vault and an economy plugin for money rewards.
3. (Optional) Install PlaceholderAPI to use placeholders on scoreboards/holograms.
4. (Optional) Install DecentHolograms for high‑quality win holograms (the plugin falls back to invisible ArmorStands if DH isn’t installed).
5. Restart the server to generate config.yml and game files under plugins/SimonSays/.

Commands

/simonsays start <gametype> <difficulty> [-f] [--with <content>]
/simonsays stop
/simonsays status
/simonsays reload
/simonsays test <survival_combo|enchant_tool>
/simonsays leaderboard gui [overall|<gametype>] [page]
/simonsays stats [player] [page]
/simonsays toggle
/simonsays shop [category]
/simonsays tokens [player]
/simonsays tokens give|take|set <player> <amount>
/simonsays games list|enable|disable <type>
/simonsays prob get|set <type> <weight>
/simonsays log [page]
/simonsays world blacklist|whitelist add|remove <world>
/simonsays join <game>

Alias: /ss

Command Flags

• -f — Force start the game even with insufficient players
• --with <content> — Start a game with custom content instead of random selection

The --with Flag

The --with flag allows you to specify custom content for supported game types. This is useful for creating custom challenges or testing specific scenarios.

Supported Game Types

• Trivia: --with question|answer or --with question|ans1,ans2,ans3
• Reaction: --with customword
• Unscramble: --with wordtounscramble
• Unreverse: --with wordtoreverse
• Completion: --with wordtocomplete
• Random: --with customstring

Examples

# Custom trivia question with single answer
/ss start trivia easy --with What is 2+2?|4

# Custom trivia with multiple accepted answers
/ss start trivia medium --with What color is the sky?|blue,azure,light blue

# Custom reaction word
/ss start reaction hard --with supercalifragilistic

# Force start with custom content
/ss start trivia easy -f --with Who created Minecraft?|Notch,Markus Persson

Note: The --with flag consumes all remaining arguments as content, so place -f before --with if using both flags.

Additional Commands

• /ss stats [player] [page] — View your stats or another player's stats. Shows wins, streaks, and per-game-type breakdown.
• /ss toggle — Toggle SimonSays broadcast messages on/off for yourself.
• /ss shop [category] — Open the shop GUI (or a specific category).
• /ss tokens — Check your token balance.
• /ss tokens <player> — Check another player's token balance.
• /ss tokens give|take|set <player> <amount> — Admin commands to manage player tokens.
• /ss games list — List all disabled game types.
• /ss games enable|disable <type> — Enable or disable a game type globally.
• /ss prob get [type] — View auto-run weight for a game type (or all types).
• /ss prob set <type> <weight> — Set the auto-run weight for a game type (0 = never picked).
• /ss log [page] — View recent game history with winners and times.
• /ss world blacklist|whitelist add|remove <world> — Manage which worlds allow SimonSays games.
• /ss join <game> — Join a game that requires explicit joining (e.g., Present Pick).

Permissions

Core Permissions

• simonsays.start — Start games (default: op)
• simonsays.stop — Stop current game (default: op)
• simonsays.status — View game status (default: true)
• simonsays.reload — Reload plugin config (default: op)
• simonsays.test — Run action test tasks (default: op)
• simonsays.admin — Full access to all commands (default: op)

Player Permissions

• simonsays.leaderboard.gui — Open leaderboard GUI (default: true)
• simonsays.toggle — Toggle broadcast messages for yourself (default: true)
• simonsays.stats — View player statistics (default: true)
• simonsays.shop — Open the shop GUI (default: true)

Token Permissions

• simonsays.tokens.others — View other players' token balance (default: op)
• simonsays.tokens.admin — Give, take, or set player tokens (default: op)

Admin Permissions

• simonsays.games — Enable/disable game types globally (default: op)
• simonsays.prob — Configure auto-run probabilities (default: op)
• simonsays.log — View game history log (default: op)
• simonsays.world — Manage world blacklist/whitelist (default: op)

Configuration (config.yml)

Key top‑level options:

messages:
  prefix: "&b[SimonSays] "         # Set to "" to disable prefix
  use-minimessage: false           # true = parse MiniMessage; false = legacy & colors + hex

settings:
  broadcast-countdown: true        # Send countdown to chat (false = titles/effects only)

auto-run:
  enabled: true
  min-interval: 300                # seconds
  max-interval: 600
  difficulties: [easy, medium, hard]
  enabled-games: [reaction, unscramble, trivia, math, action, guess_number, unreverse, completion, click_button, hoverable, shopping_list, random]

storage:
  type: YAML                       # YAML | SQLITE | MYSQL
  mysql:
    host: localhost
    port: 3306
    database: simonsays
    username: root
    password: ""

• messages.prefix: plugin message prefix; set to empty string ("") to disable.
• messages.use-minimessage: when true, text is parsed via Kyori MiniMessage enabling gradients, hover text, and click actions. See the MiniMessage Formatting section for detailed examples.
• settings.broadcast-countdown: when false, countdown messages are not sent to chat (use with title countdowns for a cleaner UI).
• auto-run: global scheduler; min players per mode are read from each mode's YAML under settings.min-players.
• storage.type: choose YAML (default), SQLITE, or MYSQL. SQL drivers are shaded in release builds.

Effects and Display Channels

SimonSays can present prompts and events in multiple channels: Title, Actionbar, Chat, and Bossbar. Configure per event under effects.channels.

effects:
  channels:
    countdown: ["title"]
    start: ["title"]
    prompt: ["title"]        # e.g., ["chat"], ["actionbar"], or ["bossbar"]
    win: ["title"]
    time_up: ["title"]

  titles:
    also_use_bukkit: true     # reliability fallback using Player#sendTitle
    countdown:
      enabled: true
      title: "&e&l%seconds%"
      subtitle: "&7Get ready"
      fade-in: 5
      stay: 10
      fade-out: 5
    start:
      enabled: true
      title: "&a&lGO!"
      subtitle: "&7Good luck"
      fade-in: 5
      stay: 20
      fade-out: 5
    win:
      enabled: true
      title: "&6&l%player%"
      subtitle: "&eWon the game!"
      fade-in: 5
      stay: 40
      fade-out: 10
    time_up:
      enabled: true
      title: "&c&lTime's up!"
      subtitle: "&7The answer was %answer%"
      fade-in: 5
      stay: 40
      fade-out: 10

  prompts:
    enabled: true
    fade-in: 5
    stay: 40
    fade-out: 10

  bossbar:
    color: YELLOW
    overlay: PROGRESS
    progress: 1.0

• Prompts are the overlay shown at round start (word/question/action).
• Bossbar shows a temporary bar for the event’s stay period.
• Use MiniMessage tags in chat when messages.use-minimessage=true (see below).

Win Holograms (DecentHolograms) + Crash‑Safe Cleanup

When a player wins, a hologram can be displayed above them. If DecentHolograms is installed it’s used automatically; otherwise the plugin uses invisible ArmorStands.

effects:
  hologram:
    win:
      enabled: true
      duration-ticks: 120
      line-height: 0.27
      lines:
        - "&6Winner: &e%player%"
        - "&7%game% &8(&7%difficulty%&8)"

• Crash safety: temporary DH holograms are tracked in plugins/SimonSays/data/temp-holograms.yml and removed automatically on startup/shutdown; fallback ArmorStands are tagged and auto‑removed too.
• Soft‑depend on DecentHolograms is declared; install DH for best visual quality.

Case‑Sensitivity Hints

• Case hints: if a mode is case‑sensitive and a player's answer matches ignoring case but not exact case, they receive a private hint (default: "Close! Check capitalization.").
• Toggle: features.case-sensitivity-hints: true
• Message: messages.player.case-hint

features:
  case-sensitivity-hints: true
messages:
  player:
    case-hint: "&eClose! Check capitalization."

MiniMessage Formatting

SimonSays supports MiniMessage, a modern text formatting system that provides gradients, hover text, click actions, and more. Enable it by setting messages.use-minimessage: true in your config.

Enabling MiniMessage

messages:
  use-minimessage: true
  prefix: "<gradient:#ff0080:#ffc800>[SimonSays]</gradient> "

Feature Comparison

Backward Compatibility

When MiniMessage mode is enabled, all legacy formatting still works. The plugin automatically converts & codes and #hex colors to MiniMessage format before parsing. This means you can:

• Keep your existing configs without changes
• Mix legacy & codes with MiniMessage tags in the same string
• Gradually migrate to MiniMessage syntax

# Mix legacy and MiniMessage in the same line
prefix: "&4[&cSimonSays&4] "                          # Legacy only - works fine
prefix: "<red>[SimonSays] "                            # MiniMessage only
prefix: "&4[<gradient:#ff0000:#ffaa00>SimonSays</gradient>&4] "  # Mixed - both work together!

# Hex colors work both ways
won: "#00ff00%player% won!"                          # Legacy hex
won: "<color:#00ff00>%player% won!"                   # MiniMessage hex

Gradient Examples

# Two-color gradient
prefix: "<gradient:#ff0080:#ffc800>[SimonSays]</gradient> "

# Multi-color gradient
won: "<gradient:#00ff00:#ffff00:#ff0000>%player% won!</gradient>"

# Rainbow effect
display: "<rainbow>Type this word fast!</rainbow>"

Hover and Click Actions

Interactive elements work in chat messages only. Titles, actionbars, and bossbars do not support click events.

# Hover tooltip
won: "<hover:show_text:'Winner: %player%'><gold>%player% won!</gold></hover>"

# Click to copy
display: "<click:copy_to_clipboard:'%word%'>Click to copy the answer</click>"

# Click to run command
help: "<click:run_command:'/ss leaderboard gui'>View Leaderboard</click>"

# Click to open URL
support: "<click:open_url:'https://discord.gg/example'>Join our Discord</click>"

Combined Formatting

You can combine multiple MiniMessage tags for rich, interactive text:

won: "<gradient:#ffd700:#ffaa00><hover:show_text:'<green>Time: %time%s'>%player% won!</hover></gradient>"

display: "<rainbow><hover:show_text:'Good luck!'><bold>%word%</bold></hover></rainbow>"

Important Notes

• Backward compatible: When MiniMessage is enabled, all legacy & codes and #hex colors are automatically converted and work alongside MiniMessage tags. No config migration required!
• Escaping: Literal < or > in MiniMessage tags must be escaped as <lt> and <gt>.
• Placeholders: The plugin performs %placeholder% replacement before MiniMessage parsing.
• Channel limitations: Hover and click actions only work in chat channels. Use effects.channels.prompt: ["chat"] to enable interactive prompts.
• Legacy-only mode: When use-minimessage: false (default), only & codes and #hex work; gradients and interactive features are not available.

Enabling Interactive Prompts

To use hover/click in game prompts, route them to the chat channel:

effects:
  channels:
    prompt: ["chat"]   # Instead of ["title"] or ["actionbar"]
    win: ["chat"]

messages:
  use-minimessage: true

For complete MiniMessage documentation, visit docs.advntr.dev/minimessage.

Per‑Game Overrides

Any effects can be toggled per game with effects.per-game.<GAME>.<category>.<feature>.enabled. Missing entries fall back to the global setting.

effects:
  per-game:
    REACTION:
      titles:
        prompt:
          enabled: true
        win:
          enabled: true
        time_up:
          enabled: true
      hologram:
        win:
          enabled: true

Auto‑Run Scheduler

• Randomly starts an enabled game at a random difficulty between min-interval and max-interval.
• Won’t start if a game is already active or there aren’t enough players for any enabled mode.
• Minimum players per mode: settings.min-players inside each game file (see game sections below).

Games Overview

All modes define per‑difficulty time limits, reward rules, and messages. Files are under plugins/SimonSays/games/<mode>/.

• Rewards:
  • rewards.points: base points, optional time‑bonus and broadcast
  • rewards.commands: console commands on win (supports per-command chance)
  • rewards.economy: Vault money (if Vault installed)
  • Tokens: separate currency for the shop (see Shop System)
• Messages: use legacy & colors (with hex) or MiniMessage when enabled.
• Available game types: REACTION, UNSCRAMBLE, TRIVIA, MATH, GUESS_NUMBER, UNREVERSE, COMPLETION, CLICK_BUTTON, HOVERABLE, SHOPPING_LIST, RANDOM, CLUE_CRACKER, NAUGHTY_NICE, PRESENT_PICK, ACTION

Reaction (chat)

Type the displayed word first to win.

File: games/reaction/reactions.yml + wordlists at games/reaction/wordlists/ (easy|medium|hard).

settings:
  min-players: 2
reaction:
  difficulties:
    easy:
      time-limit: 15
rewards:
  points:
    base-amount: 10
    time-bonus:
      enabled: true
      per-second-remaining: 2
messages:
  game:
    starting: "&eStarting in &6%seconds%s&7..."
  player:
    won: "&a%player% &7won!"
    won-points: "&a+%points% &7points (&f%base%&7 + &a%bonus%&7)"
# Matching options (all word games):
#   case-sensitive: false|true
#   ignore-diacritics: true|false   # when true, accented letters are treated as their base (ż == z)

Unscramble (chat)

Unscramble the jumbled word. Files: games/unscramble/unscramble.yml and wordlists at games/unscramble/wordlists/.

• Displays a scrambled form (%scrambled%); winner types the original word (%word%).
• Case-insensitive matching; trims leading/trailing spaces.
• Difficulty controls time limit and wordlist used.

settings:
  min-players: 2
unscramble:
  difficulties:
    medium:
      time-limit: 20
rewards:
  points:
    base-amount: 12
messages:
  game:
    starting: "&eUnscramble starts in &6%seconds%s&7..."
    display: "&fWord: &b%scrambled%"
  player:
    won: "&a%player% &7unscrambled &f%word%&7!"
    too-late: "&7Too late! The word was &f%word%&7."

Trivia (chat)

Answer a question correctly. File: games/trivia/trivia.yml.

• Supports question %question%, accepted answer(s) %answer%, and optional category %category%.
• Matching is case-insensitive; common punctuation is ignored.

settings:
  min-players: 2
trivia:
  difficulties:
    easy:
      time-limit: 25
      categories: ["general"]
rewards:
  points:
    base-amount: 15
messages:
  game:
    display: "&eTrivia: &f%question%"
  player:
    won: "&a%player% &7answered correctly!"
    too-late: "&7Time! Answer: &f%answer%"

rewards:
  commands:
    enabled: true
    commands:
      - "say %player% always runs"           # 100%
      - command: "give %player% diamond 3"   # 25% chance
        chance: 25
      - command: "eco give %player% 500"    # 50% chance
        chance: 50

Math (chat)

Solve arithmetic (addition, subtraction, multiplication, division). File: games/math/math.yml.

• Generates solvable problems; division uses integer quotient (bug fixed to use quotient, not divisor).
• Tokens: %question% and %answer% (for time-up message).

settings:
  min-players: 2
math:
  difficulties:
    easy:
      time-limit: 20
rewards:
  points:
    base-amount: 10
messages:
  game:
    display: "&fSolve: &b%question%"
  player:
    won: "&a%player% &7solved it!"
    too-late: "&7Answer was &f%answer%"

Guess Number (chat)

Guess the secret number in a range. File: games/guess-number/guess-number.yml.

• Tokens: %min%, %max%, %number% (revealed on time-up).
• Implementation tracks first exact match; considers numeric input only.

settings:
  min-players: 2
guess-number:
  difficulties:
    medium:
      time-limit: 25
      min: 1
      max: 100
rewards:
  points:
    base-amount: 12
messages:
  game:
    display: "&eGuess the number between &f%min%&e and &f%max%"
  player:
    won: "&a%player% &7guessed correctly!"
    too-late: "&7It was &f%number%"

Unreverse (chat)

Recover the original word from its reversed form. File: games/unreverse/unreverse.yml with wordlists under games/unreverse/wordlists/.

• Displays %reversed%; expect the original %word% as the winning answer.
• Case-insensitive; trims whitespace.

settings:
  min-players: 2
unreverse:
  difficulties:
    hard:
      time-limit: 20
rewards:
  points:
    base-amount: 14
messages:
  game:
    display: "&fText: &b%reversed%"
  player:
    won: "&a%player% &7recovered &f%word%&7!"
    too-late: "&7Original was &f%word%"

Completion (chat)

Complete a word with missing letters. File: games/completion/completion.yml with wordlists under games/completion/wordlists/.

• Displays an incomplete/masked form %incomplete%; answer is the full %word%.
• Case-insensitive; trims whitespace.

settings:
  min-players: 2
completion:
  difficulties:
    medium:
      time-limit: 20
rewards:
  points:
    base-amount: 12
messages:
  game:
    display: "&fComplete: &b%incomplete%"
  player:
    won: "&a%player% &7completed &f%word%&7!"
    too-late: "&7It was &f%word%"

Click Button (chat)

Be the first to click an interactive button displayed in chat. File: games/click-button/click-button.yml.

• Displays a clickable button in chat; first player to click wins.
• Button text is configurable with custom symbols and colors.
• Requires chat channel for interactive functionality.
• Works best with MiniMessage enabled for hover effects.

settings:
  min-players: 2
button-texts:
  - "[█]"          # Block character
  - "[CLICK]"
  - "[☑]"          # Checkbox

difficulties:
  easy:
    time-limit: 10
  medium:
    time-limit: 8
  hard:
    time-limit: 5

rewards:
  points:
    base-amount: 10
    time-bonus:
      enabled: true
      per-second-remaining: 2

messages:
  game:
    starting: "&eClick Button starts in &6%seconds%s&7..."
    display: "&eClick the button to win!"
  player:
    won: "&a%player% &7clicked first!"
    too-late: "&7Time's up!"

Note: For best results, ensure effects.channels.prompt includes ["chat"] to display the clickable button in chat.

Hoverable (chat)

Find the hidden word by hovering over text in chat, then type it to win. File: games/hoverable/hoverable.yml with wordlists under games/hoverable/wordlists/.

• Displays a hoverable text element in chat; the hidden word is revealed on hover.
• Players must hover to discover %word% then type it in chat.
• Requires MiniMessage enabled and chat channel for hover functionality.
• Case-insensitive matching with optional diacritic handling.

settings:
  min-players: 2
  case-sensitive: false
  ignore-diacritics: true

word-lists:
  use-external-files: true
  directory: "wordlists"
  difficulties:
    easy:
      file: "hoverable-easy.txt"
      time-limit: 12
    medium:
      file: "hoverable-medium.txt"
      time-limit: 10
    hard:
      file: "hoverable-hard.txt"
      time-limit: 7

hover-format:
  hover-text: "&6&l&n[HOVER ME]"     # Text shown in chat
  hover-content: "&e&l%word%"        # Text revealed on hover

rewards:
  points:
    base-amount: 12
    time-bonus:
      enabled: true
      per-second-remaining: 2

messages:
  player:
    won: "&a%player% &7found the hidden word! (word: &f%word%&7)"
    too-late: "&7Time's up. The word was &f%word%"

Note: Requires messages.use-minimessage: true and effects.channels.prompt: ["chat"] for hover functionality.

Shopping List (chat)

Memorize a list of items shown briefly, then type them all from memory. File: games/shopping-list/shopping-list.yml with item lists under games/shopping-list/itemlists/.

• Displays a list of items via title/subtitle for a configurable duration.
• After the list disappears, players type all items (comma or space-separated).
• Supports exact order requirement or any order matching.
• Item count and time limit scale with difficulty.

settings:
  min-players: 2
  require-exact-order: false         # If true, items must match the shown order
  case-sensitive: false
  ignore-diacritics: true

display:
  duration-seconds: 3                # How long the list is visible
  title: "&e&lMemorize the list!"
  subtitle: "&b%items%"

item-lists:
  use-external-files: true
  directory: "itemlists"
  difficulties:
    easy:
      file: "items-easy.txt"
      time-limit: 20
      item-count: 3                  # Number of items to memorize
    medium:
      file: "items-medium.txt"
      time-limit: 25
      item-count: 4
    hard:
      file: "items-hard.txt"
      time-limit: 30
      item-count: 5

rewards:
  points:
    base-amount: 15
    time-bonus:
      enabled: true
      per-second-remaining: 2

messages:
  player:
    won: "&a%player% &7remembered all the items!"
    too-late: "&7Time's up. The items were: &f%items%"

Random (chat)

Type a randomly generated string to win. File: games/random/random.yml.

• Generates a random alphanumeric string of configurable length.
• Players must type the exact string (%string%) to win.
• String length increases with difficulty for added challenge.
• Supports custom strings via the --with flag.

settings:
  min-players: 2
  case-sensitive: false
  broadcast-winner: true

difficulties:
  easy:
    time-limit: 12
    length: 4                        # 4-character random string
  medium:
    time-limit: 10
    length: 6                        # 6-character random string
  hard:
    time-limit: 8
    length: 8                        # 8-character random string

string-format:
  prefix: "<gradient:#ffd166:#ff7b54><bold>"
  suffix: "</bold></gradient>"
  broadcast-style:
    enabled: true
    format:
      - "&7------------------------"
      - "<gradient:#6bdcff:#a0e7ff><bold>Random Challenge</bold></gradient>"
      - "&7Type this string:"
      - "&7>> %string%"
      - "&7------------------------"

rewards:
  points:
    base-amount: 10
    time-bonus:
      enabled: true
      per-second-remaining: 2

messages:
  player:
    won: "&a%player% &7typed it first! (string: &f%string%&7)"
    too-late: "&7Time's up. The string was &f%string%"

Clue Cracker (chat)

Crack the clues to guess a Christmas-themed word! Players see bracketed clues and must type the answer. File: games/clue-cracker/clue-cracker.yml.

• Displays clues in bracket format like [COLD][3 BALLS][CARROT FACE].
• Players type the answer (e.g., "snowman") to win.
• Supports multiple accepted answers per puzzle.
• Optional hints shown in the puzzle display.
• Perfect for seasonal/holiday events!

settings:
  min-players: 1
  countdown-seconds: 5
  broadcast-winner: true

clue-cracker:
  difficulties:
    easy:
      time-limit: 30
      puzzles:
        snowman:
          clues: "[COLD][3 BALLS][CARROT FACE]"
          answers:
            - "snowman"
            - "snow man"
            - "frosty"
          hint: "Built in winter"

        santa:
          clues: "[CHIMNEY][COOKIES][HO HO HO]"
          answers:
            - "santa"
            - "santa claus"
          hint: "Visits on Dec 25th"

rewards:
  points:
    base-amount: 15
    time-bonus:
      enabled: true
      per-second-remaining: 2

messages:
  player:
    won: "&a%player% &7cracked it! (answer: &f%answer%&7)"
    too-late: "&7Time's up. The answer was &f%answer%"

Naughty or Nice (chat)

Quick reaction judgement game! Santa needs help deciding if behaviors are naughty or nice. File: games/naughty-nice/naughty-nice.yml.

• Displays a scenario like "Sharing cookies with friends".
• Players type naughty or nice to answer.
• Fast-paced with short time limits (especially on hard).
• Great for Christmas events!

settings:
  min-players: 1
  countdown-seconds: 3
  broadcast-winner: true

naughty-nice:
  difficulties:
    easy:
      time-limit: 10
      scenarios:
        sharing_cookies:
          description: "Sharing cookies with friends"
          answer: nice

        breaking_snowman:
          description: "Knocking down someone's snowman"
          answer: naughty

    hard:
      time-limit: 5
      scenarios:
        # More ambiguous scenarios
        white_lie_feelings:
          description: "Telling a white lie to spare feelings"
          answer: nice

rewards:
  points:
    base-amount: 10
    time-bonus:
      enabled: true
      per-second-remaining: 3

messages:
  player:
    won: "&a%player% &7judged correctly! (answer: &f%answer%&7)"
    incorrect: "&cWrong judgement!"

Present Pick (GUI)

Multi-round elimination game where players pick wrapped presents in a GUI! One (or more) contains coal—pick it and you're eliminated. File: games/present-pick/present-pick.yml.

• Click-to-join system with a lobby phase.
• Players pick from a grid of wrapped presents each round.
• Coal eliminates players (unless they have an extra life).
• Bonus presents can award points or extra lives.
• Supports custom head textures for presents (1.16-1.21+).
• Multiple end-game modes when several players survive.

settings:
  min-players: 2
  countdown-seconds: 5
  broadcast-winner: true

lobby:
  wait-time: 15  # Seconds to wait for players to join

grid:
  rows: 3
  cols: 3

round:
  max-rounds: 8
  time-limit: 12
  reveal-delay: 2
  # Options: all_win, random_winner, continue, split_rewards
  multi-survivor-mode: all_win

bonuses:
  enabled: true
  types:
    points:
      chance: 0.12      # 12% per slot
      amount: 25
    extra_life:
      chance: 0.05      # 5% per slot

presents:
  wrapped:
    material: PLAYER_HEAD
    name: "&a&lWrapped Present"
    texture: "eyJ0ZXh0dXJlcyI6..."  # Base64 from minecraft-heads.com
  locked-in:
    material: LIME_SHULKER_BOX     # Shows enchant glow
  coal:
    material: COAL
    name: "&8&lCOAL!"

difficulties:
  easy:
    round-time: 15
    coal-count: 1
  hard:
    round-time: 8
    coal-count: 2  # Multiple coals!

rewards:
  points:
    enabled: true
    base-amount: 20

Present Pick Game Flow

1. Admin runs /ss start PRESENT_PICK easy
2. Standard countdown displays (5 seconds)
3. Clickable join message appears in chat
4. Players click to join during lobby phase (15 seconds)
5. Game rounds begin—pick a present before time runs out!
6. Reveals show who picked coal (eliminated) or bonuses
7. Last player standing (or survivors at max rounds) wins!

Multi-Survivor Modes

• all_win — All survivors get full rewards (default)
• random_winner — One random survivor wins
• continue — Keep playing until only 1 remains
• split_rewards — Divide points equally among survivors

Action (in‑world)

Complete in‑world tasks such as breaking/placing blocks, crafting, enchanting, trading, fishing, killing entities, etc.

File: games/actions/actions.yml. This section serves as the textual reference for every action type.

# Example (Enchant any tool)
- type: ENCHANT
  display: "Enchant any iron/diamond tool"
  requirements:
    items: ["minecraft:iron_pickaxe", "minecraft:diamond_pickaxe"]
    enchant: "all"
    level: 0
    amount: 1

Testing helpers: /simonsays test survival_combo or /simonsays test enchant_tool to start specific Action tasks defined in the hard difficulty presets.

Action Types

See the detailed sub‑sections below for each supported action type.

Action: BREAK_BLOCK

Keys: amount, material or materials (block ids). Event: BlockBreakEvent.

- type: BREAK_BLOCK
  display: "Chop 10 logs"
  requirements:
    amount: 10
    materials: ["minecraft:oak_log", "minecraft:spruce_log"]

Action: PLACE_BLOCK

Keys: amount, material or materials. Event: BlockPlaceEvent.

- type: PLACE_BLOCK
  display: "Plant 16 saplings"
  requirements:
    amount: 16
    material: "minecraft:oak_sapling"

Action: CRAFT_ITEM

Keys: amount, material/materials (result item ids). Event: CraftItemEvent. Shift‑click counts are estimated.

- type: CRAFT_ITEM
  display: "Craft torches and bread"
  requirements:
    amount: 2
    materials: ["minecraft:torch", "minecraft:bread"]

Action: SMELT_ITEM

Keys: amount, material/materials (output items). Event: FurnaceExtractEvent.

- type: SMELT_ITEM
  display: "Smelt 8 iron or glass"
  requirements:
    amount: 8
    materials: ["minecraft:iron_ingot", "minecraft:glass"]

Action: ENCHANT

Item filter: item or items. Enchants: enchant=all|name or enchants=list. level (0 = any), amount. Event: EnchantItemEvent.

- type: ENCHANT
  display: "Apply a level 3 combat enchant"
  requirements:
    items: ["minecraft:iron_sword", "minecraft:diamond_axe"]
    enchants: ["sharpness", "smite"]
    level: 3
    amount: 1

Action: DROP_ITEM

Keys: amount, material/materials. Event: PlayerDropItemEvent.

- type: DROP_ITEM
  display: "Drop 5 rotten flesh"
  requirements:
    amount: 5
    material: "minecraft:rotten_flesh"

Action: CONSUME_ITEM

Keys: amount, edible types or single material. Event: PlayerItemConsumeEvent.

- type: CONSUME_ITEM
  display: "Eat 3 foods"
  requirements:
    amount: 3
    types: ["minecraft:bread", "minecraft:cooked_beef"]

Action: KILL_ENTITY

Keys: amount, target entity/types; optional weapon_type (category like SWORD/AXE/BOW/CROSSBOW or specific item id). Event: EntityDeathEvent.

- type: KILL_ENTITY
  display: "Slay 5 mobs with a sword"
  requirements:
    amount: 5
    types: ["ZOMBIE", "SKELETON"]
    weapon_type: "SWORD"

Action: TAME_ENTITY

Keys: amount, optional types. Event: EntityTameEvent.

- type: TAME_ENTITY
  display: "Tame a pet"
  requirements:
    amount: 1
    types: ["WOLF", "CAT"]

Action: SHOOT_BOW

Keys: amount, optional hit_entity (boolean), optional target entity/types. Events: EntityShootBowEvent, ProjectileHitEvent.

- type: SHOOT_BOW
  display: "Hit 3 zombies with arrows"
  requirements:
    amount: 3
    hit_entity: true
    target: "ZOMBIE"

Action: TRADE_VILLAGER

Keys: amount, material/materials (result item ids). Event: InventoryClickEvent (merchant result slot).

- type: TRADE_VILLAGER
  display: "Complete 2 trades"
  requirements:
    amount: 2
    materials: ["minecraft:emerald", "minecraft:bread"]

Action: FISH

Keys: amount, material/materials (caught items). Event: PlayerFishEvent (CAUGHT_FISH).

- type: FISH
  display: "Catch 2 fish"
  requirements:
    amount: 2
    materials: ["minecraft:cod", "minecraft:salmon"]

Action: JUMP

Keys: amount. Event: PlayerMoveEvent (meaningful upward motion only).

- type: JUMP
  display: "Jump 20 times"
  requirements:
    amount: 20

Action: SNEAK

Keys: amount. Event: PlayerToggleSneakEvent.

- type: SNEAK
  display: "Toggle sneak 10 times"
  requirements:
    amount: 10

Action: SWIM

Keys: distance (blocks), optional require_swimming. Events: PlayerMoveEvent, EntityToggleSwimEvent.

- type: SWIM
  display: "Swim 100 blocks"
  requirements:
    distance: 100
    require_swimming: true

Action: MULTI_ACTION

Keys: amount: 1, actions: [...] where each subtask is a full action spec. All subtasks must complete.

- type: MULTI_ACTION
  display: "Survival combo"
  requirements:
    amount: 1
    actions:
      - type: BREAK_BLOCK
        display: "Chop 5 logs"
        requirements:
          amount: 5
          material: "minecraft:oak_log"
      - type: CRAFT_ITEM
        display: "Craft bread"
        requirements:
          amount: 1
          material: "minecraft:bread"

Action: THROW_SNOWBALL

Keys: amount. Event: ProjectileLaunchEvent (SNOWBALL). Great for Christmas-themed challenges!

- type: THROW_SNOWBALL
  display: "Throw 10 snowballs"
  requirements:
    amount: 10

Shop System

Players earn Tokens from winning games and can spend them in the shop. Tokens are separate from leaderboard Points. File: shop.yml.

Token Earning

• Winners earn tokens automatically (configurable per difficulty).
• Base amount + difficulty multipliers (easy: 1x, medium: 1.5x, hard: 2x).
• Admins can manually give/take/set tokens with /ss tokens.

Shop Items

Two reward types are supported:

• Commands — Run server commands on purchase (use %player% placeholder).
• Items — Give Minecraft items with custom name, lore, and player head textures.

shop:
  enabled: true
  gui:
    title: "&5&lShop"
    confirm-title: "&6Confirm Purchase"
  currency:
    name: "Tokens"
    name-plural: "Tokens"
    symbol: "T"
  tokens:
    per-win:
      enabled: true
      base-amount: 5
      difficulty-multiplier:
        easy: 1.0
        medium: 1.5
        hard: 2.0

categories:
  rewards:
    display-name: "&6Rewards"
    description: "&7Spend your tokens here!"
    icon: CHEST
    slot: 13

items:
  # Command reward example
  diamond_kit:
    category: rewards
    display-name: "&bDiamond Starter Kit"
    description:
      - "&7Receive a full set of diamond tools!"
      - "&eOne-time purchase"
    icon: DIAMOND
    price: 100
    one-time: true
    commands:
      - "minecraft:give %player% minecraft:diamond_pickaxe 1"
      - "minecraft:give %player% minecraft:diamond_sword 1"

  # Item reward example
  golden_apple:
    category: rewards
    display-name: "&6Golden Apple"
    description:
      - "&7A shiny golden apple!"
    icon: GOLDEN_APPLE
    price: 25
    item:
      material: GOLDEN_APPLE
      amount: 1

  # Custom head example
  custom_head:
    category: rewards
    display-name: "&dTrophy Head"
    icon: PLAYER_HEAD
    price: 150
    item:
      material: PLAYER_HEAD
      amount: 1
      name: "&d&lSimonSays Trophy"
      lore:
        - "&7A mark of excellence"
      texture: "eyJ0ZXh0dXJlcyI6..."  # Base64 from minecraft-heads.com

Shop Item Options

• price — Cost in tokens
• stock — -1 = unlimited, or set a number for limited stock
• one-time — If true, player can only buy once ever
• restock-interval — Seconds until stock replenishes (0 = no restock)

Leaderboard GUI

• Inventory UI with filters (Overall, Reaction, Unscramble, Trivia, Math, Action, Guess Number, Unreverse, Completion, Click Button, Hoverable, Shopping List, Random, Clue Cracker, Naughty Nice, Present Pick).
• Paging: 28 entries per page with Previous/Next controls.
• Player heads with rich lore; top 3 entries highlighted; title kept compact.
• Command: /simonsays leaderboard gui [overall|<type>] [page]
• Permission: simonsays.leaderboard.gui (default: true)

PlaceholderAPI

Identifier: simonsays — use as %simonsays_<name>%.

Full PlaceholderAPI keys are documented below.

Storage Backends

• YAML (default) — plugins/SimonSays/data/players.yml
  • settings.leaderboard-limit controls Top‑N depth
  • settings.broadcast-changes toggles point-change broadcast
• SQLite — file plugins/SimonSays/database.db (driver shaded)
• MySQL/MariaDB — configure host/port/credentials; prefers MariaDB driver (shaded)
• APIs provide ranks and Top‑N for both overall and per‑type leaderboards.

Economy (Vault)

Optional money rewards via Vault. Enable per mode or globally.

# Per-mode example (inside a game YAML)
rewards:
  economy:
    enabled: false
    amount: 100.0
    broadcast-message: true

# Global defaults (config.yml)
economy:
  enabled: false
  rewards:
    reaction: 100.0
    unscramble: 150.0
    trivia: 150.0
    action: 150.0
    math: 100.0

Message token: %money% uses the economy plugin’s formatting.

Troubleshooting

• Economy not working: Ensure Vault and a compatible economy plugin are installed; enable rewards.economy.
• Placeholders empty: Install PlaceholderAPI; check identifier is simonsays. Some values are blank when no game is active.
• Scheduler idle: Verify auto-run.enabled and that at least one enabled game meets its min-players requirement.
• Materials invalid: If using older server versions, ensure wordlists/configs don’t reference items introduced after your MC version.

FAQ

Q: Can I use gradients in messages?

A: Yes! Enable MiniMessage mode with messages.use-minimessage: true, then use gradient tags like <gradient:#ff0080:#ffc800>text</gradient>. See the MiniMessage Formatting section for full details and examples.

Q: What's the difference between legacy mode and MiniMessage mode?

A: Legacy mode (default) supports & color codes and hex colors but no gradients. MiniMessage mode adds gradients, hover text, click actions, and rainbow effects while keeping full backward compatibility with all legacy formatting. See the feature comparison.

Q: Will my existing config break if I enable MiniMessage?

A: No! The plugin automatically converts all legacy & codes and #hex colors when MiniMessage is enabled. Your existing configs will continue to work without any changes.

Q: Where do I add words/questions?

A: Under plugins/SimonSays/games/<mode>/wordlists/ or the mode's YAML file.

Q: How do I open the leaderboard?

A: /simonsays leaderboard gui [overall|<type>] [page] (permission simonsays.leaderboard.gui).

Support

Open an issue or join our Discord for help:

• Discord: https://discord.gg/5QzFAXQJuS
• Spigot Resource Discussion