effect · `random_purchase_contract`

Definition

Supported scope:COUNTRY
Supported target:none

Description

Executes children effects on a random purchase contract of the country in scope, that fulfills the \"limit\" trigger.
tooltip = key need to be added to override the tooltip title.
ex: GER = {
  random_purchase_contract = {
	limit = { ... contract scope triggers ... }
	tooltip = my_loc_key # Optional
    ... Purchase Contract scope effects ...
  }
}

实战 · 配合 · 坑

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

实战用法

random_purchase_contract 适合在 mod 中对某国当前存在的采购合同随机抽取一个并执行批量修改或取消操作，例如战时自动清理低优先级合同、或在特定事件触发时调整合同状态。结合 limit 可精准筛选符合条件的合同（如只针对特定买方或特定装备类型），避免影响全部合同。

GER = {
    random_purchase_contract = {
        limit = {
            buyer = { tag = ITA }
            contract_contains_equipment = { type = infantry_equipment }
        }
        tooltip = ger_cancel_ita_contract_tooltip
        cancel_purchase_contract = yes
    }
}

配合关系

every_purchase_contract — 当需要对所有符合条件的合同批量执行效果时使用，与 random_purchase_contract 形成"全量 vs 随机单个"的互补关系。
cancel_purchase_contract — 最常见的子效果，用于在随机选中合同后将其取消，是该 effect 最典型的下游操作。
contract_contains_equipment — 在 limit 块中过滤合同所含装备类型，确保只有包含目标装备的合同才会被选中执行。
buyer / seller — 在 limit 中限定合同的买方或卖方国家，防止误操作无关国家的合同。

常见坑

忘记加 limit 导致随机选中预期外的合同：若不写 limit，该 effect 会从当前 scope 国家的所有合同中随机选一个，极易误取消重要合同；务必用 buyer、seller、contract_contains_equipment 等触发器进行约束。
在非 COUNTRY scope 下调用：random_purchase_contract 只能在国家 scope 中执行，若误写在州（state）或其他 scope 下，脚本会静默报错或完全不生效，排查时需仔细检查外层 scope 是否确实为一个国家。

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_purchase_contract is well-suited for mods that need to randomly pick one of a country's active purchase contracts and apply bulk modifications or cancellations — for example, automatically clearing low-priority contracts during wartime, or adjusting contract status when a specific event fires. Pairing it with a limit block lets you precisely filter eligible contracts (such as targeting only a specific buyer or a specific equipment type), preventing unintended changes to all contracts.

GER = {
    random_purchase_contract = {
        limit = {
            buyer = { tag = ITA }
            contract_contains_equipment = { type = infantry_equipment }
        }
        tooltip = ger_cancel_ita_contract_tooltip
        cancel_purchase_contract = yes
    }
}

Synergy

every_purchase_contract — Use this when you need to apply an effect to all matching contracts at once; it forms a complementary "all matching vs. one random" pair with random_purchase_contract.
cancel_purchase_contract — The most common child effect: cancels the randomly selected contract, making it the quintessential downstream operation for this effect.
contract_contains_equipment — Used inside a limit block to filter contracts by the equipment type they contain, ensuring only contracts with the target equipment are eligible for selection.
buyer / seller — Used inside limit to restrict contracts by their buyer or seller country, preventing accidental interference with unrelated nations' contracts.

Common Pitfalls

Omitting limit and accidentally selecting an unintended contract: Without a limit block, this effect picks randomly from all contracts belonging to the current scope country, making it very easy to inadvertently cancel an important contract. Always constrain the selection with triggers such as buyer, seller, and contract_contains_equipment.
Calling the effect outside a COUNTRY scope: random_purchase_contract can only execute within a country scope. If it is mistakenly placed inside a state scope or any other scope, the script will either throw a silent error or do nothing at all. When debugging, carefully verify that the enclosing scope is indeed a country.

effect · random_purchase_contract