> ## 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="配置概述" />

ArcPass 采用模块化配置设计，不同功能的配置分散在多个文件中，便于管理和维护。

<h2 id="配置文件结构">
  配置文件结构
</h2>

```
plugins/ArcPass/
├── config.yml          # 主配置
├── database.yml        # 数据库配置
├── license.yml         # 许可证配置
├── lang/               # 语言文件
│   ├── en_US.yml
│   └── zh_CN.yml
├── passes/             # 通行证配置
│   ├── default.yml
│   └── ...
├── quests/             # 任务配置
│   ├── daily/          # 日常任务
│   ├── weekly/         # 周常任务
│   └── seasonal/       # 赛季任务
├── rewards/            # 奖励配置
│   └── default.yml
└── gui/                # GUI 配置
    ├── main-menu.yml
    ├── quests.yml
    └── rewards.yml
```

<h2 id="主配置文件">
  主配置文件
</h2>

<h3 id="config-yml">
  config.yml
</h3>

```yaml theme={null}
# 配置版本（请勿修改）
config-version: 2

# 调试模式 - 启用详细日志输出
debug: false

# 语言设置
locale:
  # 新玩家的默认语言
  default: zh_CN
  # 是否允许玩家更改语言
  allow-change: true

# 通行证设置
pass:
  # 最高等级（建议 1-100）
  max-level: 100
  # 1 级所需的基础经验值
  base-experience: 100
  # 每级经验倍率（1.1 = 每级增加 10%）
  experience-multiplier: 1.1

# 任务设置
quests:
  # 日常任务重置时间（24 小时制，服务器时区）
  daily-reset-hour: 4
  # 周常任务重置日（1=周一，7=周日）
  weekly-reset-day: 1

# 通知设置
notifications:
  # 升级时通知玩家
  level-up: true
  # 完成任务时通知玩家
  quest-complete: true
  # 有可领取奖励时通知玩家
  rewards-available: true
  # 音效
  sounds:
    level-up: ENTITY_PLAYER_LEVELUP
    quest-complete: ENTITY_EXPERIENCE_ORB_PICKUP
    reward-claim: BLOCK_NOTE_BLOCK_PLING

# GUI 设置
gui:
  # 动画元素更新间隔（tick）
  update-interval: 20
  # 点击外部区域时关闭 GUI
  close-on-outside-click: true

# 性能设置
performance:
  # 数据保存间隔（秒）
  save-interval: 300
  # 缓存过期时间（分钟）
  cache-expiry: 30
```

<h3 id="database-yml">
  database.yml
</h3>

```yaml theme={null}
# 配置版本（请勿修改）
config-version: 2

# 数据库类型：sqlite 或 mysql
type: sqlite

# SQLite 设置（当 type 为 sqlite 时使用）
sqlite:
  # 数据库文件名（在插件文件夹内）
  file: data.db

# MySQL 设置（当 type 为 mysql 时使用）
mysql:
  host: localhost
  port: 3306
  database: arcpass
  username: root
  password: ""
  # 连接池大小
  pool-size: 10
  # 额外连接属性
  properties:
    useSSL: false
    autoReconnect: true
    allowPublicKeyRetrieval: true

# 跨服（网络）设置
network:
  # standalone | shared-db | redis
  mode: standalone
  server-id: "server-1"
  redis:
    host: localhost
    port: 6379
    password: ""
    database: 0
    pool-size: 8
    cache-ttl: 10
    migration-lock-timeout: 5000
  sync:
    quit-save-mode: blocking
    join-lock-wait: 3000
```

<Warning>
  **需要专业版许可证**

  跨服支持（`shared-db` 和 `redis` 模式）需要 **专业版** 许可证。标准版用户将始终运行在 `standalone` 模式。可在 [许可证中心](https://license.kitemc.com/products/arcpass) 升级。
</Warning>

<h2 id="配置热重载">
  配置热重载
</h2>

大部分配置支持热重载，无需重启服务器：

```
/arcpass admin reload
```

<Warning>
  **注意**

  以下配置修改后需要重启服务器：

  * 数据库类型切换
  * 许可证密钥更改
</Warning>

<h2 id="配置验证">
  配置验证
</h2>

ArcPass 会在加载时验证配置文件：

* 格式错误会在控制台显示详细信息
* 无效值会使用默认值并警告
* 缺失的必要配置会阻止插件启动

<h2 id="详细配置指南">
  详细配置指南
</h2>

<Columns cols={2}>
  <Card title="通行证配置" icon="ticket" href="/arcpass/config/passes">
    等级、档位、奖励设置
  </Card>

  <Card title="任务配置" icon="clipboard-list" href="/arcpass/config/quests">
    任务类型、目标、条件
  </Card>

  <Card title="奖励配置" icon="gift" href="/arcpass/config/rewards">
    奖励类型、数值设置
  </Card>

  <Card title="赛季配置" icon="trophy" href="/arcpass/config/seasons">
    赛季时间、规则设置
  </Card>

  <Card title="GUI 配置" icon="palette" href="/arcpass/config/gui">
    界面布局、物品设置
  </Card>
</Columns>

<h2 id="配置示例">
  配置示例
</h2>

插件安装目录下的 `docs/examples-zh/` 文件夹包含完整的配置示例，可以作为参考。


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