Lanes

If up to now you've used mission stages like MISSIONSTAGE_1_STAGE you've been using the main lane.
This is the default or "main" lane, however, if you wanted to mix things up and create a more dynamic mission, you can use additional lanes.
Each lane can have its own set of mission stages, allowing for parallel or branching mission objectives.

How To

Define Lanes

Lanes are defined implicitly in the naming convention of the MISSIONSTAGE_.
A lane is identified by a single character (alpha [A-Z]), which gives you 26 unique lanes.
For example, MISSIONSTAGE_A1_[name] would belong to lane A.

If there is no lane character specified, the stage belongs to the main lane.

The 26 lane limit is only relevant if you want 26 lanes at the same time.
But splitting up lanes (eg. (1-4 and 10-15) ) you can easily have more than 26 stages throughout your entire mission.

Lanes don't have to start at index 1. as in the example lanes can easily start at any index.
How lanes are then activated and activate other lanes is described below in the Dependencies Explained part.

Dependencies Explained

When we are talking about lanes it's important to make the distinction between the main lane and additional lanes.
The main lane is not only the default, but it's also the central lane that other lanes depend on.

Chapters

Another term that we have used in the code is `Chapter` which refers to a grouping of mission stages within a lane.
These are implied and cannot be directly controlled or altered.
A chapter is a set of `MissionStage`s that are directly connected.
For MissionStages [ A1, A2, A3, A5, A6 ] there are 2 chapters: [ A1, A2, A3 ] and [ A5, A6 ].
Within a chapter the stages are only directly dependent on each other. Meaning A2 will start when A1 is completed.

However, the chapter start is where the inter-lane dependencies come into play.
These operate a little differently.

In the Visual example you can see the Stages grouped into chapters by the red boxes.

Side Lane Chapter start

Side lane chapters are started when all are true:

• The main lane is at or above the current stage lane number.
• All previous chapters in the same side lane have been completed.

Main Lane Chapter start

Main lane chapters are started when all are true:

• The previous chapter in the main lane has been completed.
• All side lanes are at or above the current stage lane number or the side lane has no additional stages.

Visual

The image below illustrates how different lanes can be used within a mission.
In the example you can see how the dependency between the main lane and side lanes works.
An arrow means that the completion of one stage is required before the next stage can begin.

Mermaid

Spearhead automatically exports a spearhead diagram to the logs on starting a mission.
This can be handy to visualize the logic and lanes you've created and verify your mission flow will be the way you want it.

Log Example

2026-09-01 17:53:13.213 INFO SCRIPTING (Main): [Spearhead][StageManager] ========== STAGE FLOW DIAGRAM ========== graph TD default_8["MAIN-2 (S8)"] b_5["West Valley (S5)"] default_1["MAIN-1 (S1)"] a_5["WEST-2 (S5)"] default_4["MAIN-2 (S4)"] default_10["MAIN-1 (S10)"] default_6["MAIN-2 (S6)"] a_4["WEST-1 (S4)"] default_3["MAIN-1 (S3)"] default_9["MAIN-3 (S9)"] a_7["WEST-2 (S7)"] a_3["WEST (S3)"] default_5["MAIN-3 (S5)"] b_6["West Valley-1 (S6)"] default_61["CAP-Maykop (S61)"] default_7["MAIN-1 (S7)"] default_0["START (S0)"] a_6["WEST-3 (S6)"] default_60["CAP-Nalchik (S60)"] default_2["MAIN (S2)"] a_2["WEST-1 (S2)"] a_2 --> a_3 a_3 --> a_4 a_4 --> a_5 a_5 --> a_6 a_6 --> a_7 default_0 --> default_1 default_1 --> default_2 default_2 --> default_3 default_3 --> default_4 default_4 --> default_5 default_5 --> default_6 default_6 --> default_7 default_7 --> default_8 default_8 --> default_9 default_9 --> default_10 default_10 -->|chapter| default_60 default_60 --> default_61 b_5 --> b_6 default_2 -->|unlock| a_2 default_5 -->|unlock| b_5 a_7 -->|gate| default_60 b_6 -->|gate| default_60 ========== END DIAGRAM ==========

Diagram Example

If you want to then copy and paste everything between the
========== STAGE FLOW DIAGRAM ========== and
========== END DIAGRAM ==========
you will be able to go to https://mermaid.live/ and paste the diagram code into the editor.
It would look like this:

Limitations

CAP

Due to the CAP naming conventions, we've opted to currently have CAP only react with the main lane.
This might mean a bit less flexibility when using lanes for major mission logic, however, it's a limitation we've accepted for now.
In the future we might be able to extend CAP's interaction with other lanes as well.
Currently this issue can be tracked here.
This does not mean having both CAP and side-lanes is out of the question, since you can still have that side-lanes scouted by CAP aircraft. It just needs a bit more pre-planning on where and how those CAP flights fly.