Skip to content

Game.Simulation.ICityStatisticsSystem

Assembly:
Game (assembly name used by the game; exact assembly may vary)

Namespace:
Game.Simulation

Type:
interface

Base:
None (interface)

Summary:
Interface for accessing and querying city-wide statistics used by the simulation. Exposes events for when statistics are updated, sampling count information, methods to read individual statistic values (both 32-bit and 64-bit), methods to obtain arrays of statistics and raw statistic data (int/long), methods that accept ECS BufferLookup to operate against a provided buffer, a lookup map for statistic keys to Entities, a method to ensure writers are complete (synchronization), and a utility to get the sample frame index for a given sample slot. Useful for mods and systems that need read access to aggregated simulation statistics.

Fields

  • None — interfaces do not declare instance fields.
    {{ This interface does not define internal fields. Implementations will hold the actual storage and any synchronization primitives. }}

Properties

  • public Action eventStatisticsUpdated { get; set; }
    {{ Event that consumers can subscribe to in order to be notified when statistics are updated. Implementations should invoke this action after statistics change so listeners can refresh cached data or re-query statistics. }}

  • public int sampleCount { get; }
    {{ Returns the number of sampled frames or data points the statistics system keeps (number of samples in history). Useful to iterate or validate sample index ranges prior to calls that accept an index or parameter representing a sample slot. }}

Constructors

  • Interfaces do not define constructors.
    {{ Implementations will provide construction/initialization behaviour. }}

Methods

  • int GetStatisticValue(StatisticType type, int parameter = 0)
    {{ Retrieve a 32-bit integer statistic for the given StatisticType. The optional parameter is used for statistic variants (for example, zone index, level or sub-type) depending on the StatisticType semantics. Returns an int value representing the statistic at the current sample (or aggregate value as defined by the implementation). }}

  • long GetStatisticValueLong(StatisticType type, int parameter = 0)
    {{ Retrieve a 64-bit (long) statistic for the given StatisticType. Use this when the statistic can exceed 32-bit range. The optional parameter semantics are the same as GetStatisticValue. }}

  • int GetStatisticValue(BufferLookup<CityStatistic> stats, StatisticType type, int parameter = 0)
    {{ Variant that reads the value from a provided BufferLookup. Use when you have direct access to an entity's CityStatistic buffer (for example inside a system or job that provides a BufferLookup). This avoids implicitly using the system-global statistic storage and lets you operate on custom or per-entity statistic buffers. }}

  • long GetStatisticValueLong(BufferLookup<CityStatistic> stats, StatisticType type, int parameter = 0)
    {{ 64-bit variant of the above that reads from a provided BufferLookup. }}

  • NativeArray<CityStatistic> GetStatisticArray(StatisticType type, int parameter = 0)
    {{ Returns a NativeArray of CityStatistic structs for the requested StatisticType (and optional parameter). This array contains the per-sample CityStatistic entries or the relevant sequence for that statistic. The returned NativeArray is native memory; callers should follow ownership rules of the implementation (typically the caller must Dispose() the NativeArray when done if the array was allocated for them). Check implementation docs for exact allocator/ownership. }}

  • NativeArray<int> GetStatisticDataArray(StatisticType type, int parameter = 0)
    {{ Returns a NativeArray containing the raw integer data values for the requested statistic over the stored samples. Useful for charting or bulk processing. Observe allocator/ownership rules and dispose when appropriate. }}

  • NativeArray<int> GetStatisticDataArray(BufferLookup<CityStatistic> stats, StatisticType type, int parameter = 0)
    {{ Same as above but reads the integer data from the provided BufferLookup buffer. }}

  • NativeArray<long> GetStatisticDataArrayLong(StatisticType type, int parameter = 0)
    {{ Returns a NativeArray of raw 64-bit statistic data for the requested statistic over the stored samples. Use for very large counters. Dispose the returned array as required. }}

  • NativeArray<long> GetStatisticDataArrayLong(BufferLookup<CityStatistic> stats, StatisticType type, int parameter = 0)
    {{ 64-bit data array variant that reads from the provided BufferLookup. }}

  • NativeParallelHashMap<CityStatisticsSystem.StatisticsKey, Entity> GetLookup()
    {{ Returns a NativeParallelHashMap mapping a StatisticsKey (typically a struct identifying a statistic by type/parameter/etc.) to an Entity that owns the statistic data. This lookup can be used to find the entity/buffer associated with a statistic key. The returned hash map's lifetime and ownership must be respected — consult the implementation to know if you must Dispose it or if it's a view managed by the system. }}

  • void CompleteWriters()
    {{ Ensure all writer jobs that update statistics are completed before attempting to read from statistics. Call this to synchronize and avoid race conditions when reading statistic data that may be written by scheduled jobs. Typically invoked before extracting NativeArrays or reading values in multi-threaded contexts. }}

  • uint GetSampleFrameIndex(int index)
    {{ Translate a sample index (0..sampleCount-1) into the frame index (or internal sampling frame identifier) for that sample slot. Useful when aligning statistic samples with simulation/frame numbers for display or analysis. }}

Usage Example

// Example usage inside a MonoBehaviour or a system (pseudocode)
public class MyStatsReader
{
    private ICityStatisticsSystem m_statsSystem;

    public void Initialize(ICityStatisticsSystem statsSystem)
    {
        m_statsSystem = statsSystem;
        m_statsSystem.eventStatisticsUpdated += OnStatsUpdated;
    }

    private void OnStatsUpdated()
    {
        // Ensure writers are finished before reading
        m_statsSystem.CompleteWriters();

        int populationNow = m_statsSystem.GetStatisticValue(StatisticType.Population);
        long totalIncome = m_statsSystem.GetStatisticValueLong(StatisticType.TotalIncome);

        // Get time series data for a statistic
        using (var values = m_statsSystem.GetStatisticDataArray(StatisticType.Population))
        {
            for (int i = 0; i < values.Length; i++)
            {
                int sample = values[i];
                // process sample...
            }
        }

        // If working with ECS BufferLookup inside a system/job:
        // BufferLookup<CityStatistic> myLookup = ... (provided by system)
        // int valueFromBuffer = m_statsSystem.GetStatisticValue(myLookup, StatisticType.Buildings, someParameter);
    }
}

Notes and best practices: - Because the API returns NativeArray and NativeParallelHashMap types, pay attention to allocation/ownership and dispose semantics to avoid memory leaks. Consult the runtime/implementation documentation for exact ownership rules. - Call CompleteWriters() before reading data if the statistics are written by background jobs to avoid race conditions. - Use the BufferLookup variants when you already have ECS data (BufferLookup) available to operate directly on entity buffers without global lookups.