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 = {

    ---DEBUG LOGGING
    debugEnabled = false, -- default false

    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

        -- DELAYS.
        -- Delays work as follow.
        -- When an aircraft lands alive and well it will be rearmed and ready to go.
        -- When part of the flight died it will be repaired and then rearmed. (both delays)
        -- When the entire group dies it will first wait for the deathDelay, then it will be repaired and rearmed.
        -- while rearming: Spawned on the ramp.
        -- while repairing: Spawned on the ramp.
        -- while deathDelay no unit is spawned.

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

        -- Delay for aircraft that has died to be repaired before rearming starts.
        -- unit: seconds
        repairDelay = 600, -- default 600

        --Delay for aircraft before the repairing and rearming cycles begin.
        -- applied when the whole group dies.
        -- (see this as an additional bonus delay for destroying an entire group)
        -- 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
        drawPreActivated = true, -- default true

        --Marking the last contact for any mission.
        --If a unit is killed the location will be permanently marked on the map until the mission is complete.
        --The location will continously update for the last killed unit.
        markLastContact = false, -- default false

        --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,

        -- Amount of stages that are pre-activated on top of the current active stage.
        -- In Pre-activated the missions are not listed, but SAMs and Airbase groups are spawned.
        preactivateStage = 1, -- default 1
    },
    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_[routeID]_[Name]
Example: CAPROUTE_103_ALPHA

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

FARP Zones

Format: FARP_A|B_[Name]
Example: FARP_A_HOUSTON Example: FARP_B_HOUSTON

FARP zones are spawned and activated based on the "activation parameter".
A: Activates when the parent stage zone activates.
B: Activates when the parent stage is "Blue".

Future: FARP zones will be "buildable" once logistics are implemented.

Supply Hub

Format: SUPPLYHUB_[Name]
Format: SUPPLYHUB_A_[Name]
Example: SUPPLYHUB_HOUSTON

Supply hubs are used as zones to pick up logistics for logistic missions.
They are activated when their parent is activated.
Activated depends on what it's parent is.
If it's a stage. It can be SUPPLYHUB_A_[name] when you want it to be active when the stage is initiated. (red state) or SUPPLYHUB_B_ it you want it activated when it's BLUE only.
If you place the Supply Hub trigger zone inside of a FARP zone the supply hub will activate when the FARP zone is activated.
If the FARP needs to be built first, then that means the supply hub also is activated later.
NOTE: The supply hub does not spawn anything, but merely give options to pick up logistics.

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.

CAS

CAS missions involve close air support for friendly ground forces.
CAS mission have a special "BattleManager" module added by defualt. This will make blue and red units shoot at eachoter.
This creates a nice effect.
To see how it's done see: [Tutorials] Mission: CAS

STRIKE

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

Mission Briefings

Mission briefings are text boxes (draw layer) inside of the trigger zone of the mission.

Special Fields

Special fields are used to display information in the mission briefings.
They are replaced with the corresponding values at the time a briefing is requested and can therefore show real time data.
Field: {{coords}}
Coords are taken from the location of the trigger zone. Then converted to the aircrafts preferred format.

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>]<CapRouteID>
                n and n  at x:        [<activeStage>,<activeStage>]<CapRouteID>
                n till n at x:        [<activeStage>-<activeStage>]<CapRouteID>
                n till n and n at x:  [<activeStage>-<activeStage>,<activeStage>]<CapRouteID>

                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 CapRoute 6 when 6 is active.
                

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.

In stage depencies

If you want to have missions inside of a stage depends on each other you can.
Add a text drawing box inside of the mission trigger zone with the name: dependson_[freeform]
And in the text add the "Name" of the mission zone you want the mission to depend on.
The mission will be "pre-activated" (spawned) but won't have a f10 mission menu until the mission(s) it depends on is completed.

Buildables

Current buildables:
FARP_
BLUESAM_
Airbases

Buildables are zones or objects that first require logistics.
Eg. A forward SAM site or FARP requires logistic crates before it can be built.
To make an item buildable add a text box inside of the trigger zone and name it: buildable_[freeform]
Then in the text box type amount of kilo's you want to be transfered before the logistisc mission is complete.
The base will slowly build up with each crate giving both a nice view of it happening AND it's good for performance as there's not a big addition of objects at once.
Right now a crate takes 15 seconds to unpack per 500kg. Meaning 2 crates of 1000kg will be faster than 1 crate of 2000kg.
All helicopters have a max limit set based on quick google searches and cannot be changed but the ME at this point:
UH-1H : 2000kg
Mi-8 : 4000kg
CH-47 : 10000kg
MI-24 : 2000kg

Runway Bombing

Runway bombing can be a very effective OCA tactic. With Spearhead we've tried adding as much logic and detail to it so it will feel as engaging as possible.
Firstly, the runway is split up in 5 sections and only sections 2, 3 and 4 are then actually tracked.
+-----------+-----------+-----------+-----------+-----------+
| Section 1 | Section 2 | Section 3 | Section 4 | Section 5 |
+-----------+-----------+-----------+-----------+-----------+