Game.Simulation.ZoneAmbienceSystem

Assembly: Game
Namespace: Game.Simulation

Type: class

Base: CellMapSystem, IJobSerializable

Summary:
ZoneAmbienceSystem maintains a 2D cell map (texture) of aggregated ambient values for zones and provides sampling utilities for querying ambience at world positions. It collects per-frame accumulators into the cell values on a scheduled parallel job, exposes helper sampling functions that perform weighted blending across neighboring cells, and creates the textures used for visualization. The system is designed to run as part of the simulation update pipeline and uses Unity.Jobs (Burst-compiled job for the update sweep) and Unity.Collections (NativeArray) for performance.

Fields

public static readonly int kTextureSize = 64
Defines the internal texture resolution (width and height) used for the zone ambience cell map. The map is kTextureSize x kTextureSize.
public static readonly int kUpdatesPerDay = 128
Controls how frequently the system performs its full update over the logical day. Used to compute the update interval returned by GetUpdateInterval.
private struct ZoneAmbienceUpdateJob : IJobParallelFor (nested, BurstCompile)
Job type used to atomically move each cell's accumulated ambience into the cell's stored m_Value and then reset the accumulator. This job operates over the NativeArray that backs the map and is scheduled as a parallel-for.

Properties

public int2 TextureSize => new int2(kTextureSize, kTextureSize)
Read-only convenience property returning the texture dimensions as an int2 (64,64). Use this to query the system texture size.

Constructors

public ZoneAmbienceSystem()
Default constructor (empty). System initialization happens in OnCreate.

Methods

public override int GetUpdateInterval(SystemUpdatePhase phase)
Returns the interval (in simulation ticks) between updates for this system. Computed as 262144 / kUpdatesPerDay (with kUpdatesPerDay = 128 the interval is 2048). This determines how often OnUpdate is invoked relative to the simulation update phase scheduling.
public static float3 GetCellCenter(int index)
Returns the world-space center position for the cell at the given linear index. Delegates to CellMapSystem.GetCellCenter with kTextureSize.
public static float GetZoneAmbienceNear(GroupAmbienceType type, float3 position, NativeArray<ZoneAmbienceCell> zoneAmbienceMap, float nearWeight, float maxPerCell)
Samples the ambience for the given GroupAmbienceType near the specified position. The function:
Locates the integer cell containing the position.
Iterates a 5x5 neighborhood (cell +/-2 in x and y).
For each valid neighbor cell, computes a distance weight using math.distance(GetCellCenter(index), position)/10f raised to (1 + nearWeight) and clamped to a minimum of 1.
Adds a capped contribution (min(maxPerCell, cell.m_Value.GetAmbience(type))) divided by that weight.
Normalizes by the sum of inverse weights to return a weighted average. This variant uses linear distance with a tunable nearWeight exponent to bias nearby cells.
public static float GetZoneAmbience(GroupAmbienceType type, float3 position, NativeArray<ZoneAmbienceCell> zoneAmbienceMap, float maxPerCell)
Similar sampling method to GetZoneAmbienceNear but uses squared-distance weighting (math.distancesq) and no nearWeight exponent. Contributions are capped per cell by maxPerCell. The neighborhood and normalization are identical otherwise.
public static ZoneAmbienceCell GetZoneAmbience(float3 position, NativeArray<ZoneAmbienceCell> zoneAmbienceMap)
Returns a blended ZoneAmbienceCell (all ambience channels) at the given position by sampling the 5x5 neighborhood and performing a distance-weighted blend (using squared distance). This builds a ZoneAmbiences accumulator that is normalized by the sum of inverse weights and returned as result.m_Value.
protected override void OnCreate() [Preserve]
Called when the system is created. Calls base.OnCreate() and CreateTextures(kTextureSize) to prepare the cell map textures at the configured resolution.
protected override void OnUpdate() [Preserve]
Schedules the ZoneAmbienceUpdateJob:
Constructs ZoneAmbienceUpdateJob with m_ZoneMap = m_Map (the NativeArray backing the cell map).
Schedules the job as an IJobParallelFor with total iterations kTextureSize * kTextureSize and a batch size of kTextureSize, combining existing read/write dependencies with base.Dependency.
Adds the scheduled job as a writer dependency and combines dependencies for base.Dependency. Effectively this moves per-cell accumulators into stored values and resets accumulators on a background job.

Notes: - ZoneAmbienceUpdateJob is Burst-compiled for performance. - Sampling functions accept a NativeArray so they can be called in safe contexts where you have access to the map buffer (e.g., from other jobs if properly synchronized). - The system relies on an accumulator pattern: code elsewhere should add to cell.m_Accumulator during the frame; OnUpdate moves accumulators into m_Value once per scheduled update.

Usage Example

[Preserve]
protected override void OnCreate()
{
    base.OnCreate();
    // Prepare 64x64 textures used by the cell map
    CreateTextures(ZoneAmbienceSystem.kTextureSize);
}

[Preserve]
protected override void OnUpdate()
{
    // The system already schedules the ZoneAmbienceUpdateJob internally.
    // If you manually need to sample the map on the main thread after dependencies:
    // NativeArray<ZoneAmbienceCell> map = /* obtain the NativeArray from the system or API */;
    // float ambientValue = ZoneAmbienceSystem.GetZoneAmbienceNear(GroupAmbienceType.SomeType, position, map, nearWeight: 0.5f, maxPerCell: 1f);
}

Additional tips: - Use GetZoneAmbienceNear when you want to bias toward very close contributions (tune nearWeight), otherwise use GetZoneAmbience for squared-distance blending. - maxPerCell is useful to cap noisy cell contributions when aggregating many sources. - Ensure proper dependency synchronization if you read the map from a job (use the system's read/write dependencies).