effect · ai_message

Hands-On Usage

ai_message is primarily used to send internal messages or signal hints to AI nations within mods, commonly appearing in scenarios that require triggering specific AI behavioral responses—such as notifying AI allies to adjust their strategy after the player completes a certain focus. Due to severely limited official documentation on its parameters, actual usage often appears as a debugging or experimental feature.

country_event = {
    id = my_mod.1
    hidden = yes
    immediate = {
        ai_message = {
            # Specific parameters should be verified through testing with the actual game version
        }
    }
}

Synergy

• [add_ai_strategy](/wiki/effect/add_ai_strategy) — Often combined with ai_message; while sending the message, use add_ai_strategy to supplement concrete strategy weights for the AI nation, making AI behavioral adjustments more comprehensive.
• [has_country_flag](/wiki/trigger/has_country_flag) — Used to check whether a specific flag has been set before executing ai_message, preventing duplicate triggers or messages sent at the wrong time.
• [country_event](/wiki/effect/country_event) — Commonly paired with ai_message; trigger a hidden event in the same execution block where the message is sent, leveraging event chains to implement more complex AI response logic.
• [clr_country_flag](/wiki/effect/clr_country_flag) — Clear the flag promptly after sending the message, working in tandem with flag control to ensure the message is only sent once under intended conditions.

Common Pitfalls

1. Silent failures due to unclear parameters: Because official descriptions are critically sparse, newcomers often leave parameters empty or fill them arbitrarily, causing the effect to silently skip without errors, making troubleshooting difficult. It is recommended to repeatedly verify actual behavior in the game log and console rather than assuming its behavior matches literal meaning perfectly.
2. Mistakenly assuming usage outside COUNTRY scope: This effect only supports COUNTRY scope; if mistakenly placed in the execution block of STATE or CHARACTER scopes, it will either throw an error or be ignored. Beginners must exercise extra care regarding the current scope when nesting scopes.