• Server software: Spigot / Paper / Folia (scheduler-aware)
• Java: 17+
• Soft dependencies: Vault (economy), PlaceholderAPI (placeholders), ProtocolLib (optional extras), LuckPerms (optional perks)
• Storage backends: MongoDB, MariaDB/MySQL, JSON (fallback/testing)
• Optional auto-downloader: can fetch missing dependencies if enabled

Why servers buy ChatGames (buyer-focused)

• Your chat stops being dead. Players always have something to solve, react to, and compete for.
• Your server feels bigger. Constant rounds create momentum and “busy server” energy - even at mid player counts.
• Retention goes up. The “one more round” loop keeps people online longer.
• More reasons to donate. Optional multipliers/boosts/perks make ranks feel valuable without pay-to-win combat.
• It markets itself. Winners brag. Players spam screenshots. Activity becomes social proof.
• No disruption. Works on SMP, hubs, survival, factions, prisons - it’s an engagement layer, not a minigame takeover.
• Admins stay in control. Full enable/disable, weights, scheduling windows, and forced starts/stops for events.

Perfect for these server goals

• SMP owners: make chat active while players grind/build.
• Hub owners: give players something to do while queueing / exploring cosmetics.
• Prison owners: turn grinding into constant mini-competition.
• Networks: cross-server stats + leaderboards + shared economy integration.
• Events & seasons: run weekly contests with seasonal resets or prize tracks.

At a glance

• Plug & play - ships with sensible defaults and starter pools.
• Highly configurable - per-game timers, weights, difficulty, winners, pools, messages, rewards.
• Deep difficulty profiles - easy/normal/hard/insane style overrides for many games and challenges.
• Hints System - extremely well implemented hints system that supports every game/challenge.
• Goal Types - multiple goal types for each game like "time", "winners", "both". Defaults to "both".
• Max Winners - Each game/challenge can have multiple winners if configured like that.
• Complex Rewards Engine - fully complex and configurable rewards engine for each game/engine.
• Smart scheduler - simple interval mode or advanced time windows with minimum-online rules.
• Warmup system - optional countdown announcements for fair starts.
• Persistent stats - wins, rounds, fastest solves, toggles, per-game records.
• Leaderboard-ready - show top players in chat, GUI, scoreboard, holograms.
• Performance-first - async DB, minimal main-thread work, Folia-aware scheduling.
• Polished UI - titles, actionbars, bossbars, sounds, fireworks, hover/click events.
• Developer-ready - API + events for custom games and integrations.
• AI-ready - generate AI games/challenges or load scripts from files.
• Fully configurability per game/challenge - insanely configurable system per game/challenge.

What is actually inside the package

• One main engagement engine that handles rotation, winner detection, timeouts, rewards, logging, and UI.
• 22 registered built-in chat games available immediately after install.
• 20 registered built-in challenge types for real in-world objectives, plus AI-driven and sequence-driven flows.
• Deep config structure with global settings, per-game/per-challenge sections, difficulty overlays, hint config, warmups, progress messages, and reward tables.
• Persistent stats pipeline with JSON, MySQL/MariaDB, and MongoDB backends.
• Player-facing commands for stats, leaderboards, toggles, active round info, and Guess The Song controls.
• Admin command tree for forcing rounds, reloading, removing stats, mutating stats, viewing logs, and AI generation.
• PlaceholderAPI expansion with active-round placeholders, leaderboard placeholders, per-game wins/fastest stats, stage/progress placeholders, and hint placeholders.
• Developer API + Bukkit events for custom plugins, scoreboards, Discord bridges, reward hooks, and addons.
• Runtime dependency bootstrap through Libby plus optional jar auto-download for missing helpers when enabled.
• Bundled data/docs including aigames.json, aichallenges.json, AI_GAME_SCHEMA.json, and additional internal docs for maintainers.

How the configuration is structured
This matters because ChatGames is not a “random one-file chatgame plugin”. It is structured like a system. Once buyers understand the layout, setup becomes much easier and future edits become faster and safer.

• config.yml - engine behavior, scheduler, UI, storage, every built-in game/challenge, rewards, hints, warmups, and difficulty variants.
• messages.yml - command text, prefixes, help pages, status lines, stat labels, log formatting, and general plugin messaging.
• aigames.json - file-backed AI multi-stage game scripts.
• aichallenges.json - file-backed AI challenge scripts/objectives.
• songs/ - .nbs song files for Guess The Song.
• storage/ - JSON backend data folder when JSON is selected.

Universal section format for every game/challenge

• enabled - hard on/off switch for that entry.
• display - the display name shown to players.
• weight - how often the base variant is selected relative to others.
• announce-delay - pre-start delay in ticks before the round actually begins.
• timeout-ticks - total time window before timeout.
• max-winners - how many players can win that round.
• goal-type - time, winners, or both.
• case-sensitive - whether answers must match exact casing.
• pool - reusable word/question/item pool used by relevant games.
• messages.start / messages.success - extra per-entry message lines beyond the global system formatting.
• rewards - full reward table with money/commands/chance/splitting/placement/global execution.
• options - game-specific or challenge-specific behavior.
• difficulties - weighted variant overlays such as easy/hard/insane with their own option overrides.

Difficulty system (important and often overlooked)

• Most built-in entries ship with easy / hard / insane style variants or equivalent weighted profiles.
• Each difficulty variant has its own weight and its own option overrides.
• This means difficulty is not just cosmetic text - it can change timers, prompt styles, answer rules, target counts, sequence preset selection, hint strictness, song rules, and more.
• Buyers can keep one game enabled while still getting multiple experiences from that same game id.

Core Features (what you actually get)

1) Smart Game Rotation (no repetition fatigue)

• Weighted selection per game (control frequency precisely)
• Anti-repeat logic (avoid same game back-to-back)
• Per-game enable/disable without code edits
• Advanced scheduling (optional): time windows, intervals, “peak hours” boosts
• Minimum-online rules + per-world filters to prevent off-hours spam

2) Reward Engine (built for retention & monetization)

• Vault money rewards + optional multipliers
• Command rewards (keys, crates, items, permissions, rank perks)
• Reward tables (chance-based, tiered rewards, jackpot-style)
• Multiple winners (top 1 / top 3 / top X) with configurable payout scaling
• Presentation layer: broadcasts, titles, actionbars, sounds (all configurable)
• Cooldown gating (optional): reduce farming / keep rewards healthy

3) Competitive Stats, Records & Progression

• Player stats: wins, rounds played, streaks, fastest solve time, per-game records
• Global records: server-best solves (overall + per-game)
• Leaderboards: wins and fastest times (overall or by game)
• Opt-in/opt-out participation toggle per player
• Action logs: browse recent rounds with the admin audit log command /cga logs
• Export-friendly: structured storage for web panels / bots later

4) Professional Messaging & UI (the “premium” feel)

• Fully customizable prompts, start messages, win messages, fail messages
• Multiple message variants per event (prevents repetitive spam)
• Placeholders everywhere (chat, scoreboard, holograms, GUIs, titles, bossbars)
• Strict formatting support (colors, gradients if your formatter supports it)
• Optional “clean mode” (less spam) for minimalistic servers
• Bossbar phases for start/progress/win/timeout with smooth updates
• Adaptive hint engine with richer placeholders (masked output, next-char, progress-aware challenge hints)

5) Anti-Abuse Controls (buyer confidence)

• Case sensitivity control per game
• Input sanitization + length checks (no crash strings, no lag spam)
• Optional “first answer only” mode per player
• Participation toggle (per-player opt-out)
• Staff moderation hooks (cancel round, reroll, blacklist words/questions)

6) Performance & Stability (network-grade)

• Async DB reads/writes (no TPS drops during saves)
• Safe main-thread boundaries for Bukkit calls
• Clean task lifecycle (no orphaned schedulers)
• Optimized caches for active round state
• Designed for high chat throughput
• Folia-aware scheduler adapter for modern servers

Included Game Library (Built-In)
All games are short, addictive, and configurable. Each game supports per-game timers, winners, difficulty, pools, messages, hints, and reward profiles.

• Typing (type) - configurable prompt modes (plain, mixed_case, leet, symbols, chunks, mirror)
• Math (math) - solve fast math prompts with nested/power expression support
• Advanced Math (advanced_math) - harder algebra/expression rounds with longer timers
• Unscramble (unscramble) - decode scrambled words
• Trivia (trivia) - trivia questions with multiple valid answers
• Reverse (reverse) - type the reversed prompt correctly
• Unreverse (unreverse) - reverse the reversed string back to normal
• Random (random) - random code/sequence typing
• Variable / Solve for X (variable) - multi-pattern algebra (simple, distributive, both-sides, fraction)
• Fill Out (fillout) - advanced masking modes (random/vowels/consonants/cluster) with targeted hints
• Clickable (clickable) - click-to-answer chat prompts
• Hover (hoverable) - hover text to reveal the answer
• Guess The Number (guess_number) - guess the generated number
• Shopping List (shoppinglist) - memorize and type lists
• Stat Guesser (statguesser) - guess values from prompts
• Guess The Song (guess_the_song) - preview .nbs songs and guess the title in chat
• Cipher (cipher) - decode ciphers with hints
• Christmas (christmas) - holiday-themed prompt game
• Sequence Typing (sequence_typing) - complete multi-stage sequences
• Fast Reaction (reaction) - speed-based typing/reaction round
• Anagram (anagram) - a word or phrase formed by reordering the letters of another word or phrase, such as satin to stain
• AI Game (aigame) - dynamic multi-stage games driven by AI scripts

Hint & UX Highlights

• Fillout hints can reveal actual missing letters, not only generic prefix reveals.
• Regular game hints can expose adaptive placeholders such as masked answer format and next-character clues.
• Challenge hints include richer context (targets, progress, remaining objective counts).
• Sequence preset placeholders are resolved correctly in prompts (e.g. preset name/difficulty).

Action Challenges (the “server explodes” feature)
Not just chat answers - players compete by doing real tasks in the world. This drives movement, activity, and organic gameplay.

• Built-in standalone challenge types: Hunt, Mine, Place, Fish, Eat, Craft, Furnace, Biome Rush, Tame, Pickup, Damage Deal, Damage Take, Teleport, Level Gain, Command Sprint, Drop, Entity Interact, Risky Death, XP Gain, Sequence, and AI Challenge
• Advanced event hooks already supported by the engine: chat, commands, deaths, damage dealt/taken, bucket fill/empty, shearing, breeding, XP/level gains, teleports, block/entity interaction, pickup/drop tracking, and more for multi-step flows
• Sequence challenge: chain multiple steps into a single checklist-style challenge with preset selection by difficulty / rotation / random
• AI Challenge (aichallenge): procedural objectives generated or loaded from scripts
• Smart tracking: event-driven progress, time window, multi-winner support
• Fully configurable: targets, allowed worlds, per-step requirements, rewards
• Expanded default content: larger Minecraft-themed target sets and preset challenge flows out of the box
• SMP-friendly: creates reasons to move, gather, fight, travel, and interact - not just type

AI Systems (AI Games + AI Challenges)
AI doesn’t replace your existing content - it adds an endless pipeline of new rounds without manual setup.

• AI Game scripts: stored in aigames.json with multi-stage prompts, answers, validators, and hints.
• AI Challenge scripts: stored in aichallenges.json with objectives or multi-step checklists.
• Script variables: use {tokens} to randomize prompts/answers per round.
• Safe controls: AI generation disabled by default; requires API key and per-run limits.
• Reload-friendly: scripts load on startup and can be regenerated or extended anytime.
• Generation commands: /cg aigame generate [count], /cg aichallenge generate [count]

Premium Differentiators (why this isn’t “just another chatgames”)

• Structured configuration system - scalable, maintainable, not a mess of random keys.
• Modular architecture - games are isolated modules, not hardcoded spaghetti.
• Network-minded storage - Mongo/MySQL first-class, JSON for testing only.
• Folia-aware scheduling - modern server compatibility.
• A product page worth buying from - full docs, API, placeholders, real clarity.
• Support pipeline - built for real customers, not “good luck”.

Setup (realistic quick-start)

• Drop the jar in /plugins
• Start server (generates config + default pools + AI script files)
• (Recommended) Install Vault + economy plugin
• (Optional) Setup Mongo/MySQL for persistent stats/leaderboards
• (Optional) Enable PlaceholderAPI + scoreboard/hologram plugin
• Tune game weights + rewards + scheduler
• Done - rounds run automatically

Commands & Permissions

Main command aliases

• /chatgames
• /cg
• /chatgame

Player Commands

/chatgames - main command/help page

• Usage: /chatgames
• Permission: none

/chatgames stats [player] - view your own stats or another player's stats

• Usage: /chatgames stats, /cg stats, /cg stats <player>
• Permission: none
• Shows: wins, fastest, streak, best streak, rounds, win rate, toggle state, and per-game breakdown.

/chatgames toggle - opt out / opt back in

• Usage: /cg toggle
• Permission: none
• Notes: toggled players are ignored by round eligibility checks until re-enabled.

/chatgames top [wins|fastest] [gameId] - leaderboard lookup

• Usage: /cg top, /cg top wins, /cg top fastest, /cg top wins trivia, /cg top fastest guess_the_song
• Permission: none
• Notes: result count is controlled by chatgames.top-limit in config.

/chatgames games - list registered runtime entries

• Usage: /cg games
• Permission: none
• Shows: registered game ids, registered challenge ids, and active round/challenge if one exists.

/chatgames active - inspect the currently active round

• Usage: /cg active
• Permission: none
• Shows: display name, id, prompt, and remaining time.

/chatgames guessthesong <play|stop|replay> - control personal Guess The Song playback

• Usage: /cg guessthesong play, /cg guessthesong stop, /cg guessthesong replay
• Alias: /cg song <play|stop|replay>
• Permission: none
• Notes: only relevant during an active guess_the_song round and still obeys per-round play/replay limits.

Admin command aliases

• /chatgamesadmin
• /cga
• /cgadmin
• /chatgameadmin

Base admin permission: chatgames.admin

Admin Commands
/chatgamesadmin help - show admin help

• Usage: /chatgamesadmin help

/chatgamesadmin start <game|challenge> <id|random> - force a specific round type

• Examples: /cga start game trivia, /cga start challenge hunt, /cga start game random
• Compatibility: legacy /chatgamesadmin start <id> also works if the id uniquely matches a registered game or challenge.
• Notes: /chatgamesadmin start random starts a random game; for random challenge forcing use the engine subcommand below.

/chatgamesadmin stop [reason] - stop the currently active round

• Usage: /cga stop or /cga stop Maintenance

/chatgamesadmin toggleall [off|on] - globally disable/enable participation

• Usage: /cga toggleall off, /cga toggleall on
• Notes: off disables participation for everyone in storage; on re-enables it.

/chatgamesadmin remove <player> - reset a player's stored ChatGames data

• Usage: /cga remove <player>

/chatgamesadmin reload - reload config/messages safely

• Usage: /cga reload
• Notes: use this after editing config.yml, messages.yml, or script file references.

/chatgamesadmin logs [page] [per-page] - recent round audit log

• Usage: /cga logs, /cga logs 2 10
• Shows: recent rounds with id, completion state, winners, timestamps, difficulty, world, and prompt snapshot.

/chatgamesadmin stats <player> <set|add|toggle> <field> <value> [gameId] - mutate stored stats

• Base fields: wins, rounds, streak, beststreak, fastest, toggled
• Extended gateway fields: winsgame and fastestgame with a trailing gameId for backend-level per-game mutation.
• Examples: /cga stats Steve set wins 50, /cga stats Steve add rounds 10, /cga stats Steve set winsgame 25 trivia

/chatgamesadmin engine <start-random-game|start-random-challenge|stop> - low-level engine controls

• Usage: /cga engine start-random-game, /cga engine start-random-challenge, /cga engine stop

/chatgamesadmin aigame generate [count] - generate AI game scripts

• Requires: core.ai-generation.enabled: true and a valid API key.
• Notes: count is capped by core.ai-generation.max-count.

/chatgamesadmin aichallenge generate [count] - generate AI challenge scripts

• Requires: core.ai-generation.enabled: true and a valid API key.

Info command aliases

• /chatgamesreborn
• /cgr

/chatgamesreborn / /chatgamesreborn info - plugin information page

• Permission: none

/chatgamesreborn support - support link

• Permission: operator / console only

/chatgamesreborn reload - lightweight reload entrypoint

• Permission: operator / console only

Permission nodes

• chatgames.admin - access to /chatgamesadmin
• chatgames.admin.bypass - reserved bypass permission path configured in chatgames.admin.bypass-permission
• chatgames.play - required only if chatgames.require-permission is enabled

Command behavior notes, limitations & edge cases

• Console + stats: console must provide a player name for /cg stats <player>; only players may omit the target.
• Toggle semantics: /cg toggle edits the stored participation flag for that player. Toggled players are excluded from eligibility checks until toggled back on.
• Global toggle semantics: /cga toggleall off is a storage-wide state change, not a temporary chat mute. Treat it as an administrative participation kill-switch.
• Remove semantics: /cga remove <player> resets the stored ChatGames profile for that target rather than merely removing them from the current round.
• Reload semantics: /cga reload is not cosmetic. It tears down active runtime state and rebuilds settings/UI from disk.
• Logs pagination: negative or invalid page values are sanitized to safe positive defaults.
• Stats mutation: fastest values are millisecond-based; per-game fields like winsgame and fastestgame require the trailing gameId.
• Guess The Song controls: /cg guessthesong ... only matters while a guess_the_song round is active and the game is actually registered/enabled.
• Admin info reload path: /cgr reload exists, but for actual operational changes you should still document /cga reload as the standard workflow.

Getting Started

• API entry: dev.bytecore.chatgames.api.ChatGamesAPI
• Common use cases: custom GUIs, scoreboard hooks, Discord bots, rank perks, custom games, moderation tools

What the public API currently exposes cleanly

• ChatGamesAPI.manager() - direct access to the GameManager for low-level integrations.
• ChatGamesAPI.getStats(UUID) - stat snapshot for a player.
• ChatGamesAPI.registerGame(ChatGame) - register additional custom game implementations.
• ChatGamesAPI.leaderboard(gameId, limit) - top wins by game id.
• ChatGamesAPI.activePrompt() - quick access to the current active prompt.

For advanced integrations you can also use the manager directly to inspect active rounds, registered ids, stage/progress state, and other runtime data.


Core Helpers
Events
(Listen with EventHandler)

• ChatGameStartEvent - round started (game or challenge)
• ChatGameWinEvent - winner declared
• ChatGameEndEvent - round ended (completed or expired)

Code (Java):

public final class MyAddon extends JavaPlugin implements Listener {
    @Override public void onEnable ( ) {
        Bukkit. getPluginManager ( ). registerEvents ( this, this ) ;
    }

    @EventHandler
    public void onStart (ChatGameStartEvent e ) {
        getLogger ( ). info ( "ChatGames started: " + e. getId ( ) + " in world " + e. getWorldName ( ) ) ;
    }

    @EventHandler (ignoreCancelled = true )
    public void onWin (ChatGameWinEvent e ) {
        getLogger ( ). info ( "Winner: " + e. getPlayer ( ). getName ( ) + " in " + e. getDurationMs ( ) + "ms for " + e. getId ( ) ) ;
    }
}

PAPI Placeholders (PlaceholderAPI)

AI Script Files & Documentation

• AI games format: supports JSON array or {"games": []} wrapper with variables + stages.
• Schema reference: bundled AI_GAME_SCHEMA.json to validate scripts.
• AI challenges format: supports simple objectives or multi-step sequences.
• Defaults: the plugin ships with example scripts in aigames.json and aichallenges.json.

AI script file details (for owners who want endless custom content)

• AI Games: aigames.json supports either a raw JSON array of scripts or an object wrapper with a games array.
• AI Challenges: aichallenges.json supports either a raw JSON array or an object wrapper with a challenges array.
• Variables: both systems support tokenized content so prompts/answers/objectives can be randomized from reusable placeholders.
• Validation: bad ids, missing steps, missing targets, invalid amounts, and malformed objectives are rejected instead of silently polluting runtime.
• Schema support: AI_GAME_SCHEMA.json is bundled to help validate AI game documents externally.

Manual AI Game example (conceptual)
Manual AI Challenge example (conceptual)

Deep operational notes for server owners (edge-case coverage)







FAQ (what buyers ask)


Extra FAQ / Troubleshooting

Environment, optional dependencies & first-boot behavior

• Java requirement: Java 17 or newer. The plugin hard-fails on older Java versions and disables itself rather than running in a broken state.
• Plugin descriptor: api-version: 1.13 with modern Paper/Spigot compatibility and Folia-aware scheduling internals.
• Soft dependencies: ProtocolLib, Vault, PlaceholderAPI, and LuckPerms are all optional companions. The plugin still starts without them, but feature depth changes.
• Vault missing: money rewards are skipped; command rewards still work.
• PlaceholderAPI missing: the plugin still runs normally, but the chatgames expansion is not registered.
• ProtocolLib missing: plugin core still starts; protocol-level extras are simply unavailable.
• LuckPerms missing: no problem for normal runtime; it only matters if your own reward/admin setup expects LP-backed permission workflows.
• Automatic companion download: when core.download-dependencies is enabled, the plugin may attempt to fetch missing helper plugins such as ProtocolLib / PlaceholderAPI automatically. If your host blocks outbound downloads, disable this and install dependencies manually.

What gets created on disk after first startup
Exact storage contents depend on backend choice. JSON uses the folder layout above; SQL/Mongo move player/log persistence into the selected database backend while still keeping the normal plugin data folder for config/message/script assets.

Production deployment sequence (recommended if you want zero surprises)

• Step 1: install the jar and boot once on a test copy of your server.
• Step 2: confirm Java 17+, confirm the plugin enables cleanly, and confirm the songs folder + script files exist.
• Step 3: decide your backend early: JSON only for local testing/small servers, MySQL/MariaDB or MongoDB for serious production.
• Step 4: install Vault if you want money rewards; install PlaceholderAPI if you want scoreboards / holograms / tab / GUI integration.
• Step 5: prune the game pool before launch. Disable any rounds that do not fit your gamemode, economy, or chat culture.
• Step 6: configure scheduler rules, minimum-online values, allowed-world filters, and reward tables before exposing the system to players.
• Step 7: test with /cga start game <id> and /cga start challenge <id> before trusting automation.
• Step 8: once messages/rewards/weights look correct, use /cga reload for runtime-safe refreshes after edits.

Lifecycle notes: startup, reload, and shutdown

• Startup: the plugin boots config, checks backend validity, registers listeners/commands/placeholders, builds the registry, and starts rotation/autostart tasks.
• Startup edge case: Guess The Song always bootstraps the songs folder during enable. If it is empty, the plugin warns loudly and can optionally auto-download a starter pack.
• Full admin reload: /cga reload reloads config/messages and then rebuilds ChatGames runtime settings. Active rounds are cancelled as part of this flow so you do not keep stale timers/UI/settings alive.
• Info-command reload: /cgr reload is much lighter and should not be treated as the main runtime management command. For real production reconfiguration, prefer /cga reload.
• Shutdown: active rounds are stopped, scheduler tasks are cancelled, bossbar/UI tasks are shut down, and storage is flushed before backend shutdown.
  
  

Stats, Leaderboards & Storage

• Tracked by default: wins, rounds, fastest, toggled status, per-game bests
• Leaderboards: overall or per-game top wins / fastest solves
• Database support:
  • MongoDB - recommended for networks
  • MariaDB/MySQL - standard SQL
  • JSON - fallback/testing (don’t use in production)
• Designed for scale: async persistence + low overhead

Exactly what is tracked

• Overall stats: wins, fastest time, rounds played, current streak, best streak, toggle state.
• Per-game stats: wins-by-game and fastest-by-game maps.
• Logs: game/challenge id, finish timestamp, completion state, winner list, prompt snapshot, started-at timestamp, difficulty, and world.

Backend notes

• JSON uses a dedicated storage folder with configurable pretty printing, flush interval, atomic writes, backups, shard depth, and optional eager loading.
• SQL includes host/port/database/user/password settings, table prefixing, connection pool sizing, and timeout tuning.
• Mongo includes URI/database/collection prefix settings and wildcard index support.
• Leaderboard cache is tunable to reduce repeated expensive reads while still keeping rank displays fresh.

Eligibility, scheduler behavior & runtime edge cases






Servers using ChatGames: Reborn
You can request your server to be added here!

• kyodo.network | Kyodo Network
• seiky.net | Seiky Network

• Redistribution of this plugin to other individuals, networks, or websites is strictly prohibited.
• This plugin is licensed for use exclusively on your server or network.
• Refunds are not available.
• If you need help, open a discussion or use support - issues are handled quickly.