Skip to content

Game.Effects.EffectFlagSystem

Assembly: Game
Namespace: Game.Effects

Type: class

Base: GameSystemBase, IDefaultSerializable, ISerializable

Summary:
EffectFlagSystem tracks simple environment "flags" used by effects (day/night and cold/warm season state) and exposes helper logic to decide whether an effect guarded by those flags should be active. It samples TimeSystem and ClimateSystem at a low frequency to determine (and timestamp) transitions between night/day and cold/warm season, supports deterministic randomness windows for fading effects, and implements serialization for save/load and default initialization.

Fields

  • public struct EffectFlagData
    Represents a serializable snapshot of the system state used by effects. Contains:
  • m_IsNightTime (bool) — whether the system considers it night.
  • m_LastTimeChange (uint) — simulation frame when day/night last toggled.
  • m_IsColdSeason (bool) — whether the system considers it a cold season.

  • m_LastSeasonChange (uint) — simulation frame when season last toggled.

  • public static readonly uint kNightRandomTicks

  • Maximum randomized tick window used when m_IsNightTime is true to evaluate Night-flagged effects. Used to provide stochastic fading behavior across frames.

  • public static readonly uint kDayRandomTicks

  • Maximum randomized tick window used when m_IsNightTime is false for Day evaluations.

  • public static readonly float kNightBegin
    0.75. Normalized time (from TimeSystem) at or after which the system considers it night.

  • public static readonly float kDayBegin
    0.25. Normalized time (from TimeSystem) before which the system considers it day (used together with kNightBegin to define night range across wrap-around).

  • public static readonly uint kSpringRandomTicks

  • Randomized tick window used when the system is in spring (used for Cold flag logic).

  • public static readonly uint kAutumnRandomTicks

  • Randomized tick window used when the system is in autumn (used for Cold flag logic).

  • public static readonly float kSpringTemperature

  • Temperature threshold used to transition out of a cold season (if temperature >= 10 => leave cold season).

  • public static readonly float kAutumnTemperature

  • Temperature threshold used to transition into a cold season (if temperature < 5 => enter cold season).

  • private Entity m_CurrentSeason
    Holds the currently observed Season entity from the ClimateSystem to detect season changes.

  • private uint m_LastSeasonChange
    Frame index when the system last updated m_IsColdSeason.

  • private bool m_IsColdSeason
    Current flag whether it is considered a cold season.

  • private bool m_IsNightTime
    Current flag whether it is considered night.

  • private uint m_LastTimeChange
    Frame index when the system last updated m_IsNightTime.

  • private SimulationSystem m_SimulationSystem
    Cached reference to the SimulationSystem used to read the current frameIndex.

  • private TimeSystem m_TimeSystem
    Cached reference to the TimeSystem used to read normalizedTime.

  • private ClimateSystem m_ClimateSystem
    Cached reference to the ClimateSystem used to read temperature and currentSeason.

Properties

  • None exposed by this class. (State is exposed via GetData().)

Constructors

  • public EffectFlagSystem()
    Default constructor. The system relies on OnCreate to cache references to other world systems; construction itself does not initialize runtime state beyond defaults (SetDefaults will be used during deserialization or initialization).

Methods

  • public override int GetUpdateInterval(SystemUpdatePhase phase)
    Returns 2048. The system updates infrequently (every 2048 ticks as scheduled by the game) because the tracked flags change slowly (time of day / seasons).

  • public static bool IsEnabled(EffectConditionFlags flag, Random random, EffectFlagData data, uint frame)
    Evaluates whether an effect guarded by the provided EffectConditionFlags should trigger given a deterministic Random instance, a snapshot of EffectFlagData, and the current frame. Logic:

  • If flag contains Night: when data.m_IsNightTime is true, returns true only if data.m_LastTimeChange + random.NextUInt(kNightRandomTicks) < frame. If false, returns true only if data.m_LastTimeChange + random.NextUInt(kDayRandomTicks) >= frame. This produces a randomized enable/disable window around transitions.
  • If flag contains Cold: similar randomized logic using kAutumnRandomTicks and kSpringRandomTicks depending on data.m_IsColdSeason and data.m_LastSeasonChange.

  • If neither Night nor Cold flags are present, returns true (no condition). Note: EffectConditionFlags and Random types are expected from the game's modding API; Random.NextUInt is used to produce the random tick offset.

  • public EffectFlagData GetData()
    Returns a snapshot of the current internal state packaged into EffectFlagData (m_IsColdSeason, m_IsNightTime, m_LastSeasonChange, m_LastTimeChange). Use this to query the system state to pass into IsEnabled or to store with effects.

  • public void Deserialize<TReader>(TReader reader) where TReader : IReader
    Reads m_LastSeasonChange, m_IsColdSeason, m_LastTimeChange and (conditionally, depending on reader.context.version) m_IsNightTime from the reader. For backward compatibility, m_IsNightTime defaults to false unless the save version includes the night flag (Version.addNightForestAmbienceSound).

  • public void Serialize<TWriter>(TWriter writer) where TWriter : IWriter
    Writes m_LastSeasonChange, m_IsColdSeason, m_LastTimeChange and m_IsNightTime in that order. This persists the state across saves.

  • public void SetDefaults(Context context)
    Resets state to defaults used when no saved data is present: sets last change timestamps to 0 and both flags to false.

  • [Preserve] protected override void OnCreate()
    Called when the system is created. Caches references to SimulationSystem, TimeSystem and ClimateSystem from the ECS world (via base.World.GetOrCreateSystemManaged<...>).

  • [Preserve] protected override void OnUpdate()
    Executed on the system's update interval. Reads the current SimulationSystem.frameIndex and ClimateSystem.temperature/currentSeason to determine season transitions:

  • If the season entity changed, the system compares the ClimateSystem temperature with thresholds (kSpringTemperature and kAutumnTemperature) to detect transitions into/out of cold season and updates m_IsColdSeason and m_LastSeasonChange accordingly.
  • Sets m_IsNightTime based on TimeSystem.normalizedTime and the kNightBegin / kDayBegin thresholds accounting for wrap-around (night if normalizedTime >= kNightBegin OR normalizedTime < kDayBegin).
  • Finally, updates m_CurrentSeason to the ClimateSystem.currentSeason.

Usage Example

// Example: Check if a night-only effect should be active this frame
var effectSystem = world.GetExistingSystemManaged<Game.Effects.EffectFlagSystem>();
if (effectSystem != null)
{
    var data = effectSystem.GetData();
    // 'random' should be a deterministic Random instance used by the effect (seeded per effect/entity).
    if (Game.Effects.EffectFlagSystem.IsEnabled(EffectConditionFlags.Night, random, data, simulationSystem.frameIndex))
    {
        // Activate or update the effect for night
    }
}

Notes and tips for modders: - The system is designed to update rarely; if you need more responsive behavior in your mod, query TimeSystem or ClimateSystem directly instead of relying on this system's flags. - Use GetData + IsEnabled to reproduce the game's randomized fade/activation windows to make custom effects behave consistently with built-in ones. - Respect serialization order when storing custom data that depends on these flags to remain compatible with save/load behavior.