Reference

This page provides a detailed overview of all settings, naming conventions, and logic used in Spearhead.
For a quick start guide, visit the Tutorials page.

Configuration

For the configuration you can reference the configuration as it is below:

SpearheadConfig = {

    CapConfig = {
        --quickly enable of disable the entire CAP Logic 
        --(you can also just rename all units to not be named "CAP_")
        enabled = true, -- default true
        
        --min ground speed for CAP aircraft during patrol
        -- unit: knots
        minSpeed = 400, -- default 400

        --max speed for CAP aircraft during patrol
        -- unit: knots
        maxSpeed = 500, -- default 500

        --minAlt for aircraft on patrol
        -- unit: feet
        minAlt = 18000, -- default 18000

        --maxAlt for aircraft on patrol
        -- unit: feet
        maxAlt = 28000, -- default 28000

        --Delay for aircraft from touchdown to off the chocks.
        -- unit: seconds
        rearmDelay = 600, -- default 600

        --Delay for aircraft from death to takeoff.
        --When the seconds remaining is the same at the rearmDelay it will be spawned on the ramp and follow the rearm logic.
        -- !! Can not be lower than rearmDelay
        -- unit: seconds
        deathDelay = 1800, -- default 1800
    },
    StageConfig = {
        
        -- management of stages and its missions. 
        -- This is not related to CAP managers which will continue to work even if stage management is disabled
        enabled = true, -- default true

        --Will draw the active and the next stage 
        drawStages = true, -- default true

        --AutoStages will continue to the next stage automatically on completion of the missions within the stage. 
        -- If you want to make it so the next stage triggers only when you want to disable it here and manually implement the actions needed.
        --[
            TODO: Add manual stage transition documentation
        ]]
        autoStages = true, --default true

        --Maximum missions per stage (includes all types of missions)
        maxMissionStage = 10,

        --Stage starting number
        startingStage = 1,

        ---DEBUG logging. Consider keeping this disabled
        debugEnabled = false
    },
    Persistence = {
        --- io and lfs cannot be sanitized in the MissionScripting.lua
        
        --- enables or disables the persistence logic in spearhead
        enabled = false,

        --- sets the directory where the persistence file is stored
        --- if nil then lfs.writedir() will be used. 
        --- which will 
        directory = nil,

        --- the filename of the persistence file. Should end with .json for convention, but any text extension should do.
        fileName = "Spearhead_Persistence.json"

    }
}

Naming Conventions

Spearhead uses specific naming conventions for zones, missions, and CAP configurations. These conventions are critical for the framework to function correctly.

Stage Zones

Format: MISSIONSTAGE_[OrderNumber]_[FreeForm]
Example: MISSIONSTAGE_1_EAST

Stages are logical parts of a mission. They encapsulate multiple missions, airbases, and other objects.
Secondary stages can be defined using the format: MISSIONSTAGE_x[OrderNumber].

Waiting Stages

Format: WAITINGSTAGE_[Order]_[Seconds]
Example: WAITINGSTAGE_2_180

Waiting stages introduce delays between stages. They activate only after the previous stage is completed.

Mission Zones

Format: MISSION_[Type]_[Name]
Example: MISSION_DEAD_BYRON

Missions are completable objectives with specific types, such as DEAD, BAI, STRIKE, or SAM.
Randomized missions can be defined using the format: RANDOMMISSION_[Type]_[Name]_[Index].

CAP Routes

Format: CAPROUTE_[Name]
Example: CAPROUTE_ALPHA

CAP routes define the patrol paths for CAP units. They are tied to specific stages and zones.

CAP Zones

Format: CAPZONE_[Name]
Example: CAPZONE_BRAVO

CAP zones are areas where CAP units operate. They are linked to CAP routes and stages.

Mission Types

Each mission type has specific logic and completion criteria. Below are the supported types:

SAM

SAM missions involve surface-to-air missile sites. These missions are activated when a stage is "Pre-Active."
Completion Logic: Destroy all air defenses in the zone.

DEAD

DEAD missions target enemy air defenses. They are activated at the start of a stage.
Completion Logic: Destroy all designated targets in the zone.

BAI

BAI missions involve battlefield air interdiction. These missions target enemy ground forces.

STRIKE

STRIKE missions target strategic objectives, such as supply depots or command centers.
Completion Logic: Destroy all designated targets in the zone.

CAP Configuration

CAP (Combat Air Patrol) units are managed using specific naming conventions and configurations.

CAP Group Naming

Format: CAP_[A|B][Config]_[FreeForm]
Example: CAP_A[1-4]5_SomeName

CAP Group Config

                1 at x:               [<activeStage>]<capStage>
                n and n  at x:        [<activeStage>,<activeStage>]<capStage>
                n till n at x:        [<activeStage>-<activeStage>]<capStage>
                n till n and n at x:  [<activeStage>-<activeStage>,<activeStage>]<capStage>
                n till n at Active:   [<activeStage>-<activeStage>]A

                Divider: |

                Examples:
                CAP_A[1-4,6]7|[5,7]8_SomeName => Will fly CAP at stage 7 when stages 1 through 4 and 6 are active and will fly CAP at 8 when 5 and 7 are active.
                CAP_A[2-5]5|[6]6_SomeName => Will fly CAP at stage 5 when stages 2 through 5 are active and will fly CAP at 6 when 6 is active.
                CAP_A[1-5]A|[6]7_SomeName => Will fly CAP at the ACTIVE stage if stages 1-5 are active. Then when 6 is active, it will fly in 7.
                

Active and Backup CAP

Active Units: Define the maximum number of groups in a zone at a time.
Backup Units: Fill in when active units are unavailable due to RTB, death, or rearming.

Randomization

Missions can be randomized using the RANDOMMISSION prefix.
Spearhead will pick one random mission from zones with the same name.