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.

Game Modes

Reaction
Unscramble
Trivia
Math
Guess Number
Unreverse
Completion
Action (in‑world tasks)

Highlights

Easy/Medium/Hard with per‑mode wordlists/questions
Auto‑run scheduler with min/max intervals
Vault rewards + command rewards
YAML / SQLite / MySQL storage

Integrations

Vault (economy rewards)
PlaceholderAPI (placeholders + Top‑N)
Kyori Adventure (MiniMessage optional)

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

Installation

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

Requirements

Spigot/Paper 1.16+ (works with 1.13+ content)
Java 8+

Optional

Vault + economy plugin (rewards)
PlaceholderAPI (placeholders)

Commands

/simonsays start <gametype> <difficulty> [-f]
/simonsays stop
/simonsays status
/simonsays reload
/simonsays test <survival_combo|enchant_tool>
/simonsays leaderboard gui [overall|reaction|unscramble|trivia|math|action|guess_number|unreverse|completion] [page]

Alias: /ss

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 (default: op)
simonsays.leaderboard.gui — Open leaderboard GUI (default: true)

Configuration (config.yml)

Key top‑level options:

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

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]

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

messages.use-minimessage: when true, text is parsed via Kyori MiniMessage (<gradient:...> etc.). Escape </> as <lt>/<gt>.
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 + MiniMessage Hover/Click

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
MiniMessage hover/click (optional): set messages.use-minimessage: true and route prompts/win to the chat channel to use tags like <hover:show_text:'…'>, <click:copy_to_clipboard:'…'>.

messages:
  use-minimessage: true
  player:
    case-hint: "&eClose! Check capitalization."

Note: Hover/click actions only apply in chat. Titles/actionbar/bossbar do not support click events.

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
- rewards.economy: Vault money (if Vault installed)
Messages: use legacy & colors (with hex) or MiniMessage when enabled.

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)"

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%"

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%"

Action (in‑world)

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

File: games/actions/actions.yml. See also docs/ACTIONS.md for a textual reference.

# 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"

Leaderboard GUI

Inventory UI with filters (Overall, Reaction, Unscramble, Trivia, Math, Action, Guess Number, Unreverse, Completion).
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>%.

State & Timing

current_game_type, current_game_type_human
game_win_time, game_win_time_formatted_s, ..._seconds
time_until_game, time_until_game_formatted_s, ..._seconds

Scores (requesting player)

reaction_score, unscramble_score, trivia_score, math_score, action_score, guess_number_score, unreverse_score, completion_score, total_score

Ranks

overall_rank and per‑type <type>_rank

Top‑N Lists (global)

<scope>_player_N
<scope>_score_N
<scope>_rank_N → Name - Score
Scopes: overall, reaction, unscramble, trivia, math, action, guess_number, unreverse, completion

See placeholders.md and docs/PLACEHOLDERS.txt in this repository for full details and examples.

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 MiniMessage formatting? A: Yes. Set messages.use-minimessage: true. Escape literal < or > as <lt>/<gt>.

Q: Where do I add words/questions? A: Under plugins/SimonSays/games/<mode>/wordlists/ or the mode’s YAML.

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