Combat Operation Protocol
About 2211 wordsAbout 7 min
Usage of resource/copilot/*.json files and field descriptions
Tips
Please note that JSON files do not support comments. The comments in this document are for demonstration purposes only. Do not copy them directly into your JSON files.
Complete Field Reference
{
"stage_name": "暴君", // Stage name, required. Chinese name, code, stageId, levelId, etc. are all acceptable as long as they uniquely identify the stage. ("暴君" = "Patriot")
"opers": [
// Specified operators
{
"name": "重岳", // Operator name ("重岳" = "Chongyue")
"role": "guard", // Operator role. Optional, used to distinguish operators with the same name; English role names should be used, case-insensitive
"skill": 3, // Skill number. Optional, default is 0, range [0, 3]
"skill_usage": 2, // Skill usage method. Optional, default is 0
// 0 - Do not use automatically (depends on "actions" field)
// 1 - Use whenever ready, as many times as possible (e.g., Thorns S3, Myrtle S1, etc.)
// 2 - Use X times (e.g., Mountain S2 once, Chongyue S3 five times, set via "skill_times" field)
// 3 - Auto-determine usage timing (placeholder)
// For auto-trigger skills, use 0
"skill_times": 5, // Number of skill activations. Optional, default is 1
"requirements": {
// Level requirements, validated during auto-formation. Optional, default is empty
"elite": 2, // Elite level. Optional, default is -1, i.e., no requirement
"level": 90, // Operator level. Optional, default is -1, i.e., no requirement
"skill_level": 10, // Skill level. Optional, default is -1, i.e., no requirement
"module": 1, // Module number. Optional, default is -1, i.e., no requirement; 0 means no module, 1-5 correspond to the χ, γ, α, Δ, β modules respectively
"module_level": 3, // Module level. Not yet supported
"potential": 1 // Potential requirement. Not yet supported
}
}
],
"groups": [
{
"name": "任意正常群奶", // Group name, required ("任意正常群奶" = "Any Medic")
// Use any name that matches the "name" field in the deploy section below
"opers": [
// Choose any one operator, unordered, higher level operators preferred, usage same as opers field above
{
"name": "夜莺", // Operator name ("夜莺" = "Nightingale")
"skill": 3,
"skill_usage": 2 // For specific timing, different operators may have different skill CDs, please be aware
},
{
"name": "白面鸮", // Operator name ("白面鸮" = "Ptilopsis")
"skill": 2,
"skill_usage": 2
}
]
}
],
"actions": [
// Combat operations. Ordered, executes the next one only after completing the previous one. Required
{
"type": "部署", // Operation type, optional, default is "Deploy" ("部署" = "Deploy")
// "Deploy" | "Skill" | "Retreat" | "SpeedUp" | "BulletTime" | "SkillUsage" | "Output" | "SkillDaemon" | "MoveCamera" | "ResetStopwatch" | "Click" | "Swipe" | "SetUnitLocation"
// "部署" | "技能" | "撤退" | "二倍速" | "子弹时间" | "技能用法" | "打印" | "摆完挂机" | "移动镜头" | "重置全局计时器" | "点击" | "滑动" | "设置单位坐标"
// Both English and Chinese are supported (e.g., "部署" for "Deploy")
// For "Deploy", waits until enough DP is available (unless timeout)
// For "Skill", waits until skill is ready (unless timeout)
// "SpeedUp" toggles between normal and 2x speed
// "BulletTime" is 1/5 speed after clicking an operator; any following action returns to normal speed
// "name" or "location" must be specified to indicate which operator to enter bullet time with (auto-detected)
// If next action is "Skill"/"Retreat", use the same "name" or "location" as the next action
// If next action is "Deploy", use any operator (but avoid using the operator to be deployed as it affects recognition)
// "Output" doesn't show this step in UI, used only to output doc content (for subtitles, etc.)
// "SkillDaemon" only uses "use when ready" skills, does nothing else until battle ends
// "MoveCamera" for Guide mode, requires the distance field
// "ResetStopwatch" — Resets the global stopwatch. Please refer to the “elapsed_time” condition.
// "Click" directly clicks the pixel rect specified by "rect" or the battlefield tile specified by "location", without any recognition; empty tiles can also be clicked
// At least one of "rect" or "location" must be set; the copilot fails to load (parse-time error) if neither is set; when both are set, "rect" takes priority (a warning is logged)
// "Swipe" swipes from the "begin" rect to the "end" rect, directly issuing the underlying swipe command; the copilot fails to load if either is missing
// "SetUnitLocation" sets the tile coordinate of a battlefield unit: both "name" and "location" are required; the copilot fails to load if either is missing or malformed ("name" must be a non-empty string, "location" must be a 2-element numeric array)
// Only updates MAA's internal record of the unit's position; performs no operation on the game
// Used to correct an operator's position after it moves, so that subsequent "Skill" / "Retreat" / "SkillUsage" actions by "name" target the new tile;
// also used to register on-field devices and facilities, combined with "SkillUsage" and "SkillDaemon" to auto-cast device skills;
// if the "name" is already on the field its position is updated; otherwise it is registered as a new unit ("role" is optional, default is role-agnostic)
// Currently the five conditions below use AND relationship
"kills": 0, // Kill count condition, waits until reached. Optional, default is 0, executes immediately
"costs": 50, // DP condition, waits until reached. Optional, default is 0, executes immediately
// DP can be affected by potential, may not be entirely accurate, suitable for battles with loose timing requirements.
// Otherwise use cost_changes below
// Recognition is more accurate for two-digit DP; three-digit DP may be misrecognized, not recommended
"cost_changes": 5, // DP change condition, waits until reached. Optional, default is 0, executes immediately
// Calculated from when this action begins executing (using DP at the end of previous action as baseline)
// Supports negative values (e.g., when operators like Jaye reduce DP)
// Recognition is more accurate for two-digit DP; three-digit DP may be misrecognized, not recommended
"cooling": 2, // Number of operators on cooldown condition, waits until reached. Optional, default is -1, no recognition
"elapsed_time": 1000, // Global timing condition in milliseconds. If the specified time has not elapsed, the action will keep waiting. Optional, default is 0, executes immediately
// Note: the time is measured from the last action with type: ResetStopwatch
// You must execute an action with type: ResetStopwatch beforehand to reset the stopwatch; otherwise, it will get stuck.
// TODO: Other conditions
// TODO: "condition_type": 0, // Relationship between execution conditions, optional, default is 0
// // 0 - AND; 1 - OR
"name": "棘刺", // Operator name or group name, required when type is "Deploy", optional for "Skill"|"Retreat", required for "SetUnitLocation" ("棘刺" = "Thorns")
"role": "guard", // Operator role. Optional, used to distinguish operators with the same name; English role names should be used, case-insensitive
"location": [
5,
5
], // Operator deployment position.
// Required when type is "Deploy".
// Optional when type is "Skill"|"Retreat".
// "Skill": Recommended only for automatic devices on the field, use location without name to activate skill. For normal deployed operators, use name
// "Retreat": Recommended only when multiple summons share the same name, use location without name to retreat. For normal deployed operators, use name
// When type is "Skill"|"Retreat"|"SkillUsage" and both name and location are set, location takes priority
// When type is "SetUnitLocation", this is required; sets the position of the "name" unit to this tile; any valid tile coordinate is accepted, including [0, 0]
// When type is "Click", at least one of this and "rect" must be set; directly clicks this tile; any valid tile coordinate is accepted, including [0, 0]
"rect": [
100,
100,
50,
50
], // At least one of this and "location" must be set when type is "Click"; "rect" takes priority if both are set; pixel rect based on 720p [x, y, w, h]
// The click point is randomly picked within the rect and automatically scaled to the current resolution
"direction": "左", // Operator facing direction. Required when type is "Deploy" ("左" = "Left")
// "Left" | "Right" | "Up" | "Down" | "None"
// "左" | "右" | "上" | "下" | "无"
// Both English and Chinese are supported (e.g., "左" for "Left")
// "skip_if_not_ready": false, DEPRECATED, please use "timeout": 0 instead
"skill_usage": 1, // Change skill usage method. Required when type is "SkillUsage"
// Example: Initially need Myrtle to help attack without using skill, later need auto skill activation
// Can set to 1 at the appropriate time
"skill_times": 5, // Number of skill activations. Optional, default is 1
"pre_delay": 0, // Pre-delay. Optional, default is 0, unit is milliseconds
// After all conditions for the current action are met, starts timing, executes the corresponding action when timing ends
"post_delay": 0, // Post-delay. Optional, default is 0, unit is milliseconds
// After the current action is executed, starts timing, begins next action when timing ends
"timeout": 999999999, // Timeout. Optional when type is "Skill". Default -1, no limit, unit is milliseconds
// Starts timing after the conditions and pre_delay are met, abandons the current action and executes the next one when timeout occurs; only checks once when set to 0
"distance": [
4.5,
0
], // Required when type is "MoveCamera"
// [x movement in tiles, y movement in tiles], can be decimal
// Note that during "MoveCamera", operators on field cannot be recognized, need to use sleep to cover entire animation
"keep_kills": false, // Whether to keep the kill count when moving the camera. Optional, default is false; when true, the camera move does not wait for the current wave to end and the kill count is not reset, for moving the camera within the same wave
"begin": [
100,
100,
50,
50
], // Required when type is "Swipe"; start rect of the swipe, pixel rect based on 720p [x, y, w, h]; the start point is randomly picked within the rect and automatically scaled to the current resolution
"end": [
400,
400,
50,
50
], // Required when type is "Swipe"; end rect of the swipe, pixel rect based on 720p [x, y, w, h]; the end point is randomly picked within the rect and automatically scaled to the current resolution
"duration": 200, // Swipe duration. Optional, default is 0, unit is milliseconds
"extra_swipe": 1, // Direction of the compensating swipe appended after the main swipe. Optional, default is 0, disabled
// 0 disables it, 1/2/3/4 are up/down/left/right respectively
// A short swipe in the given direction is appended after the main swipe, to cancel the inertia along the main swipe direction after the finger is released
// e.g. after swiping a list horizontally, appending a short vertical swipe prevents the list from keep scrolling past on release
"slope_in": 10, // Start slope of the swipe. Optional, default is 10; stored as an integer multiplied by 10, so 10 means 1.0
"slope_out": 10, // End slope of the swipe. Optional, default is 10; stored as an integer multiplied by 10, so 10 means 1.0
"with_pause": false, // Whether to pause the game while swiping (for cases that need to swipe while paused). Optional, default is false; only supported by some touch modes
"high_resolution_swipe_fix": false, // Whether to enable the high-resolution swipe fix. Optional, default is false. Rarely needed: this fix targets interfaces that do not use Unity swipe handling (currently only the chapter swipe in mainline stage navigation requires it), which auto-battle swipes never touch
// duration, extra_swipe, slope_in, and slope_out share the same value semantics as the first four elements
// of special_params of the Swipe task in tasks.json; high_resolution_swipe_fix corresponds to the standalone
// highResolutionSwipeFix task field in tasks.json; with_pause is unique to this schema (tasks.json has no
// counterpart — whether pipeline swipes pause the game is a global setting, not per-task)
"doc": "下棘刺了！", // Description, optional. Displayed in UI, no actual function ("下棘刺了！" = "Deploying Thorns!")
"doc_color": "orange" // Description text color, optional, default is gray. Displayed in UI, no actual function
},
// Example 1
{
"name": "任意正常群奶", // ("任意正常群奶" = "Any Medic")
"location": [
5,
6
],
"direction": "右" // ("右" = "Right")
},
// Example 2
{
"name": "史尔特尔", // ("史尔特尔" = "Silverash")
"location": [
4,
5
],
"direction": "左", // ("左" = "Left")
"doc": "你史尔特尔奶奶来啦！", // ("你史尔特尔奶奶来啦！" = "Here comes your Silverash grandma!")
"doc_color": "red"
},
// Example 3
{
"type": "二倍速" // ("二倍速" = "SpeedUp")
}
],
"minimum_required": "v4.0", // Minimum required MAA version, required. Reserved field, not yet implemented
"doc": {
// Description, optional.
"title": "低练度高成功率作业", // ("低练度高成功率作业" = "Low-investment high-success rate operation")
"title_color": "dark",
"details": "对练度要求很低balabala……", // ("对练度要求很低balabala……" = "Very low level requirements etc...") Recommend adding your name (author), reference video links, etc. here
"details_color": "dark"
},
"difficulty": 0 // Operation difficulty, optional, default value is 0.
// 0: Default, not set
// 1: Supports normal difficulty
// 2: Supports challenge mode
// 3: Supports both normal and challenge modes
}