SimpleQuiz

A lightweight, high-performance automated quiz plugin designed for modern Minecraft servers (Paper 1.21.1+)

English | 简体中文

---

🌟 Introduction

SimpleQuiz is designed to increase server activity by providing automated math problems and customizable fill-in-the-blank questions, creating an engaging and interactive experience for players.

The plugin uses a dynamic timing mechanism based on server TPS calculations to ensure accurate operation even under high server load and low TPS conditions.

---

✨ Core Features

Dual-Mode Question System:

• Math Mode: Supports addition, subtraction, and multiplication. Includes built-in easy-multiplier logic to prevent overly difficult multiplication problems.
• Fill-in-the-Blank Mode: Supports standard text matching and a True/False mode (automatically appends Yes/No prompts).

TPS-Based Timing: Dynamically calculates the number of game ticks to wait based on the server's average TPS, minimizing countdown inaccuracies caused by TPS fluctuations.

Modern Item Support: Uses Paper 1.20.6+ native binary serialization (Base64), fully supporting custom reward items including enchantments, Data Components, and NBT attributes.

Standalone Question Bank: Fill-in-the-blank questions live in their own questions.yml, separate from config.yml. Each question carries a stable id and a validated flag. Question banks from older versions are migrated out of config.yml automatically on first startup.

Player-Driven Question Correction: When the answer to an unvalidated question is revealed, players see a clickable report prompt. Reports are persisted to reports.yml, pushed to online admins in real time, and reviewed with /simplequiz report list|view. Admins fix the question, reload, and mark it validated — after which the prompt disappears for that question.

Ban System: Robust UUID-based persistent ban logic, supporting targeted blocking of both online and offline players.

Feedback System: Supports customizable BossBar countdown displays and sound effect notifications.

Per-Player Preferences: Each player can turn off their own countdown bar or quiz sounds with /simplequiz toggle, or opt out of the quiz entirely — opted-out players receive no quiz messages, bar or sounds, and cannot win a round. The settings are stored on the player and survive relogging.

---

🛠 Build & Development

Requirements

• Java: 21
• Platform: Paper API 1.21.1-R0.1-SNAPSHOT
• Build Tool: Gradle 8.x

Gradle Build Process

1. Clone the repository:

git clone https://github.com/DiamondPie/SimpleQuiz.git

2. Build locally:

./gradlew clean build

The generated JAR file will be located in the build/libs/ directory.

---

📦 Developer Integration (Maven)

This project automatically generates and publishes pom-default.xml via GitHub Actions. Maven users can integrate it as a dependency using the following steps.

1. Obtain the POM File

Download the corresponding version of pom-default.xml from the GitHub Release page. This file contains all necessary metadata required to build SimpleQuiz and resolve its dependencies.

2. Add as a Dependency

If you have installed the project into your local Maven repository, or are referencing the published artifact, add the following to your pom.xml:

<dependencies>
    <dependency>
        <groupId>com.diamondpie</groupId>
        <artifactId>simplequiz</artifactId>
        <version>VERSION</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
    <repository>
        <id>papermc</id>
        <url>https://repo.papermc.io/repository/maven-public/</url>
    </repository>
</repositories>

---

🚀 Continuous Integration (GitHub Actions)

This project includes an automated release workflow. When a tag starting with v (e.g., v1.0) is pushed, the workflow automatically:

1. Initializes the environment using Temurin JDK 21
2. Builds the project and generates a production-ready JAR
3. Extracts CHANGELOG.md as the Release description
4. Uploads both the JAR file and the Maven POM to the GitHub Release assets for easy developer integration

---

📜 Commands

Command	Permission	Description
/simplequiz reload	simplequiz.admin	Reloads configuration and validates reward item integrity
/simplequiz start [type] [id] [seconds]	simplequiz.admin	Forces a quiz round to start; with text you may name a question id, and the duration can be overridden
/simplequiz ban <player>	simplequiz.admin	Adds a player to the UUID blacklist and broadcasts it server-wide
/simplequiz unban <player>	simplequiz.admin	Removes a player from the blacklist (supports offline names)
/simplequiz encodehand	simplequiz.admin	Serializes the item in hand into a Base64 string
/simplequiz report <id> [reason]	simplequiz.use	Reports a wrong or ambiguous question (usually via the click prompt)
/simplequiz toggle <bossbar|sound|quiz> [on|off]	simplequiz.use	Switches the player's own countdown bar, quiz sounds, or participation; omit on/off to flip it
/simplequiz report list	simplequiz.admin	Lists every question with pending feedback
/simplequiz report view <id>	simplequiz.admin	Shows the question, its answer and all reports for it
/simplequiz report validate <id>	simplequiz.admin	Marks the question as validated and clears its feedback
/simplequiz report resolve <id>	simplequiz.admin	Clears the feedback without marking the question validated

---

🔧 Configuration

The generated config.yml file includes detailed comments for reference and customization.

Question Bank (questions.yml)

fill:
  - id: q1              # Required and unique; auto-filled on startup if missing
    validated: true     # Optional, defaults to false — false shows the report prompt to players
    quiz: "Question text"
    answer:
      type: text        # text: value is a list of accepted answers
      value: [ "A" ]
  - id: q2
    quiz: "True or false?"
    answer:
      type: judge       # judge: value is true/false, matched against judge.ansYes / judge.ansNo
      value: true

Run /simplequiz reload after editing.

Feedback Workflow

1. A player clicks the report prompt shown after an unvalidated question is revealed.
2. Online admins get an instant notification with a [view] button; the report is also written to reports.yml and the console log.
3. The admin runs /simplequiz report view <id>, edits questions.yml, then /simplequiz reload.
4. /simplequiz report validate <id> marks the question as checked and clears its feedback.

report.auto-hide-threshold in config.yml can additionally stop a question from being drawn once enough distinct players have reported it (0 disables this).

report.auto-validate-rounds (default 2) closes the loop from the other side: once an unvalidated question has been asked that many rounds in a row without anyone reporting it, the plugin marks it validated by itself. The check for a round is deferred until the next round starts, so late clicks on the report prompt still count. Any pending feedback on the question breaks the streak, and the whole thing is silent — it only ever appears in the console log, never in chat. Set it to 0 to disable.