Wiki

effect · clamp_variable

Definition

  • Supported scope:any
  • Supported target:none

Description

Clamps a variable between two values or variables.
Note that either min or max can be omitted.
The order in which the operations are applied is Max( Min( var, max ), min ).
An error will be logged if max < min as the result will be more often than not undesired (requires the game to run in debug mode).
Example: clamp_variable = {
    var = num_dogs
    min = 0
    max = num_cats
}

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

clamp_variable is commonly used in scenarios where dynamic variables require boundary protection, such as resource values in economic systems, custom faction favorability, or population counts, preventing them from exceeding reasonable ranges (such as negative values or hitting upper limits) due to successive add/subtract operations. A typical scenario is when a player triggers an event to modify a variable, then immediately clamps it to ensure its validity.

# Monthly pulse: after adding/subtracting from the player's "popular_support", constrain it between 0~100
add_to_variable = { var = popular_support value = stability_bonus }
clamp_variable = {
    var = popular_support
    min = 0
    max = 100
}

Synergy

  • [add_to_variable](/wiki/effect/add_to_variable) / [subtract_from_variable](/wiki/effect/subtract_from_variable): After performing arithmetic operations on a variable, immediately use clamp_variable to prevent result overflow—this is the most typical "modify → clamp" combination.
  • [set_variable](/wiki/effect/set_variable): When initializing values from uncontrollable sources (such as copying from other variables), you can subsequently clamp to ensure the initial value is valid.
  • [check_variable](/wiki/trigger/check_variable): Before deciding whether additional clamping is needed, first check the current range of the variable in an if block to avoid unnecessary triggers; can also be used during debugging to verify that clamp is working as expected.
  • [multiply_variable](/wiki/effect/multiply_variable): Multiplication operations can cause values to expand dramatically, making it especially necessary to pair with clamp_variable for upper-bound protection afterward.

Common Pitfalls

  1. Counterintuitive results when min exceeds max: According to official documentation, the execution order is Max( Min(var, max), min ). If min > max, the final result will always equal min rather than an expected intermediate value. Error logs are only output in debug mode; Release builds silently produce incorrect behavior. Always ensure min ≤ max.
  2. Mistakenly using literal values instead of variable names: Both min/max can be numeric literals or variable names, but variable names must be existing variables in the current scope with assigned values. If you reference a variable that has not been initialized (does not exist) as a boundary, that boundary will be treated as 0, causing clamping behavior completely at odds with expectations, and no obvious error will be reported.