feat: add option strategy for variant (#64)

MaaAssistantArknights · Oct 4, 2023 · b96857a · b96857a
1 parent 9bdf39b
commit b96857a
Show file tree

Hide file tree

Showing 6 changed files with 252 additions and 61 deletions.
diff --git a/README-EN.md b/README-EN.md
@@ -117,6 +117,7 @@ A task should be defined with a TOML or JSON file, the located in `$MAA_CONFIG_D
 A task is consists of multiple subtasks,
 available subtasks and params are defined by `type` and `params` fields,
 it will passed to MaaCore, see [here](https://maa.plus/docs/en-us/3.1-INTEGRATION.html#asstappendtask) for more details:
+
 ```toml
 [[tasks]]
 type = "StartUp" # the type of maa task
@@ -127,6 +128,7 @@ params = { client_type = "Official", start_game_enabled = true } # the params of
 
 If you want to run a task with different params based on some conditions,
 you can define multiple variants of a task:
+
 ```toml
 [[tasks]]
 type = "Infrast"
@@ -150,6 +152,7 @@ params = { plan_index = 2 }
 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.
 
@@ -158,6 +161,7 @@ including the time period defined in the `infrast` file,
 so you must define the time period in the `condition` field.
 
 Besides of `Time` condition, there are also `DateTime` and `Weakday` conditions:
+
 ```toml
 [[tasks]]
 type = "Fight"
@@ -174,12 +178,42 @@ params = { stage = "CE-6" }
 [[tasks.variants]]
 params = { stage = "1-7" }
 ```
-If multiple variants are matched, the first one will be used.
+
+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 5 expiring medicine on Sunday
+[[tasks.variants]]
+condition = { type = "Weekday", weekdays = ["Sun"] }
+params = { expiring_medicine = 5 }
+# fight 1-7 otherwise
+[[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" }
+```
+
+This example will fight the same stage as above, but use 5 expiring medicine on Sunday 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]]

diff --git a/README.md b/README.md
@@ -109,6 +109,7 @@ resources = ["platform_diff/macOS"]
 #### 基本结构
 
 一个任务文件包含多个子任务，每一个子任务是一个[MAA任务链](https://maa.plus/docs/3.1-集成文档.html#asstappendtask)：
+
 ```toml
 [[tasks]]
 type = "StartUp" # maa任务的类型
@@ -118,6 +119,7 @@ params = { client_type = "Official", start_game_enabled = true } # maa任务的
 #### 任务条件
 
 如果你想要根据一些条件运行不同参数的任务，你可以定义多个任务的变体：
+
 ```toml
 [[tasks]]
 type = "Infrast"
@@ -141,15 +143,17 @@ params = { plan_index = 2 }
 condition = { type = "Time", start = "18:00:00" }
 params = { plan_index = 0 }
 ```
-这里的`condition`字段用于确定哪一个变体应该被使用，
-而匹配的变体的`params`字段将会被合并到任务的参数中。
 
-**注意**：这个CLI不会读取基建计划文件中的任何内容，
+这里的 `condition` 字段用于确定哪一个变体应该被使用，
+而匹配的变体的 `params` 字段将会被合并到任务的参数中。
+
+**注意**：这个 CLI 不会读取基建计划文件中的任何内容，
 包括基建计划文件中定义的时间段，
-所以你必须在`condition`字段中定义时间段，
+所以你必须在 `condition` 字段中定义时间段，
 来在不同的时间运行不同的基建计划。
 
-除了`Time`条件，还有`DateTime`和`Weakday`条件：
+除了 `Time` 条件，还有 `DateTime` 和 `Weakday` 条件：
+
 ```toml
 [[tasks]]
 type = "Fight"
@@ -168,12 +172,45 @@ params = { stage = "CE-6" }
 [[tasks.variants]]
 params = { stage = "1-7" }
 ```
-如果有多个变体被匹配，第一个将会被使用。
+
+在默认的策略下，如果有多个变体被匹配，第一个将会被使用。
 如果没有给出条件，那么变体将会总是被匹配，
 所以你可以把没有条件的变体放在最后，作为默认的情况。
 
+你可以使用 `strategy` 字段来改变匹配策略：
+
+```toml
+[[tasks]]
+type = "Fight"
+strategy = "merge" # 或者 "first" (默认)
+
+# 在周天，使用5个即将过期的理智药
+[[tasks.variants]]
+condition = { type = "Weekday", weekdays = ["Sun"] }
+params = { expiring_medicine = 5 }
+
+# 默认刷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个即将过期的理智药。
+在 `merge` 策略下，如果有多个变体被匹配，后面的变体的参数将合并入前面的变体的参数中。
+如果多个变体都有相同的参数，那么后面的变体的参数将会覆盖前面的变体的参数。
+
 如果没有变体被匹配，那么任务将不会被执行，
 这在你想要只在某些条件下运行任务时很有用：
+
 ```toml
 # 只在在18:00:00之后进行信用商店相关的操作
 [[tasks]]

diff --git a/config_examples/tasks/daily.json b/config_examples/tasks/daily.json
@@ -9,21 +9,24 @@
     },
     {
       "type": "Fight",
+      "strategy": "merge",
       "variants": [
         {
           "condition": {
-            "type": "DateTime",
-            "start": "2023-08-01T16:00:00",
-            "end": "2023-08-21T03:59:59"
+            "type": "Weekday",
+            "weekdays": [
+              "Sun"
+            ]
           },
+          "params": {
+            "expiring_medicine": 5
+          }
+        },
+        {
           "params": {
             "stage": {
-              "alternatives": [
-                "SL-6",
-                "SL-7",
-                "SL-8"
-              ],
-              "description": "a stage to fight in summer event"
+              "default": "1-7",
+              "description": "a stage to fight"
             }
           }
         },
@@ -41,10 +44,19 @@
           }
         },
         {
+          "condition": {
+            "type": "DateTime",
+            "start": "2023-08-01T16:00:00",
+            "end": "2023-08-21T03:59:59"
+          },
           "params": {
             "stage": {
-              "default": "1-7",
-              "description": "a stage to fight"
+              "alternatives": [
+                "SL-6",
+                "SL-7",
+                "SL-8"
+              ],
+              "description": "a stage to fight in summer event"
             }
           }
         }

diff --git a/config_examples/tasks/daily.toml b/config_examples/tasks/daily.toml
@@ -5,24 +5,30 @@ params = { client_type = "Official", start_game_enabled = true }
 
 [[tasks]]
 type = "Fight"
+strategy = "merge"
 
-# fight the last stage if on event period
+# use expiring medicine on Sunday
+[[tasks.variants]]
+condition = { type = "Weekday", weekdays = ["Sun"] }
+params = { expiring_medicine = 5 }
+
+# fight 1-7 by default
 [[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"
+default = "1-7"
+description = "a stage to fight"
 
 # fight CE-6 on Tue, Thu, Sat
 [[tasks.variants]]
 condition = { type = "Weekday", weekdays = ["Tue", "Thu", "Sat"] }
 params = { stage = "CE-6" }
 
-# fight 1-7 otherwise
+# fight the last stage if on event period
 [[tasks.variants]]
+condition = { type = "DateTime", start = "2023-08-01T16:00:00", end = "2023-08-21T03:59:59" }
 [tasks.variants.params.stage]
-default = "1-7"
-description = "a stage to fight"
+alternatives = ["SL-6", "SL-7", "SL-8"]
+description = "a stage to fight in summer event"
 
 # Mall after 16:00
 [[tasks]]

diff --git a/config_examples/tasks/daily.yml b/config_examples/tasks/daily.yml
@@ -4,18 +4,18 @@ tasks:
       client_type: Official
       start_game_enabled: true
   - type: Fight
+    strategy: merge
     variants:
       - condition:
-          type: DateTime
-          start: 2023-08-01T16:00:00
-          end: 2023-08-21T03:59:59
+          type: Weekday
+          weekdays:
+            - Sun
         params:
+            expiring_medicine: 5
+      - params:
           stage:
-            alternatives:
-              - SL-6
-              - SL-7
-              - SL-8
-            description: a stage to fight in summer event
+            default: 1-7
+            description: a stage to fight
       - condition:
           type: Weekday
           weekdays:
@@ -24,10 +24,17 @@ tasks:
             - Sat
         params:
           stage: CE-6
-      - params:
+      - condition:
+          type: DateTime
+          start: 2023-08-01T16:00:00
+          end: 2023-08-21T03:59:59
+        params:
           stage:
-            default: 1-7
-            description: a stage to fight
+            alternatives:
+              - SL-6
+              - SL-7
+              - SL-8
+            description: a stage to fight in summer event
   - type: Mall
     variants:
       - condition: