SeasonFlow

Scheduled content unlocks and server-wide community goals for Paper servers.

Players rush Netherite and the dragon in a week, get bored, and leave — so owners reset the map over and over. SeasonFlow fixes that by pacing your server: define a season, and as it progresses the world border grows in stages, the Nether and the End unlock on a schedule, and everyone contributes to shared goals ("mine 5,000 diamond ore together") that trigger new unlocks when completed.

✨ Features

• 📅 Season lifecycle — one active season with a start date (or manual start) and a duration in days.
• 🌍 Gradual world border — the border expands automatically as stages activate, with a smooth animation.
• 🔒 Dimension locks — Nether and End portals stay blocked until their stage unlocks them; players get a friendly message instead of a hard denial.
• 🤝 Community goals — server-wide counters for block breaking, mob kills and item crafting. Every player's contribution goes into one shared counter; completion fires a broadcast, a title and a sound, and can unlock stages.
• 🗓️ Stage timeline — stages trigger by season day, by calendar date, or when a goal completes. Each stage can grow the border, open a dimension and broadcast a message. Stages fire exactly once, even across restarts.
• 💾 Crash-safe persistence — progress is stored in SQLite. Goal counters are batched to disk asynchronously and flushed on shutdown, so heavy mining never causes main-thread disk I/O.

🕹️ Commands

Command	Description	Permission
/season	Season summary: current stage, day counter, locked dimensions	seasonflow.use (default: everyone)
/season goals	Active community goals with progress bars and percentages	seasonflow.use
/season timeline	Upcoming stages and the unlock schedule	seasonflow.use
/season reload	Reload config.yml without breaking the running season	seasonflow.admin (default: op)
/season start	Start the season now (manual/testing)	seasonflow.admin
/season stop	End the active season	seasonflow.admin
/season advance <stageId>	Force-activate a stage (testing)	seasonflow.admin
/season setprogress <goalId> <n>	Set a goal counter manually (testing/corrections)	seasonflow.admin

Aliases: /sf, /seasonflow.

⚙️ Configuration

A fully commented config.yml is generated on first start. Example:

season:
  name: "Season 1: A New Beginning"
  auto-start: true
  start-date: "2026-08-01 00:00"   # leave empty to start with /season start
  duration-days: 60

world:
  name: "world"
  border:
    initial-size: 2000

stages:
  - id: "nether-open"
    trigger:
      type: "day"          # day | date | goal
      value: 7
    unlocks:
      dimension: "NETHER"
      border-size: 4000
      broadcast: "&cThe Nether is now open!"
  - id: "end-open"
    trigger:
      type: "goal"
      value: "diamonds-goal"
    unlocks:
      dimension: "THE_END"
      broadcast: "&5The End has opened! The dragon awaits."

goals:
  - id: "diamonds-goal"
    display: "Community Diamond Mining"
    type: "BLOCK_BREAK"    # BLOCK_BREAK | ENTITY_KILL | ITEM_CRAFT
    target-material: "DIAMOND_ORE"   # single value or a list
    amount: 5000
    on-complete-broadcast: "&bCommunity goal complete: Diamonds!"

locked-dimensions:
  - "NETHER"
  - "THE_END"

• trigger.type: day fires on season day value (0 = season start), date fires at a yyyy-MM-dd HH:mm timestamp, and goal fires when the referenced goal completes.
• target-material accepts one value or a list; material names are resolved with Material.matchMaterial, so both 1.20 and 1.21 names work.
• Creative-mode block breaks are not counted, and goals only count while a season is active.

🚀 Installation

1. Drop the jar into your server's plugins/ folder.
2. Start the server once to generate plugins/SeasonFlow/config.yml.
3. Edit the config (season dates, stages, goals) and run /season reload — or restart.

Requirements: Paper or Purpur 1.20.x – 1.21.x, Java 21. The SQLite JDBC driver is declared in plugin.yml's libraries section and is downloaded automatically by the server — no manual dependency setup.

💾 Data & resetting

All progress (season state, goal counters, unlocked dimensions, stage history) lives in plugins/SeasonFlow/seasonflow.db. To start a completely fresh season, stop the server and delete that file. Stage and goal definitions live only in config.yml, so editing them never corrupts stored progress.

📦 Source

Source code and issue tracker: CyberSoldier112/seasonflow