fz-mirrors/MaaAssistantArknights
0
0
Fork 0
mirror of https://github.com/MaaAssistantArknights/MaaAssistantArknights.git synced 2026-07-16 09:50:40 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: update CLI document for latest version

Browse Source
This commit is contained in:
Loong
2023-10-23 20:57:05 +08:00
parent 80d8e8aefe
commit bcb142a6ab
3 changed files with 570 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@@ -86,7 +86,7 @@ MAA 的意思是 MAA Assistant Arknights
### CLI支持
MAA 支持命令行界面（CLI）操作，支持 Linux 和 macOS，可用于自动化脚本或在无图形界面的服务器上使用。请参考 [CLI 使用指南](https://maa.plus/docs/1.6-CLI使用指南.html)
MAA 支持命令行界面（CLI）操作，支持 Linux，macOS 和 Windows，可用于自动化脚本或在无图形界面的服务器上使用。请参考 [CLI 使用指南](https://maa.plus/docs/1.6-CLI使用指南.html)
## 加入我们

332
docs/1.6-CLI使用指南.md
View File

@@ -12,113 +12,103 @@ icon: material-symbols:terminal
## 安装
### Linux
### Appimage
对于最新版本的 MAA，CLI 已经打包在 MAA 压缩包中，如果你下载了最新版 MAA，解压后就可以使用 CLI，无需额外安装。 **注意**: 请不要将库文件和资源文件随便移动到其他位置，否则CLI将无法找到它们。 如果你想将它们移动到其他位置，你可以通过以下命令：
CLI 是 MAA 在 Linux 平台的默认界面，你可以直接下载最新的 Appimage 包来使用 CLI。
### 包管理器
#### macOS
使用 [Homebrew](https://brew.sh/) 安装：
```bash
# 请确保你当前的工作目录是解压后的MAA目录
lib_dir="$(./maa dir data)/lib"
resource_dir="$(./maa dir data)/resource"
mv lib* "$lib_dir"
mv resource "$resource_dir"
brew install MaaAssistantArknights/tap/maa-cli
```
如果你当前使用的是旧版本的 MAA 或者希望单独安装 CLI，你可以前往 [CLI Release页面](https://github.com/MaaAssistantArknights/maa-cli/releases/latest) 根据你的架构下载对应的预编译的 CLI 二进制文件（对于 x86_64 架构，你可以下载以 `x86_64-unknown-linux-gnu.tar.gz` 结尾的文件，对于 aarch64 架构，你可以下载以 `aarch64-unknown-linux-gnu.tar.gz` 结尾的文件），解压后将 `maa` 文件移动到你任何在 `PATH` 环境变量中的目录下, 然后使用 `maa install` 命令安装 MAA 共享库和资源。
#### Linux
### macOS
ArchLinux 用户可以安装[AUR包](https://aur.archlinux.org/packages/maa-cli/):
macOS用户和Linux用户一样，可以在 [CLI Release 页面](https://github.com/MaaAssistantArknights/maa-cli/releases/latest)下载对应的预编译的CLI二进制文件（macOS提供通用的二进制文件，以 `universal-apple-darwin.zip` 结尾），解压后将 `maa` 文件移动到你任何在 `PATH` 环境变量中的目录下，然后使用 `maa install` 命令安装 MAA 共享库和资源。
```bash
yay -S maa-cli
```
### Windows
对于 LinuxBrew 用户，可以使用 [LinuxBrew](https://docs.brew.sh/Homebrew-on-Linux) 安装：
CLI目前尚不支持Windows。
```bash
brew install MaaAssistantArknights/tap/maa-cli
```
## 使用和配置
### 预编译二进制文件
你可以从 [`maa-cli` release 页面](https://github.com/MaaAssistantArknights/maa-cli/releases/latest)下载预编译的二进制文件，将其解压后得到的可执行文件放在你喜欢的位置。不同的平台对应的文件名如下：
<table>
<thead>
<tr>
<th>操作系统</th>
<th>处理器架构</th>
<th>文件名</th>
</tr>
</thead>
<tbody>
<tr>
<td rowspan=2>Linux</td>
<td>x86_64</td>
<td>maa_cli-x86_64-unknown-linux-gnu.tar.gz</td>
</tr>
<tr>
<td>aarch64</td>
<td>maa_cli-aarch64-unknown-linux-gnu.tar.gz</td>
</tr>
<tr>
<td rowspan=2>macOS</td>
<td>x86_64</td>
<td rowspan=2>
maa_cli-universal-apple-darwin.zip
</td>
</tr>
<tr>
<td>aaarch64</td>
</tr>
<tr>
<td rowspan=2>Windows</td>
<td>x86_64</td>
<td>maa_cli-x86_64-pc-windows-msvc.zip</td>
</tr>
</tbody>
</table>
## 使用
`maa-cli` 的主要功能是运行任务，你可以通过 `maa run <task>` 来运行一个任务。这里的 `<task>` 是一个任务的名字，你可以通过 `maa list` 来列出所有可用的任务。
更多信息可以通过 `maa help` 获取。
## 配置
### 配置目录
你的配置文件（选项，任务等）位于配置目录中，你可以通过 `maa dir config` 获取配置目录，并通过 `mkdir -p "$(maa dir config)"` 创建它。在以下的介绍中，配置目录的将被称为 `$MAA_CONFIG_DIR`。此外尽管所有的例子都是针对 TOML 格式的，但是以下所有配置文件的格式可以是 TOML，JSON 或 YAML。
`maa-cli` 配置文件位于特定的配置目录中，你可以通过`maa dir config`获取配置目录。配置目录也可以通过环境变量 `MAA_CONFIG_DIR` 更改。在下面的例子中，我们将用 `$MAA_CONFIG_DIR` 来表示配置目录。
### MAA选项
所有的配置文件都可以使用 TOML，YAML 或者 JSON 格式，在下面的例子中，我们将使用 TOML 格式，并使用 `.toml` 作为文件扩展名。但是你可以混合这三种格式中的任意一种，只要你的文件扩展名正确。
针对 MAA 本身的选项，你可以在 `$MAA_CONFIG_DIR/asst.toml` 中进行配置。 这里的选项包括三个部分：
### 定义自定义任务
- `connection`：MAA连接设置；
- `instance_options`：MAA实例选项；
- `resources`: 额外资源地址。
每一个自定义任务都是一个单独的文件，它们应该位于 `$MAA_CONFIG_DIR/tasks` 目录中。
#### `connection` 设置
#### 基本结构
`connection` 设置用于配置 MAA 连接游戏，其包括两种方式：通过 ADB 连接和通过 PlayTools 连接。
##### ADB连接
当你使用 ADB 连接时，你需要提供 `adb` 的路径和设备的序列号:
```toml
[connection]
type = "ADB"
adb_path = "adb" # adb可执行文件的路径
device = "emulator-5554" # 你的android设备的序列号
config = "General" # maa connect的配置名称，可选，不建议修改
```
设备的序列号可以是地址加端口号，也可以是非地址的任意字符串，可以通过 `adb devices` 命令获取。更多信息参见模拟器支持文档。
##### PlayTools 连接
当你使用 PlayTools 连接时，你需要提供在 PlayCover 中设置的 MacTools 的地址:
```toml
[connection]
type = "PlayTools"
client_address = "localhost:1717" # MacTools的地址
config = "CompatMac" # maa connect的配置，可选，不建议修改
```
使用之前请先阅读 [Mac模拟器支持](https://maa.plus/docs/1.4-Mac模拟器支持.html#✅-playcover-原生运行最流畅🚀)。
#### `instance_options` 设置
`instance_options` 部分用于配置 MAA 实例的选项：
```toml
[instance_options]
touch_mode = "ADB" # 使用的触摸模式，可选值为 "ADB", "MiniTouch", "MaaTouch" 或者 "MacPlayTools"（仅适用于PlayTools连接）
deployment_with_pause = false # 是否在部署时暂停游戏
adb_lite_enabled = false # 是否使用adb-lite
kill_adb_on_exit = false # 是否在退出时杀死adb
```
注意，如果你使用 PlayTools 连接，`touch_mode`字段将被忽略并被设置为`MacPlayTools`。
#### `resources` 设置
`resources` 部分用于指定资源的路径，这是一个资源目录列表（如果是相对路径，路径应该相对于 MAA 主仓库的 `resource` 目录）：
```toml
resources = ["platform_diff/iOS", "global/YoStarEN"]
```
这对于指定不同平台的资源和使用外服的用户非常有用。
### 定义任务
任务文件位于 `$MAA_CONFIG_DIR/tasks` 目录下。 每一个任务文件都是一个任务列表，每一个子任务是一个 MAA 任务，其中包含任务类型和参数，可用的任务及其参数参见[集成文档](https://maa.plus/docs/3.1-集成文档.html#asstappendtask)。
一个简单的任务文件示例：
一个任务文件包含多个子任务，每一个子任务是一个[MAA任务](https://maa.plus/docs/3.1-集成文档.html#asstappendtask)：
```toml
[[tasks]]
type = "StartUp"
params = { client_type = "Official", start_game_enabled = true }
[[tasks]]
type = "CloseDown"
type = "StartUp" # maa任务的类型
params = { client_type = "Official", start_game_enabled = true } # maa任务的参数
```
建议每个任务中都包含 `StartUp` 并声明参数 `client_type` ，这个参数用于指定客户端类型，并会在 CLI 其他部分使用。
#### 任务条件
如果你想要根据一些条件运行不同参数的任务，你可以定义多个任务的变体：
@@ -146,11 +136,11 @@ condition = { type = "Time", start = "18:00:00" }
params = { plan_index = 0 }
```
这里的 `condition` 字段用于确定哪一个变体应该被使用，而匹配的变体的 `params` 字段将会被合并到主任务的 `params` 字段中。
这里的 `condition` 字段用于确定哪一个变体应该被使用，而匹配的变体的 `params` 字段将会被合并到任务的参数中。
**注意**：这个CLI不会读取基建计划文件中的任何内容，包括基建计划文件中定义的时间段，所以你必须在 `condition` 字段中定义时间段来在不同的时间运行不同的基建计划。
**注意**：如果你的自定义基建计划文件使用相对路径，应该相对于 `$MAA_CONFIG_DIR/infrast`。此外，由于基建文件是由 `MaaCore` 而不是 `maa-cli` 读取的，因此这些文件的格式必须是 `JSON`。同时，`maa-cli` 不会读取基建文件，也不会根据其中定义的时间段来选择相应的子计划。因此，必须通过 `condition` 字段来指定在相应时间段使用正确的基建计划的参数中的 `plan_index` 字段。这样可以确保在适当的时间段使用正确的基建计划。
除了 `Time` 条件，还有 `DateTime`，`Weakday`和 `Combined`（其他条件的组合）条件：
除了 `Time` 条件，还有 `DateTime`，`Weakday` 以及 `Combined` 条件。`DateTime` 条件用于指定一个时间段，`Weekday` 条件用于指定一周中的某些天，`Combined` 条件用于指定多个条件的组合。
```toml
[[tasks]]
@@ -181,38 +171,168 @@ params = { stage = "CE-6" }
params = { stage = "1-7" }
```
如果有多个变体被匹配，第一个将会被使用。如果没有给出条件，那么变体将会总是被匹配，所以你可以把没有条件的变体放在最后作为默认的情况。
在默认的策略下，如果有多个变体被匹配，第一个将会被使用。如果没有给出条件，那么变体将会总是被匹配，所以你可以把没有条件的变体放在最后，作为默认的情况。
如果没有变体被匹配，那么任务将不会被执行，这在你想要任务只在某些条件下运行任务时很有用：
你可以使用 `strategy` 字段来改变匹配策略：
```toml
[[tasks]]
type = "Fight"
strategy = "merge" # 或者 "first" (默认)
# 在周天晚上使用所有的将要过期的理智药
[[tasks.variants]]
params = { expiring_medicine = 1000 }
[tasks.variants.condition]
type = "Combined"
conditions = [
{ type = "Time", start = "18:00:00" },
{ type = "Weekday", weekdays = ["Sun"] },
]
# 默认刷1-7
[[tasks.variants]]
params = { stage = "1-7" }
# 在周二、周四和周六，刷CE-6
[[tasks.variants]]
condition = { type = "Weekday", weekdays = ["Tue", "Thu", "Sat"] }
params = { stage = "CE-6" }
# 在夏活期间，刷SL-8
[[tasks.variants]]
params = { stage = "SL-8" }
condition = { type = "DateTime", start = "2023-08-01T16:00:00", end = "2023-08-21T03:59:59" }
# 周一早上刷5次剿灭
[[tasks.variants]]
params = { "stage" = "Annihilation", times = 5 }
[tasks.variants.condition]
type = "Combined"
conditions = [
{ type = "Weekday", weekdays = ["Mon"] },
{ type = "Time", end = "12:00:00" },
]
```
这个例子和上面的例子将刷同样的关卡，但是在周天晚上，将会使用所有的将要过期的理智药。在 `merge` 策略下，如果有多个变体被匹配，后面的变体的参数将合并入前面的变体的参数中。如果多个变体都有相同的参数，那么后面的变体的参数将会覆盖前面的变体的参数。
如果没有变体被匹配，那么任务将不会被执行，这可以用于只在特定的条件下运行子任务：
```toml
# 只在在18:00:00之后进行信用商店相关的操作
[[tasks]]
type = "Mall"
[tasks.params]
shopping = true
credit_fight = true
buy_first = ["招聘许可", "龙门币"]
blacklist = ["碳", "家具", "加急许可"]
[[tasks.variants]]
condition = { type = "Time", start = "18:00:00" }
```
### 运行任务
#### 用户输入
当你定义了任务后，你可以通过 `maa run <task>` 命令运行任务，所有可用的任务可以通过 `maa list` 命令列出。 更多其他可用命令参见 `maa --help`。
对于一些任务，你可能想要在运行时输入一些参数，例如关卡名称。 你可以将对应需要输入的参数设置为 `Input` 或者 `Select` 类型：
#### 日志级别
```toml
[[tasks]]
type = "Fight"
当运行任务时，CLI 会处理 MAA 的消息。但是不是所有的消息都会输出。日志级别用于控制哪些消息会被输出。当前有6个日志级别：
# 选择一个关卡
[[tasks.variants]]
condition = { type = "DateTime", start = "2023-08-01T16:00:00", end = "2023-08-21T03:59:59" }
[tasks.variants.params.stage]
alternatives = ["SL-6", "SL-7", "SL-8"] # 可选的关卡，必须提供至少一个可选值
description = "a stage to fight in summer event" # 描述，可选
- Error：出现错误，MAA将会停止运行或者无法正常工作；
- Warning：出现错误，但是MAA仍然可以正常工作；
- Normal：一些简要的信息，例如任务开始和结束；
- Info：更详细的信息，例如关卡掉落统计，基建自定义换班干员，肉鸽关卡信息等；
- Debug：关于你的配置的详细信息，例如将要运行任务的类型和参数；
- Trace：任何没有被CLI正确解析的MAA消息。
# 无需任何输入
[[tasks.variants]]
condition = { type = "Weekday", weekdays = ["Tue", "Thu", "Sat"] }
params = { stage = "CE-6" }
默认的日志级别是 `Normal`，你可以通过 `-v` 和 `-q` 选项来控制日志级别：`-v`将会提高日志级别以显更多消息，`-q` 将会减少日志级别以显示更少的消息，重复使用 `-v` 和 `-q` 将会提高或降低日志级别，直到达到最高或最低级别。比如，`-vv` 将会显示 `Debug` 级别及以上的消息，而 `-qq` 将会显示 `Warning` 级别及以下的消息。
# 输入一个关卡
[[tasks.variants]]
[tasks.variants.params.stage]
default = "1-7" # 默认的关卡，可选（如果没有默认值，输入空值将会重新提示输入）
description = "a stage to fight" # 描述，可选
```
对于一般使用，建议使用 `maa run -v <task>`，这样你可以看到 MAA 的所有有用的消息。 当你在调试配置时，你可以使用 `maa run -vv <task>` 来看到更多的调试信息。
对于 `Input` 类型，当运行任务时，你将会被提示输入一个值。如果你输入了一个空值，那么默认值将会被使用。
对于 `Select` 类型，当运行任务时，你将会被提示选择一个值 （通过输入可选值的序号）。
注意，当你的输入不是可选值时，你将会被提示重新输入。
### MaaCore 相关配置
和 MaaCore 相关的配置需要放在 `$MAA_CONFIG_DIR/asst.toml` 中。
目前其包含的配置有：
```toml
user_resource = true
resources = ["platform_diff/iOS"]
[connection]
type = "ADB"
adb_path = "adb"
device = "emulator-5554"
config = "CompatMac"
[static_options]
cpu_ocr = false
gpu_ocr = 1
[instance_options]
touch_mode = "MAATouch"
deployment_with_pause = false
adb_lite_enabled = false
kill_adb_on_exit = false
```
`user_resource` 字段用于指定是否从用户资源目录加载资源，它的默认值是`false`。这个参数和命令行选项 `--user-resource` 相同。更多信息可以通过 `maa help run` 获取。
`resources`字段用于指定资源的路径，这是一个资源目录列表，如果是相对路径，它应该相对于 `resource` 目录（`maa dir resource`）。这可以用来加载外服资源或者平台差异资源。
`[connection]` 相关字段用于指定 MaaCore 连接游戏的方式和参数。目前可用的连接方式有 `ADB` 和 `PlayTools`。
当你使用 `ADB` 连接时，你需要提供 `adb` 的路径和设备的序列号：
```toml
[connection]
type = "ADB"
adb_path = "adb" # adb可执行文件的路径
device = "emulator-5554" # 你的android设备的序列号
config = "General" # maa connect的配置
```
当你使用 `PlayTools` 连接时，你需要提供 `PlayTools` 的地址：
```toml
[connection]
type = "PlayCover"
address = "localhost:1717" # PlayTools的地址
config = "CompatMac" # maa connect的配置
```
两者都需要提供 `config`，这个值将被传给 MaaCore，用于指定一些平台和模拟器相关的配置。对于 Linux 他默认为 `CompatPOSIXShell`，对于 macOS 他默认为 `CompatMac`，对于 Windows 他默认为 `General`。更多可选配置可以在资源文件夹中的 `config.json` 文件中找到。
`[instance_options]` 相关字段用于指定 MaaCore 实例的选项，详见 [集成](https://maa.plus/docs/3.1-集成文档.html#asstsetinstanceoption)：
```toml
[instance_options]
touch_mode = "ADB" # 使用的触摸模式，可选值为"ADB", "MiniTouch", "MAATouch" 或者 "MacPlayTools"(仅适用于PlayCover)
deployment_with_pause = false # 是否在部署时暂停游戏
adb_lite_enabled = false # 是否使用adb-lite
kill_adb_on_exit = false # 是否在退出时杀死adb
```
注意，如果你使用`PlayTools`，`touch_mode`字段将被忽略并被设置为`MacPlayTools`。
### `maa-cli` 相关配置
`maa-cli` 相关的配置需要放在 `$MAA_CONFIG_DIR/cli.toml` 中。目前其包含的配置如下：
```toml
[core]
channel = "beta"
components.resource = false
```
`[core]` 相关字段用于指定 CLI 安装和更新 `MaaCore` 的方式。`channel` 字段用于指定 `MaaCore` 的更新通道，可选值为 `stable` 和 `beta`，`alpha`。`components.resource` 字段用于指定是否安装资源。

343
docs/en-us/1.6-USER_GUIDE_FOR_CLI.md Normal file
View File

@@ -0,0 +1,343 @@
---
icon: material-symbols:terminal
---
# User Guide for CLI
## Feature
- Define tasks by TOML, YAML or JSON file, then run it by `maa run <task>`;
- Install and update `MaaCore` and resources with `maa install` and `maa update`;
- Update self with `maa self update`;
## Installation
### Appimage
The CLI is the default interface of MAA on Linux. You can use the CLI directly by download the latest Appimage.
### Package manager
#### macOS
Install with [Homebrew](https://brew.sh/):
```bash
brew install MaaAssistantArknights/tap/maa-cli
```
#### Linux
ArchLinux user can install [AUR package](https://aur.archlinux.org/packages/maa-cli/):
```bash
yay -S maa-cli
```
For LinuxBrew user, you can install with [LinuxBrew](https://docs.brew.sh/Homebrew-on-Linux):
```bash
brew install MaaAssistantArknights/tap/maa-cli
``
### Prebuilt binary
You can install CLI by download prebuilt binary from
[`maa-cli` release page](https://github.com/MaaAssistantArknights/maa-cli/releases/latest) and extract it to your favorite location. The filename for different platform is:
<table>
<thead>
<tr>
<th>Operation System</th>
<th>Architecture</th>
<th>Filename</th>
</tr>
</thead>
<tbody>
<tr>
<td rowspan=2>Linux</td>
<td>x86_64</td>
<td>maa_cli-x86_64-unknown-linux-gnu.tar.gz</td>
</tr>
<tr>
<td>aarch64</td>
<td>maa_cli-aarch64-unknown-linux-gnu.tar.gz</td>
</tr>
<tr>
<td rowspan=2>macOS</td>
<td>x86_64</td>
<td rowspan=2>
maa_cli-universal-apple-darwin.zip
</td>
</tr>
<tr>
<td>aaarch64</td>
</tr>
<tr>
<td rowspan=2>Windows</td>
<td>x86_64</td>
<td>maa_cli-x86_64-pc-windows-msvc.zip</td>
</tr>
</tbody>
</table>
### Build from source
You can also build from source by yourself with `cargo`:
```bash
cargo install --git https://github.com/MaaAssistantArknights/maa-cli.git --bin maa --locked
```
### Dependencies
#### MaaCore
`maa-cli` only provides a interface for MaaCore, it needs `MaaCore` and resources to run tasks, which can be installed by `maa install`:
```bash
maa install
```
## Usage
### Commands
The main feature of `maa-cli` is to run tasks, you can run a task by `maa run <task>`. Here `<task>` is the name of a task, you can list all available tasks by `maa list`.
More details can be found by `maa help`.
## Configurations
### Configuration directory
All configurations of `maa-cli` is located in a specific configuration directory, which can be get by `maa dir config`.
The configuration directory can be changed by environment variable `MAA_CONFIG_DIR`. In below examples, we will use `$MAA_CONFIG_DIR` to represent the configuration directory.
All configuration files can be written in TOML, YAML or JSON format. In below examples, we will use TOML format and `.toml` as file extension. But you can mix these three formats as long as the file extension is correct.
### Define tasks
A `maa-cli` task should be defined in a single file, which should be located in `$MAA_CONFIG_DIR/tasks` directory.
#### Basic structure
A `maa-cli` task is a sequence of `MAA` tasks, each `MAA` task is defined by `type` and `params` fields:
```toml
[[tasks]]
type = "StartUp" # the type of maa task
params = { client_type = "Official", start_game_enabled = true } # the params of given task
```
See documentation of [MAA](https://maa.plus/docs/en-us/3.1-INTEGRATION.html#asstappendtask) for all available task types and params.
#### Task variants and conditions
In some case, you may want to run a task with different params in different conditions. You can define multiple variants for a task, and use `condition` field to determine whether the variant should be used. For example, you may want to use different infrast plan in different time period of a day:
```toml
[[tasks]]
type = "Infrast"
[tasks.params]
mode = 10000
facility = ["Trade", "Reception", "Mfg", "Control", "Power", "Office", "Dorm"]
dorm_trust_enabled = true
filename = "normal.json" # the filename of custom infrast plan
# use plan 1 before 12:00:00, use plan 2 between 12:00:00 and 18:00:00, use plan 0 after 18:00:00
[[tasks.variants]]
condition = { type = "Time", end = "12:00:00" } # if start is not defined, it will be 00:00:00
params = { plan_index = 1 }
[[tasks.variants]]
condition = { type = "Time", start = "12:00:00", end = "18:00:00" }
params = { plan_index = 2 }
[[tasks.variants]]
condition = { type = "Time", start = "18:00:00" } # if end is not defined, it will be 23:59:59
params = { plan_index = 0 }
```
The `condition` field is used to determine whether the variant should be used,
and the `params` field of matched variant will be merged into the params of the task.
**Note**: If the `filename` field is a relative path, it will be relative to `$MAA_CONFIG_DIR/infrast`. Besides, the custom infrast plan file will not be read by `maa-cli` but `MaaCore`. So the format of the file must be `JSON` and time period defined in the file will not be used to select the corresponding sub-plan. So you must specify the `plan_index` field in the params of the task to use the correct infrast plan in the corresponding time period. This will ensure that the correct infrast plan is used in the appropriate time period.
Besides of `Time` condition, there are also `DateTime`, `Weakday`, and `Combined` conditions. `DateTime` condition is used to specify a specific datetime period, `Weekday` condition is used to specify some days in a week, `Combined` condition is used to specify a combination of multiple conditions.
```toml
[[tasks]]
type = "Fight"
# fight SL-8 on summer event
[[tasks.variants]]
params = { stage = "SL-8" }
condition = { type = "DateTime", start = "2023-08-01T16:00:00", end = "2023-08-21T03:59:59" }
# fight CE-6 on Tue, Thu, Sat if not on summer event
[[tasks.variants]]
condition = { type = "Weekday", weekdays = ["Tue", "Thu", "Sat"] }
params = { stage = "CE-6" }
# fight 1-7 otherwise
[[tasks.variants]]
params = { stage = "1-7" }
```
With default strategy, if multiple variants are matched, only the first one will be used. And if the condition is not given, the variant will always be matched. So you can put a variant without condition at the end of variants.
The strategy of matching variants can be changed by `strategy` field:
```toml
[[tasks]]
type = "Fight"
strategy = "merge" # or "first" (default)
# use all expiring medicine on Sunday night
[[tasks.variants]]
params = { expiring_medicine = 1000 }
[tasks.variants.condition]
type = "Combined"
conditions = [
{ type = "Time", start = "18:00:00" },
{ type = "Weekday", weekdays = ["Sun"] },
]
# fight 1-7 by default
[[tasks.variants]]
params = { stage = "1-7" }
# fight CE-6 on Tue, Thu, Sat if not on summer event
[[tasks.variants]]
condition = { type = "Weekday", weekdays = ["Tue", "Thu", "Sat"] }
params = { stage = "CE-6" }
# fight SL-8 on summer event
[[tasks.variants]]
params = { stage = "SL-8" }
condition = { type = "DateTime", start = "2023-08-01T16:00:00", end = "2023-08-21T03:59:59" }
```
The outcome stage of this example should be identical to the previous one, but expiring medicine will be used on Sunday night additionally.
With the `merge` strategy, if multiple variants are matched, the params of all matched variants will be merged. If multiple variants have the same param, the last one will be used.
If no variant is matched, the task will not be executed, which is useful when you want to only run a task in some conditions:
```toml
# Mall after 18:00
[[tasks]]
type = "Mall"
[[tasks.variants]]
condition = { type = "Time", start = "18:00:00" }
```
#### User input
In some case, you may want to input some value at runtime, instead of hard code it in the task file. Such as the stage to fight, the item to buy, etc. You can specify the value as `Input` or `Select` type:
```toml
[[tasks]]
type = "Fight"
# Select a stage to fight
[[tasks.variants]]
condition = { type = "DateTime", start = "2023-08-01T16:00:00", end = "2023-08-21T03:59:59" }
# Set the stage to a `Select` type with alternatives and description
[tasks.variants.params.stage]
alternatives = ["SL-6", "SL-7", "SL-8"] # the alternatives of stage, at least one alternative should be given
description = "a stage to fight in summer event" # description of the input, optional
# Task without input
[[tasks.variants]]
condition = { type = "Weekday", weekdays = ["Tue", "Thu", "Sat"] }
params = { stage = "CE-6" }
# Input a stage to fight
[[tasks.variants]]
# Set the stage to a `Input` type with default value and description
[tasks.variants.params.stage]
default = "1-7" # default value of stage, optional (if not given, user can input empty value to re-prompt)
description = "a stage to fight" # description of the input, optional
```
For `Input` type, a prompt will be shown to ask user to input a value. If the default value is given, it will be used if user input empty value, otherwise it will re-prompt. For `Select` type, a prompt will be shown to ask user to select a value from alternatives (by index). If user input is not a valid index, it will re-prompt. The promote and input can be disabled by `--batch` option, which is useful for running tasks in Schedule.
### `MaaCore` related configurations
The related configurations of `MaaCore` is located in `$MAA_CONFIG_DIR/asst.toml`. The current available configurations are:
```toml
user_resource = true
resources = ["platform_diff/iOS"]
[connection]
type = "ADB"
adb_path = "adb"
device = "emulator-5554"
config = "CompatMac"
[static_options]
cpu_ocr = false
gpu_ocr = 1
[instance_options]
touch_mode = "MAATouch"
deployment_with_pause = false
adb_lite_enabled = false
kill_adb_on_exit = false
```
The feild `user_resource` is used to specify whether load user resource, which is a boolean value. If it is `true`, additional resources in `$MAA_CONFIG_DIR/resource` directory will be loaded at last (after all other resources). This is identical to the `--user-resource` command line option. See `maa help run` for more information.
The `resources` field is used to specify additional resources, which is a list of resource directories (if relative path is given, it will be relative to `$(maa dir resource)/resource` directory):
The `connection` section is used to specify how to connect to the game. Currently, there are two types of connection: `ADB` and `PlayTools`.
If you use `ADB`, you should set `adb_path` and `device` fields:
```toml
[connection]
type = "ADB"
adb_path = "adb" # the path of adb executable
device = "emulator-5554" # the serial of your android device
config = "General" # the config of maa
```
If you use `PlayTools`, you should set `address` which is the address of MaaTools set in PlayCover, more details can be found at
[here](https://maa.plus/docs/en-us/1.4-EMULATOR_SUPPORTS_FOR_MAC.html#✅-playcover-the-software-runs-most-fluently-for-its-nativity-🚀):
```toml
[connection]
type = "PlayTools"
address = "localhost:1717" # the address of MaaTools
config = "CompatMac" # the same as above
```
Both `ADB` and `PlayTools` share the `config` field, which is a parameter of `connect` function of maa.It's default value is `CompatMac` on macOS, `CompatPOSIXShell` on Linux and `General` on other platforms. More optional configs can be found in `config.json` in resource directory.
The `instance_options` section is used to configure maa [instance options](https://maa.plus/docs/en-us/3.1-INTEGRATION.html#asstsetinstanceoption):
```toml
[instance_options]
touch_mode = "ADB" # touch mode to use, can be "ADB", "MiniTouch", "MAATouch" or "MacPlayTools" (only for PlayCover)
deployment_with_pause = false # whether pause the game when deployment
adb_lite_enabled = false # whether use adb-lite
kill_adb_on_exit = false # whether kill adb when exit
```
Note: If you connect to the game with `PlayCover`, the `touch_mode` will be ignored and `MacPlayTools` will be used.
### `maa-cli` related configurations
The `maa-cli` related configurations should be located in `$MAA_CONFIG_DIR/cli.toml`. Currently, it only contains one section: `core`:
```toml
[core]
channel = "beta"
[core.components]
resource = false
```
The `channel` field is used to specify the channel of `MaaCore` to install, which can be `stable`, `beta` or `alpha`. The components of `MaaCore` to install can be specified by `components` field, which is a table of boolean values. Currently, only `resource` component is supported.