effect · `force_update_map_mode`

Definition

Supported scope:any
Supported target:any

Description

force rebuilds map mode. no tooltip generated.
force_update_map_mode = { 
  limit = { always = yes } # limit to check against player
  mapmode = scripted_map_mode_name

实战 · 配合 · 坑

实战内容由 AI 生成,并已对照 vanilla 命令词表校验 —— 请当作起点而非权威依据。上方的定义节才是游戏自带文档原文。

实战用法

force_update_map_mode 主要用于自定义地图模式（scripted map mode）的 mod 中，当某些变量或状态发生改变后，强制刷新地图显示，确保玩家看到最新的着色结果。例如，在一个追踪势力范围的 mod 里，每当某国加入或退出阵营时触发刷新：

country_event = {
    id = my_mod.1
    hidden_effect = {
        force_update_map_mode = {
            mapmode = my_influence_map_mode
        }
    }
}

配合关系

[hidden_effect](/wiki/effect/hidden_effect)：force_update_map_mode 本身不产生 tooltip，通常包裹在 hidden_effect 里避免在事件选项中出现多余的空白提示行。
[set_variable](/wiki/effect/set_variable)：自定义地图模式往往依赖变量驱动着色逻辑，修改变量后立即调用该 effect 可保证视觉同步。
[if](/wiki/effect/if)：配合条件判断，仅在当前地图模式确实为目标 scripted map mode 时才执行刷新，避免无意义的重建开销。
[has_global_flag](/wiki/trigger/has_global_flag)：通过全局标记判断某 mod 功能是否已激活，再决定是否触发地图刷新，常见于 mod 初始化阶段的保护逻辑。

常见坑

mapmode 字段填写错误：必须填写在 scripted_map_modes 中精确定义的名称，拼写错误或填写原版地图模式 ID 都会导致静默失败，地图不会刷新且不报错，排查困难。
不必要地频繁调用：在每日 on_actions 或高频循环中无条件调用会持续重建地图模式，造成明显性能下降；应配合 [if](/wiki/effect/if) 或标记位控制调用时机，仅在数据真正变化时才触发。

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

force_update_map_mode is primarily used in mods that implement custom scripted map modes. It forces a refresh of the map display when certain variables or states change, ensuring players see the latest coloring results. For example, in a mod that tracks sphere of influence, trigger a refresh whenever a country joins or leaves a faction:

country_event = {
    id = my_mod.1
    hidden_effect = {
        force_update_map_mode = {
            mapmode = my_influence_map_mode
        }
    }
}

Synergy

[hidden_effect](/wiki/effect/hidden_effect): force_update_map_mode itself produces no tooltip and is typically wrapped in hidden_effect to avoid extraneous blank tooltip lines appearing in event options.
[set_variable](/wiki/effect/set_variable): Custom map modes often rely on variables to drive coloring logic; calling this effect immediately after modifying a variable ensures visual synchronization.
[if](/wiki/effect/if): Combined with conditional checks, only execute the refresh if the current map mode is indeed the target scripted map mode, avoiding unnecessary rebuild overhead.
[has_global_flag](/wiki/trigger/has_global_flag): Use global flags to determine whether a mod feature is activated before deciding whether to trigger map refresh, commonly used in protective logic during mod initialization.

Common Pitfalls

Incorrect mapmode field: Must use the exact name as defined in scripted_map_modes. Typos or using vanilla map mode IDs will silently fail—the map won't refresh and no error is reported, making debugging difficult.
Excessive frequent calls: Unconditionally calling this in daily on_actions or tight loops causes continuous map mode rebuilding, resulting in noticeable performance degradation. Use [if](/wiki/effect/if) or flag conditions to control call timing, triggering only when data actually changes.

effect · force_update_map_mode