Files
MaaAssistantArknights/docs/en-us/protocol/integration.md
Constrat a65299e4df i18n: EN overhaul entire documentation!
Thank you Claude
2025-08-05 19:40:51 +02:00

518 lines
26 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
order: 1
icon: bxs:book
---
# Integration
## API
### `AsstAppendTask`
#### Prototype
```cpp
TaskId ASSTAPI AsstAppendTask(AsstHandle handle, const char* type, const char* params);
```
#### Description
Appends a task.
#### Return Value
- `TaskId`
The task ID if the task is successfully appended, for the following configuration;
0 if the task is not successfully appended.
#### Parameter Description
- `AsstHandle handle`
Instance handle
- `const char* type`
Task type
- `const char* params`
Task parameters in JSON
##### List of Task Types
- `StartUp`
Start-up
```json5
// Corresponding task parameters
{
"enable": bool, // Whether to enable this task, optional, true by default
"client_type": string, // Client version, required
// Options: "Official" | "Bilibili" | "txwy" | "YoStarEN" | "YoStarJP" | "YoStarKR"
"start_game_enabled": bool, // Whether to launch client automatically, optional, false by default
"account_name": string // Switch account, optional, don't switch by default
// Only supports switching to already logged-in accounts, using login name for identification
// Official server: 123****4567, can input 123****4567, 4567, 123, or 3****4567
// Bilibili server: Zhang San, can input Zhang San, Zhang, or San
}
```
- `CloseDown`
Close Game Client
```json5
// Corresponding task parameters
{
"enable": bool, // Whether to enable this task, optional, true by default
"client_type": string, // Client version, required, no execution if left blank
// Options: "Official" | "Bilibili" | "txwy" | "YoStarEN" | "YoStarJP" | "YoStarKR"
}
```
- `Fight`
Operation
```json5
// Corresponding task parameters
{
"enable": bool, // Whether to enable this task, optional, true by default
"stage": string, // Stage name, optional, by default current/last stage. Editing in run-time is not supported.
// Supports all mainline stages, such as "1-7", "S3-2", etc.
// At the end of the level, enter Normal/Hard to switch between Normal and Tough difficulty
// Annihilation. The input should be `Annihilation`.
// For current SS event last three stages, must input complete stage code.
"medicine": int, // Maximum number of Sanity Potions used, optional, by default 0
"expiring_medicine": int, // Maximum number of expired Sanity Potions within 48 hours, optional, by default 0
"stone": int, // Maximum number of Originite Prime used, optional, by default 0
"times": int, // Fight times, optional, by int32.max
"series": int, // Number of series, optional, -1~6
// -1 To disable switching series
// 0 To automatically switch to the maximum number of series currently available, if the current sanity is less than 6 times, select the minimum number of times available
// 1~6 To modify to a specified number of times
"drops": { // Specifying the number of drops, optional, no specification by default
"30011": int, // Key: item ID; value: number of items. Key refers to resource/item_index.json
"30062": int // OR combination
},
/* Items are combined with OR operators, i.e. the task stops when any condition meets. */
"report_to_penguin": bool, // Whether to upload data to Penguin Statistics, optional, by default false
"penguin_id": string, // Penguin Statistics ID, optional, by default empty. Available only when `report_to_penguin` is `true`.
"server": string, // Server, optional, by default "CN", will affect the drop recognition and upload
// Options"CN" | "US" | "JP" | "KR"
"client_type": string, // Client version, optional, empty by default. Used to reconnect after the game crashed. Empty means to disable this feature
// Options: "Official" | "Bilibili" | "txwy" | "YoStarEN" | "YoStarJP" | "YoStarKR"
"DrGrandet": bool, // Save sanity by using Originites, optional, false by default. effective only when Originites may be used
// Wait in the using Originites confirmation screen until the 1 point of sanity has been restored and then immediately use the Originite.
}
```
Supports some of the special stages, please refer to [autoLocalization example](https://github.com/MaaAssistantArknights/MaaAssistantArknights/blob/master/tools/AutoLocalization/example/en-us.xaml#L260).
- `Recruit`
Recruitment
```json5
// Corresponding task parameters
{
"enable": bool, // Whether to enable this task, optional, by default true
"refresh": bool, // Whether to refresh 3★ tags, optional, by default false
"select": [ // Tag level to click, required
int,
...
],
"confirm": [ // Tag level for confirmation, required. Can be set to empty array for calculation only.
int,
...
],
"first_tags": [ // Preferred Tags, valid only if 3★ tags. Optional, by default empty
string, // When Tag is level-3, as many Tags here as possible (if any) will be selected.
... // It's a forced selection, i.e. it ignores all "unselect 3★ Tags" settings.
],
"extra_tags_mode": int, // Select more tags, optional, default is 0
// 0 - default behavior
// 1 - select 3 tags even if they may conflict
// 2 - select more high star tag combinations if possible, even if they might conflict
"times": int, // The times of recruitment, optional, by default 0. Can be set to 0 for calculation only.
"set_time": bool, // Whether to set time to 9 hours, available only when `times` is 0, optional, by default true
"expedite": bool, // Whether to use expedited plans, optional, by default false
"expedite_times": int, // The times of using expedited plans, available only when `expedite` is `true`
// Optional, by default infinity until `times` reaches its limitation.
"skip_robot": bool, // Whether to skip when robot tag is recognized, optional, skip by default.
"recruitment_time": { // Tags level and set duration in minutes, optional, by default 540 (i.e. 9 hours)
"3": int,
"4": int,
...
},
"report_to_penguin": bool, // Whether to report to Penguin Statistics, optional, by default false.
"penguin_id": string, // Penguin Statistics user id, optional, by default empty. Valid only if report_to_penguin is true.
"report_to_yituliu": bool, // Whether to report to YITULIU, optional, by default false.
"yituliu_id": string, // YITULIU user id, optional, by default empty. Valid only if report_to_yituliu is true.
"server": string, // Server, optional, by default "CN", will affect upload
// Options: "CN" | "US" | "JP" | "KR"
}
```
- `Infrast`
Infrastructure shifting
```json5
{
"enable": bool, // Whether to enable this task, optional, by default true
"mode": int, // Shift mode, optional. Editing in run-time is not supported.
// 0 - Default: Default shift mode, single facility optimal solution
// 10000 - Custom: Custom shift mode, reads user configuration, see protocol/base-scheduling-schema.md
// 20000 - Rotation: One-key rotation mode, skips control center, power station, dormitory and office, other facilities do not change shifts but retain basic operations (such as using drones, reception room logic)
"facility": [ // Facilities for shifting (ordered), required. Editing in run-time is not supported.
string, // Facility name: "Mfg" | "Trade" | "Power" | "Control" | "Reception" | "Office" | "Dorm"
...
],
"drones": string, // Usage of drones, optional, by default "_NotUse"
// This field is ignored when mode = 10000
// "_NotUse" | "Money" | "SyntheticJade" | "CombatRecord" | "PureGold" | "OriginStone" | "Chip"
"threshold": float, // Morale threshold with range [0, 1.0], optional, by default 0.3
// When mode = 10000, this field is only effective for "autofill"
// This field is ignored when mode = 20000
"replenish": bool, // Whether to replenish Originium Shard in trading post, optional, by default false
"dorm_notstationed_enabled": bool, // Whether to enable "Not Stationed in Dorm" option, optional, by default false
"dorm_trust_enabled": bool, // Whether to fill dormitory with operators not at max trust, optional, by default false
"reception_message_board": bool, // Whether to collect credits from reception room message board, optional, by default true
"reception_clue_exchange": bool, // Whether to perform clue exchange, optional, by default true
/* The following parameters are only effective when mode = 10000, otherwise they are ignored */
"filename": string, // Custom config path, required. Editing in run-time is not supported.
"plan_index": int, // Plan index number in the configuration, required. Editing in run-time is not supported.
}
```
- `Mall`
Collecting Credits and auto-purchasing.
Will buy items in order following `buy_first` list, buy other items from left to right ignoring items in `blacklist`, and buy other items from left to right ignoring the `blacklist` while credit overflows.
```json5
// Corresponding task parameters
{
"enable": bool, // Whether to enable this task, optional, by default true
"shopping": bool, // Whether to buy items from the store, optional, by default false. Editing in run-time is not supported.
"buy_first": [ // Items to be purchased with priority, optional. Editing in run-time is not supported.
string, // Item name, e.g. "招聘许可" (Recruitment Permit), "龙门币" (LMD), etc.
...
],
"blacklist": [ // Blacklist, optional. Editing in run-time is not supported.
string, // Item name, e.g. "加急许可" (Expedited Plan), "家具零件" (Furniture Part), etc.
...
],
"force_shopping_if_credit_full": bool, // Whether to ignore the Blacklist if credit overflows, by default true
"only_buy_discount": bool, // Whether to purchase only discounted items, applicable only on the second round of purchases, by default false
"reserve_max_credit": bool // Whether to stop purchasing when credit points fall below 300, applicable only on the second round of purchases, by default false
}
```
- `Award`
Collecting various rewards
```json5
// Corresponding task parameters
{
"enable": bool, // Whether to enable this task, optional, by default true
"award": bool, // Collect daily/weekly task rewards, default true
"mail": bool, // Collect all mail rewards, default false
"recruit": bool, // Collect daily free pulls from limited banners, default false
"orundum": bool, // Collect Originium from lucky drop wall, default false
"mining": bool, // Collect Originium from limited mining licenses, default false
"specialaccess": bool // Collect monthly card rewards from 5th anniversary, default false
}
```
- `Roguelike`
Integrated Strategies
```json5
// Task parameters
{
"enable": bool, // Whether to enable this task, optional, default is true
"theme": string, // Theme, optional, default is "Phantom"
// Phantom - Phantom & Crimson Solitaire
// Mizuki - Mizuki & Caerula Arbor
// Sami - Expeditioner's Jǫklumarkar
// Sarkaz - 萨卡兹的无终奇语 (Sarkaz Endless Tale)
// JieGarden - 界园 (Boundary Garden)
"mode": int, // Mode, optional, default is 0
// 0 - Score farming/reward points, aiming to consistently reach higher levels
// 1 - Source stone farming, exit after investing in the first layer
// 2 - [Deprecated] Balances modes 0 and 1; continues until the next investment, exits otherwise
// 3 - Under development...
// 4 - Opening reset; first reaches the third layer at difficulty 0, then restarts and switches to the specified difficulty to reset
// the opening reward. If not a specific item, restart at difficulty 0; in the Phantom theme, retry only in the current difficulty
// 5 - Collapsal Paradigm farming; only for the Sami theme; accelerates collapsal buildup via missed enemies;
// if the first collapsal paradigm encountered is in the `expected_collapsal_paradigms` list, stops the task; otherwise, restarts
// 6 - Monthly squad rewards farming, same as mode 0 except for specific mode adaptations
// 7 - Deep Dive rewards farming, same as mode 0 except for specific mode adaptations
"squad": string, // Starting squad name, optional, default is "指挥分队" (Command Squad);
"roles": string, // Starting role group, optional, default is "取长补短" (Complementary Strength);
"core_char": string, // Starting operator name, optional; supports only single operator **in Chinese**, regardless of server;
// leave empty or set to "" to auto-select based on level
"use_support": bool, // Whether the starting operator is a support operator, optional, default is false
"use_nonfriend_support": bool, // Whether non-friend support operators are allowed, optional, default is false; only effective when `use_support` is true
"starts_count": int, // Number of times to start exploration, optional, default is INT_MAX; stops automatically upon reaching limit
"difficulty": int, // Specified difficulty level, optional, default is 0; only applicable to themes **excluding Phantom**;
// selects the highest unlocked difficulty if the desired one is not unlocked
"stop_at_final_boss": bool, // Whether to stop before the level 5 final boss node, optional, default is false; only applicable to themes **excluding Phantom**
"stop_at_max_level": bool, // Whether to stop if max level for roguelike has been achieved, optional, default is false
"investment_enabled": bool, // Whether to invest source stones, optional, default is true
"investments_count": int, // Number of source stone investments, optional, default is INT_MAX; stops automatically upon reaching limit
"stop_when_investment_full": bool, // Whether to stop automatically when investment limit is reached, optional, default is false
"investment_with_more_score": bool, // Whether to try shopping after investment, optional, default is false; only applicable to mode 1
"start_with_elite_two": bool, // Whether to start with an Elite 2 operator reset, optional, default is false; only applicable to mode 4
"only_start_with_elite_two": bool, // Whether to reset only for Elite 2 operator while ignoring other starting conditions, optional, default is false;
// only effective when mode is 4 and `start_with_elite_two` is true
"refresh_trader_with_dice": bool, // Whether to refresh the shop with dice for special items, optional, default is false; only applicable to the Mizuki theme, used to refresh pointers
"first_floor_foldartal": string, // Desired Foldartal to acquire in the first floor foresight phase, optional; only applicable to the Sami theme, any mode;
// task stops once obtained successfully
"start_foldartal_list": [ // Desired Foldartals for the starting reward phase during opening reset, optional, default is []; effective only for Sami theme and mode 4;
string, // Reset is successful only when all Foldartals in the list are present in the opening rewards;
... // Note: This parameter must be used with the "生活至上分队" (Life-Sustaining Squad) as other squads do not obtain Foldartals in the opening reward phase;
],
"collectible_mode_start_list": { // Desired starting rewards (optional), all false by default; only valid in mode 4
"hot_water": bool, // Hot Water reward, typically used to trigger boiling mechanism (universal)
"shield": bool, // Shield reward, equivalent to extra HP (universal)
"ingot": bool, // Originium Ingot reward (universal)
"hope": bool, // Hope reward (universal, note: not available in JieGarden theme)
"random": bool, // Random reward option: consumes all Ingots for a random collectible (universal)
"key": bool, // Key reward, only available in Mizuki theme
"dice": bool, // Dice reward, only available in Mizuki theme
"ideas": bool, // 2 Ideas reward, only available in Sarkaz theme
},
"use_foldartal": bool, // Whether to use Foldartals, default is false in mode 5 and true in other modes; only applicable to the Sami theme
"check_collapsal_paradigms": bool, // Whether to check obtained Collapsal Paradigms, default is true in mode 5 and false in other modes
"double_check_collapsal_paradigms": bool, // Whether to perform additional checks to prevent missed Collapsal Paradigms, default is true in mode 5 and false in other modes;
// only effective when theme is Sami and `check_collapsal_paradigms` is true
"expected_collapsal_paradigms": [ // Desired Collapsal Paradigms to trigger, default is ["目空一些" (Blank Somewhat), "睁眼瞎" (Blind Eye), "图像损坏" (Image Distortion), "一抹黑" (Pitch Black)];
string, // only effective when theme is Sami and mode is 5
...
],
"monthly_squad_auto_iterate": bool, // Whether to enable automatic monthly squad rotation
"monthly_squad_check_comms": bool, // Whether to also check monthly squad communications as rotation criteria
"deep_exploration_auto_iterate": bool, // Whether to enable automatic deep exploration rotation
"collectible_mode_shopping": bool, // Whether to enable shopping in hot water mode, default false
"collectible_mode_squad": string, // Squad to use in hot water mode, default synced with squad, when squad is empty and collectible_mode_squad not specified, uses Command Squad
"collectible_mode_start_list": { // Desired rewards for hot water mode, all false by default, key options:
"hot_water": bool, // [hot_water: Hot water, shield: Shield, ingot: Originium Ingot, hope: Hope, random: Random reward, key: Key, dice: Dice, ideas: Ideas]
...
},
"start_with_seed": bool, // Use seed for money farming, effective when true
// Only possible to be true in Sarkaz theme, Investment mode, with "点刺成锭分队" (Point-Stab Ingot Squad) or "后勤分队" (Logistics Squad)
// Uses fixed seed
}
```
For specific information about the Collapsal Paradigm farming feature, please refer to [Integrated Strategy Schema](./integrated-strategy-schema.md#sami-integrated-strategy-collapsal-paradigms)
- `Copilot`
Auto combat feature
```json5
{
"enable": bool, // Whether to enable this task, optional, by default true
"filename": string, // Filename and path of the task JSON, supporting absolute/relative paths. Editing in run-time is not supported.
"formation": bool // Whether to "quick build", optional, by default false. Editing in run-time is not supported.
}
```
For more details about auto-combat JSON, please refer to [Combat Operation Protocol](./copilot-schema.md)
- `SSSCopilot`
Auto combat feature for Stationary Security Service
```json5
{
"enable": bool, // Whether to enable this task, optional, by default true
"filename": string, // Filename and path of the task JSON, supporting absolute/relative paths. Editing in run-time is not supported.
"loop_times": int // Number of times to loop execution
}
```
For more details about Stationary Security Service JSON, please refer to [SSS Schema](./sss-schema.md)
- `Depot`
Depot recognition
```json5
// Corresponding task parameters
{
"enable": bool // Whether to enable this task, optional, by default true
}
```
- `OperBox`
Operator box recognition
```json5
// Corresponding task parameters
{
"enable": bool // Whether to enable this task, optional, by default true
}
```
- `Reclamation`
Reclamation Algorithm
```json5
{
"enable": bool,
"theme": string, // Theme, optional, Fire by default
// Fire - *Fire Within the Sand*
// Tales - *Tales Within the Sand*
"mode": int, // Mode, optional, 0 by default
// 0 - Farm badges & construction pts (exiting the stage immediately)
// 1 - Fire Within the Sand: Farm Crude Gold (forging Gold at headquarter after purchasing water)
// Tales Within the Sand: Automatically craft items and load to earn currency
"tools_to_craft": [
string, // Automatically crafted items, optional, glow stick by default
...
]
// Suggested to fill in the substring
"increment_mode": int, // Click type, optional. 0 by default
// 0 - Rapid Click
// 1 - Long Press
"num_craft_batches": int // Maximum number of craft batches per session, optional. 16 by default
}
```
- `Custom`
Custom Task
```json5
{
"enable": bool,
"task_names": [ // Execute the task on the first match in the array (and subsequent next, etc.)
// If you want to perform multiple tasks, you can append Custom task multiple times
string,
...
]
}
```
- `SingleStep`
Single-step task (currently only supports copilot)
```json5
{
"enable": bool,
"type": string, // currently only supports "copilot"
"subtask": string, // "stage" | "start" | "action"
// "stage" to set stage name, eg: "details": { "stage": "xxxx" }
// "start" to start mission, without details
// "action": single battle action, details is single action in Copilot,
// eg: "details": { "name": "史尔特尔", "location": [ 4, 5 ], "direction": "左" }, see protocol/copilot-schema.md for details
"details": {
...
}
}
```
- `VideoRecognition`
Video recognition, currently only supports operation (combat) video
```json5
{
"enable": bool,
"filename": string, // Video file path, supporting absolute/relative paths. Editing in run-time is not supported.
}
```
### `AsstSetTaskParams`
#### Prototype
```cpp
bool ASSTAPI AsstSetTaskParams(AsstHandle handle, TaskId id, const char* params);
```
#### Description
Set task parameters
#### Return Value
- `bool`
Whether the parameters are successfully set.
#### Parameter Description
- `AsstHandle handle`
Instance handle
- `TaskId task`
Task ID, the return value of `AsstAppendTask`
- `const char* params`
Task parameter in JSON, same as `AsstAppendTask`
For those fields that do not mention "Editing in run-time is not supported" can be changed during run-time. Otherwise these changes will be ignored when the task is running.
### `AsstSetStaticOption`
#### Prototype
```cpp
bool ASSTAPI AsstSetStaticOption(AsstStaticOptionKey key, const char* value);
```
#### Description
Set process-level parameters
#### Return Value
- `bool`
Is the setup successful
#### Parameter Description
- `AsstStaticOptionKey key`
key
- `const char* value`
value
##### List of Key and value
None currently
### `AsstSetInstanceOption`
#### Prototype
```cpp
bool ASSTAPI AsstSetInstanceOption(AsstHandle handle, AsstInstanceOptionKey key, const char* value);
```
#### Description
Set instance-level parameters
#### Return Value
- `bool`
Is the setup successful
#### Parameter Description
- `AsstHandle handle`
handle
- `AsstInstanceOptionKey key`
key
- `const char* value`
value
##### List of Key and value
```cpp
enum InstanceOptionKey
{
Invalid = 0,
// Deprecated // MinitouchEnabled = 1, // Is minitouch enabled
// If you can't use minitouch, it's useless to turn it on.
// "1" - on, "0" - off
TouchMode = 2, // Touch mode, minitouch by default
// minitouch | maatouch | adb
DeploymentWithPause = 3, // Deployment with Pause (Works for IS, Copilot and Stationary Security Service)
// "1" | "0"
AdbLiteEnabled = 4, // Enable AdbLite or not, "0" | "1"
KillAdbOnExit = 5, // Release Adb on exit, "0" | "1"
};
```