⚡ TSeason — The Complete Minecraft SMP Season Lifecycle Engine

---

🌟 Why Choose TSeason?

Running repeated seasons on modern Minecraft servers typically forces administrators to coordinate dozens of disjointed plugins, manual world deletions, custom broadcast scripts, and permission resets. A single server hitch or crash during a world wipe often leads to corrupted files, duped items, or ruined player data.

TSeason replaces this fragile, stressful manual ordeal with a deterministic, crash-resilient, commercial-grade season lifecycle engine that feels like a premium plugin while being completely free and open-source.

---

🚀 Key Feature Showcases

🎬 Synchronized Cinematic Launch Protocol

Launch your seasons with a thrilling, synchronized event that requires zero client-side mods:

• 10..9..8..1 Synchronized Countdown: Real-time broadcasts, multi-stage titles, and actionbar alerts.
• Dynamic Adventure BossBar: Live progress indicator with automatic color-shifting from Gold to Bold Red during the final 3 seconds. Mid-countdown joining players are automatically synced.
• Scaling Audio Pitch: Scaling note-block pitch (0.6f → 2.0f) with dramatic bell accents in the final stretch.
• Smooth Anti-Jitter Player Freeze: Coordinates are locked while camera/head rotation remains 100% fluid. Block breaking, placing, PvP, and item dropping are strictly locked until world opening.
• The World Opens Fanfare: Instantaneous simultaneous player release, multi-layered victory fanfare audio, totem and firework particle bursts, and automated transition to Grace protection.
• Instant Admin Cancel: Easily abort any launch countdown at any time using /tseason season cancel.

🛡️ Deterministic State Machine Engine

Every phase of a season is governed by a strict, validated transition matrix:

IDLE ➜ COUNTDOWN ➜ LAUNCHING ➜ GRACE ➜ ACTIVE ➜ ENDING ➜ ARCHIVED ➜ IDLE

• Safety Over Flashiness: Destructive operations (world resets, inventory purges) can never trigger accidentally or run concurrently.
• In-Flight Crash Journaling: State transitions are tracked in atomic transaction journals (transition_journal.json). If power fails or the server crashes, TSeason prompts administrators with safe rollback tools upon restart.
• Crash-Safe Atomic File Storage: Vaults, passports, and configuration snapshots are written using atomic temporary file swaps (.tmp → atomic filesystem swap) to guarantee zero file corruption.

🎒 Cross-Season Player Vaults (/tseason vault)

Reward loyal players by letting them safely roll over select items to the next season:

• Exploit & Dupe-Proof: Built on native Bukkit serialization with container nesting prevention (Shulker Boxes & Bundles blacklist) and strict item blacklists.
• Tiered Unlocks: Grant custom vault capacities per player rank using Vault / LuckPerms permission nodes.

📜 Seasonal Passports & Lifetime Progression (/tseason passport)

Build long-term community retention:

• Lifetime vs. Seasonal Stats: Tracks playtime, mob/player kills, deaths, achievements, points, and milestones across seasons.
• Zero-Tick Playtime Tracking: Calculates playtime using timestamp deltas on join and quit — absolutely zero per-tick timers.
• Archival Hall of Fame: Historical snapshots of top leaderboards are automatically generated and preserved when a season concludes.

⚡ Performance-First (Folia & Paper Native)

• Zero Idle Overhead: No chunk scanners, no repeating entity loops, and no per-tick world checks.
• Native Folia Support: Seamlessly utilizes Folia's GlobalRegionScheduler, RegionScheduler, and AsyncScheduler alongside Paper's main-thread schedulers.
• Microscopic JAR Footprint (~175 KB): Extremely fast startup and minimal RAM allocation.

---

🎮 Archetype Season Presets

Get up and running in seconds with 5 pre-tuned archetypes:

Preset	Ideal For	Defaults
SMP	Vanilla Survival, Hermitcraft-style	30-Day duration, 1h grace, safe reset
LIFESTEAL	High-stakes competitive PvP	14-Day duration, 30m grace, strict finale
HARDCORE	Hardcore survival challenge	21-Day duration, 1h grace, no item vaulting
SURVIVAL	Casual community building	60-Day duration, 24h grace, preserved economy
BOXPVP	Fast-paced weekly wipe cycle	7-Day duration, 10m grace, in-place fast resets

---

🕹️ Commands & Permissions

Player Commands

Command	Permission	Description
/tseason	Default	Opens the interactive Season Hub GUI
/tseason info	Default	Displays current season state, remaining time, and grace status
/tseason vault	tseason.vault	Opens the player's cross-season item preservation vault
/tseason leaderboard [cat]	tseason.leaderboard	Views seasonal leaderboard rankings
/tseason passport [player]	tseason.passport	Inspects multi-season career statistics

Admin Commands

Command	Permission	Description
/tseason admin	tseason.admin	Opens the interactive Admin Dashboard GUI
/tseason setup	tseason.admin	Launches the interactive step-by-step setup wizard
/tseason preflight [id]	tseason.admin	Runs a comprehensive safety audit on target worlds and storage
/tseason season list	tseason.admin	Lists all configured season profiles
/tseason season start <id>	tseason.admin	Initiates the synchronized cinematic launch sequence
/tseason season cancel	tseason.admin	Aborts an active countdown launch sequence
/tseason season end	tseason.admin	Manually triggers the finale sequence and archives the season
/tseason season reset <id> confirm	tseason.admin	Safely triggers automated world resets and player migrations
/tseason backup [create]	tseason.admin	Creates an instantaneous compressed backup archive
/tseason reload	tseason.admin	Performs a zero-downtime transactional configuration reload

---

🔌 PlaceholderAPI Integration

TSeason includes a built-in PlaceholderAPI expansion:

• %tseason_state% — Current engine phase (e.g. Active, Grace Period, Countdown)
• %tseason_season_id% — Active season identifier (e.g. season-1)
• %tseason_season_name% — Active season display name (e.g. Season 1 (Origin))
• %tseason_time_remaining% — Human-readable remaining season duration (e.g. 14d 6h 30m)
• %tseason_grace_remaining% — Remaining grace period duration (e.g. 45m 12s)
• %tseason_player_vault_slots% — Number of unlocked vault slots for the player
• %tseason_player_points% — Player's lifetime career points

---

⚙️ Installation & Quick Setup

1. Drop TSeason-1.0.0.jar into your server's plugins/ directory.
2. Restart your server (Java 21 LTS or newer required).
3. Run the setup wizard in console or in-game:

   /tseason setup create season-1 SMP
   

4. Verify your environment with the pre-flight check:

   /tseason preflight season-1
   

5. Trigger the cinematic launch countdown:

   /tseason season start season-1
   

---