terrain-workflows.md 17 KB
Terrain Workflow Tests
Testing in this area revolves around the construction of Terrain surfaces, applying materials and vegetation to the terrain, and ensuring proper physics reactions with terrain. Workflows in this area will lead into each other, ultimately resulting in a saved level with physicalized terrain defined by heightmap with macro and detail materials applied.
Project Requirements
AutomatedTesting project, or another project with Terrain/PhysX Gems enabled.
Common Issues to Watch For
Test guidance will sometimes note specific issues to watch for. The common issues below should be watched for through all testing, even if unrelated to the current workflow being tested.
- Console log errors/warnings/spam
- Asserts
Workflow 1: Constructing terrain
User-facing Documentation:
https://o3de.org/docs/user-guide/gems/reference/environment/terrain/
https://o3de.org/docs/user-guide/components/reference/terrain/layer_spawner/
https://o3de.org/docs/user-guide/components/reference/terrain/terrain_height_gradient_list/
Product: Saved level with basic terrain
Suggested Time Box: 20-30 mins
| Workflow | Requests | Things to Watch For |
|---|---|---|
| Define the area for Terrain to be spawnable in | * Add the Terrain level components: * Terrain World * Terrain World Renderer * Terrain World Debugger * Adjust Min Bounds * Adjust Max Bounds * Adjust Height Query Resolution * Toggle Terrain World Debugger display options * Adjust the Rendered world size on the World Renderer (WIP - Currently defaults to 1km) |
* Rendering issues with base World plane * Rendering issues with Terrain World Debugger |
| Define a spawner area | * Add the required Terrain components: * Terrain Layer Spawner * Terrain Height Gradient List * Axis Aligned Box Shape * Setup a new Gradient generator (or several) entity to serve as a heightmap: * Image Gradient component * Shape component to define Gradient area (e.g. Shape Reference pinned to Spawner) * Gradient Transform Modifier * Assign the heightmap gradient(s) to the spawner: * Terrain Height Gradient List |
* Crash when translating generated terrain near edges of Terrain Spawner plane |
| Define additional spawner areas | * Resize defined spawner areas as needed to fit additional spawner areas * Overlap/arrange terrain spawner areas, defining Layer and Sub Priorities as needed to create an interesting look |
* Rendering artifacts * Seams where spawner areas meet * Priority issues |
| Adjust Continuous LOD | * In the Terrain World Renderer: * Toggle on Continuous LOD (CLOD) * Adjust the following: * First LOD distance * CLOD Distance |
|
| Adjust Clipmap configuration | * In the Terrain World Renderer: * Toggle on Clipmap Enabled * Adjust the following: * Clipmap image size * Macro clipmap max resolution: texels/m * Detail clipmap max resolution: texels/m * Macro clipmap scale base * Detail clipmap scale base * Macro clipmap margin size: texels * Detail clipmap margin size: texels |
* Crash when quickly adjusting settings * Rendering issues with terrain in viewport |
| Save Level/Spawners as Prefabs |
Workflow 2: Generating Terrain surfaces
User-facing Documentation:
Product: Saved level with terrain spawners configured to generate surfaces
Suggested Time Box: 15-20 mins
| Workflow | Requests | Things to Watch For |
|---|---|---|
| Define the gradient for a surface area | * Setup a new Gradient generator (or several) entity to serve as a heightmap: * Image Gradient * Shape component to define Gradient area (e.g. Shape Reference component pinned to Spawner) * Gradient Transform Modifier |
|
| Map configured gradients to surface tags | * Add the required component to a Terrain Layer Spawner: * Terrain Surface Gradient List * Add configured gradients, and assign a surface tag |
|
| Adjust terrain surfaces | * Adjust Surface Data Query Resolution in the Terrain World component | |
| Save Level/Spawners as Prefabs |
Workflow 3: Applying Materials to Terrain
User-facing Documentation:
Product: Saved level with terrain with a macro material and detail materials
Suggested Time Box: 15-20 mins
| Workflow | Requests | Things to Watch For |
|---|---|---|
| Create a Macro Material | * Add required component to the Terrain Layer Spawner: * Terrain Macro Material * Configure the parameters to generate a Macro Material: * Color Texture * Normal Texture * Flip/Adjust normals as desired |
* Rendering issues (texture stretching, missing color data, etc.) |
| Assign Detail Materials | * Add required components: * Terrain Surface Materials List * Add elements, and assign a configured tag * Specify Material Asset to map to the assigned tag |
|
| Adjust Detail Materials | * Utilize various texture blend modes * Toggle Height based texture blending in the Terrain World Renderer * Adjust detail rendering controls in the Terrain World Renderer |
|
| Save Level/Spawners as Prefabs |
Workflow 4: Physicalized Terrain
User-facing Documentation:
https://o3de.org/docs/user-guide/components/reference/physx/collider/
Product: Saved level with terrain with a macro material and detail materials that reacts to physics objects
Suggested Time Box: 15-20 mins
| Workflow | Requests | Things to Watch For |
|---|---|---|
| Define a physicalized area | * Add required components to a Terrain Layer Spawner: * Terrain Physics Heightfield Collider * PhysX Heightfield Collider |
|
| Define a physicalized terrain using a physics material | * Select a Default Surface Physics Material for the entire terrain within the Terrain Physics Heightfield Collider | * Physics material mapping not working correctly |
| Verify Terrain collision with physics objects | * Instantiate a collider prefab or create a new PhysX Rigid Body collider setup (see https://o3de.org/docs/user-guide/components/reference/physx/collider/) * Position the prefab on/above the physicalized terrain * Enter/Exit Game Mode * Enter/Exit Simulate Mode |
|
| Save Level/Spawners as Prefabs | ||
| Open the level in ProjectName.GameLauncher.exe | * Missing or inconsistent data (textures, heightmap, detail materials, etc.) * Excessive load times * Large Frame Rate disparity vs Game Mode in Editor |
Workflow 5: Large Terrain Support
Product: Saved level with terrain spawners configured to generate surfaces
Suggested Time Box: 5-10 mins
| Workflow | Requests | Things to Watch For |
|---|---|---|
| Define a larger terrain area | * Proportionally increase the size of your Terrain Spawner's Shape component to the following dimensions (X,Y,Z): 32 km x 32 km x ? * In the Terrain World Renderer:
* Increase the Camera component's Far clip distance to match, or exceed, the Terrain Spawner Shape component | * Rendering issues (texture stretching, missing color data, etc.) |