effect · `random`

Definition

Supported scope:any
Supported target:none

Description

a random effect

实战 · 配合 · 坑

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

实战用法

random 效果用于在 mod 中执行一个随机结果，常见于随机事件触发、随机奖惩分配或概率性状态变化等场景。例如，在某个决策或事件选项中，希望有一定概率给某国家增加国策或触发后续效果时，可以嵌套在 random_list 内部使用，也可以独立使用产生单次随机行为。

# 在事件选项中使用 random 执行随机效果
option = {
    name = my_event.1.a
    random = {
        chance = 50
        add_victory_points = {
            province = 3340
            value = 5
        }
    }
}

配合关系

[random_list](/wiki/effect/random_list)：random_list 提供多分支加权随机，而 random 用于单一概率判断，两者互补，适合不同粒度的随机逻辑设计。
[hidden_effect](/wiki/effect/hidden_effect)：将 random 包裹在 hidden_effect 内可以静默执行随机效果，避免在事件界面产生多余的提示文本。
[if](/wiki/effect/if)：在 random 内部配合 if 做条件判断，可实现"有概率触发，但触发后还需满足额外条件"的复合逻辑。
[custom_effect_tooltip](/wiki/effect/custom_effect_tooltip)：由于 random 的随机性在 UI 上不直观，配合 custom_effect_tooltip 可向玩家展示概率说明，改善可读性。

常见坑

遗漏 chance 字段：random 需要通过 chance 指定触发概率（通常为 0–100 的整数），若省略或写错字段名，效果可能始终不触发或始终触发，新手容易将其与 random_list 的权重写法混淆。
在 trigger 块中误用：random 是 effect 指令，只能用在执行块（如 immediate、option、hidden_effect）中，不能用在 trigger 或 limit 块里，混用会导致脚本报错或逻辑静默失败。

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

random is an effect used to execute a randomized outcome in mods, commonly seen in random event triggers, probabilistic reward/penalty distribution, or chance-based state changes. For example, when you want a certain probability to grant a nation a focus or trigger subsequent effects within a decision or event option, it can be nested inside random_list, or used independently to produce a single random behavior.

# Using random in an event option to execute a randomized effect
option = {
    name = my_event.1.a
    random = {
        chance = 50
        add_victory_points = {
            province = 3340
            value = 5
        }
    }
}

Synergy

[random_list](/wiki/effect/random_list): random_list provides multi-branch weighted randomization, while random handles single probability checks; they complement each other and suit different granularities of random logic design.
[hidden_effect](/wiki/effect/hidden_effect): Wrapping random inside hidden_effect executes the randomized effect silently, avoiding extraneous tooltip text in the event interface.
[if](/wiki/effect/if): Pairing if conditionals within random enables compound logic such as "trigger with some probability, but only if additional conditions are met after triggering."
[custom_effect_tooltip](/wiki/effect/custom_effect_tooltip): Since random's randomness is not intuitive in the UI, combining it with custom_effect_tooltip can display probability explanations to players and improve readability.

Common Pitfalls

Missing the chance field: random requires chance to specify trigger probability (typically an integer from 0–100); omitting or misspelling the field name may cause the effect to never trigger or always trigger. Beginners often confuse this with random_list's weighting syntax.
Misuse in trigger blocks: random is an effect command and can only be used in execution blocks (such as immediate, option, or hidden_effect), not in trigger or limit blocks. Mixing them causes script errors or silent logic failure.

effect · random