effect · `add_project_progress_ratio`

Definition

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

Description

Add progress to the project's prototype phase.
The input value is a ratio of the total needed progress to complete the special project, i.e. a decimal number between -1 and 1.
ex:
sp:my_project = {
  add_project_progress_ratio = 0.1
  add_project_progress_ratio = var:my_var
}

实战 · 配合 · 坑

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

实战用法

在特殊项目类 mod 中，当玩家完成某项前置任务或事件时，可用此 effect 奖励一定比例的原型阶段进度，加快研发节奏。例如在某个科研事件的 option 块里，给关联特殊项目直接推进 10% 的进度：

option = {
    name = my_event.1.a
    sp:my_secret_weapon = {
        add_project_progress_ratio = 0.1
    }
}

也可以通过变量动态控制推进量，使进度增幅随游戏状态而变化（如科研投入越多进度越快）。

配合关系

[has_project_flag](/wiki/trigger/has_project_flag)：在推进进度前先检查特殊项目是否处于特定阶段或状态，避免在不适当时机触发进度奖励。
[set_project_flag](/wiki/effect/set_project_flag)：推进进度后立刻打上标记，防止同一事件链重复触发同一次进度加成，实现"一次性奖励"逻辑。
[complete_prototype_reward_option](/wiki/effect/complete_prototype_reward_option)：当进度被推至满值后，配合此 effect 触发原型阶段的奖励选项，形成完整的研发完成流程。
[add_dynamic_modifier](/wiki/effect/add_dynamic_modifier)：在进度提升的同时叠加动态修正，用来模拟"研发加速状态"对后续阶段的持续影响。

常见坑

scope 写错导致静默失效：此 effect 必须在 SPECIAL_PROJECT scope 下执行，直接写在国家 scope（如 owner = { add_project_progress_ratio = 0.1 }）不会报错但完全无效，务必先用 sp:项目键名 = { } 进入正确 scope。
误以为值可以超过 1 累加：输入值是相对于完成所需总进度的比例，传入大于 1 的值在逻辑上无意义且行为不可预期，若需"直接完成"应配合 [complete_prototype_reward_option](/wiki/effect/complete_prototype_reward_option) 而非堆砌超额比例值。

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

In special project-focused mods, you can use this effect to reward players with a proportional boost to prototype stage progress upon completing prerequisite tasks or events, accelerating research timelines. For example, within an option block of a research event, you can directly advance an associated special project by 10%:

option = {
    name = my_event.1.a
    sp:my_secret_weapon = {
        add_project_progress_ratio = 0.1
    }
}

You can also dynamically control the advancement amount through variables, making progress gains scale with game state (such as research investment increasing progress speed).

Synergy

[has_project_flag](/wiki/trigger/has_project_flag): Check whether the special project is in a specific stage or state before advancing progress, preventing reward triggers at inappropriate moments.
[set_project_flag](/wiki/effect/set_project_flag): Mark the project immediately after advancing progress to prevent the same event chain from triggering duplicate progress gains, implementing "one-time reward" logic.
[complete_prototype_reward_option](/wiki/effect/complete_prototype_reward_option): When progress reaches full value, pair this effect to trigger the prototype stage's reward options, forming a complete research completion workflow.
[add_dynamic_modifier](/wiki/effect/add_dynamic_modifier): Stack dynamic modifiers alongside progress increases to simulate how "accelerated research states" impact subsequent stages.

Common Pitfalls

Silent failure from incorrect scope: This effect must execute within a SPECIAL_PROJECT scope. Writing it directly in a country scope (e.g., owner = { add_project_progress_ratio = 0.1 }) produces no error but is completely ineffective—always enter the correct scope first using sp:project_key = { }.
Assuming values can accumulate beyond 1: The input value is a ratio relative to the total progress required for completion. Passing values greater than 1 is logically meaningless and produces unpredictable behavior. For "instant completion," pair with [complete_prototype_reward_option](/wiki/effect/complete_prototype_reward_option) rather than stacking excess ratio values.

effect · add_project_progress_ratio