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

Audience: Developers writing Mind the School events who need dynamic values — a random outfit variant, the acting character, a stat reading, a time-of-day — computed at runtime and woven into image paths, dialogue, effects and conditions.

Scope: The selector system (selector.rpy). Selectors are an event-authoring tool: they produce values that land in the event's kwargs. They pair with Events (which run them), and some Conditions / Effects accept a Selector in place of a fixed value.

A Selector computes a value under a key; that key becomes a kwarg the rest of the event can read:

SelectorSet(
    CharacterSelector("char"),                      # pick the acting character → kwargs["char"]
    RandomValueSelector("variant", 1, 4),           # random 1..4 → kwargs["variant"]
    StatSelector("corr", CORRUPTION, "char", [0, 100]),  # a stat reading (+ "corr_range")
)

Downstream you reference those keys:

• in image paths: "images/scene/<char>/pose_<variant>.webp" (resolved by refine_image/get_image);
• in Ren'Py text: "[char] looks away.";
• as values passed into conditions/effects that accept a Selector.

1. What is a Selector?
2. The base contract
3. SelectorSet & how values reach kwargs
4. realtime vs. cached, and rerolling
5. Nesting selectors
6. The selector catalog
7. Using selector values downstream
8. Conventions
9. Troubleshooting
10. Reference tables

A Selector produces a value at runtime and stores it in the event kwargs under a key. That is how an event stays generic: instead of hard-coding "Yuriko" or "variant 2", you declare how to pick and let the selector roll it when the event runs. The result flows into image resolution, dialogue interpolation, and any condition/effect that reads the kwarg.

Selectors are almost always attached to events (via a SelectorSet). They are a content-authoring convenience, not a gameplay system of their own.

Every selector subclasses Selector(realtime, key, *options):

• key — the kwarg name the value is stored under (get_name() returns it).
• roll(**kwargs) -> Any (abstract) — compute a fresh value.
• get_value(**kwargs) — return the value; rolls first if realtime or if no value is cached yet.
• update(**kwargs) — force a re-roll (caches the result).
• options — trailing *options (OptionSet); see the Options guide (e.g. FragmentReroll).

You read values through get_value (or, in practice, through the SelectorSet); never poke _value directly.

SelectorSet(*selectors) is the container an event holds. Its job is to turn the selectors into kwargs:

• get_values(**kwargs) -> dict — merges every selector's key: value into kwargs and returns it (rolling once if not yet rolled). This is what feeds the event.
• roll_values(**kwargs) — re-rolls all selectors and re-merges.
• add_selector(*selectors) — extend the set.

Two selectors are merged specially:

• KwargsSelector contributes multiple keys at once (not one key: value).
• StatSelector contributes both key and key + "_range" (so downstream can scale against the stat's range).

• Cached (realtime=False, the default for most) — the value is rolled once and stays fixed for the event, so an image path and the dialogue that reference the same key agree.
• Realtime (realtime=True) — re-rolled on every get_value. StatSelector defaults to realtime (a stat reading should be current); use realtime only when you truly want a fresh value each access.

reroll_selectors() re-rolls every selector queued in the global rerollSelectors list — used to refresh values across a parenting/fragment boundary so a follow-up scene can pick new values.

Selectors compose. Wherever a selector takes a value, that value may itself be a Selector, and it gets rolled recursively:

• RandomListSelector("x", "a", "b", AnotherSelector(...)) — if the nested selector is chosen, it rolls and its result is used.
• Many selectors accept str | Selector for their target (e.g. StatSelector's stat/char, LevelSelector's char) — so the character or stat to read can itself be selected dynamically.

This lets you build "pick a character, then read that character's stat" without hard-coding the link.

realtime defaults to False unless noted; *options accepted last.

Legacy: RuleUnlockedSelector / ClubUnlockedSelector target the retired rules/clubs system. Prefer reading unlock state via an UnlockableCondition (or a GameDataSelector on the unlocked flag) instead.

Unlike every selector above, a ModifierSelector's value is never substituted into art or dialogue. It carries a Modifier_Obj that the event activates on demand by calling load_modifier("key", **kwargs) in its scene label. load_modifier applies the modifier and registers it with the lifecycle registry, owned by the event — so it is orphan-safe: kept alive while the event stays registered, swept if the event goes away. Give each ModifierSelector on an event a distinct key (it becomes part of the modifier's registry key "<event>:<key>"). Full flow: Events §13 and Modifiers.

Once a selector has put key: value into the kwargs:

• Image paths substitute <key> — refine_image / get_image replace every <key> with its kwarg value (this is how variants, characters and levels select the right art). StatSelector's key_range is available for range-based art.
• Dialogue uses Ren'Py interpolation — "[key]".
• Conditions/effects that accept Union[..., Selector] (e.g. NumValueCondition, CompareCondition, NumClampSelector) can be handed a selector directly, or read the resulting kwarg by key.

Because everything travels as kwargs, a selector defined once drives art, text and logic consistently within the event.

• One key, one meaning. A selector's key is a kwarg name; keep it descriptive and don't collide with kwargs the event system already sets (char_obj, event metadata, …).
• Cache by default. Leave realtime=False unless a value must be fresh on each read; otherwise the image and the dialogue referencing the same key can disagree.
• Nest instead of duplicating. "Read the selected character's stat" = pass the character selector into the stat selector, don't roll the character twice.
• Prefer UnlockableCondition/GameData over the legacy rule/club selectors.
• StatSelector gives you a range too (key_range) — use it for range-scaled art rather than hard-coding bounds.

Selector(realtime, key, *options) · abstract roll(**kwargs) · get_value (rolls if realtime/uncached) · update (force re-roll) · get_name = key.

SelectorSet(*selectors) · get_values(**kwargs) → kwargs dict · roll_values · add_selector. Special: KwargsSelector (many keys), StatSelector (+_range).

Image paths: <key> (via refine_image/get_image) · Text: [key] (Ren'Py) · Logic: pass a Selector where Union[..., Selector] is accepted.

• game/scripts/selector.rpy — all selector classes + SelectorSet
• game/scripts/event.rpy — events that run selectors
• game/scripts/images.rpy — refine_image / get_image (<key> substitution)
• Images — path resolution, PNG/WebP, mod prefixes
• Conditions / Effects — consumers that accept a Selector