1. Install/Update

Install：Please download and install this package through the Package Manager. This package contains dependencies, at the following prompts, click Install / Upgrade to install the dependency packages. If you choose not to install the dependency package, please verify that the Dots-related packages (Entities, Entities Grphics, Physics) and HDRP or URP are already installed in your project.

 

Upgrade: If you already have the older version of the resource pack installed, please delete the older version of the resource file before installing it.

 

2. Project Settings。

Open Edit-> Project Settings window, find the Allow unsafe code option in the Player settings and check it.

 

3. Convert unity terrain to grid entities。

 

（1） Add a Baker script to the gameobjects in the scene

You can add a TerrainGridBaker script directly to existing terrain objects in the scene, or an TerrainGridBaker script to objects that have no terrain, and then set the value for the Terrain field in the script. After adding the script, click the "Create Terrain Setting ScriptObject" button below the Inspector, which creates the conversion texture, the material, and the ScriptObject for saving the conversion data. The generated TerrainSettingScriptObject file will be saved under the Asset / CustomerDataForTerrainGrid folder. After generation, confirm that the ScriptObject field in the script has been correctly assigned.

 

（2）Put the object of the Baker script into the subscene. Wait for the system to complete the conversion.

Note: To avoid repeatedly triggering the baking, the Bakeversion is controlled in the code.If you need to redo baking, repeat step 2 with step 1, or use "Preferences-Entities-Clear Entity Cache".

 

4.Parameter Setting

 

（1）TerrainGridBaker parameters

TerrainGridBaker script provides simple parameters to determine the overall effect of the terrain that affect the final effect of the terrain by changing the way the script generates the script setting the script resource. If more precise control is required, the values of the corresponding options for generating the script resource need to be modified.

 

TerrainData：

Terrain：Set up the terrain objects that you need to convert.You do not need to set this value if the script is added directly to the terrain object in the scene。

Script Setting: Click "Create Terrain Setting ScriptObject" below Inspector to generate the correct resource file. The incorrect assignment of this field to Baker will not yield the expected result.

MaterialType:

MaterialType：Select the terrain material type. It is recommended to choose Array or Array _ Triplanar for better operation efficiency and display effect..

MeshSetting：

MeshResolution：Set the size of the terrain grid. The terrain grid is always a square. This value also determines the number of vertices of each LOD grid. The number of vertices per edge in the grid of Lod 0 is MeshResolution + 1, while the number of vertices per edge of the Lod 1 grid is MeshResolution / 2 + 1. Note that a small MeshResolution value may causes a invalid LOD.

Collider Generation：

Collide Vert Pixel Distance：This parameter determines the number of grid vertices for the collider. When set to 1, the collider is generated pixel by pixel according to the height map data, and when set to 2, the collider generates a vertex per two pixels. Note that this small setting causes a large memory footprint and reduced runtime efficiency, but too large values ignore the details of the terrain.。

CollisionFliter：Set Unity Physics collision fliter value.

LodSetting：

Lod Distance0：Set the distance from Lod0 to Lod3

Lod Distance1：Set the distance from Lod4 to Lod7

 

（2）TerrainSettingScrptObject parameters

In most cases, the parameter values in TerrainSettingScriptObject are converted from the value of the existing Terrain, so no change is required. However, in order to keep the simplicity of the Baker parameter interface setting, the opening and closing of some function options need to directly modify the parameters in the generated TerrainSettingScriptObject.

EnablePaint: Turn on the terrain graffiti function. Not open can save the memory space of the corresponding map. This option is enabled by default.

Enable Height Blend: Open this option, and consider the influence from Mask Map height channel during layer mixing. Open this option to consider the influence from Mask Map height channel during layer mixing. When this option is enabled, the weight of all layers is compared to the layer weight with the highest value, and the layer weight with a difference higher than the Threshold Discard By Height parameter value in the material is set to 0. Note that you may need to adjust this value multiple times to achieve the desired effect. This option is not enabled by default.

 

5. Use the runtime features.

DotsGridTerrain support runtime modification of terrain height, holes, and small maps.When the height and holes of the terrain are modified, the corresponding physical components are modified synchronously.

 

（1）Modify terrain height

To modify the height of the terrain, you need to create a Entity and then attach the ModifyHeightSystem.Description component. Please do not attach this component directly to any entity that you don't want to destroy. When the system is running, all Entity s with this component are destroyed. This component needs to set 6 parameters:

Center：The float3 type.Specifies the center point where the terrain needs to be modified.

Param: float3 type, which describes the overall size and height of the modified shape. The XZ component specifies the distance from the center point, and the y component specifies the height calculated value to be modified. Y component positive raises the vertex and negative lowers the vertex.

ModifyMaskType: This is an enum that defines which vertices need to modify the height values within the rectangle range specified by the XZ component of the Param parameter. There are currently two values: Box specifies all vertices within the current rectangle, and Sphere specifies a circular range.

ModifyComputeType: This is an enum that defines how to calculate the height value for each vertex of the modified terrain. There are four ways defined: Box lifts the summit through a rectangular shape, sin uses a sinusoidal curve to lift the summit, FixedHeight sets all vertices to the same height, and Array specifies the value of each vertex through an incoming array. Note that the value effect of TextureSample is equivalent to selecting Array. There is a code example in Demo's Test script that shows how to generate the corresponding terrain modification through a single texture.

Target: The entity type. This specified Entity should be the entity of the terrain grid and must contain the TerrainSetting and TerrainGridTag components. In general, the entity can be obtained by ray detection because the terrain grid entity all have collision components. And the entity can be any grid entity of the current terrain.

AninmateTime: Realize the highly altered animation duration. Set to 0, there is no animation.

 

（2）Modify the holes

To do this, you need to create a entity and add the ModifyPaintMapSystem.Description components. Please do not attach this component directly to any entity that you don't want to destroy. When the system is running, all entity s with this component are destroyed. This component includes 4 parameters.

Center：The float3 type.Specifies the center point where the terrain needs to be modified.

Param: The float3 type. Specifies the shape size of the painting. The XZ specifies the impact distance. When the Y component value is negative, the terrain generates holes and recovers when the Y component value is greater than or equal to 0.

ModifyMaskType: This is an enum that defines which vertices need to modify the height values within the rectangle range specified by the XZ component of the Param parameter. There are currently two values: Box specifies all vertices within the current rectangle, and Sphere specifies a circular range.

Target: The entity type. This specified Entity should be the entity of the terrain grid and must contain the TerrainSetting、TerrainMaterialSetting and TerrainGridTag components. In general, the entity can be obtained by ray detection because the terrain grid entity all have collision components. And the entity can be any grid entity of the current terrain.

 

（3）Terrain graffiti

To use this feature, first make sure that the "EnablePaint" option in the Baker script is already checked, otherwise this feature is invalid.To implement graffiti on the terrain, you need to create a entity and add two components, ModifyPaintMapSystem.Description and ModifyPaintMapSystem.PaintParam.Note that when the entity has both components, the effect of the Param.y value is ignored. Please do not attach these components directly to any entity that you do not want to destroy. When the system is complete, all entity with these components are destroyed.

ModifyPaintMapSystem.Description: Refer to Article 2 for the parameters.

ModifyPaintMapSystem.PaintParam There are 3 parameters:

paintMap：Specifies the image that needs to be painted by a doodle.When using this function, please try to ensure that the pixel size of the image reasonably matches the number of vertices within the range of influence, otherwise unreasonable results will occur.

paintRange：The float4 type.This parameter specifies that that area of the copied image needs to be copied.The Xy component specifies the uv minimum of the replication region, and the wz component specifies the replication region maximum.This value works only if the paintmap is correctly assigned.

Rotation: The float3 type.Rotation angle of the copied image.

If you need to clear the graffiti, you need to create a entity and add the ModifyPaintMapSystem.Description component, while setting the Param.y to 0. When clearing the graffiti, please do not attach the ParintParam component.

 

（4）Custom build colliders

When generating terrain through a Baker script, the default generates collisions for all grids. Meanwhile, NoNeedReGenerateCollider this enableable component is used to provide a way to manually update the collision body. First, you need to filter out the entity that needs to update the collider. All terrain Entity s contain TerrainGridTag components which will help you with proper filtering. Second, set the NoNeedReGenerateCollider to false for the filtered terrain entity. This opens a job to calculate the vertex information of the collision body and replaces the current collision body after the calculation.

 

（5）Use the DotsTerrainGrid.MSG class

As a tool, the call functions of the above functions are written in the DotsTerrainGrid.MSG class.Just need to call the corresponding API in this class.The script is located under the DotTerrainGrid / Scripts / Tool folder.Functions with different parameters of the same name apply to MonoBehaviour and to various scenarios of system under Dots.