🧱 Terrain Layers Overview

What is a Terrain Layer?

In the Hex Terrains Framework, each terrain entity consists of several Terrain Layers, each responsible for managing a specific kind of spatial data or functionality over the hex grid. These layers are modular, extensible, and powered by job-safe DataLayer components.

All layers share a common pattern:

• Store core data per-cell or per-chunk using DataLayers.
• Optionally include color maps for visualization and minimaps.
• Support reinitialization, cleanup, and job completion workflows.

---

🌍 Terrain Layer Types

There are four primary layer types included in the framework:

Layer Type	Purpose	Example Class
SurfaceLayer	Defines core physical terrain (height, biome, surface mesh)	HexGroundLayer
AreasLayer	Stores area/country/province indices per cell	HexCountriesLayer
CellItemsLayer	Stores static objects per cell, renderable with instancing	CellItemPropsLayer
CellEntitiesLayer	Stores a full ECS entity per cell	CellEntityPropsLayer

---

🟫 Surface Layer

Represents visible terrain features like land or water.

Key Features:

• Stores HeightMapDataLayer and CellBiomesDataLayer
• Contains a CellColorsDataLayer for visual overlays
• Linked to a HexSurfaceRenderLayer<T> for rendering

Example: HexGroundLayer

This is a simple implementation of HexSurfaceLayer for ground terrain.

[ChunkSerializable]
public partial class HexGroundLayer : HexSurfaceLayer, IComponentData { }

Render Data

Paired with HexGroundRenderLayer, which inherits HexSurfaceRenderLayer<HexGroundLayer> and handles:

• Mesh generation from data layers
• Material configs per view mode
• Dirty flag tracking and cleanup

---

🧱 Areas Layer

Used to mark cells with region identifiers, such as provinces or countries.

Example: HexCountriesLayer

public partial class HexCountriesLayer : HexByteAreasLayer, IComponentData { }

Internally uses:

• NativeListChunkedDataLayer<byte> for area indices
• CellColorsDataLayer for coloring each area

---

🧍 Cell Items Layer

Stores static renderable objects per cell using GPU instancing (Graphics.DrawMeshInstanced).

Key Components:

• CellItemDataLayer – index into a shared list of item types
• CellTransformDataLayer – transformation matrix per cell
• ItemsColorMap – overlay color per item
• RenderEntitiesConfig – defines instancing behavior
• RenderEntities – stores active render entity instances

Example: CellItemPropsLayer

public class CellItemPropsLayer : CellItemsLayer, IComponentData { }

Utility Methods:

• SetCellItem(cellIndex, item)
• SetAllCellsItem(item)
• Init(settings, copyItemConfigsFrom, renderConfig)
• Resize(newSize)
• Dispose()

Render Pipeline: Cell items are rendered based on their index and corresponding RenderEntitySettings.

---

🧬 Cell Entities Layer

Stores an entire ECS entity per cell, useful for dynamic agents, buildings, or gameplay units.

Example: CellEntityPropsLayer

[ChunkSerializable]
public class CellEntityPropsLayer : CellEntitiesLayer, IComponentData, IDisposable { }

Each cell can store:

• A reference to a full entity
• A color (via CellColorsDataLayer)
• A transform if needed

Like other layers, it implements:

• Init()
• SetAllDirty(bool)
• Cleanup(), CleanupAsync()
• CompleteAllJobs()

---

🎨 Color Maps

Every layer includes a CellColorsDataLayer or ItemsColorMap, which stores per-cell Color32 values to:

• Support terrain visual overlays
• Fill GPU textures used in terrain materials or minimaps
• Provide diagnostic feedback in the editor

To apply the color map:

public void ApplyColorsToTexture(Texture2D texture, CellColorsDataLayer colorsDataLayer)
{
	colorsDataLayer.ApplyColorsToTexture(Texture2D texture);
}

---

🔁 Lifecycle Hooks

Each TerrainLayer supports:

• Initialization (Init)
• Resizing (Resize)
• Dirty flag control (SetAllDirty(bool))
• Cleanup (Cleanup, CleanupAsync)
• Disposal (Dispose)
• Job sync (CompleteAllJobs)

These ensure safe parallel updates and smooth interoperation with Unity’s ECS and Jobs system.

---

✅ Summary

Feature	Surface	Areas	Items	Entities
Height & Biome	✅	❌	❌	❌
Area Index (byte)	❌	✅	❌	❌
Static Rendered Objects	❌	❌	✅	❌
Dynamic ECS Entities	❌	❌	❌	✅
Cell Color Map	✅	✅	✅	✅
Render Mesh Support	✅	❌	✅	❌

---