Hex Map 2.2.0

Visibility Transitions

Add a boolean array to HexCellShaderData to track the visibility transitions and initialize it in the Initialize method.

	bool[] visibilityTransitions;

	…
	
	public void Initialize (int x, int z) {
		…

		if (cellTextureData == null || cellTextureData.Length != x * z) {
			cellTextureData = new Color32[x * z];
			visibilityTransitions = new bool[x * z];
		}
		else {
			for (int i = 0; i < cellTextureData.Length; i++) {
				cellTextureData[i] = new Color32(0, 0, 0, 0);
				visibilityTransitions[i] = false;
			}
		}

		transitioningCells.Clear();
		enabled = true;
	}

Make RefreshVisiblity use that array instead of checking and setting the B channel to 255. Make UpdateCell use the array as well.

	public void RefreshVisibility (HexCell cell) {
		…
		//else if (cellTextureData[index].b != 255) {
		//	cellTextureData[index].b = 255;
		else if (!visibilityTransitions[index]) {
			visibilityTransitions[index] = true;
			transitioningCells.Add(cell);
		}
		enabled = true;
	}

	…

	bool UpdateCellData (HexCell cell, int delta) {
		…

		if (!stillUpdating) {
			//data.b = 0;
			visibilityTransitions[index] = false;
		}
		cellTextureData[index] = data;
		return stillUpdating;
	}

There is also a SetMapData method, which is currently unused but was and can be used to send debug data to the shader. It was limited 254 because of the transition indication, but can now use the full by range.

			data < 0f ? (byte)0 : (data < 1f ? (byte)(data * 255f) : (byte)255);

Water Surface

Now that we have the B channel available we'll use it to send the water height of cells to the shader. Make RefreshTerrain set it. If the cell is underwater then grab its WaterSurfaceY and store it in the B channel so it can support a water level up to 30 units high. If the cell is not underwater then set it to zero.

Supports water surfaces up to 30 units high.

	public void RefreshTerrain (HexCell cell) {
		//cellTextureData[cell.Index] = (byte)cell.TerrainTypeIndex;
		Color32 data = cellTextureData[cell.Index];
		data.b = cell.IsUnderwater ? (byte)(cell.WaterSurfaceY * (255f / 30f)) : (byte)0;
		data.a = (byte)cell.TerrainTypeIndex;
		cellTextureData[cell.Index] = data;
		enabled = true;
	}

We also need to update this data when the view elevation of a cells is changed, so give ViewElevationChanged a cell parameter and also set the water level there.

	public void ViewElevationChanged (HexCell cell) {
		cellTextureData[cell.Index].b = cell.IsUnderwater ?
			(byte)(cell.WaterSurfaceY * (255f / 30f)) : (byte)0;
		needsVisibilityReset = true;
		enabled = true;
	}

Adjust the Elevation and WaterLevel properties of HexCell so they provide the new argument. Also, simply always invoke ViewElevationChanged instead of checking whether there was a change to make sure that the water level is always set correctly.

	public int Elevation {
		get => elevation;
		set {
			…
			//if (ViewElevation != originalViewElevation) {
			//	ShaderData.ViewElevationChanged();
			//}
			ShaderData.ViewElevationChanged(this);
			…
		}
	}

	public int WaterLevel {
		get => waterLevel;
		set {
			…
			//if (ViewElevation != originalViewElevation) {
			//	ShaderData.ViewElevationChanged();
			//}
			ShaderData.ViewElevationChanged(this);
			…
		}
	}

We should now also delay invoking RefreshTerrain until all required cell data has been retrieved in Load, so let's move it to the end of the method.

	public void Load (BinaryReader reader, int header) {
		terrainTypeIndex = reader.ReadByte();
		//ShaderData.RefreshTerrain(this);
		…

		IsExplored = header >= 3 ? reader.ReadBoolean() : false;
		ShaderData.RefreshTerrain(this);
		ShaderData.RefreshVisibility(this);
	}

Submergence Visualized

We can now used the cell's water surface level to colorize it based on its submergence, to add more visual depth to underwater areas. We need to make some changes to the Terrain HLSL code to do this. First, we have to pass the water data to the fragment program via a custom interpolator. We use the existing Terrain output of GetVertexCellData_float for this, changing it to a 4D vector, filling its W component with the highest water level of the retrieved cells, scaled up to cover the 30-unit range.

void GetVertexCellData_float (
	…
	out float4 Terrain,
	…
) {
	…
	Terrain.z = cell2.w;
	Terrain.w = max(max(cell0.b, cell1.b), cell2.b) * 30.0;

	…
}

Create a ColorizeSubmergence function that applies a blue color filter to a base color. It also needs to know the surface and water Y coordinates for that. Apply the filter (0.25, 0.25, 0.75) to the color and fade it in based on submergence depth, over a 15-unit range.

float3 ColorizeSubmergence (float3 baseColor, float surfaceY, float waterY) {
	float submergence = waterY - max(surfaceY, 0);
	float3 colorFilter = float3(0.25, 0.25, 0.75);
	float filterRange = 1.0 / 15.0;
	return baseColor * lerp(1.0, colorFilter, saturate(submergence * filterRange));
}

Use that function to adjust the base color after retrieving the cell color, based on the new terrain data.

void GetFragmentData_float (
	…
	float4 Terrain,
	…
) {
	float4 c = …;

	BaseColor = ColorizeSubmergence(c.rgb, WorldPosition.y, Terrain.w);

	…
	
	//BaseColor = c.rgb * grid.rgb;
	BaseColor *= grid.rgb;
	Exploration = Visibility.w;
}

Change GetTerrainColor so it can keep working with the terrain as a 4D vector. I also renamed its Color€ parameter to Weights to make its use clearer.

float4 GetTerrainColor (
	…
	float4 Terrain,
	float3 Weights,
	…
) {
	…
	return c * (Weights[index] * Visibility[index]);
}

To make this work adjust the Terrain shader graph to use a 4D vector for the custom Terrain interpolator.

Hex Space

We begin by introducing the concept of hex space. This is the same as the world space XZ plane, but scaled such that the distance between cell centers of east-west neighbors is one unit. We can convert from world to hex space via a division by twice the outer hex radius scaled by the outer-to-inner radius factor. Add a function for this conversion named WorldToHexSpace to HexMetrics.hlsl.

float2 WoldToHexSpace (float2 p) {
	return p * (1.0 / (2.0 * OUTER_RADIUS * OUTER_TO_INNER));
}

Include the metrics at the top of HexCellData.hlsl.

#include "HexMetrics.hlsl"

To prevent duplicate inclusion remove the explicit metrics inclusion from Terrain.hlsl and Water.hlsl.

//#include "HexMetrics.hlsl"

Then move the inclusion of water until after the hex cell data in CustomFunctions.hlsl.

//#include "Water.hlsl"
#include "HexCellData.hlsl"
#include "Water.hlsl"

Hex Grid Data

To make working with hex grid data convenient add a HexGridData struct type to HexCellData.hlsl. Give it a cell center, cell offset coordinates—which will be approximate but good enough for sampling the cell data—cell UV coordinates for potential future use, the hex distance from cell edge to center, and a distance smoothing value used for smoothing lines.

float4 GetCellData (float2 cellDataCoordinates, bool editMode) { … }

struct HexGridData {
	// Cell center in hex space.
	float2 cellCenter;

	// Approximate cell offset coordinates. Good enough for point-filtered sampling.
	float2 cellOffsetCoordinates;

	// For potential future use. U covers entire cell, V wraps a bit.
	float2 cellUV;

	// Hexagonal distance to cell center, 0 at center, 1 at edges.
	float distanceToCenter;

	// Smoothstep smoothing for cell center distance transitions.
	// Based on screen-space derivatives.
	float distanceSmoothing;
};

To create anti-aliased lines based on this data we introduce three smoothstep functions, which we add as members to HexGridData. The first is Smoothstep01. It has a threshold parameter that it uses to step from 0 to 1 based on the hex distance to center, smoothed by the distance smoothing range in both directions. The second is Smoothstep10 which does the same but in the other direction. The third is SmoothstepRange which steps from 0 to 1 and back to 0 given an inner and outer threshold.

struct HexGridData {
	…

	// Smoothstep from 0 to 1 at cell center distance threshold.
	float Smoothstep01 (float threshold) {
		return smoothstep(
			threshold - distanceSmoothing,
			threshold + distanceSmoothing,
			distanceToCenter
		);
	}

	// Smoothstep from 1 to 0 at cell center distance threshold.
	float Smoothstep10 (float threshold) {
		return smoothstep(
			threshold + distanceSmoothing,
			threshold - distanceSmoothing,
			distanceToCenter
		);
	}

	// Smoothstep from 0 to 1 inside cell center distance range.
	float SmoothstepRange (float innerThreshold, float outerThreshold) {
		return Smoothstep01(innerThreshold) * Smoothstep10(outerThreshold);
	}
};

From Position to Cell

To find the grid data we need to know the hexagonal distance from its center to its closest edge. Create an HexagonalCenterToEdgeDistance function for this that converts a position in hex space to this distance, assuming that the cell's center is at the origin. As hexagons are symmetrical in both dimension we can reduce the problem space to only the positive quadrant by taking the absolute of the given position. Then we find the distance to its angled edge by taking the dot product of the position and the normalized hex angled edge vector. This vector points in the NE direction and is (1, √3) to reach the neighbor two steps away.

To also take the vertical edge into account take the maximum of the result and the X coordinate. As this is in hex space the maximum distance from center to edge is ½, so we double it to get the desired 0–1 range.

#define HEX_ANGLED_EDGE_VECTOR float2(1, sqrt(3))

// Calculate hexagonal center-edge distance for point relative to center in hex space.
// 0 at cell center and 1 at edges.
float HexagonalCenterToEdgeDistance (float2 p) {
	// Reduce problem to one quadrant.
	p = abs(p);
	// Calculate distance to angled edge.
	float d = dot(p, normalize(HEX_ANGLED_EDGE_VECTOR));
	// Incorporate distance to vertical edge.
	d = max(d, p.x);
	// Double to increase range from center to edge to 0-1.
	return 2 * d;
}

To find the nearest cell center to a point in hex space we add a HexModulo function. It does this by subtracting the hex angled edge vector scaled by the floor of the position divided by the same vector.

// Calculate hex-based modulo to find position vector.
float2 HexModulo (float2 p) {
	return p - HEX_ANGLED_EDGE_VECTOR * floor(p / HEX_ANGLED_EDGE_VECTOR);
}

To get the final hex grid data introduce a GetHexGridData function with a world XZ position parameter, which it converts to hex space. Then there are two candidates for the closest cell position. The first is found by taking the hex modulo of the position. The second is found the same way, except that it is offset by one cell diagonally by subtracting half the hex angled edge vector before taking the modulo. Then the same offset is subtracted from both to align them with our grid. These are vectors from the cell centers to the hex position. Whichever is smallest is the one we need.

// Get hex grid data analytically derived from world-space XZ position.
HexGridData GetHexGridData (float2 worldPositionXZ) {
	float2 p = WoldToHexSpace(worldPositionXZ);
	
	// Vectors from nearest two cell centers to position.
	float2 gridOffset = HEX_ANGLED_EDGE_VECTOR * 0.5;
	float2 a€ = HexModulo(p) - gridOffset;
	float2 b€ = HexModulo(p - gridOffset) - gridOffset;
	bool aIsNearest = dot(a€, a€) < dot(b€, b€);

	float2 vectorFromCenterToPosition = aIsNearest ? a€ : b€;

	HexGridData d;
	return d;
}

Now we can fill the grid data. The cell center is found by subtracting the vector that we found from the hex position.

The cell offset X coordinate is the cell center X, offset by −½ if the first cell candidate ended up being closest, so it matches the zigzag offset of the rows. The cell offset Y coordinate is the cell center Y divided by the outer-to-inner radius factor. These offset coordinates are not exact, but good enough for our purposes.

The cell UV coordinates are the same as the found vector, plus ½ to align it with the cell center. We currently don't use this but could be used to texture the cells.

The distance to center is found by passing the vector through HexagonalCenterToEdgeDistance.

For the distance smoothing we use the fwidth of the distance to center to make the transition roughly two pixels wide.

	HexGridData d;
	d.cellCenter = p - vectorFromCenterToPosition;
	d.cellOffsetCoordinates.x = d.cellCenter.x - (aIsNearest ? 0.5 : 0.0);
	d.cellOffsetCoordinates.y = d.cellCenter.y / OUTER_TO_INNER;
	d.cellUV = vectorFromCenterToPosition + 0.5;
	d.distanceToCenter = HexagonalCenterToEdgeDistance(vectorFromCenterToPosition);
	d.distanceSmoothing = fwidth(d.distanceToCenter);
	return d;

Sharp Grid Lines

To create sharp analytical grid lines add an ApplyGrid function to Terrain.hlsl with parameters for a base color and hex grid data. Reduce the color to 20% by using SmoothStep10 with 0.965 as the threshold.

// Apply an 80% darkening grid outline at hex center distance 0.965-1.
float3 ApplyGrid (float3 baseColor, HexGridData h) {
	return baseColor * (0.2 + 0.8 * h.Smoothstep10(0.965));
}

Remove the GridTexture parameter from GetFragmentData_float and make it use the new function to show the grid.

void GetFragmentData_float (
	…
	//UnityTexture2D GridTexture,
	…
) {
	…

	//float4 grid = 1;
	HexGridData hgd = GetHexGridData(WorldPosition.xz);

	if (ShowGrid) {
		//float2 gridUV = WorldPosition.xz;
		//gridUV.x *= 1 / (4 * 8.66025404);
		//gridUV.y *= 1 / (2 * 15.0);
		//grid = GridTexture.Sample(GridTexture.samplerstate, gridUV);
		BaseColor = ApplyGrid(BaseColor, hgd);
	}

	…
	
	//BaseColor *= grid.rgb;
	Exploration = Visibility.w;
}

Also remove the texture from the Terrain shader graph and delete the Grid texture asset.

Feature Visibility

We can also use the new hex grid data in the vertex function of Feature.hlsl to find the cell offset coordinates, removing its GridCoordinatesTexture parameter.

void GetVertexCellData_float (
	//UnityTexture2D GridCoordinatesTexture,
	…
) {
	//float2 gridUV = WorldPosition.xz;
	//gridUV.x *= 1 / (4 * 8.66025404);
	//gridUV.y *= 1 / (2 * 15.0);
	//float2 cellDataCoordinates = floor(gridUV.xy) + GridCoordinatesTexture.SampleLevel(
	//	GridCoordinatesTexture.samplerstate, gridUV, 0
	//).rg;
	//cellDataCoordinates *= 2;
	HexGridData hgd = GetHexGridData(WorldPosition.xz);
	float4 cellData = GetCellData(hgd.cellOffsetCoordinates, EditMode);

	…
}

Also remove the texture from the Feature shader graph and delete the Grid Coordinates texture asset. Besides no longer needing the texture this also fixes some visibility artifacts caused by incorrect offset interpretations very close to some cell edges.

Cell Highlighting Data

To know which cells are affected we have to send some highlighting data to the GPU. At minimum we'll need the brush center XZ coordinates in hex space. Add properties to retrieve these coordinates to HexCoordinates.

	public float HexX => X + Z / 2 + ((Z & 1) == 0 ? 0f : 0.5f);

	public float HexZ => Z * HexMetrics.outerToInner;

We'll make HexMapEditor communicate the highlighing data to the shader by setting a global 4D vector shader property named _CellHighlighting. Its XY components contain the hex coordinates, its Z component contains the squared brush size plus ½, and its W component contains the wrap size, in case a wrapping map is used. Set this data in a new UpdateCellHighlightData method with a cell parameter. If the cell is null instead clear the data, via a separate ClearCellHighlightData method that set the vector to (0, 0, −1, 0).

	static int cellHighlightingId = Shader.PropertyToID("_CellHighlighting");
	
	…
	
	void UpdateCellHighlightData (HexCell cell) {
		if (cell == null) {
			ClearCellHighlightData();
			return;
		}

		// Works up to brush size 6.
		Shader.SetGlobalVector(
			cellHighlightingId,
			new Vector4(
				cell.Coordinates.HexX,
				cell.Coordinates.HexZ,
				brushSize * brushSize + 0.5f,
				HexMetrics.wrapSize
			)
		);
	}

	void ClearCellHighlightData () =>
		Shader.SetGlobalVector(cellHighlightingId, new Vector4(0f, 0f, -1f, 0f));

In Update, if the cursor is not claimed by the UI and the primary mouse button isn't pressed, invoke UpdateCellHighlightingData with the cell currently under the cursor. If the cursor is claimed by the UI invoke ClearHighlightData. Also invoke UpdateCellHighlightData with the current cell at the end of HandleInput.

	void Update () {
		if (!EventSystem.current.IsPointerOverGameObject()) {
			if (Input.GetMouseButton(0)) {
				HandleInput();
				return;
			}
			else {
				// Potential optimization: only do this if camera or cursor has changed.
				UpdateCellHighlightData(GetCellUnderCursor());
			}
			…
		}
		else {
			ClearCellHighlightData();
		}
		previousCell = null;
	}
	
	…
	
	void HandleInput () {
		…
		UpdateCellHighlightData(currentCell);
	}

Showing Highlighted Cells

To check whether a cell is highlighted in the shader add an IsHighlighted function to HexGridData in HexCellData.hlsl. The relative positive-quadrant position of the cell to highlight is found by taking the absolute of the highlighting hex coordinates minus the cell center.

Then in case world wrapping is enabled check whether the X position exceeds half the wrap size and if so wrap once. We can do this also when wrapping is disabled because in that case the wrap size is zero.

The cell should be highlighted if the square magnitude of the relative position vector is less than the highlighting Z component, which is the squared edit radius plus ½. This simple circular threshold check works up to brush size 6. This is acceptable because our largest brush size is only 4.

	// Is highlighed if square distance from cell to highlight center is below threshold.
	// Works up to brush size 6.
	bool IsHighlighted () {
		float2 cellToHighlight = abs(_CellHighlighting.xy - cellCenter);

		// Adjust for world X wrapping if needed.
		if (cellToHighlight.x > _CellHighlighting.w * 0.5) {
			cellToHighlight.x -= _CellHighlighting.w;
		}

		return dot(cellToHighlight, cellToHighlight) < _CellHighlighting.z;
	}

We apply the highlight in Terrain.hlsl by adding a new ApplyHighlight function with parameters for a base color and hex grid data. The highlight is made by drawing a white hexagon outline by using SmoothstepRange with thresholds 0.68 and 0.8.

// Apply a white outline at hex center distance 0.68-0.8.
float3 ApplyHighlight (float3 baseColor, HexGridData h) {
	return saturate(h.SmoothstepRange(0.68, 0.8) + baseColor.rgb);
}

Apply the highlight if needed after showing the grid in GetFragmentData_float.

	if (ShowGrid) {
		BaseColor = ApplyGrid(BaseColor, hgd);
	}

	if (hgd.IsHighlighted()) {
		BaseColor = ApplyHighlight(BaseColor, hgd);
	}

The next tutorial is Hex Map 2.3.0.