MazeSprinters 0.1

Transform your server with handcrafted maze runs, co-op puzzles, and speed-driven challenges.

What is Maze Sprinters?
Maze Sprinters is a premium mini-game plugin that drops players into procedurally generated arenas filled with twisting corridors, optional co-op gates, hidden loot chests, and dynamic scoreboards. Every race feels fresh thanks to themed presets, difficulty scaling, and reward-driven progression.

Core Gameplay Loop

- **Single** – Solo runners dive straight into adventure-ready mazes with difficulty-scaled rewards.
- **Group** – Queue friends with join codes, launch together, and compete for the best completion time.
- **Co-op Puzzle** – Two-player runs that require two synchronized pressure plates to be pressed to unlock the goal block.

Feature Highlights
- Procedural Mazes – Fast generation with biome-aware themes, ambient lighting, and safety walls to prevent griefing.
- Solo & Co-op Modes – Create single-player sprints or two-player co-op puzzles with synchronized pressure plates.
- Live Scoreboards – Per-maze objectives, times, and participant tracking via configurable scoreboards.
- Loot & Progression – Drop configurable chests, award XP, and integrate server economies through Vault.
- Admin Toolset – In-game editors for themes, difficulties, loot tables, configuration toggles, and live adjustments.
- Lifecycle Events – Hook into start, early-leave, and completion events to trigger rewards, analytics, or broadcast effects.

Why Servers Love It
- Zero setup grind: the world service boots a dedicated maze dimension and manages chunk safety automatically.
- Fully localized messages and GUI prompts for streamlined player onboarding.

Key Values
- Replayability – Infinite maze layouts with smart hint trails and co-op gating.
- Monetization Ready – Premium experience, VIP whitelists, and Vault-based rewards.
- Performance – Async generation pipelines with main-thread safe world edits tested on production servers.
- Polish – Particle finish markers, ambient lighting, and narrated tutorials keep the experience accessible.

Commands & Permissions Snapshot

• /maze start – Queue or generate a maze run and distribute join codes once ready.
• /maze go – Launch your queued maze, teleporting the party into the entrance.
• /maze join <mazeId> <code> – Join a friend’s lobby with their maze ID and access code.
• /maze leave – Exit the current maze run and restore inventory state.
• /maze list – View active mazes and their joinability status.
• /maze hint – Request a particle hint trail, respecting cooldowns.
• /maze config – Toggle live configuration options through the admin menu.
• /maze theme – Edit or preview maze themes in-game.
• /maze difficulty – Manage difficulty profiles, XP balance, and economy tuning.
• /maze loot – Curate loot tables and chest drops.
• Permissions – Namespaced as mazesprinters.* for fine-grained gameplay, editor, and economy control.

Premium Resource Positioning
Maze Sprinters is engineered as a turnkey attraction for mid-to-large servers that want a polished parkour alternative.

Launch Maze Sprinters today and turn your lobby into a competitive maze arena!

1. Overview
Maze Sprinters is a competitive mini-game plugin that generates themed maze arenas on demand. It has rich in-game editors, optional Vault economy support, and an extendable API for network operators. Lifecycle events (launch, leave, completion) let you wire custom rewards, analytics, or spectator systems into every run.

2. System Architecture
- Core Loader: Boots configuration, prepares the dedicated maze world, and wires session tracking, scoreboards, and economy hooks on enable.
- Maze Generation Pipeline: Builds layouts asynchronously, applies biome-aware themes, places loot, and registers new maze instances for active sessions.
- Session & Scoreboards: Tracks every participant from queue to finish while broadcasting progress and objectives through live scoreboards.
- Command Surface: The `/maze` command family covers player actions (start, join, go, hint) and administrative controls for setup and moderation.
- Editor Suite: GUI/chat editors let staff tweak difficulties, presets, loot, and toggles mid-season without server restarts.

3. Configuration & Messages
- Primary configuration sits in `config.yml` with sections for world setup, generation padding, ambient lighting, co-op settings, economy toggles, and message customization.
- All chat prompts and notifications can be localized through the `config.yml`, allowing admins to brand announcements, rewards, joins, and tutorial prompts.

4. Economy Integration via Vault
- Manager: The Vault integration layer detects providers, checks affordability, handles entry fee withdrawals, completion rewards, and optional refunds when players leave early.
- Configuration: Enable under `economy.enabled` in `config.yml`. Define per-difficulty `entry-cost`, `completion-reward`, optional `speed-bonus`, and `refund-on-leave` settings.
- Permissions:
- `mazesprinters.economy.receive` – Required to get payouts.
- `mazesprinters.economy.bypass-cost` – Allows free entry and blocks refunds.
- Workflow:
- Entry checks occur before runners are launched via commands or GUI confirmations.
- On completion, the plugin fires `MazeRewardEvent`, which the Vault integration listens to for payouts.
- Leaving mid-run can trigger refunds if the economy refund setting is enabled.

5. Event API – Maze Lifecycle Hooks
- MazeStartEvent: Fired moments before a runner is teleported into a maze. Provides the launching player, maze instance, and session group so you can log launches, spawn cosmetics, or gate extra requirements.
- MazeLeaveEarlyEvent: Triggered when a player uses `/maze leave` before finishing. It supplies the player, maze (if still available), and session group context for logging, messaging, or add-on side effects.
- MazeRewardEvent: Located at `src/main/java/de/liebki/mazeSprinters/economy/MazeRewardEvent.java`. Fired after a player completes a maze and XP has been awarded. Payload includes the player, difficulty profile, completion time, granted XP, suggested money reward (overrideable), and cancellable flag.

6. Extensibility
- Loot & Themes: New presets are quick to build by cloning existing themes and iterating with the in-game editors.
- Scoreboards: Sidebar layouts are fully configurable, letting you highlight objectives, timers, or branding.

7. Administration Playbook
- World Management: Mazes run inside a dedicated world space with automatic chunk loading and safety defaults. `/maze tp` returns staff to the maze spawn.
- Launching Mazes: `/maze start <difficulty> <theme>` optionally flagged with `joinable` and `cooppuzzle`. Owners share the generated join code, then trigger `/maze go` once the group is ready.
- Hints & Accessibility: `/maze hint` supplies particle trails—adjust cooldowns, counts, and ambient lighting in `config.yml`.
- Maintenance: `/maze list` enumerates active runs; `/maze delete <id>` can be added if you expose the manager through custom commands.

8. Deployment Notes
- Requires Spigot 1.21.8
- Optional dependencies: Vault and any compatible economy plugin.
- Bundle the provided resource pack or ambient textures if you ship themed presets.