Conditions - SuIT-pub/Mind-the-School GitHub Wiki

Audience: Developers comfortable with Python/Ren'Py who need to gate content in Mind the School — events, situations, unlockables, effects, votes. This guide explains what a Condition is, the base contract, how to combine conditions, the shared Option system, and the full catalog of condition types.

Scope: Conditions only. They are the shared gating primitive used by nearly every other system (events, situations, unlockables, selectors, PTA). Those systems have their own guides; this one is the reference for the conditions themselves.

A Condition answers one yes/no question about the game state. You build one and hand it to whatever system does the gating (an event, a situation threshold, an unlockable's visibility, …):

# "school level ≥ 2 AND at least $1500 AND the intro event was seen"
AND(
    LevelCondition("2"),
    MoneyCondition(1500),
    EventSeenCondition(True, "intro_done"),
)

• A bare condition is checked with condition.is_fulfilled(**kwargs).
• A group is checked with ConditionStorage(*conditions).is_fulfilled(**kwargs) (all must pass) — most systems wrap your conditions in a storage for you.
• Combine with AND / OR / NOR / NOT / XOR.
• While work is in progress, use PlaceholderCondition() (never fulfilled).

1. What is a Condition?
2. The base contract
3. ConditionStorage
4. Logic combinators
5. Options
6. The condition catalog
7. Common patterns
8. Conventions
9. Troubleshooting
10. Reference tables

A Condition is a small object that evaluates the game state and returns True/False. It is the universal gating primitive: events use conditions to decide when they can fire, situation thresholds use them as gate conditions, teasers use them as unlock triggers, unlockables use them for visibility, PTA votes use them for cost gates, and so on.

Conditions are declarative and reusable. You never subclass to gate ordinary content — you compose the existing types. Because everything is coupled only through keys and conditions, a mod can gate on base content and vice versa.

Every condition subclasses Condition(*options):

• check_condition(**kwargs) -> bool (abstract) — the actual test. Subclasses implement this.
• is_fulfilled(**kwargs) -> bool — the public entry point. It wraps check_condition with universal short-circuits: it returns True in replay mode / journal gallery (in_replay, check_in_replay, in_journal_gallery), and True if the condition carries the Optional option. Otherwise it delegates to check_condition. Call is_fulfilled, not check_condition.
• get_name() -> str (abstract) — a human-readable identifier, used in logs and default description text.
• type (property, on many subclasses) — a string tag ("stat", "money", "timer", …) used by find_by_type to pull specific conditions back out of a storage.

**kwargs carry the evaluation context — most importantly char_obj (the character or school the condition applies to; defaults to the school), plus event/selector data. Conditions read what they need and ignore the rest.

Display hooks (mostly for the journal): display_in_list / display_in_desc flags (default False; set True by display-worthy subclasses like StatCondition), to_list_text / to_desc_text, and get_diff / calculate_probability (how close to fulfilled — feeds vote probability and sorting).

Note: "Blocking" is not a Condition concept. The old blocking attribute that once controlled journal display was removed — a condition's own visibility is driven by display_in_list / display_in_desc (above). Situation blocking thresholds are an unrelated, threshold-level mechanic and live in the Situations guide, not here.

ConditionStorage(*conditions) is the container systems use to hold a set of conditions. Key behavior:

• is_fulfilled(**kwargs) — AND semantics: True only if every member is fulfilled. (An empty storage is True.)
• add_conditions(*conditions) / add_condition(c) / add_storage(other) — build it up incrementally; duplicates (same object) are skipped.
• find_by_type(type) — returns all members whose type matches (recursing into combinators). This is how systems extract, e.g., the TimerCondition or MoneyCondition out of a mixed list.
• Sorts members into list_conditions / desc_conditions for the journal, and tracks whether a LockCondition is present (is_locked).

You rarely construct a storage yourself for gating — you pass a list of conditions to a system and it wraps them. You do use ConditionStorage when writing a system that gates on author-supplied conditions.

Conditions compose. Each combinator is itself a Condition, so it nests anywhere a condition is accepted:

OR(
    AND(LevelCondition("3"), EventSeenCondition(True, "sb_event_3")),
    MoneyCondition(5000),
)

Note: a bare ConditionStorage / a plain condition list is already an implicit AND. Use the explicit AND(...) only when you need it inside an OR/NOT/etc.

Both conditions and effects accept trailing *options (from option.rpy). An Option tweaks how the host is evaluated or displayed — see the Options guide for the full shared catalog. The condition-relevant ones:

Other options are event- or effect-specific (FragmentRepeatOption, EffectNoRevertOption, MoneyEscrowOption, …) — see the Options guide. Options are passed positionally after the constructor's own args: StatCondition(OptionalOption(), corruption=20).

All constructors below are Condition subclasses. *options is always accepted last. Numeric arguments written as "2", "2+", "3-7", "1,3,5" are value ranges — the shared number-pattern grammar is documented in Value Ranges.

Deprecated (as of 0.2.3 — replaced by the Unlockables system, kept only for save compatibility): RuleCondition(value, …), ClubCondition(value, …), BuildingLevelCondition(name, level, …) and PTAOverride(char, accept, …). The rule/club conditions are effectively always-false stubs. Use UnlockableCondition instead (and BuildingCondition for building state).

Gate on multiple stats: one StatCondition takes several stat kwargs (implicit AND across them):

StatCondition(corruption=30, inhibition=20)

Probabilistic appearance: RandomCondition(35) ≈ a 35 % chance gate — often combined with hard requirements via AND.

Duration / cooldown / grace (situations): TimerCondition("my_id", daytime=3). The situation/measure machinery starts and reads the timer; you just declare it.

"Not yet done": NOT(EventSeenCondition(True, "some_event")), or simply EventSeenCondition(False, "some_event").

Mixed AND/OR: compose explicitly:

AND(LevelCondition("3"), OR(MoneyCondition(2000), UnlockableCondition("grant")))

WIP gate: PlaceholderCondition() — the host stays uncompletable until you replace it. (Some hosts self-test that they carry ≥ 1 condition — e.g. situation gate thresholds and teasers; a placeholder satisfies "has a condition" but never fires, so the gate can never pass until you replace it.)

• Compose, don't subclass. Gate ordinary content with the existing types + combinators. Only write a new Condition subclass for a genuinely new kind of check (then implement check_condition + get_name, and add a type if it should be find_by_type-discoverable).
• Call is_fulfilled, never check_condition. Only is_fulfilled honors replay/gallery/Optional.
• Keys are identity. Condition arguments reference keys (event_name, situation_key, GameData key, unlockable key). Use the real, stable keys; a typo silently makes the gate unsatisfiable.
• Prefer UnlockableCondition / BuildingCondition over the legacy RuleCondition / ClubCondition.
• Placeholders are temporary. Replace every PlaceholderCondition() before shipping — grep for them.

Condition(*options) · abstract check_condition + get_name · public is_fulfilled · type → find_by_type · display_in_list / display_in_desc + to_list_text / to_desc_text.

is_fulfilled = AND · add_conditions / add_condition / add_storage · find_by_type · get_conditions.

AND · OR · NOR · NOT(single) · XOR (odd count).

> · < · >= · <= · == — a separate argument on NumCompareCondition / KeyCompareCondition. Not to be confused with the value-range suffix form ("20+", "3-7") that stat/level/time checks parse — that grammar is documented in Value Ranges.

day · week · month · year · daytime · weekday · date · condition (+/-/``) for TimeCondition; span keys `day=` / `daytime=` / … for `TimerCondition`.

• game/scripts/conditions.rpy — all condition classes + ConditionStorage
• game/scripts/option.rpy — the Option / OptionSet system
• game/scripts/selector.rpy — Selectors (some conditions accept one as value)
• game/scripts/effects.rpy — the counterpart: Effects (what happens when a gate passes)