# Actions

An action is something a mission does: activate another mission, grant a reward, show a message. Actions live in a mission's content branches and fire when that branch runs. The missions module gives you a factory for building an action and the typed branch list to append it to.

## Building an action

`PM.Missions:Action(type, callback)` creates an action of the named type and runs your callback against it to fill in its fields. The type is the action's short name. The callback receives the action's JSON, where you set whatever that action needs:

```lua
PM.Missions:Action("ActivateMissionAction", function(action)
    action.TargetMissionID = "KSP2Mission_Secondary_Tier_1_Gateway"
    action.MissionOwner = "Agency"
end)
```

That call returns the built action, ready to add to a branch.

## Content branches

A mission's content branches are on `mission.ContentBranches`, keyed by branch id (`OnSubmit` and the like). Each branch has an `actions` list. To make an action happen, append it to the right branch's `actions`:

```lua
PM.Missions:Patch("MoonLandingActivation")
           :Named("KSP2Mission_Main_Mun_01")
           :Do(function(mission)
               mission.ContentBranches.OnSubmit.actions:Append(
                   PM.Missions:Action("ActivateMissionAction", function(action)
                       action.TargetMissionID = "KSP2Mission_Secondary_Kerbin_KerbinTourSOI"
                       action.MissionOwner = "Agency"
                   end))
           end)
```

`mission.ContentBranches.OnSubmit` reaches the branch whose id is `OnSubmit`, and `.actions:Append(...)` adds the action built by `PM.Missions:Action`.

## Pulling out a helper

When you add the same kind of action to several missions, factor it into a function. This is the pattern Redux uses to wire up mission unlocks across many missions:

```lua
function AddMissionActivation(mission, target)
    mission.ContentBranches.OnSubmit.actions:Append(
        PM.Missions:Action("ActivateMissionAction", function(action)
            action.TargetMissionID = target
            action.MissionOwner = "Agency"
        end))
end

PM.Missions:Patch("Tier1GatewayActivations")
           :Named("KSP2Mission_Main_Kerbin_03")
           :Do(function(mission)
               AddMissionActivation(mission, "KSP2Mission_Secondary_Tier_1_Gateway")
               AddMissionActivation(mission, "KSP2Mission_Secondary_Kerbin_OrbitInclination")
               AddMissionActivation(mission, "KSP2Mission_Secondary_Kerbin_EVAGround")
           end)
```

## Action types

The type string you pass to `Action` is an action's registered short name, like `ActivateMissionAction`. The full set of action types comes from the game and other mods, and the fields each action needs vary by type. Your editor's autocomplete and `pm-missions.d.lua` list the ones it knows about. When you copy an action from an existing mission, copy its type name and field names from there.

## Related type lookups

Some action and condition fields want a fully-qualified type name for a property watcher or a message rather than a plain string. `PM.Missions:GetPropertyWatcher(name)` and `PM.Missions:GetMessage(name)` resolve those from a short name, so you do not hand-write assembly-qualified names. See [Conditions](/doc/conditions-fmWJskmwWx), which is where property watchers usually come up.