Skip to content

Commit

Permalink
refactor: rename APIs to the term (#472)
Browse files Browse the repository at this point in the history
  • Loading branch information
@MistEO
MistEO authored Jan 9, 2025
1 parent eaf6a60 commit 837782d
Show file tree
Hide file tree
Showing 56 changed files with 351 additions and 341 deletions.
12 changes: 6 additions & 6 deletions docs/en_us/1.1-QuickStarted.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,10 +38,10 @@ Launch the CLI through the API while registering some custom tasks. This method
{
"Recognize and Click Confirm Icon": {
"next": [
"My Custom Task"
"My Custom Node"
]
},
"My Custom Task": {
"My Custom Node": {
"recognition": "Custom",
"custom_recognition": "MyReco",
"action": "Custom",
Expand Down Expand Up @@ -74,7 +74,7 @@ class MyAction(CustomAction):
# Perform click action
context.controller.post_click(100, 10).wait()
# Override the next tasks to execute
context.override_next(task_name, ["TaskA", "TaskB"])
context.override_next(node_name, ["TaskA", "TaskB"])
```

### Write Your Own Code
Expand All @@ -85,7 +85,7 @@ You can use low-code as a "wrapper" for invocation or register custom callbacks.
# This is pseudo code, for reference only, and cannot be run directly
# "Recognize and click the start button", "Recognize and click the confirmation icon" and so on are all logic in Json
def main():
detail = tasker.post_pipeline("Recognize and click the start button").wait().get()
detail = tasker.post_task("Recognize and click the start button").wait().get()

if detail.completed:
tasker.controller.post_click(100, 100).wait()
Expand All @@ -95,7 +95,7 @@ def main():
save_to_file(image)

tasker.resource.register_custom_action("MyAction", MyAction())
tasker.post_pipeline("Recognize and click the confirmation icon").wait()
tasker.post_task("Recognize and click the confirmation icon").wait()

image: np.ndarray = tasker.controller.post_screencap().wait().get()
```
Expand Down Expand Up @@ -169,7 +169,7 @@ If needed, you can also fine-tune the official pre-trained models of PaddleOCR y
- `logging`: Save the log and generate `debug/maa.log`. Default true.
- `recording`: Save recording function, which will save all screenshots and operation data during operation. You can use `DbgController` for reproducible debugging. Default false.
- `save_draw`: Saves the image recognition visualization results. All image recognition visualization results drawings during the run will be saved. Default false.
- `show_hit_draw`: Displays the task hit pop-up window. Each time the recognition is successful, a pop-up window will display the recognition result. Default false.
- `show_hit_draw`: Displays the node hit pop-up window. Each time the recognition is successful, a pop-up window will display the recognition result. Default false.
- `stdout_level`: The console displays the log level. The default is 2 (Error), which can be set to 0 to turn off all console logs, or to 7 to turn on all console logs.

- If you integrate it yourself, you can enable debugging options through the `Toolkit.init_option` / `MaaToolkitConfigInitOption` interface. The generated json file is the same as above.
Expand Down
90 changes: 45 additions & 45 deletions docs/en_us/3.1-PipelineProtocol.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,21 +4,21 @@

```jsonc
{
"TaskA": {
"NodeA": {
"next: [
"TaskB",
"TaskC"
"NodeB",
"NodeC"
]
// properties ...
},
"TaskB": {
"NodeB": {
// properties ...
},
// other task ...
// other node ...
}
```
When we execute a task (passing the task name to the MaaTaskerPostPipeline interface), it will recognize the tasks in the "next" list one by one (based on the recognition settings for each task). Once a match is found, it will exit the recognition of the "next" list and proceed to execute the matched task. It's similar to traversing and comparing, and as soon as a match is found, it will break and execute the found task.
When we execute a node (passing the entry name to the MaaTaskerPostTask interface), it will recognize the nodes in the "next" list one by one (based on the recognition settings for each node). Once a match is found, it will exit the recognition of the "next" list and proceed to execute the matched node. It's similar to traversing and comparing, and as soon as a match is found, it will break and execute the found node.
## Example
Expand Down Expand Up @@ -53,11 +53,11 @@ For example, let's say we have a game where different fruits, such as apples, or
}
```
Let's assume there are no apples on the screen, but there are oranges and bananas. In the above JSON, if we execute "StartFruit" (i.e., pass "StartFruit" to the MaaTaskerPostPipeline interface), it will first recognize "Apple." Since there are no apples on the screen, it will continue to recognize "Orange." If it recognizes an orange, it will start executing the "Orange" task, and it won't attempt to recognize "Banana." After executing "Orange" according to its action, it will continue to recognize "Orange's" "next" tasks.
Let's assume there are no apples on the screen, but there are oranges and bananas. In the above JSON, if we execute "StartFruit" (i.e., pass "StartFruit" to the MaaTaskerPostTask interface), it will first recognize "Apple." Since there are no apples on the screen, it will continue to recognize "Orange." If it recognizes an orange, it will start executing the "Orange" node, and it won't attempt to recognize "Banana." After executing "Orange" according to its action, it will continue to recognize "Orange's" "next" nodes.
Within "Orange's" "next," if it recognizes "Cat," it won't continue to recognize "Dog." It will execute the "Cat" action and continue to recognize "Cat's" "next" after the action is completed. If neither "Cat" nor "Dog" is recognized, it will continue to attempt recognition for these two tasks until a timeout occurs.
Within "Orange's" "next," if it recognizes "Cat," it won't continue to recognize "Dog." It will execute the "Cat" action and continue to recognize "Cat's" "next" after the action is completed. If neither "Cat" nor "Dog" is recognized, it will continue to attempt recognition for these two nodes until a timeout occurs.
This loop continues until the "next" of a task is empty, which signifies that the task is complete.
This loop continues until the "next" of a node is empty, which signifies that the task is complete.
## Property Fields
Expand All @@ -74,65 +74,65 @@ This loop continues until the "next" of a task is empty, which signifies that th
See [Action Types](#action-types) for details.
- `next`: *string* | *list<string, >*
List of tasks to execute next. Optional, default is empty.
It recognizes each task in sequence and executes the first one it recognizes.
List of nodes to execute next. Optional, default is empty.
It recognizes each node in sequence and executes the first one it recognizes.
- `interrupt` : *string* | *list<string, >*
The list of candidate tasks when all tasks in `next` are not recognized, and similar interrupt operations will be performed. Optional, empty by default.
If all tasks in `next` are not recognized, each task in the interrupt list will be recognized in order, and the first recognized one will be executed. After all subsequent tasks are executed, jump back to this task to try to recognize it again.
The list of candidate nodes when all nodes in `next` are not recognized, and similar interrupt operations will be performed. Optional, empty by default.
If all nodes in `next` are not recognized, each node in the interrupt list will be recognized in order, and the first recognized one will be executed. After all subsequent nodes are executed, jump back to this node to try to recognize it again.
For example: A: { next: [B, C], interrupt: [D, E] }
When B and C are not recognized and D is recognized, D and D.next will be fully executed. But when the pipeline of D is fully executed. It will return to task A again and continue to try to recognize B, C, D, E.
This field is mostly used for exception handling. For example, D is to recognize the "network disconnection prompt box". After clicking confirm and waiting for the network connection to succeed, continue the previous task flow.
When B and C are not recognized and D is recognized, D and D.next will be fully executed. But when the pipeline of D is fully executed. It will return to node A again and continue to try to recognize B, C, D, E.
This field is mostly used for exception handling. For example, D is to recognize the "network disconnection prompt box". After clicking confirm and waiting for the network connection to succeed, continue the previous node flow.
- `is_sub`: *bool*
**(Deprecated in version 2.x, but retains compatibility. `interrupt` is recommended instead.)**
Whether it is a subtask. Optional, default is false.
If it's a subtask, after completing this task (and subsequent tasks such as "next"), it will return to re-recognize the "next" list of this task.
For example: A.next = [B, Sub_C, D], where Sub_C.is_sub = true. If Sub_C is matched, after fully executing Sub_C and subsequent tasks, it will return to re-recognize [B, Sub_C, D] and execute the matching items and subsequent tasks.
Whether it is a sub-node. Optional, default is false.
If it's a sub-node, after completing this node (and subsequent nodes such as "next"), it will return to re-recognize the "next" list of this node.
For example: A.next = [B, Sub_C, D], where Sub_C.is_sub = true. If Sub_C is matched, after fully executing Sub_C and subsequent nodes, it will return to re-recognize [B, Sub_C, D] and execute the matching items and subsequent nodes.

- `rate_limit`: *uint*
Identification rate limit, in milliseconds. Optional, default 1000.
Each round of identification "next" + "interrupt" consumes at least `rate_limit` milliseconds, and sleep will wait if the time is less than that.

- `timeout`: *uint*
Timeout for recognizing "next" + "interrupt" tasks, in milliseconds. Optional, Default is 20,000 milliseconds (20 seconds).
Timeout for recognizing "next" + "interrupt" nodes, in milliseconds. Optional, Default is 20,000 milliseconds (20 seconds).
The detailed logic is `while(!timeout) { foreach(next + interrupt); sleep_until(rate_limit); }`

- `on_error` : *string* | *list<string, >*
When recognition timeout or the action fails to execute, the tasks in this list will be executed next. Optional, empty by default.
When recognition timeout or the action fails to execute, the nodes in this list will be executed next. Optional, empty by default.

- `timeout_next`: *string* | *list<string, >*
**(Deprecated in version 2.x, but retains compatibility. `on_error` is recommended instead.)**
List of tasks to execute after a timeout. Optional, default is empty.
List of nodes to execute after a timeout. Optional, default is empty.

- `inverse`: *bool*
Reverse the recognition result: recognized as not recognized, and not recognized as recognized. Optional, default is false.
Please note that tasks recognized through this setting will have their own clicking actions disabled (because nothing was actually recognized). If there is a need, you can set the `target` separately.
Please note that nodes recognized through this setting will have their own clicking actions disabled (because nothing was actually recognized). If there is a need, you can set the `target` separately.

- `enabled`: *bool*
Whether to enable this task. Optional, default is true.
If set to false, this task will be skipped when it appears in the "next" lists of other tasks, meaning it won't be recognized or executed.
Whether to enable this node. Optional, default is true.
If set to false, this node will be skipped when it appears in the "next" lists of other nodes, meaning it won't be recognized or executed.
- `pre_delay`: *uint*
Delay in milliseconds between recognizing a task and executing the action. Optional, default is 200 milliseconds.
It is recommended to add intermediate tasks whenever possible and use less delay to maintain both speed and stability.
Delay in milliseconds between recognizing a node and executing the action. Optional, default is 200 milliseconds.
It is recommended to add intermediate nodes whenever possible and use less delay to maintain both speed and stability.
- `post_delay`: *uint*
Delay in milliseconds between executing the action and recognizing the "next" tasks. Optional, default is 200 milliseconds.
It is recommended to add intermediate tasks whenever possible and use less delay to maintain both speed and stability.
Delay in milliseconds between executing the action and recognizing the "next" nodes. Optional, default is 200 milliseconds.
It is recommended to add intermediate nodes whenever possible and use less delay to maintain both speed and stability.
- `pre_wait_freezes`: *uint* | *object*
Time in milliseconds to wait for the screen to stop changing between recognizing a task and executing the action. Optional, default is 0 (no waiting).
Time in milliseconds to wait for the screen to stop changing between recognizing a node and executing the action. Optional, default is 0 (no waiting).
It will exit the action only when the screen has not had significant changes for "pre_wait_freezes" milliseconds in a row.
If it's an object, more parameters can be set, see [Waiting for the Screen to Stabilize](#waiting-for-the-screen-to-stabilize) for details. The specific order is `pre_wait_freezes` - `pre_delay` - `action` - `post_wait_freezes` - `post_delay`.

- `post_wait_freezes`: *uint* | *object*
Time in milliseconds to wait for the screen to stop changing between executing the action and recognizing the "next" tasks. Optional, default is 0 (no waiting).
Time in milliseconds to wait for the screen to stop changing between executing the action and recognizing the "next" nodes. Optional, default is 0 (no waiting).
Other logic is the same as `pre_wait_freezes`.

- `focus`: *bool*
Whether to focus on the task, resulting in additional callback messages. Optional, default is false (no messages).
See [Task Notifications](#task-notifications) for details.
Whether to focus on the node, resulting in additional callback messages. Optional, default is false (no messages).
See [Node Notifications](#node-notifications) for details.

## Default Properties

Expand All @@ -154,7 +154,7 @@ This algorithm property requires additional fields:
- `roi`: *array<int, 4>* | *string*
Recognition area coordinates. Optional, default [0, 0, 0, 0], i.e. full screen.
- *array<int, 4>*: Recognition area coordinates, [x, y, w, h], if you want full screen, you can set it to [0, 0, 0, 0].
- *string*: Fill in the task name, and identify within the target range identified by a previously executed task.
- *string*: Fill in the node name, and identify within the target range identified by a previously executed node.

- `roi_offset`: *array<int, 4>*
Move additionally based on `roi` as the range, and add the four values ​​separately. Optional, default [0, 0, 0, 0].
Expand Down Expand Up @@ -434,8 +434,8 @@ Additional properties for this action:

- `target`: *true* | *string* | *array<int, 4>*
The position to click. Optional, default is true.
- *true*: Clicks the target just recognized in this task (i.e., clicks itself).
- *string*: Enter the task name to click a target recognized by a previously executed task.
- *true*: Clicks the target just recognized in this node (i.e., clicks itself).
- *string*: Enter the node name to click a target recognized by a previously executed node.
- *array<int, 4>*: Clicks a random point within a fixed coordinate area [x, y, w, h]. To click the entire screen, set it to [0, 0, 0, 0].

- `target_offset`: *array<int, 4>*
Expand Down Expand Up @@ -551,7 +551,7 @@ Additional properties for this action:

### `StopTask`

Stops the current task chain (the individual task chain passed to MaaTaskerPostPipeline).
Stops the current task chain (the individual task chain passed to MaaTaskerPostTask).

### `Command`

Expand All @@ -574,13 +574,13 @@ This action attribute requires additional fields:
- `{LIBRARY_DIR}`: The path of the folder where the MaaFW library is located.

- `detach`: *bool*
Detach the child process, that is, do not wait for the child process to complete, and directly continue with the subsequent tasks. Optional, default false.
Detach the child process, that is, do not wait for the child process to complete, and directly continue with the subsequent nodes. Optional, default false.

Example:

```jsonc
{
"TaskA": {
"NodeA": {
"action": "Command",
"exec": "Python",
"args": [
Expand All @@ -591,7 +591,7 @@ Example:
"{BOX}"
]
},
"TaskB": {
"NodeB": {
"action": "Command",
"exec": "{RESOURCE_DIR}/my_exec/my_exec.exe"
}
Expand All @@ -601,10 +601,10 @@ Example:
The actual command is:

```bash
# TaskA
Python C:/MaaXXX/resource/my_script/test.py Haha C:/temp/123.png TaskA [0,0,0,0]
# NodeA
Python C:/MaaXXX/resource/my_script/test.py Haha C:/temp/123.png NodeA [0,0,0,0]
# TaskB
# NodeB
C:/MaaXXX/resource/my_exec/my_exec.exe
```

Expand Down Expand Up @@ -634,10 +634,10 @@ The field value can be a uint or an object. For example:

```jsonc
{
"TaskA": {
"NodeA": {
"pre_wait_freezes": 500
},
"TaskB": {
"NodeB": {
"pre_wait_freezes": {
// more properties ...
}
Expand Down Expand Up @@ -669,6 +669,6 @@ If the value is an object, you can set additional fields:
- `timeout`: *uint*
Timeout for recognizing, in milliseconds. Optional, default is 20,000 milliseconds (20 seconds).

## Task Notifications
## Node Notifications

See [Callback Protocol](2.2-CallbackProtocol.md) (not written yet).
8 changes: 4 additions & 4 deletions docs/en_us/NodeJS/J1.1-QuickStarted.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ async function main() {
console.log(msg, detail)
}
// Load resource
await res.post_path('./resource')
await res.post_bundle('./resource')

// Create tasker
const tskr = new maa.Tasker()
Expand All @@ -76,7 +76,7 @@ async function main() {

// Launch task. Task1 is declared in pipeline/Task.json
if (await tskr
.post_pipeline('Task1')
.post_task('Task1')
.wait().success) {
console.log('success!')
}
Expand All @@ -87,7 +87,7 @@ main()

## Alter Resource Behavior on NodeJS Side

Take a look at this code `await tskr.post_pipeline('task', 'Task1').wait()`
Take a look at this code `await tskr.post_task('task', 'Task1').wait()`

Function `post` can be called with three params. The third one is an object, which has exact the same structure to json in `pipeline`, and will override the original `pipeline`. Thus, you can pass an object here to control the task (even create new task).

Expand All @@ -97,7 +97,7 @@ Function `post` can be called with three params. The third one is an object, whi
// 通过第三个参数, 创建了一个新的任务Task2, 然后执行它
// 此处创建的任务仅在当前执行中有效
await tskr
.post_pipeline('Task2', {
.post_task('Task2', {
Task2: {
next: [
'Task1'
Expand Down
Loading

0 comments on commit 837782d

Please sign in to comment.