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.