# Seasons

Seasons provide time-limited competitions with fresh leaderboards and seasonal rewards. Players earn seasonal rank separate from their global Elo, and the season leaderboard keeps the Elo snapshot from the moment the season ends.

**Requires:** resource running · config/seasons.lua access

## How Seasons Work

Seasons cycle on a configurable schedule. Here's the flow:

1. **Season Start:** A new season begins; seasonal leaderboards reset.
2. **Earning Points:** Players earn seasonal rank through races.
3. **Season End:** Rewards distribute to top racers; seasonal rank resets and a season-end Elo snapshot is stored.
4. **Global Elo:** Resets to the default starting value for the new season.

Players see both global Elo and seasonal rank on their profile. Season dropdown leaderboards show that season's finishing Elo for each racer.

## Enabling Seasons

**Requires:** access to `config/seasons.lua`

1. Open `config/seasons.lua`:

```lua
-- File: config/seasons.lua
Seasons = {
    enabled = true,              -- EDIT THIS
    defaultLengthDays = 30,      -- EDIT THIS: how long each season lasts
    rotationCheckIntervalMs = 60000  -- EDIT THIS: how often to check for season rotation
}
```

2. Restart the resource.

## Configuring Seasonal Points

Points determine seasonal rank. Configure how races earn points:

1. Open `config/seasons.lua`:

```lua
-- File: config/seasons.lua
Seasons = {
    points = {
        firstPlace = 100,        -- EDIT THIS: points for 1st place
        secondPlace = 75,        -- EDIT THIS: points for 2nd place
        thirdPlace = 50,         -- EDIT THIS: points for 3rd place
        participation = 10       -- EDIT THIS: minimum points just for finishing
    }
}
```

2. Restart the resource.

## Configuring Seasonal Rewards

When a season ends, top placers receive money. Configure payout table:

1. Open `config/seasons.lua`:

```lua
-- File: config/seasons.lua
Seasons = {
    rewards = {
        money = {
            {
                place = 1,           -- EDIT THIS: 1st place
                account = 'bank',    -- EDIT THIS: bank or cash
                amount = 50000       -- EDIT THIS: payout amount
            },
            {
                place = 2,
                account = 'bank',
                amount = 30000
            },
            {
                place = 3,
                account = 'bank',
                amount = 20000
            }
            -- Add more as needed
        }
    }
}
```

2. Restart the resource.

> **Warning:** Test reward payouts on staging before production to avoid incorrect economy grants.

## Validating Seasonal Gameplay

1. Enable seasons and restart.
2. Run several ranked races with multiple players.
3. Check profiles and confirm players show seasonal rank separate from global Elo.
4. Open seasonal leaderboards and confirm they display only current season.
5. Simulate season end (or wait for natural rotation) and confirm payouts are applied.

> **Tip:** For testing, reduce `defaultLengthDays` to 1 so seasons rotate quickly.

## Next Steps

* **Progression:** [Global Elo and leaderboards](/vibesez/docs/features/progression.md)
* **Daily Rewards:** [Streaks and participation rewards](/vibesez/docs/features/daily-rewards.md)
* **Configuration Reference:** [config/seasons.lua](/vibesez/docs/configuration/season-config.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://vibesez.gitbook.io/vibesez/docs/features/seasons.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.