Creating Custom Operations

When a change is required to be made to the terrain, this must be done within a terrain operation. These are clearly defined methods in which modifications can be generated and applied. In order to actually execute the terrain operation for a given map, you must schedule it for that map. Terrain operations are an abstraction to define mutation of state and allow for optimizations in the internal code.

Tycoon Tile allows users to create their own operations. This section explains how this works.

ITerrainOperation

The ITerrainOperation interface is the contract that defines what a terrain operation is. In order to create your own terrain operation, you need to implement this interface.

using TycoonTerrain.Core.TerrainOperations;

public struct MyTerrainOperation : ITerrainOperation 
{
    public void ScheduleOperation(OperationContext context, ref OperationResult result)
    {
        // Implementation here..
    }
}

Note

It is recommended to make your operation a struct in order to avoid excessive garbage generation. Be careful about storing many member variables into the operation when it is a struct, as that might negate the performance benefits.

The ITerrainOperation contains a single method that is called when the operation is executed. It has two parameters: The OperationContext and the OperationResult.

OperationContext

The OperationContext allows access to the internal datastructures of Tycoon Tile. From here, you can query for tiles, tile types or water levels.

OperationResult

The OperationResult parameter is used to queue tile modifications. By queueing changes via this object, Tycoon Tile can keep track of changed tiles automatically and regenerate any meshes or notify tile listeners as necessary.

Example

This example shows how to create a terrain operation that flattens all tiles within a given tile bounds. It uses the batch overload of OperationResult.SetHeight that takes an IntBound and a height for efficiency.

using TycoonTerrain.Core.TerrainOperations;

public struct FlattenTerrainOperation : ITerrainOperation 
{
    private readonly IntBound selectionBounds;

    public FlattenTerrainOperation(IntBound bounds)
    {
        selectionBounds = bounds;
    }

    public void ScheduleOperation(OperationContext context, ref OperationResult result)
    {
        //Determine the highest and lowest point within the selected tile bounds.
        var max = context.Grid.GetTilesIn(selectionBounds).Highest();
        var min = context.Grid.GetTilesIn(selectionBounds).Lowest();

        //Determine our target height. Lets take the middle between the highest and lowest.
        var height = (max - min) / 2;

        //Apply the new height to the tiles in the selected bounds
        result.SetHeight(selectionBounds, height);
    }
}

Performance Considerations

The OperationResult allows to change tiles on a per tile basis, but it also has overload to change whole section of terrain at a time. These batch operations usually take an IntBound argument to define the tile bounds in which the changes are applied. It is recommended to prefer these batch operation overloads over the per-tile overloads whenever possible. This way, Tycoon Tile can track tile changes more quickly and with less overhead.