Wiki

trigger · convoy_threat

Definition

  • Supported scope:COUNTRY
  • Supported target:THIS, ROOT, PREV, FROM, OWNER, CONTROLLER, OCCUPIED, CAPITAL

Description

A trigger to check convoy threat for a country. Controlled by NAVAL_CONVOY_DANGER defines. Returns a value between 0 and 1. Example convoy_threat > 0.5

Hands-On Notes

Hands-on notes are AI-generated and checked against the vanilla command vocabulary — treat them as a starting point, not authoritative reference. The definition above is the game's own documentation.

Hands-On Usage

convoy_threat is commonly used to assess the threat level faced by a nation's convoy routes, making it ideal for dynamically triggering naval reinforcements, adjusting strategic doctrines, and similar logic in naval combat decisions or events. For example, when the threat exceeds a threshold, you can automatically activate emergency naval decisions or grant related ideas.

# Trigger event when a nation's convoy threat exceeds 50%
country_event = {
    id = naval_crisis.1
    trigger = {
        convoy_threat > 0.5
        has_war = yes
    }
    ...
}

Synergy

  • [fuel_ratio](/wiki/trigger/fuel_ratio): Fuel supply depends on safe convoy routes; combining these two creates a composite crisis check for "convoys under threat AND fuel shortage".
  • [has_convoys_war_support](/wiki/trigger/has_convoys_war_support): Convoy losses directly impact domestic war support; using them together lets you detect if domestic morale is shaken by convoy crises.
  • [add_war_support](/wiki/effect/add_war_support): Once convoy threat reaches a threshold, use effects to reduce war support, simulating the negative impact of convoy losses on public morale.
  • [add_ideas](/wiki/effect/add_ideas): When convoy situations deteriorate, assign negative ideas (such as blockade penalties); remove them via inverse logic once conditions normalize, implementing a dynamic state machine.

Common Pitfalls

  1. Treating the return value as a boolean directly: convoy_threat returns a float between 0 and 1, so it must be used with comparison operators (>, <). Writing convoy_threat = yes is invalid syntax that won't cause an error but will produce unpredictable results.
  2. Ignoring scope restrictions: This trigger only works in COUNTRY scope. Calling it in STATE or UNIT_LEADER scopes will have no effect. Beginners often mistakenly reference it inside subscopes like any_owned_state and fail to get expected results.