Skip to content

Home

Jump to bottom
j.vinet.ext edited this page Jul 2, 2026 · 11 revisions

Landscape Displacement Collision - User Guide

Welcome to the documentation for the Landscape Displacement Collision plugin! This guide will walk you through the setup process to get pixel-perfect, dynamic physical collisions for your Nanite-tessellated Displacement Maps.

📋 Table of Contents

  1. Plugin Installation
  2. RVT & Material Setup (Crucial)
  3. Level Setup (Manager & Precompute Zones)
  4. Project Settings
  5. Actor Setup (The Tracker Component)
  6. Blueprint API Reference
  7. Troubleshooting & FAQ
  8. Under the Hood (Pipeline Basics)

1. Plugin Installation

  1. Install the plugin via the Epic Games Launcher (Fab) into your Unreal Engine version.
  2. Launch your Unreal Engine project.
  3. Go to Edit > Plugins, search for Landscape Displacement Collision, and check the box to enable it.
  4. Restart the editor.

2. RVT & Material Setup (Crucial)

To extract height data from your landscape, the plugin relies on Unreal Engine's Runtime Virtual Textures (RVT). Your Landscape Material must be configured to write to these textures. (For a complete overview of RVTs, refer to the Official Unreal Engine RVT Documentation).

Step 2.1: Create RVT Assets

Create Virtual Texture assets in your Content Browser (Right Click > Textures > Runtime Virtual Texture). In addition to your standard visual landscape RVT (used for Base Color, Roughness, and Normal), create the dedicated collision RVTs required by our plugin:

  • RVT_Landscape (Your standard visual Virtual Texture for terrain shading)
  • RVT_Height (Used by the plugin for base landscape height)
  • RVT_Displacement (Used by the plugin for tessellation displacement data)
  • RVT_Mask (Optional, used if you want to mask out collision in certain areas)

Step 2.2: Update the Landscape Material

Open your Landscape Material (the one generating the Nanite Tessellation) and add a Runtime Virtual Texture Output node.

  1. Plug the World Position Z (or Absolute World Position -> Mask B) into the WorldHeight input.
  2. Plug your final Displacement Map/Logic into the WorldDisplacement input.
  3. (Optional) Plug your Mask logic into the Mask input. (Ensure your standard RVT_Landscape visual output is also properly plugged in for your terrain shading).

Material RVT Output Node

Step 2.3: Configure the Landscape Actor

  1. Select your Landscape in the outliner.
  2. In the Details Panel, find the Virtual Textures array under the Virtual Texture category.
  3. Add all of your created RVTs (RVT_Landscape, RVT_Height, RVT_Displacement, and RVT_Mask if used) to this array so the landscape renders to both visual and collision textures.

Landscape Draw Virtual Textures

Step 2.4: Place RVT Volumes

  1. Drag and drop Runtime Virtual Texture Volume actors into your level for each of the RVTs created in Step 2.1 (one for your visual RVT_Landscape, and one for each collision RVT: RVT_Height, RVT_Displacement, etc.).
  2. Assign the respective RVT asset to each volume.
  3. Select each volume and your Landscape, then click Set Bounds (or Copy Bounds) on the volumes so they perfectly cover the entire terrain extent.

3. Level Setup (Manager)

  1. In the Place Actors panel, search for Landscape Collision Manager and drag it into your level.
  2. In its Details Panel, assign the RVT Volumes you placed in Step 2.4.
  3. Important: Assign your Landscape Material to the Manager so it can automatically read the Max Displacement and Displacement Center magnitudes. Alternatively, you can check Override Material Settings and type these values manually.
  4. If you assigned a RVT_Mask in Step 2, you can configure the Mask Channel (R, G, B, or A) and toggle Invert Mask depending on your logic (0 = full collision, 1 = no collision).
  5. (Optional) Check Enable Update in Editor if you want to preview the collision generation in the viewport without pressing Play.
  6. (Optional) You can check Override Max Deferred Updates to set a specific Max Deferred Updates Per Frame for this level instead of using the global Project Settings.

Landscape Collision Manager Settings

3.1 Static Collision (Precompute Zones)

If your game requires a static physical ground (for example, a racing track or a small arena) rather than dynamic vehicle tracking, you can use the Landscape Collision Precompute Zone actor.

  1. Drag a Landscape Collision Precompute Zone into the level.
  2. Scale its Zone Extent to cover your desired area.
  3. In its Details Panel, configure the chunk settings:

Landscape Collision Precompute Zone

Property Description
Chunk Size & Resolution The system will automatically chunk the area and compute the exact vertex density required!
Overlap Padding Shrinks the culling extent slightly so dynamic collision meshes overlap the precomputed zone border, preventing seams.
Pixel Multiplier Adjusts the RVT sampling texture resolution per chunk.
Collision Profile Name The preset applied to the static ground (default is LandscapeDisplacement).
Collision Mesh Class Override this if you have a custom ULandscapeCollisionMesh child class.
Override Physical Materials If checked, overrides the global Physical Material extraction setting for this zone.
Enable Physical Materials If override is checked, determines if this zone extracts physical materials from the landscape.
Show Collision Mesh In Editor Toggle the visibility of the generated meshes in the editor viewport.
Max Chunk Count Safety limit for the total number of collision chunks allowed in this zone (default: 1024). Prevents accidental memory spikes or editor freezes if the zone is scaled excessively. If exceeded, the system automatically clamps grid counts and scales up individual chunk dimensions to maintain 100% gapless coverage without crashing.
Max Extractions Per Frame Limit the number of GPU extraction requests sent per frame to prevent stalling the RVT.
Max Mesh Updates Per Frame Limit the number of CPU physics meshes built per frame to prevent editor freezes (keep low, e.g., 1-2).
  1. Smart Time-Slicing & Adaptive Performance: The generation is highly optimized and asynchronous. Instead of freezing your game to build a massive collision area, the zone spreads the chunk generation across multiple frames, dynamically adapting its workload based on your framerate (Adaptive Limits). If your area is too large for the configured Chunk Size, the safety limit (Max Chunk Count) seamlessly scales chunks to preserve performance and prevent VRAM exhaustion.
  2. Movement Filtering: Once generated, the zone monitors the world. It will only recalculate chunks whose bounding boxes have actually moved or been affected, completely eliminating redundant CPU processing.
  3. (Optional) You can type p.LandscapeCollision.Debug 1 in the console while in-game to visualize the generated meshes.

4. Project Settings

You can configure global fallback rules and performance budgets for your entire game. Go to Edit > Project Settings, scroll down to the Game section, and select Landscape Collision.

Project Settings

Category Property Description
Performance Max Deferred Updates Per Frame The maximum number of vehicles allowed to rebuild their physics mesh in a single frame. Lower values protect your FPS, higher values make collision more instantly responsive.
Collision Fade Duration Time in seconds for the physics mesh to smoothly blend up/down to match the ground. Prevents vehicles from violently launching into the air.
Default Physics Default Collision Profile The collision preset (e.g., BlockAll, Vehicle) applied to the generated ground mesh.
Enable Physical Materials By default, the system reads Physical Materials from the Landscape and applies them to the collision mesh (allowing tire sounds/dust to work).
Optimization Default Optimization Rules Fallback settings for Culling (Screen Size, Max Tracking Height), Update Thresholds, Virtual Texture Settings, and Grid Settings.
Auto Registration Auto Registration If enabled (default: true), the system automatically detects and registers actors without needing a Tracker component. Perfect for instant Plug & Play!
Auto Register Classes Explicit list of classes to always register (default includes APawn, ensuring characters and vehicles work instantly without components).
Auto Register Simulating Physics If true (default: true), catches any actor simulating physics on its root component.
Auto Register Exclude Classes Use this to filter out noise or debug cameras from the physics sweep (default excludes ASpectatorPawn and ADefaultPawn).
Extensibility Collision Engine Class The main pipeline orchestrator class.
Collision Culler Class Custom visibility and frustum culling behavior.
Collision Mesh Class Custom dynamic collision mesh generated under actors.
Scheduler Class The CPU update scheduler logic.
RVT Processor Class The GPU extraction processor.

5. Actor Setup (The Tracker Component)

By default, characters (APawn) and physics-simulating bodies are automatically registered via the plugin's Plug & Play Auto-Registration settings without needing any additional components!

However, if you want to explicitly register an actor, or override the default fallback settings for an actor that is already auto-registered (such as assigning a custom collision profile, enabling velocity prediction for fast sports cars, or overriding optimization/culling rules), add the Landscape Collision Tracker component (ULandscapeCollisionTracker) to its Blueprint.

When a Tracker component is attached to an actor, the Subsystem automatically prioritizes its custom Collision Params and override rules instead of the global Project Settings defaults.

In the Tracker's Details Panel, you will find the Collision Params structure. This gives you granular control over how the collision is generated for this specific actor:

Landscape Collision Tracker Details

Pipeline Settings

Property Description
Start Tracking Enabled Should the collision start generating immediately upon spawning?
Update Priority Deferred respects the Project Settings frame budget (best for traffic/NPCs). Immediate forces generation immediately (best for the player's main vehicle).
Enable World Aligned If true, the generated grid stays locked to North/South instead of rotating with the vehicle.

Grid Settings

Property Description
Resolution Number of subdivisions (e.g., 16x16, 32x32). Higher is more precise but costs more CPU to cook the physics.
Override Size If false, it operates in Auto Mode. The system continuously and dynamically calculates the grid size during gameplay based on the Actor's Axis-Aligned Bounding Box (AABB) + Auto Margin.
Auto Calculate Resolution If enabled, you specify a single Max Resolution (e.g., 16). The system calculates the object's physical dimensions and automatically reduces the resolution on the shorter axis to maintain perfectly square RVT sampling pixels.
Pixel Multiplier How many RVT pixels are sampled per grid square. Higher values capture sharper details before smoothing them into the physical grid.

Prediction & Collision

Property Description
Enable Prediction Uses the vehicle's velocity to spawn the grid ahead of the vehicle, ensuring fast-moving cars never "outrun" their collision floor.
Override Collision Allows you to set a custom Collision Profile just for this vehicle's ground mesh.

Optimization Overrides

If checked, you can override the global Project Settings locally:

Property Description
bOverrideGlobalGrid Override the global default grid dimensions and resolutions for this specific actor.
bOverrideGlobalCulling Change Min Required Screen Size (to cull small distant vehicles) or Max Tracking Height (to stop tracking when planes fly high into the air).
bOverrideGlobalThresholds Dictates how far the actor must move before the grid snaps to the new location.
bOverrideGlobalRVT Override the virtual texture preloading behaviors for this actor.
bOverridePhysicalMaterials Allows you to individually enable or disable Physical Material mapping for this specific actor to save performance.

6. Blueprint API Reference

Global Management (Subsystem)

Access these nodes by searching for the Landscape Collision Subsystem.

  • Set Global System Enabled: Completely pauses or resumes the collision engine. Pass Clear Existing Collisions = True to instantly destroy all active meshes (useful during cutscenes or fast-travel).
  • Update Virtual Texture Volumes: Dynamically swap the targeted RVT volumes at runtime. Essential for World Partition games when streaming different biomes.
  • Update Global Culling Settings: Change the culling aggression dynamically from your game's Graphics Settings menu.
  • Set Physical Materials Enabled: Dynamically enable or disable the extraction and mapping of Physical Materials for a specific actor at runtime (great for optimizing distant traffic).
  • Set Max Deferred Updates Per Frame: Dynamically adjust the CPU physics budget (e.g. increase it during a pause menu or reduce it during heavy combat).
  • Purge Physical Material Cache: Clears the CPU memory cache of physical materials.
  • Get Registered Actors Count / Get Active Calculating Actors Count: Excellent for profiling! See exactly how many vehicles are registered vs how many are currently actively consuming CPU/GPU calculations.
  • Get Registered Actors / Get Active Calculating Actors: Returns arrays of actors. Useful if you want to loop through active vehicles and draw a debug HUD over them.

Actor Diagnostics (Function Library)

Drag a wire directly from your Actor or right-click anywhere to access these static nodes:

  • Get Landscape Collision Host Actor: Returns the global ALandscapeCollisionHost actor in the level that owns all dynamic ground collision meshes. Crucial: Pass this actor directly into your LineTrace's IgnoreActor or IgnoreActors array to instantly ignore all procedural ground collision across your entire game in one single node!
  • Get Actor Collision Mesh Component: Returns the dynamically generated ULandscapeCollisionMesh for a specific actor. You can plug this into the Ignore Component array of your custom LineTraces if you only want to ignore a specific vehicle's ground mesh.
  • Is Actor Collision Tracked / Active: Check if the system is currently managing this actor.
  • Get Actor Collision Telemetry: Retrieves the distance the actor has traveled since the last mesh update, and its true distance to the displaced ground.
  • Get Actor Grid Resolution: Returns the exact calculated dimensions of the active grid.

7. Troubleshooting & FAQ

Q: My vehicle is still falling through the displacement rocks!
A: Verify your Landscape Material has the Runtime Virtual Texture Output node correctly plugged in. Ensure the Landscape Actor has the RVTs added to its "Virtual Textures" array, and that the RVT Volumes cover the map.

Q: The generated collision meshes are not accurate or form a flat wall in certain areas of the map.
A: This usually happens when the Virtual Texture has not been fully streamed into memory for that specific area, causing the system to read the fallback value. To resolve this, simply add a Streaming Virtual Texture to your Runtime Virtual Texture Volume in the level. This ensures the engine streams the texture data correctly even when moving fast across the map.

Q: The collision meshes are blocking my weapons/LineTraces.
A: The generated meshes are standard physics bodies. To prevent self-interference or unwanted weapon/wheel raycast impacts against procedural ground, you have two simple options: 1. Ignore all ground collision globally (Recommended): Call the Get Landscape Collision Host Actor node (from any Blueprint) and pass it into your LineTrace's IgnoreActor or IgnoreActors array. Since this host actor owns every procedural ground mesh in the scene, your trace will ignore all displacement ground at once! 2. Ignore a specific actor's ground mesh: Call Get Actor Collision Mesh Component on a specific character/vehicle and pass it into your LineTrace's IgnoreComponent list.

Q: My Chaos Vehicle is acting crazy / flying when it hits a displacement rock!
A: Chaos Vehicles have their own complex suspension simulation. The plugin automatically generates a LandscapeDisplacement collision profile that ignores vehicles. You should ensure your vehicle's collision profile ignores the displacement mesh, allowing the vehicle's suspension raycasts to handle the bumps smoothly while the chassis remains unaffected.

Q: The collision is lagging behind my fast car.
A: Open the vehicle's Tracker component and enable Enable Prediction. You may also want to set its Update Priority to Immediate instead of Deferred.

8. Under the Hood (Pipeline Basics)

For developers interested in performance and optimization, here is how the plugin's pipeline operates under the hood to ensure zero hitches:

  1. Registration: The Landscape Collision Tracker (or Plug & Play Auto-Registration) silently registers the Actor with the Subsystem. If a Tracker component is present, its custom parameters override the default fallback settings.
  2. Filtering (CPU): Every frame, the Engine loops through registered actors. If an actor is moving fast enough (Threshold) and is close enough to the camera (Culling), it flags it for an update.
  3. Extraction (GPU): The Engine requests the RVT Processor to capture RVT pixels precisely under the actor's bounding box using a lightweight Compute Shader.
  4. Readback (VRAM -> RAM): The texture data is copied asynchronously. The Game Thread never stalls waiting for the GPU.
  5. Scheduling (CPU): Received data is placed into the Scheduler queue. The Scheduler acts as a governor, ensuring that only a set amount of physics updates occur per frame (controlled by your Max Deferred Updates Per Frame setting).
  6. Generation: The Dynamic Mesh Component is built and its physics body is "cooked" asynchronously.

Clone this wiki locally