Skip to content

Game.StatisticTriggerSystem

Assembly: Game
Namespace: Game.Simulation

Type: class

Base: GameSystemBase

Summary:
StatisticTriggerSystem scans prefab entities that carry StatisticTriggerData (and TriggerData) and evaluates city statistics to produce trigger actions. It reads city statistic buffers (via CityStatisticsSystem), supports normalization against other statistic prefabs, and computes TotalValue, AverageValue, AbsoluteChange and RelativeChange over a configurable timeframe and minimum samples. Computation is performed in a Burst-compiled IJobChunk (SendTriggersJob) and enqueued into the TriggerSystem via a parallel action buffer. The system respects Locked components on statistic prefabs to avoid using stats from locked sources. It registers a prefab query and requires it for update, and schedules its workload as a parallel job.

Fields

  • public const int kUpdatesPerDay
    Constant value set to 32. Represents updates-per-day used by statistic triggers (present for reference).

  • private ICityStatisticsSystem m_CityStatisticsSystem
    Reference to the city statistics system used to obtain lookups and statistic data arrays.

  • private EntityQuery m_PrefabQuery
    EntityQuery used to find prefab entities that contain StatisticTriggerData and TriggerData (required for update).

  • private TriggerSystem m_TriggerSystem
    Reference to the TriggerSystem used to create action buffers and publish TriggerAction items.

  • private TypeHandle __TypeHandle
    Internal helper that stores component/handle lookups (EntityTypeHandle, ComponentTypeHandle, ComponentLookup, ComponentLookup, BufferLookup). Assigned in OnCreateForCompiler.

  • private struct SendTriggersJob (nested)
    Burst-compiled IJobChunk that iterates matching prefab chunks, reads StatisticTriggerData and related statistic buffers, computes the requested statistic value or change, and enqueues a TriggerAction into the TriggerSystem action buffer (ParallelWriter). It uses:

  • EntityTypeHandle
  • ComponentTypeHandle
  • ComponentLookup
  • ComponentLookup
  • BufferLookup
  • NativeParallelHashMap (statistics lookup)

  • NativeQueue.ParallelWriter (action queue) The job contains logic to:

    • Fetch statistic arrays via CityStatisticsSystem.GetStatisticDataArray
    • Ensure minimum samples and timeframe length
    • Optionally normalize values with another statistic prefab
    • Compute TotalValue, AverageValue, AbsoluteChange, RelativeChange
    • Skip computation when Locked components are present or when denominator/previous values are zero
    • Enqueue TriggerAction with computed m_Value and the triggering prefab entity

  • private struct TypeHandle (nested)
    Wrapper struct that contains the concrete handles used by the system and a __AssignHandles method to populate them from a SystemState.

Properties

  • (none public)
    The system does not expose public properties.

Constructors

  • public StatisticTriggerSystem()
    Default constructor. The system uses OnCreate to initialize references to CityStatisticsSystem and TriggerSystem and to build its prefab query.

Methods

  • public override int GetUpdateInterval(SystemUpdatePhase phase)
    Returns 8192. Controls the update interval used by the game scheduling—this system is configured to run with this interval value.

  • public override int GetUpdateOffset(SystemUpdatePhase phase)
    Returns 0. Controls scheduling offset; the system sets offset to zero.

  • [Preserve] protected override void OnCreate()
    Initializes the system:

  • Obtains the CityStatisticsSystem and TriggerSystem from the World.
  • Builds m_PrefabQuery to match entities with StatisticTriggerData and TriggerData (read-only).

  • Calls RequireForUpdate(m_PrefabQuery) so this system only runs when matching prefabs exist.

  • [Preserve] protected override void OnUpdate()
    Prepares and schedules the SendTriggersJob:

  • Fills jobData with component/handle lookups (via InternalCompilerInterface helpers and __TypeHandle), the statistics lookup from m_CityStatisticsSystem, and an action buffer ParallelWriter from m_TriggerSystem.
  • Schedules the job as a parallel JobChunk (JobChunkExtensions.ScheduleParallel) using m_PrefabQuery.

  • Stores the returned JobHandle in base.Dependency and notifies m_TriggerSystem by calling AddActionBufferWriter(base.Dependency) so TriggerSystem knows about the writer dependency.

  • private void __AssignQueries(ref SystemState state)
    Compiler helper (used in OnCreateForCompiler) for query setup. In this implementation it constructs and disposes an EntityQueryBuilder; real handle assignment happens in __TypeHandle.

  • protected override void OnCreateForCompiler()
    Compiler-time initialization helper:

  • Calls __AssignQueries(ref base.CheckedStateRef)

  • Calls __TypeHandle.__AssignHandles(ref base.CheckedStateRef) to populate entity/component/buffer handles used by jobs.

  • private struct SendTriggersJob.Execute(in ArchetypeChunk chunk, int unfilteredChunkIndex, bool useEnabledMask, in v128 chunkEnabledMask)
    The main execution function of the job that processes each chunk. Iterates entities in the chunk, reads StatisticTriggerData, retrieves statistic arrays, computes the chosen statistic metric (with or without normalization), and enqueues TriggerAction entries into the provided action queue.

  • private bool SendTriggersJob.NonZeroValues(NativeArray<int> values, int timeframe)
    Helper inside the job to check that the last timeframe samples in the provided array are all non-zero (used before divisions to avoid divide-by-zero and to ensure valid normalization).

  • void SendTriggersJob.IJobChunk.Execute(...)
    Explicit interface implementation that forwards to the job's Execute method (standard IJobChunk pattern).

Usage Example

// Acquire the system (example from a mod init or another system)
var statTriggerSystem = World.GetOrCreateSystemManaged<StatisticTriggerSystem>();

// StatisticTriggerSystem runs automatically each update if there are prefabs with
// StatisticTriggerData + TriggerData. To use it, create or configure a prefab entity
// with a StatisticTriggerData component (and TriggerData) so the system will evaluate
// the configured statistic and enqueue TriggerAction(s) into TriggerSystem.
//
// Pseudocode example (actual component fields depend on game definitions):
// Entity prefab = PrefabManager.CreatePrefab("MyStatisticTrigger");
// prefab.AddComponent(new StatisticTriggerData {
//     m_StatisticEntity = someStatisticsPrefabEntity,
//     m_Type = StatisticTriggerType.AverageValue,
//     m_TimeFrame = 32,
//     m_MinSamples = 4,
//     m_NormalizeWithPrefab = Entity.Null
// });
// prefab.AddComponent(new TriggerData { /* trigger setup */ });
//
// The system will then evaluate that prefab's statistic values on its scheduled updates
// and enqueue TriggerAction items which TriggerSystem will process.

Notes and tips for modders: - StatisticTriggerSystem expects statistic data to be available from CityStatisticsSystem. Ensure the referenced statistic prefabs exist and produce data for the required timeframe/minimum samples. - If you normalize against another statistic (m_NormalizeWithPrefab), both statistic arrays must have sufficient non-zero data for the timeframe. - Locked components on statistic source prefabs prevent the system from using their data. - The job is Burst-compiled and scheduled in parallel; avoid relying on main-thread-only APIs inside statistic evaluation.