fz-mirrors/MaaAssistantArknights
0
0
Fork 0
mirror of https://github.com/MaaAssistantArknights/MaaAssistantArknights.git synced 2026-07-01 10:10:27 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
8815af55334b966674da583763123c52b27b2387
MaaAssistantArknights/docs/en-us/protocol/integration.md

37 KiB
Raw Blame History

order, icon
order icon
1 bxs:book

Integration

API

AsstAppendTask

Prototype

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

:::: field-group
::: field name="handle" type="AsstHandle" required
Instance handle
:::
::: field name="type" type="const char*" required
Task type
:::
::: field name="params" type="const char*" required
Task parameters, json string
:::
::::

List of Task Types
  • StartUp
    Start-up

:::: field-group
::: field name="enable" type="boolean" optional default="true"
Whether to enable this task.
:::
::: field name="client_type" type="string" required
Client version.

Options: Official | Bilibili | txwy | YoStarEN | YoStarJP | YoStarKR
:::
::: field name="start_game_enabled" type="boolean" optional default="false"
Whether to launch client automatically.
:::
::: field name="account_name" type="string" optional
Switch account, don't switch by default.

Only supports switching to already logged-in accounts, using login name for identification, ensure the input content is unique among all logged-in accounts.

Official server: 123****4567, can input 123****4567, 4567, 123, or 3****4567

Bilibili server: Zhang San, can input Zhang San, Zhang, or San
:::
::::

Example 
{
   "enable": true,
   "client_type": "Official",
   "start_game_enabled": true,
   "account_name": "123****4567"
}
  • CloseDown
    Close Game Client

:::: field-group
::: field name="enable" type="boolean" optional default="true"
Whether to enable this task.
:::
::: field name="client_type" type="string" required
Client version, no execution if left blank.

Options: Official | Bilibili | txwy | YoStarEN | YoStarJP | YoStarKR
:::
::::

Example 
{
   "enable": true,
   "client_type": "Official"
}
  • Fight
    Operation

:::: field-group
::: field name="enable" type="boolean" optional default="true"
Whether to enable this task.
:::
::: field name="stage" type="string" optional
Stage name, by default empty, recognizes current/last stage. Editing in run-time is not supported.
Currently supported stages for navigation include:

  • All mainline stages. You can add -NORMAL or -HARD at the end of the stage to switch difficulty: Chapters 10-14 map to Standard/Adverse, while Chapters 15+ map to Normal/Raid.
  • For LMD and Battle Record stages 5/6, must input CE-6 / LS-6. MAA will automatically switch to stage 5 if stage 6 cannot be delegated.
  • Skill Summary, Voucher, and Carbon stage 5, must input CA-5 / AP-5 / SK-5.
  • All chip stages. Must input complete stage code, e.g. PR-A-1.
  • Annihilation mode supports the following values, must use corresponding Value:
    • Current Annihilation: Annihilation
    • Chernobog: Chernobog@Annihilation
    • Lungmen Outskirts: LungmenOutskirts@Annihilation
    • Lungmen Downtown: LungmenDowntown@Annihilation
  • OF-1 / OF-F3 in side stories.
  • Last three stages of current SS events. Visit API for the list of supported stages. Requires additional loading of event stage navigation in tasks.json file.
  • Rerun SS events. Input SSReopen-<stage prefix> to farm XX-1 ~ XX-9 stages at once, e.g. SSReopen-IC. :::
    ::: field name="medicine" type="number" optional default="0"
    Maximum number of Sanity Potions used.
    :::
    ::: field name="expiring_medicine" type="number" optional default="0"
    Maximum number of Sanity Potions expiring within 48 hours.
    :::
    ::: field name="stone" type="number" optional default="0"
    Maximum number of Originite Prime used.
    :::
    ::: field name="times" type="number" optional default="2147483647"
    Number of battles.
    :::
    ::: field name="series" type="number" optional
    Number of consecutive battles, -1~6.
    -1 to disable switching.
    0 to automatically switch to the current maximum available times, if current sanity is not enough for 6 times, select the minimum available times.
    1~6 to specify number of consecutive battles.
    :::
    ::: field name="drops" type="object" optional
    Specifying the number of drops, no specification by default. key is item_id, value is quantity. key can refer to resource/item_index.json file.

    Example: { "30011": 10, "30062": 5 }

    All above are OR relations, i.e. task stops when any one is reached.
    :::
    ::: field name="report_to_penguin" type="boolean" optional default="false"
    Whether to upload data to Penguin Statistics.
    :::
    ::: field name="penguin_id" type="string" optional
    Penguin Statistics report id, empty by default. Only effective when report_to_penguin is true.
    :::
    :::
    ::: field name="report_to_yituliu" type="boolean" optional default="false"
    Whether to report to YITULIU.
    :::
    ::: field name="yituliu_id" type="string" optional
    YITULIU report id, empty by default. Only effective when report_to_yituliu is true.
    :::
    ::: field name="server" type="string" optional default="CN"
    Server, will affect drop recognition and upload.
    Options: CN | US | JP | KR
    :::
    ::: field name="client_type" type="string" optional
    Client version, empty by default. Used to restart and reconnect after game crash, does not enable this feature if empty.
    Options: Official | Bilibili | txwy | YoStarEN | YoStarJP | YoStarKR
    :::
    ::: field name="DrGrandet" type="boolean" optional default="false"
    Sanity-saving Originite usage mode, only effective when Originite usage may occur.
    Wait at the Originite confirmation screen until the current 1 sanity point is restored, then immediately use Originite.
    :::
    ::::
Example 
{
   "enable": true,
   "stage": "1-7",
   "medicine": 1,
   "expiring_medicine": 0,
   "stone": 0,
   "times": 10,
   "series": 0,
   "drops": {
      "30011": 10
   },
   "report_to_penguin": true,
   "penguin_id": "123456",
   "report_to_yituliu": true,
   "yituliu_id": "123456",
   "server": "CN",
   "client_type": "Official",
   "DrGrandet": false
}
  • Recruit
    Recruitment

:::: field-group
::: field name="enable" type="boolean" optional default="true"
Whether to enable this task.
:::
::: field name="refresh" type="boolean" optional default="false"
Whether to refresh 3★ tags.
:::
::: field name="select" type="array" required
Tag ★ rarity to click.
:::
::: field name="confirm" type="array" required
Tag ★ rarity for confirmation. Can be set to empty array for calculation only.
:::
::: field name="first_tags" type="array" optional
Preferred Tags, valid only when selecting 3★ tags. Default is empty.
For 3★ recruits, MAA will try to include as many of the listed tags as possible. This is treated as a hard requirement and will override any "don't select 3★ Tags" settings.
:::
::: field name="extra_tags_mode" type="number" optional default="0"
Select more tags.
0 - default behavior
1 - select 3 tags even if they may conflict
2 - if possible, select more high star tag combinations even if they might conflict
:::
::: field name="times" type="number" optional default="0"
Number of recruitments. Can be set to 0 for calculation only.
:::
::: field name="set_time" type="boolean" optional default="true"
Whether to set recruitment time limit. Only effective when times is 0.
:::
::: field name="expedite" type="boolean" optional default="false"
Whether to use Expedited Plans.
:::
::: field name="expedite_times" type="number" optional
Number of expedites, only effective when expedite is true. By default unlimited (until times limit is reached).
:::
::: field name="skip_robot" type="boolean" optional default="true"
Whether to skip when robot tag is recognized.
:::
::: field name="recruitment_time" type="object" optional
Tag ★ rarity (greater than or equal to 3) and corresponding desired recruitment time limit, in minutes, all default to 540 (i.e. 09:00:00).
Example: { "3": 540, "4": 540 }
:::
::: field name="report_to_penguin" type="boolean" optional default="false"
Whether to report to Penguin Statistics.
:::
::: field name="penguin_id" type="string" optional
Penguin Statistics report id, empty by default. Only effective when report_to_penguin is true.
:::
::: field name="report_to_yituliu" type="boolean" optional default="false"
Whether to report to YITULIU data.
:::
::: field name="yituliu_id" type="string" optional
YITULIU report id, empty by default. Only effective when report_to_yituliu is true.
:::
::: field name="server" type="string" optional default="CN"
Server, will affect upload.
Options: CN | US | JP | KR
:::
::::

Example 
{
   "enable": true,
   "refresh": true,
   "select": [5, 4],
   "confirm": [4, 3],
   "first_tags": ["高级资深干员"],
   "extra_tags_mode": 1,
   "times": 4,
   "set_time": true,
   "expedite": false,
   "expedite_times": 0,
   "skip_robot": true,
   "recruitment_time": {
      "3": 540,
      "4": 540
   },
   "report_to_penguin": false,
   "penguin_id": "123456",
   "report_to_yituliu": false,
   "yituliu_id": "123456",
   "server": "CN"
}
  • Infrast
    Infrastructure shifting

:::: field-group
::: field name="enable" type="boolean" optional default="true"
Whether to enable this task.
:::
::: field name="mode" type="number" optional default="0"
Shift mode. 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 Base Scheduling Schema.
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).
:::
::: field name="facility" type="array" required
Facilities for shifting (ordered). Editing in run-time is not supported.
Facility name: Mfg | Trade | Power | Control | Reception | Office | Dorm | Processing | Training
:::
::: field name="drones" type="string" optional default="_NotUse"
Usage of drones. This field is ignored when mode = 10000.
Options: _NotUse | Money | SyntheticJade | CombatRecord | PureGold | OriginStone | Chip
:::
::: field name="threshold" type="number" optional default="0.3"
Morale threshold, range [0, 1.0].
When mode = 10000, this field is only effective for "autofill".
This field is ignored when mode = 20000.
:::
::: field name="replenish" type="boolean" optional default="false"
Whether to replenish Originium Shard in trading post.
:::
::: field name="dorm_notstationed_enabled" type="boolean" optional default="false"
Whether to enable "Not Stationed in Dorm" option.
:::
::: field name="dorm_trust_enabled" type="boolean" optional default="false"
Whether to fill dormitory with operators not at max trust.
:::
::: field name="reception_message_board" type="boolean" optional default="true"
Whether to collect credits from reception room message board.
:::
::: field name="reception_clue_exchange" type="boolean" optional default="true"
Whether to perform clue exchange.
:::
::: field name="reception_send_clue" type="boolean" optional default="true"
Whether to send clues.
:::
::: field name="filename" type="string" required
Custom config path. Editing in run-time is not supported.

:::
::: field name="plan_index" type="number" required
Plan index number in the configuration. Editing in run-time is not supported.

:::
::::

Example 
{
   "enable": true,
   "mode": 0,
   "facility": ["Mfg", "Trade", "Reception"],
   "drones": "PureGold",
   "threshold": 0.3,
   "replenish": true,
   "dorm_notstationed_enabled": false,
   "dorm_trust_enabled": true,
   "reception_message_board": true,
   "reception_clue_exchange": true,
   "reception_send_clue": true,
   "filename": "schedules/base.json",
   "plan_index": 1
}
  • 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.

:::: field-group
::: field name="enable" type="boolean" optional default="true"
Whether to enable this task.
:::
::: field name="visit_friends" type="boolean" optional default="true"
Whether to visit friends' base to obtain Credits.
:::
::: field name="shopping" type="boolean" optional default="true"
Whether to buy items from the store.
:::
::: field name="buy_first" type="array" optional default="[]"
Items to be purchased with priority. Item name, e.g. "招聘许可" (Recruitment Permit), "龙门币" (LMD), etc.
:::
::: field name="blacklist" type="array" optional default="[]"
Blacklist. Item name, e.g. "加急许可" (Expedited Plan), "家具零件" (Furniture Part), etc.
:::
::: field name="force_shopping_if_credit_full" type="boolean" optional default="false"
Whether to ignore the Blacklist if credit overflows.
:::
::: field name="only_buy_discount" type="boolean" optional default="false"
Whether to purchase only discounted items, applicable only on the second round of purchases.
:::
::: field name="reserve_max_credit" type="boolean" optional default="false"
Whether to stop purchasing when credit points fall below 300, applicable only on the second round of purchases.
:::
::: field name="credit_fight" type="boolean" optional default="false"
Whether to run one battle of OF-1 to gain more Credits the next day.
:::
::: field name="formation_index" type="number" optional default="0"
Formation slot index used for the OF-1 battle.
Integer between 0–4, where 0 = current squad, 1–4 = first, second, third, fourth squad.
:::
::::

Example 
{
   "enable": true,
   "visit_friends": true,
   "shopping": true,
   "buy_first": ["招聘许可", "龙门币"],
   "blacklist": ["家具零件"],
   "force_shopping_if_credit_full": false,
   "only_buy_discount": true,
   "reserve_max_credit": false,
   "credit_fight": false,
   "formation_index": 0
}
  • Award
    Collecting various rewards

:::: field-group
::: field name="enable" type="boolean" optional default="true"
Whether to enable this task.
:::
::: field name="award" type="boolean" optional default="true"
Collect daily/weekly task rewards.
:::
::: field name="mail" type="boolean" optional default="false"
Collect all mail rewards.
:::
::: field name="recruit" type="boolean" optional default="false"
Collect daily free pulls from limited banners.
:::
::: field name="orundum" type="boolean" optional default="false"
Collect Orundum from lucky drop wall.
:::
::: field name="mining" type="boolean" optional default="false"
Collect Orundum from limited mining licenses.
:::
::: field name="specialaccess" type="boolean" optional default="false"
Collect monthly card rewards from 5th anniversary.
:::
::::

Example 
{
   "enable": true,
   "award": true,
   "mail": true,
   "recruit": true,
   "orundum": false,
   "mining": true,
   "specialaccess": false
}
  • Roguelike
    Integrated Strategies

:::: field-group
::: field name="enable" type="boolean" optional default="true"
Whether to enable this task.
:::
::: field name="theme" type="string" optional default="Phantom"
Theme.
Phantom - Phantom & Crimson Solitaire
Mizuki - Mizuki & Caerula Arbor
Sami - Expeditioner's Jǫklumarkar
Sarkaz - Tales of the Unfathomable
JieGarden - Sui's Garden of Grotesqueries
:::
::: field name="mode" type="number" optional default="0"
Mode.
0 - Score farming/reward points, aiming to consistently reach higher levels.
1 - Originium Ingot farming, exit after investing in the first layer.
2 - 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 the desired 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. :::
::: field name="squad" type="string" optional default="指挥分队"
Starting squad name.
:::
::: field name="roles" type="string" optional default="取长补短"
Starting role group.
:::
::: field name="core_char" type="string" optional
Starting operator name. Supports only single operator Chinese name, regardless of server; leave empty or set to "" to auto-select based on level.
:::
::: field name="use_support" type="boolean" optional default="false"
Whether the starting operator is a support operator.
:::
::: field name="use_nonfriend_support" type="boolean" optional default="false"
Whether non-friend support operators are allowed. Only effective when use_support is true.
:::
::: field name="starts_count" type="number" optional default="2147483647"
Number of times to start exploration. Stops automatically upon reaching limit.
:::
::: field name="difficulty" type="number" optional default="0"
Specified difficulty level. Selects the highest unlocked difficulty if the desired one is not unlocked.
:::
::: field name="stop_at_final_boss" type="boolean" optional default="false"
Whether to stop before the level 5 final boss node. Only applicable to themes excluding Phantom.
:::
::: field name="stop_at_max_level" type="boolean" optional default="false"
Whether to stop if max level for roguelike has been achieved.
:::
::: field name="investment_enabled" type="boolean" optional default="true"
Whether to invest Originium Ingots.
:::
::: field name="investments_count" type="number" optional default="2147483647"
Number of Originium Ingot investments. Stops automatically upon reaching limit.
:::
::: field name="stop_when_investment_full" type="boolean" optional default="false"
Whether to stop automatically when investment limit is reached.
:::
::: field name="investment_with_more_score" type="boolean" optional default="false"
Whether to try shopping after investment. Only applicable to mode 1.
:::
::: field name="start_with_elite_two" type="boolean" optional default="false"
Whether to reset for an Elite 2 operator at start. Only applicable to mode 4.
:::
::: field name="only_start_with_elite_two" type="boolean" optional default="false"
Whether to reset only for Elite 2 operator while ignoring other starting conditions. Only effective when mode is 4 and start_with_elite_two is true.
:::
::: field name="refresh_trader_with_dice" type="boolean" optional default="false"
Whether to refresh the shop with dice for special items. Only applicable to the Mizuki theme, used to refresh Scale of Past.
:::
::: field name="first_floor_foldartal" type="string" optional
Desired Foldartal to acquire in the first floor foresight phase. Only applicable to the Sami theme, any mode; task stops once obtained successfully.
:::
::: field name="start_foldartal_list" type="array" optional default="[]"
Desired Foldartals for the starting reward phase during opening reset. Effective only for Sami theme and mode 4.
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.
:::
::: field name="collectible_mode_start_list" type="object" optional
Desired starting rewards, all false by default. Only valid in mode 4.
hot_water: Hot Water reward, typically used to trigger boiling mechanism (universal).
shield: Shield reward, equivalent to extra HP (universal).
ingot: Originium Ingot reward (universal).
hope: Hope reward (universal, note: not available in JieGarden theme).
random: Random reward option: consumes all Ingots for a random collectible (universal).
key: Key reward, only available in Mizuki theme.
dice: Dice reward, only available in Mizuki theme.
ideas: 2 Ideas reward, only available in Sarkaz theme.
ticket: Coupon reward, only available in JieGarden theme. :::
::: field name="use_foldartal" type="boolean" optional
Whether to use Foldartals. Default is false in mode 5 and true in other modes. Only applicable to the Sami theme.
:::
::: field name="check_collapsal_paradigms" type="boolean" optional
Whether to check obtained Collapsal Paradigms. Default is true in mode 5 and false in other modes.
:::
::: field name="double_check_collapsal_paradigms" type="boolean" optional default="true"
Whether to perform additional checks to prevent missed Collapsal Paradigms. Only effective when theme is Sami and check_collapsal_paradigms is true. Default is true in mode 5 and false in other modes.
:::
::: field name="expected_collapsal_paradigms" type="array" optional default="['目空一些', '睁眼瞎', '图像损坏', '一抹黑']"
Desired Collapsal Paradigms to trigger. Only effective when theme is Sami and mode is 5.
:::
::: field name="monthly_squad_auto_iterate" type="boolean" optional
Whether to enable automatic monthly squad rotation.
:::
::: field name="monthly_squad_check_comms" type="boolean" optional
Whether to also check monthly squad communications as rotation criteria.
:::
::: field name="deep_exploration_auto_iterate" type="boolean" optional
Whether to enable automatic deep exploration rotation.
:::
::: field name="collectible_mode_shopping" type="boolean" optional default="false"
Whether to enable shopping in hot water mode.
:::
::: field name="collectible_mode_squad" type="string" optional
Squad to use in hot water mode, default synced with squad, when squad is empty and collectible_mode_squad not specified, uses 指挥分队.
:::
::: field name="start_with_seed" type="boolean" optional default="false"
Use seed for money farming.
Only possible to be true in Sarkaz theme, Investment mode, with "点刺成锭分队" (Point-Stab Ingot Squad) or "后勤分队" (Logistics Squad).
Uses fixed seed.
:::
::::

Example 
{
   "enable": true,
   "theme": "Sami",
   "mode": 5,
   "squad": "指挥分队",
   "roles": "取长补短",
   "core_char": "塑心",
   "use_support": false,
   "use_nonfriend_support": false,
   "starts_count": 3,
   "difficulty": 8,
   "stop_at_final_boss": false,
   "stop_at_max_level": false,
   "investment_enabled": true,
   "investments_count": 2,
   "stop_when_investment_full": false,
   "investment_with_more_score": false,
   "start_with_elite_two": false,
   "only_start_with_elite_two": false,
   "refresh_trader_with_dice": false,
   "first_floor_foldartal": "",
   "start_foldartal_list": [],
   "collectible_mode_start_list": {
      "hot_water": true,
      "shield": false,
      "ingot": false,
      "hope": true,
      "random": false,
      "key": false,
      "dice": false,
      "ideas": false
   },
   "use_foldartal": true,
   "check_collapsal_paradigms": true,
   "double_check_collapsal_paradigms": true,
   "expected_collapsal_paradigms": ["目空一些", "睁眼瞎"],
   "monthly_squad_auto_iterate": false,
   "monthly_squad_check_comms": false,
   "deep_exploration_auto_iterate": false,
   "collectible_mode_shopping": false,
   "collectible_mode_squad": "指挥分队",
   "start_with_seed": false
}

For specific information about the Collapsal Paradigm farming feature, please refer to Integrated Strategy Schema

  • Copilot
    Auto combat feature

:::: field-group
::: field name="enable" type="boolean" optional default="true"
Whether to enable this task.
:::
::: field name="filename" type="string"
Path to a single job JSON file, mutually exclusive with copilot_list (required, choose one); both relative and absolute paths are supported.
:::
::: field name="copilot_list" type="array

Reference in New Issue View Git Blame Copy Permalink