> ## Documentation Index
> Fetch the complete documentation index at: https://www.kitemc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 赛季配置

<span id="赛季配置" />

赛季系统管理通行证的周期性重置和特殊活动。

<h2 id="赛季概念">
  赛季概念
</h2>

* 每个赛季有独立的开始和结束时间
* 赛季结束时，玩家进度可选择重置
* 不同赛季可以有不同的任务和奖励
* 支持无限期赛季（永久运行）

<h2 id="赛季管理">
  赛季管理
</h2>

<h3 id="开启赛季">
  开启赛季
</h3>

**方式一：命令开启**

```
/arcpass admin season start <赛季名称>
```

**方式二：GUI 开启**

1. 执行 `/arcpass admin`
2. 点击「开启赛季」
3. 输入赛季名称
4. 确认开启

<h3 id="结束赛季">
  结束赛季
</h3>

```
/arcpass admin season end
```

<h3 id="查看赛季信息">
  查看赛季信息
</h3>

```
/arcpass admin season info
```

<h2 id="赛季配置-1">
  赛季配置
</h2>

在 `config.yml` 中配置赛季行为：

```yaml theme={null}
# 赛季设置
seasons:
  # 赛季结束时的行为
  on-end:
    # 重置玩家等级
    reset-level: true
    # 重置玩家经验
    reset-experience: true
    # 重置已完成任务
    reset-quests: true
    # 保留已购买的档位
    keep-purchased-tiers: true
    # 保留已领取的奖励记录
    keep-claimed-rewards: false

  # 自动赛季（可选）
  auto:
    enabled: false
    # 赛季持续时间（天）
    duration-days: 90
    # 赛季结束前通知（天）
    notify-before-end: [7, 3, 1]
```

<h2 id="赛季特殊任务">
  赛季特殊任务
</h2>

在 `quests/seasonal/` 目录下创建赛季专属任务：

```yaml theme={null}
# quests/seasonal/main_story.yml

chapter_1:
  type: seasonal
  display-name: "&6第一章：新的开始"
  description:
    - "&7完成新手引导任务"
  icon: BOOK
  experience-reward: 100
  objectives:
    - type: block_break
      block: OAK_LOG
      amount: 10
      description: "&7砍伐 10 棵树"

chapter_2:
  type: seasonal
  display-name: "&6第二章：地下探险"
  description:
    - "&7探索地下世界"
  requires:
    - chapter_1
  icon: IRON_PICKAXE
  experience-reward: 150
  objectives:
    - type: block_break
      block: IRON_ORE
      amount: 30
```

<h2 id="赛季奖励">
  赛季奖励
</h2>

<h3 id="赛季结束奖励">
  赛季结束奖励
</h3>

根据最终等级发放奖励：

```yaml theme={null}
# config.yml
seasons:
  end-rewards:
    # 达到 10 级的奖励
    10:
      - reward_season_badge_bronze
    # 达到 50 级的奖励
    50:
      - reward_season_badge_silver
    # 达到 100 级的奖励（满级）
    100:
      - reward_season_badge_gold
      - reward_season_title
```

<h3 id="排行榜奖励">
  排行榜奖励
</h3>

```yaml theme={null}
seasons:
  leaderboard-rewards:
    # 第 1 名
    1:
      - reward_champion_title
      - reward_exclusive_item
    # 第 2-3 名
    2-3:
      - reward_top3_title
    # 第 4-10 名
    4-10:
      - reward_top10_badge
```

<h2 id="赛季数据">
  赛季数据
</h2>

<h3 id="数据存储">
  数据存储
</h3>

赛季数据存储在数据库中：

* 当前赛季信息
* 历史赛季记录
* 玩家赛季进度

<h3 id="数据迁移">
  数据迁移
</h3>

赛季结束时的数据处理：

```yaml theme={null}
seasons:
  data:
    # 保存历史数据
    archive-history: true
    # 历史数据保留数量
    max-history: 10
```

<h2 id="赛季通知">
  赛季通知
</h2>

<h3 id="赛季开始通知">
  赛季开始通知
</h3>

```yaml theme={null}
seasons:
  notifications:
    start:
      # 全服公告
      broadcast: true
      # 标题通知
      title:
        enabled: true
        title: "&6新赛季开始！"
        subtitle: "&e%season_name%"
```

<h3 id="赛季结束通知">
  赛季结束通知
</h3>

```yaml theme={null}
seasons:
  notifications:
    end:
      broadcast: true
      title:
        enabled: true
        title: "&c赛季结束"
        subtitle: "&7感谢您的参与"
      # 提前通知
      warnings:
        - days: 7
          message: "&e赛季将在 7 天后结束！"
        - days: 1
          message: "&c赛季明天结束！抓紧完成任务！"
```

<h2 id="无限期赛季">
  无限期赛季
</h2>

如果不需要赛季重置，可以配置永久赛季：

```yaml theme={null}
seasons:
  permanent:
    enabled: true
    # 永久赛季不会自动结束
    # 需要手动结束或切换
```

<h2 id="api-集成">
  API 集成
</h2>

<h3 id="赛季事件">
  赛季事件
</h3>

```java theme={null}
@EventHandler
public void onSeasonStart(SeasonStartEvent event) {
    Season season = event.getSeason();
    // 处理赛季开始
}

@EventHandler
public void onSeasonEnd(SeasonEndEvent event) {
    Season season = event.getSeason();
    // 处理赛季结束
}
```

<h3 id="赛季数据查询">
  赛季数据查询
</h3>

```java theme={null}
ArcPassAPI api = ArcPassProvider.get();
Optional<Season> season = api.getCurrentSeason();
if (season.isPresent()) {
    String name = season.get().getDisplayName();
    long remaining = season.get().getTimeRemainingSeconds();
}
```

<h2 id="示例-90-天赛季配置">
  示例：90 天赛季配置
</h2>

```yaml theme={null}
# config.yml
seasons:
  auto:
    enabled: true
    duration-days: 90
    notify-before-end: [30, 14, 7, 3, 1]

  on-end:
    reset-level: true
    reset-experience: true
    reset-quests: true
    keep-purchased-tiers: true

  end-rewards:
    25:
      - reward_bronze_badge
    50:
      - reward_silver_badge
    75:
      - reward_gold_badge
    100:
      - reward_platinum_badge
      - reward_season_exclusive

  leaderboard-rewards:
    1:
      - reward_champion
    2-5:
      - reward_elite
    6-20:
      - reward_veteran
```

<h2 id="下一步">
  下一步
</h2>

<Columns cols={2}>
  <Card title="配置 GUI" icon="palette" href="/arcpass/config/gui">
    设置界面布局
  </Card>

  <Card title="查看命令" icon="terminal" href="/arcpass/commands">
    命令和权限列表
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.