Demo & Runtime Guide

On a small screen, scroll wide tables sideways to read every column.

Try the demo and identify its parts

1. Open Assets/DPTGames/Vertex_3D_Terrain/Vertex3DTerrain_Demo/VertexTerrain_DemoScene.unity.
2. Inspect the terrain material and Ground Library. Assign that material to the Dynamic Biome Demo Controller and optionally assign a directional Sun light.
3. Set up the first appearance in the terrain material Inspector. Click + Capture Current Settings as NEW Profile on the demo controller. Name the profile, for example Spring.
4. Change the actual material settings to create the next appearance. Capture again and name the new profile Summer. Continue for Autumn, Winter or other appearances.
5. To revisit a saved appearance, click Apply Profile To Material on its profile. This loads the stored settings into the actual shared material for further editing. If you want to keep the edits, click Capture Profile From Material afterward.
6. Set Transition Seconds, Easing and Channels to Animate on each profile, including the first. Choose its biome slots, lighting and optional Wind. Click that profile’s Animate To Profile to reach it and stay there.
7. To test an entire sequence, capture at least two profiles and click Run Sequence From Start. Both playback methods work in Edit Mode and Play mode. Use Pause, Resume and Stop & Restore. Edit Mode scrubbing applies to the full sequence.
8. Optionally enable Play On Start to run the sequence automatically when entering Play mode. Use the demo camera to explore the results.
9. Use Surface Raycast Tester to inspect the biome IDs returned for painted surfaces.

Dynamic Biome Demo Controller

Click Open Documentation at the top of the component Inspector, or the component header’s Help icon, to open this online guide: Demo & Runtime Guide.

Add DPT → Dynamic Biome Demo Controller to a GameObject. Assign Terrain Material or place the component on a GameObject with a Renderer so it can resolve that Renderer’s shared material. Assign Sun if you want to blend a directional light’s rotation, intensity and colour.

The material Inspector is the authoring interface. Set your dynamic biome slots, target IDs, dusting, scatter density and colour, surface overrides and flow settings there. The demo controller deliberately does not duplicate those controls. It reads and stores material values only when you click a capture button.

All terrain objects using the same material receive the same changes. This is useful when several neighbouring tiles need to change together. Use separate materials if you need independent behaviour.

Inspector sections

What the profile stores

Each profile captures an independent copy of all four modifier slots, including active states, biome IDs, weight, smoothness, normals, parallax, emission, flow, dusting and scatter response. It also captures supported stylized lighting values, the assigned Sun’s rotation, intensity and colour, and the terrain material’s Wind enabled state, strength, direction and Height To Tip.

A profile does not keep a link to the material’s live values. Changing the material to create Winter does not change a previously captured Autumn snapshot. To change an existing snapshot, capture again using that profile’s own button.

Apply Profile To Material instantly loads the entire captured snapshot into the shared material and optional Sun, regardless of Channels to Animate. Use it in Edit Mode, with playback and preview stopped, to return quickly to a saved appearance and edit it. It supports Unity Undo and does not change the saved profile.

Animate To Profile instead blends from the current appearance, changes only the destination profile’s checked channels and holds the result. It works in Edit Mode, Play mode and while another profile transition is running.

See Terrain Material Settings for the shader settings themselves and 3D Scatter Guide for how a biome’s scatter-response settings affect instanced vegetation.

Environment Profiles & Timeline

Use Environment Profiles for seasons, droughts, flooding and temperature shifts. Run Sequence From Start uses the first profile’s checked channels as its starting appearance, then moves through the later profiles. Animate To Profile requests any captured profile directly, including the first.

Profile 1 has the same controls as every other profile: Transition Seconds, Easing, Slot 1–4, Stylized Lighting, Directional Light and Wind. Unchecked channels retain their current settings. A newly captured first profile selects all channels by default; later captures detect changes from the previous resolved state. Existing checkbox selections are preserved.

Capture a sequence

1. Spring: configure the material and optional Sun, then click + Capture Current Settings as NEW Profile. Rename the new profile Spring. This defines the beginning of the timeline.
2. Summer: edit the material and light to show summer, then click the same button again. Name this profile Summer and set Transition Seconds to the desired duration.
3. Autumn: adjust dusting, scatter and lighting as required, then capture a third profile and name it Autumn.
4. Winter: finish configuring snow dusting, reduced vegetation and colder lighting. Capture another profile and set its transition duration.
5. After the first profile, captures automatically check the biome, lighting and wind channels that differ from the previous resolved state. Adjust Channels to Animate manually on any profile, including the first. Unchecked channels keep their current values.
6. Preview the full sequence with Preview In Edit Mode and Preview Normalized, then use Stop Preview & Restore Material. With Loop enabled, the final state returns through the first profile’s checked channels. Unchecked channels remain unchanged.

Controls

Animate to one profile and hold it

1. Capture the appearance you want. One captured profile is enough for a direct request.
2. Choose the destination profile’s Transition Seconds, Easing and checked channels. The first profile has these controls too.
3. Click its Animate To Profile button. Completion shows Holding: profile name in the progress bar.
4. When another state is needed, request that profile. If a transition is still running, the new request starts from the current blended appearance without jumping back to its original start.

The destination stays active until another request, Stop & Restore, a sequence restart or component cleanup. Loop never advances a direct request automatically. Pause holds an unfinished transition; Resume continues it. A completed holding state has nothing left to resume.

Wind in environment profiles

Author Enable Wind, Wind Strength, Wind Direction and Height To Tip in the terrain material Inspector, then capture the profile. Check its Wind channel to animate these settings. An unchecked Wind channel leaves the current wind unchanged.

Turning wind off fades strength toward zero before disabling its shader feature at the destination. Turning it on fades from zero toward the captured strength. Direction and Height To Tip also blend. Unlike stylized lighting, this selected channel can change wind’s enabled state.

Older profiles without captured wind data leave wind alone, even if their Wind checkbox is selected. To add wind settings, stop and restore, apply the old profile, configure wind on the material, then recapture it. Scatter groups also need their own Enable Wind selection and a compatible material; capturing global wind does not change per-group wind selections.

Request profiles from code or UnityEvents

Call AnimateToProfile(string profileName) by name or AnimateToProfile(int profileIndex) by list position. Indices start at 0, so controller.AnimateToProfile(0) requests the first profile. Names are case-insensitive; duplicate names select the first match, so use unique names. Invalid or uncaptured requests warn and leave the current transition unchanged.

Save this example as EnvironmentProfileRequests.cs, add it to a GameObject and assign the Demo Controller reference. Prepare captured profiles named Winter and Summer, then call the appropriate request from your game logic or UI.

using UnityEngine;
using DPT.Vertex3DTerrain.Demo;

public class EnvironmentProfileRequests : MonoBehaviour
{
    [SerializeField] private DPT_DynamicBiomeDemoController controller;

    public void RequestWinter()
    {
        if (controller != null)
            controller.AnimateToProfile("Winter");
    }

    public void RequestSummer()
    {
        if (controller != null)
            controller.AnimateToProfile("Summer");
    }
}

Connect a UnityEvent without a wrapper script

1. Add an event entry, such as a UI Button’s On Click().
2. Assign the GameObject containing the Dynamic Biome Demo Controller.
3. Select its AnimateToProfile method accepting a string or integer.
4. Enter the profile name, such as Winter, or its zero-based index. Invoking the event uses the same transition-and-hold behaviour as the Inspector button.

Read playback status

PlayFromStart() runs the full sequence. PauseTimeline(), ResumeTimeline() and StopAndRestore() control either playback method. SetTimelineNormalized(float) seeks a direct request from 0 to 1 while that session exists, or controls the sequence outside a direct session. ApplyProfileToMaterial(int) and CaptureCurrentMaterialIntoProfile(int) are Edit Mode authoring methods used with playback and preview stopped.

Lighting and transition limits

• Stylized lighting is optional. Its values are animated only when _STYLIZED_LIGHTING was already enabled when preview or playback began. The controller never turns the keyword on or off. The Sun transition works independently.
• Numeric values and colours blend. Parameters such as weight, dusting strength, scatter density and colour, flow speed, emission, shading and Sun rotation can change over the selected duration.
• Identifiers and switches are discrete. Biome target IDs, overlay biome IDs and shader feature switches do not continuously blend. Keep target biome IDs consistent across transitions where possible, and use strength, weight or density for gradual changes.
• Dynamic biomes must be enabled on the terrain material. Profile transitions will not make live modifier effects visible when the material’s master switch is disabled.
• Preview modifies the shared material temporarily. Stop and restore before saving assets or editing the material. Keep a saved source material as a precaution against editor crashes during a preview.

Profiles do not repaint terrain, change terrain geometry or seams, physically raise water or implement precipitation. Live weight changes act on existing painted biome contributions; snow dusting requires suitable biome IDs and existing painted dusting masks.

Stable scatter fades and editing visibility

Scatter placements are generated from painted biome coverage. Dynamic Weight Multiplier and Scatter Density thin a stable set of existing clumps at draw time. Reducing grass strength for mud, yellow grass or drought no longer rebuilds placement at every step. Returning to the original strength restores the same placements. Colour changes remain live too.

Strength is a fade control, capped at 1 for scatter. Strength 0 hides matching animated scatter; strength 0.5 retains roughly half; strength 1 or higher shows the configured painted amount. Values above 1 can still affect terrain shading, but do not increase scatter density. Increase the scatter group’s configured Density to author a denser maximum. Strength and Scatter Density Response multiply; overlapping slots combine their weight multipliers before the cap.

For crystals or other scatter that should ignore seasonal biome changes, enable that group’s Static Scatter beside Wind. Static groups ignore dynamic biome weight, scatter density and colour/surface overrides. Painting or sculpting still updates placement, and the shared instance limit still applies.

In Scatter Settings, Disable While Brushing hides scatter and pauses placement updates whenever any surface or geometry tool is selected, including between strokes. It returns when both selections are None or the terrain tool window closes. This option affects Edit Mode only. Update After Stroke separately keeps placement visible during a stroke and updates affected sources after release when hiding is off.

Surface Raycast Tester

A raycast asks Unity, “What collider is along this line?” The tester displays that hit and then asks the terrain’s surface target for a biome. These are separate steps: hitting a collider does not mean it has terrain surface data.

Set up a probe on your own terrain

1. Finish a small painted test terrain and save its mesh.
2. Give it a MeshCollider whose triangle layout matches the mesh you are baking.
3. Use Bake Surface Data in the terrain tool.
4. Check that DPT → Terrain Surface Target is on the appropriate terrain object, with the baked Surface Data asset assigned. It requires a Renderer.
5. Create a separate empty object above the terrain and add DPT → Surface Raycast Tester.
6. Choose Downward Probe, a sufficient Max Ray Distance and a layer mask that includes the terrain collider.
7. Enable Scene Gizmos or Game HUD and check the hit object, triangle index, biome ID and name. Move the probe between two clearly different painted areas.

Read the result

Hit Object is the collider that intercepted the ray. Triangle Index identifies the triangle used for the lookup. Biome ID and Name are the surface query result. Hit Point, Normal and Distance describe the physical intersection.

If a collider is hit but the biome is unknown, check for the surface target and its data. A box or sphere collider is not a replacement for a matching terrain MeshCollider in a triangle-based lookup. Do not treat a negative or otherwise invalid triangle index as a valid terrain query.

Terrain Demo Camera

Add DPT → Terrain Demo Camera to your inspection camera. It provides free movement and mouse look. It does not supply walking physics, collision avoidance, grounded movement or planet gravity.

Movement Speed sets the ordinary travel rate, Fast Multiplier sets the Shift boost, and Mouse Sensitivity changes the look response. The optional controls overlay is useful while learning. Use a slower speed when examining a small feature and a faster one when crossing a large terrain.

The camera can pass through the terrain because it is an inspection rig. Replace it with your own gameplay controller when testing whether a bridge, cave or staircase is traversable.

Use surface data in gameplay

The intended flow is: paint terrain → bake its surface data → link that data to the terrain → raycast the matching collider → read a biome ID → choose your gameplay response.

The baked asset records representative biome information per triangle, including candidate IDs and weights used for live reweighting. The surface target reads that information and the terrain material’s current modifiers. It returns one biome ID for a hit, rather than a full texture or a list of every visible surface.

A small integration example

Save the following as TerrainSurfaceProbe.cs and add it to an object above your test terrain. Set its terrain layer mask and distance. Use Read Surface from the component context menu to perform one query. The Console message is only an example; replace it with your own sound, particle or movement lookup when connecting gameplay.

using UnityEngine;
using DPT.Vertex3DTerrain;

public class TerrainSurfaceProbe : MonoBehaviour
{
    public LayerMask terrainLayers = ~0;
    public float distance = 2f;

    [ContextMenu("Read Surface")]
    public void ReadSurface()
    {
        if (!Physics.Raycast(transform.position, Vector3.down,
                out RaycastHit hit, distance, terrainLayers))
        {
            Debug.Log("No collider within the probe distance.");
            return;
        }

        if (hit.triangleIndex < 0)
        {
            Debug.Log("This collider has no usable terrain triangle index.");
            return;
        }

        if (DPT_TerrainSurfaceTarget.TryGetHitBiome(
                hit, out int biomeID, out string biomeName))
        {
            Debug.Log($"Surface: {biomeName} (ID {biomeID})");
            // Choose your project's response using biomeID.
        }
        else
        {
            Debug.Log("The hit has no linked terrain surface data.");
        }
    }
}

For footsteps, call your query at the time a footstep occurs, using the appropriate foot or character position. Map the returned ID to your own audio/effects table. Keep that table in step with library changes; biome names are helpful labels, but library IDs are the numeric values the query returns.

For a planet or custom gravity system, replace the example’s world-down direction with your game’s local gravity direction. The tool does not infer that direction for this script.

When to rebake

• After repainting areas that your gameplay will query.
• After adding, deleting or reordering biomes when this changes the IDs used by the data.
• After subdivision, deletion, tunnel creation, simplification or another operation that changes triangles.
• After other geometry changes that affect the bake or its representative surface information.
• When switching to a different collider mesh, including a simplified LOD collider.

Ordinary supported live material multipliers can be evaluated without repainting or rebuilding the triangle data, because the target reads them at query time. They still operate on the baked candidates; they cannot recover newly painted information from a stale bake.

How closely does a query match the picture?

The supplied query is useful for choosing a representative terrain surface, but it is not a pixel-perfect sample of what the shader renders. Test it against your gameplay needs rather than promising that every edge or snow patch returns exactly what is visible beneath the cursor.

If your gameplay needs exact small patches, local gravity-aware snow or precise per-pixel coverage, build and validate an appropriate query for those rules. The supplied components are a starting point with the limits described above.

Runtime and demo problems

Support

If you need help, describe the result you expected, the control you used, and what appeared instead. Include your Unity version, the selected surface pipeline, and a screenshot of the relevant settings. For a runtime query problem, also include the collider type and when you last baked surface data.

Use the DPT Games contact form or join the DPT Games Discord.

Back to top