StateFlags reference
StateFlags are timed engine state labels carried on a girl. They decay one tick per week and are removed when they reach zero. A flag marked permanent (where allowed) skips decay and stays active indefinitely.
What StateFlags are
Section titled “What StateFlags are”A StateFlag is a named, timed label attached to a specific girl. It is distinct from:
- Temporary traits – timed trait-registry entries that bring stat/skill/mutex machinery with them. Use a Temporary trait when you need
<effect>contributions,<Excludes>/<Implies>relationships, or trait-gallery presence. <Status>leaves (Pregnant, Slave, etc.) – hard-wired engine statuses evaluated by<Status id="..."/>in<When>blocks.
Use a StateFlag when you need:
<HasStateFlag>queries in<When>blocks to gate text variants, gains, or effects.- Turn Summary onset messaging (“Alice is now SpiritPossessed”).
- A visible status row in Girl Details.
- Engine consequences driven by a timed, refreshable label that outlasts a single shift.
The current registry
Section titled “The current registry”| Flag | Visible | Allow permanent | Meaning |
|---|---|---|---|
RefusedJobRecently |
no | no | Internal pressure escalation, set by the refusal model. |
SpiritPossessed |
yes | yes | Channeler-line state, named in Turn Summary, displayed on Girl Details. |
InHeat |
yes | no | Beastgirl-line cycle state, named in Turn Summary, displayed on Girl Details. |
Visible – whether the flag appears in the Girl Details status row and in Turn Summary onset messages. Non-visible flags are checked by the engine internally but not surfaced to the player.
Allow permanent – whether Turns="permanent" is accepted when inflicting this flag. Flags that represent time-limited physiological states (like InHeat) do not allow permanent infliction; the engine will reject the rule at load time.
Decay semantics
Section titled “Decay semantics”Each active StateFlag carries a turn counter. Once per week, tick_weekly_stats decrements every non-permanent counter by one. When a counter reaches zero, the flag is removed from the girl.
A flag inflicted with Turns="permanent" (where the flag allows it) has no counter and is never decremented.
Refresh on reapply
Section titled “Refresh on reapply”If a flag is re-inflicted while it is already active (e.g. a Periodic rule fires while SpiritPossessed is still ticking), the turn counter is reset to the new value. The engine does not re-emit the onset Turn Summary line on a refresh – only the first inflict (from zero to active) produces the onset message.
StateFlag vs Temporary trait
Section titled “StateFlag vs Temporary trait”| Need | Use |
|---|---|
| Stat/skill modifiers while active | Temporary trait |
<Excludes> / <Implies> behavior |
Temporary trait |
| Trait-gallery / tagger visibility | Temporary trait |
<HasStateFlag> query in <When> |
StateFlag |
| Turn Summary onset line | StateFlag |
| Girl Details visible status row | StateFlag |
| Timed, refreshable engine-side label with no stat machinery | StateFlag |
How to inflict from a trait
Section titled “How to inflict from a trait”Traits attach StateFlag inflict rules via <OnGenerate> (fires at acquisition) and <Periodic> (fires on a hashed-phase cadence). See traits-reference.md for the full attribute table, validation rules, and worked examples.
How to query in prose
Section titled “How to query in prose”Use <HasStateFlag name="..." .../> inside any <When> block to gate text variants, gain rules, effect groups, or job eligibility on a girl’s current StateFlag. See when-conditions.md for the attribute reference and an example.