# Getting Started

**Version:** 2.0.7

## Installation

1. Stop the server.
2. Make sure KyuubiSoft Core is in the `mods/` folder, version 2.9.9 or newer. Season Pass does not load without it; with an older Core, update Core first.
3. Put `KyuubiSoftSeasonPass-2.0.7.jar` into `mods/`. When you update, remove the old `KyuubiSoftSeasonPass-*.jar` first.
4. Start the server. The plugin creates its data folder `mods/kyuubisoft_seasonpass/` and fills it with the default files.

The UI textures and the Season Pass item come with the jar. There is nothing else to install.

---

## Files after the first start

```
mods/
  KyuubiSoftCore-x.y.z.jar
  KyuubiSoftSeasonPass-2.0.7.jar
  kyuubisoft_seasonpass/
    config.json              main configuration (language, active season, Season Pass item)
    seasons/
      season_1.json          default season "Season 1: Explorer"
    localization/            en-US, de-DE, fr-FR, es-ES, pt-BR, ru-RU, pl-PL, tr-TR, it-IT
    players/                 one <uuid>.json (+ .bak) per player, created on join
    xp_event_state.json      only while a server-wide XP event runs
  kslang/                    language choice shared by all KyuubiSoft mods
```

With MySQL set up in KyuubiSoft Core, player data goes to the table `seasonpass_players` instead of `players/`. See [Configuration](./configuration#data-folder).

The server log shows lines like these on a working start:

```
[KyuubiSoft SeasonPass] Setting up Season Pass System...
[KyuubiSoft SeasonPass] Loaded 1 season definitions
[KyuubiSoft SeasonPass] Loaded 9 language(s): en-US(918) de-DE(918) ...
[KyuubiSoft SeasonPass] Currency: internal tokens
[KyuubiSoft SeasonPass] SeasonPassService using file storage: mods\kyuubisoft_seasonpass
[KyuubiSoft SeasonPass] Registered with Core TrackingService
[KyuubiSoft SeasonPass] Season Pass System started!
```

With KyuubiSoft Quests or KyuubiSoft Achievements installed, the log also shows "Quest XP: listening to KyuubiSoft Quests" or "Achievement XP: listening to KyuubiSoft Achievements".

---

## Start the first season

No season runs after installation. As an admin, start the default season:

```
/spadmin start season_1
/spadmin info
```

`/spadmin info` answers `Season: season_1 | Status: Active | Players: <online count>`. You can also start a season in the admin panel (`/spadmin panel`, section **Season**, button **Start season**).

:::note[No season, no progress]
Without a running season players earn no XP, `/sp open` answers "No season is currently active." and the Season Pass item is not handed out. While a season is **paused** players earn no XP and the HUD is hidden, but the book still opens.
:::

## Open the Season Pass

- **Season Pass item:** players get the book (a grimoire named "Season Pass") in the last hotbar slot (`hotbarSlot` 8) 3 seconds after joining, as long as they do not carry one already. Right-click opens the Season Pass.
- **Command:** `/sp open` (or `/ksseasonpass open`). `/sp` alone only prints the list of subcommands.
- **NPC:** a KyuubiSoft Core citizen with the ID `showcase_seasonpassplayer` opens the book.

The book opens on the **Tiers** tab at the page of your current tier. See [UI & HUD](./ui).

## Quick test

```
/spadmin start season_1
/spadmin grantxp YourName 5000
/spadmin grantpremium YourName
/sp open
```

With the default XP curve 5000 XP take you to tier 4 (admin XP goes through the same multipliers and caps as normal XP, so the same command after `grantpremium` gives x1.5). Claim the rewards in the book with a click on a reward card or **Claim all**.

---

## Before you open the season to players

The default season is an example. Check these points first:

1. **Premium currency.** The default season sells the premium pass for 1000 Gold Ingots (`premiumCurrencyId` `"item:Ingredient_Bar_Gold"`). Change it to the currency you want, for example `economy` (your economy plugin through KyuubiSoft Core) or `season_tokens`. See [Seasons](./seasons#premium-pass).
2. **Lootbag rewards.** The default season uses KyuubiSoft Core's default lootbags (`Default_Lootbag_Uncommon`, `Default_Lootbag_Rare`, `Default_Lootbag_Epic`, `Default_Lootbag_Legendary`). Replace them with your own lootbags if you like. Season files from before 2.0.0 keep their old IDs; the log lists unknown premium currencies and lootbag IDs at every start and reload.
3. **Command rewards.** The default commands (`emote_grant {player} ...`, `kstitles grant {player} ...`, `effect_give {player} ...`) are examples. Replace them with commands that exist on your server.
4. **End date.** A season only ends by itself when its `endDate` is set (`YYYY-MM-DD`). `durationDays` alone does not end it. Set the date in the season file or in the admin panel (section **Season**, field **End**).

All of this can be changed in the admin panel without a restart. If you edit the files by hand, run `/spadmin reload` afterwards.

---

## Next steps

- [Seasons](./seasons) - every field of a season file
- [Rewards](./rewards) - reward types
- [Challenges](./challenges) - challenge types and rotation
- [Commands](./commands) and [Permissions](./permissions)
- [Admin Panel](./admin-panel) - editing everything in game