Skip to content

Game.TerrainAttractivenessSystem

Assembly: Game
Namespace: Game.Simulation

Type: class

Base: CellMapSystem, IJobSerializable

Summary:
TerrainAttractivenessSystem builds and maintains a 2D cell map (texture) of terrain attractiveness modifiers used by the Attraction/Building placement logic (e.g., forest and shore bonuses and height-based bonuses). It samples terrain height, water depth and zone ambience, and computes per-cell forest and shore bonus values on a fixed-size grid (kTextureSize x kTextureSize) using Unity Jobs (Burst compiled) for CPU parallelism. The system exposes helper methods to query and evaluate attractiveness for world positions and integrates with other systems by adding job readers/writers (TerrainSystem, WaterSystem, ZoneAmbienceSystem). The map is updated incrementally according to GetUpdateInterval.

Fields

  • public static readonly int kTextureSize
    Provides the resolution of the attractiveness cell map. Value: 128 (the map is kTextureSize x kTextureSize).

  • public static readonly int kUpdatesPerDay
    Determines how many times per in-game day the attractiveness map is intended to be updated. Value: 16.

  • private TerrainSystem m_TerrainSystem
    Reference to the TerrainSystem used to read terrain height data.

  • private WaterSystem m_WaterSystem
    Reference to the WaterSystem used to read water surface/depth data.

  • private ZoneAmbienceSystem m_ZoneAmbienceSystem
    Reference to the ZoneAmbienceSystem used to sample ambience data (used for forest contribution).

  • private EntityQuery m_AttractivenessParameterGroup
    EntityQuery used to access AttractivenessParameterData singleton (parameters that control distances/effects/height bonus).

  • private NativeArray<float3> m_AttractFactorData
    Persistent NativeArray used as an intermediate buffer. For each cell it stores a float3 where: x = sampled water depth, y = sampled terrain height, z = zone ambience (forest) value. Allocated in OnCreate and disposed in OnDestroy.

Note: The system also defines two nested job structs: - TerrainAttractivenessPrepareJob (IJobParallelForBatch, Burst) — samples terrain, water and zone ambience into m_AttractFactorData. - TerrainAttractivenessJob (IJobParallelForBatch, Burst) — computes forest/shore bonuses from prepared factor data and writes TerrainAttractiveness values into the cell map.

Properties

  • public int2 TextureSize { get; }
    Returns the texture size as an int2 (kTextureSize, kTextureSize). Use this to obtain the grid resolution.

Constructors

  • public TerrainAttractivenessSystem()
    Default parameterless constructor. Standard ECS system construction; initialization is performed in OnCreate.

Methods

  • public override int GetUpdateInterval(SystemUpdatePhase phase)
    Returns the update interval in simulation ticks for this system. Implementation returns 262144 / kUpdatesPerDay. (262144 = 512 * 512; this value maps the update frequency to the total map area and the configured updates per day.)

  • public static float3 GetCellCenter(int index)
    Utility delegating to CellMapSystem.GetCellCenter(index, kTextureSize). Returns world position of the center of the cell at a flat index.

  • public static float EvaluateAttractiveness(float terrainHeight, TerrainAttractiveness attractiveness, AttractivenessParameterData parameters)
    Compute combined attractiveness value from a given terrainHeight and corresponding TerrainAttractiveness (structure with forest/shore bonuses) using the given parameters. The result sums:

  • forest effect * forest bonus
  • shore effect * shore bonus

  • height bonus calculation: clamps and scales (uses parameters.m_HeightBonus components)

  • public static float EvaluateAttractiveness(float3 position, CellMapData<TerrainAttractiveness> data, TerrainHeightData heightData, AttractivenessParameterData parameters, NativeArray<int> factors)
    Higher-level evaluator that:

  • samples the terrain height at position,
  • fetches interpolated TerrainAttractiveness for the position (GetAttractiveness),
  • computes each attractiveness factor (forest, beach, height),
  • writes individual factor values into the provided factors array via AttractionSystem.SetFactor,

  • returns the summed attractiveness value.

  • public static TerrainAttractiveness GetAttractiveness(float3 position, NativeArray<TerrainAttractiveness> attractivenessMap)
    Samples the map at a world position. Performs bilinear interpolation between up to 4 neighboring cells to produce a smooth TerrainAttractiveness result. If the position maps outside the grid, a default (zeroed) TerrainAttractiveness is returned.

  • protected override void OnCreate()
    Initializes the system:

  • Calls base.OnCreate(),
  • Calls CreateTextures(kTextureSize) from CellMapSystem to allocate underlying textures/maps,
  • Resolves TerrainSystem, WaterSystem, ZoneAmbienceSystem,
  • Sets up m_AttractivenessParameterGroup to read AttractivenessParameterData,

  • Allocates m_AttractFactorData as a persistent NativeArray with length equal to the map buffer.

  • protected override void OnDestroy()
    Disposes m_AttractFactorData and calls base.OnDestroy().

  • protected override void OnUpdate()
    Core update logic that:

  • Obtains TerrainHeightData from TerrainSystem,
  • Prepares and schedules two Burst jobs:
    • TerrainAttractivenessPrepareJob: fills m_AttractFactorData by sampling water depth, terrain height and zone ambience.
    • TerrainAttractivenessJob: computes forest/shore bonuses per cell using m_AttractFactorData, AttractivenessParameterData, and writes results to the system's m_Map (CellMap).
  • Correctly composes job dependencies and registers readers with TerrainSystem, WaterSystem and ZoneAmbienceSystem (AddCPUHeightReader / AddReader / AddSurfaceReader) so those systems can track and synchronize access.

  • Adds writers and combines dependencies to ensure safe access to the map and other read/write sets.

  • public TerrainAttractivenessSystem()
    Parameterless system constructor (same as earlier constructor entry).

Notes about the job implementations: - TerrainAttractivenessPrepareJob (Burst, IJobParallelForBatch) - Inputs: TerrainHeightData, WaterSurfaceData, CellMapData - Output: m_AttractFactorData (float3 per cell) - For each cell: writes float3(depth, height, zoneAmbienceForestValue) - TerrainAttractivenessJob (Burst, IJobParallelForBatch) - Inputs: m_AttractFactorData, scale, AttractivenessParameterData - Output: m_AttractivenessMap (CellMap buffer) - For each cell: searches a neighborhood sized by the max of forest/shores distances (converted to cell count using m_Scale), and computes per-cell forest and shore bonus as the maximum attenuated contribution from surrounding factor cells. Forest uses zone ambience (z), shore uses depth threshold (x > 2f) and distance attenuation.

Thread-safety / lifecycle: - m_AttractFactorData is allocated in OnCreate with Allocator.Persistent and disposed in OnDestroy — ensure systems that access this are alive during that lifetime. - The system uses Unity Jobs + Burst; data access synchronization is handled through JobHandle dependency composition and registration with other systems (AddReader/AddWriter).

Usage Example

[Preserve]
protected override void OnCreate()
{
    base.OnCreate();
    // Cell maps and intermediate buffers are created automatically by the system's OnCreate.
    // The system will allocate m_AttractFactorData and create textures with resolution kTextureSize.
}

// Example: query attractiveness at a world position (outside the system — e.g., from another system or manager)
public float GetAttractivenessAtPosition(float3 worldPos, CellMapData<TerrainAttractiveness> mapData, TerrainHeightData heightData, AttractivenessParameterData parameters)
{
    NativeArray<int> factors = new NativeArray<int>(AttractionSystem.kFactorCount, Allocator.Temp);
    float total = TerrainAttractivenessSystem.EvaluateAttractiveness(worldPos, mapData, heightData, parameters, factors);
    // use 'total' and optionally inspect individual factors in 'factors'
    factors.Dispose();
    return total;
}

If you need the layout of TerrainAttractiveness or AttractivenessParameterData or how to obtain the CellMapData instance at runtime, I can add small reference snippets for those types and how they interoperate with this system.