An interactive terrain height visualization tool using color-coded spheres
for the Unity Editor by BigBuffaloBill.
Author's Note on Expected Functionality: The author has written an important note about the intended scope, known limitations, and support expectations for this toolset. Please see Notes on Tool Intent, Status and Author Support before proceeding.
Terrain Height Spheres is a Unity Editor tool that gives you an instant, at-a-glance read of your terrain’s elevation across your entire scene — right in the Scene view. Click Generate and a grid of color-coded spheres appears directly on top of your terrain: yellow spheres mark the lowest ground, red spheres mark the highest, and everything in between blends smoothly across the gradient. You can read the shape of your entire landscape in terms of elevation at a glance, without leaving the Editor. When you’re done, a single click removes every sphere instantly. You stay in complete control of what’s in the scene at all times.
What makes the tool especially powerful is its height filter. Two simple sliders — a bottom percentile and a top percentile, each ranging from 0 to 100 — let you tell the tool exactly which slice of your terrain’s elevation range you want to see. Set the top slider to 20, for example, and only the highest peaks and ridgelines are marked in the scene. Set the bottom slider to 70 and the top to 100, and you isolate just the upper 30% of your elevation range. Dial the bottom to 0 and the top to 30, and the tool highlights your valleys and low-lying areas only. You can focus on any band of the elevation spectrum you need, from a broad overview of the whole landscape down to a precise slice just a few percent wide.
The spheres are never saved to your scene — they exist only while you choose to show them, and each new generation starts completely fresh. Your settings from the last session — grid density, sphere size, and your percentile range — are remembered automatically so you can pick up exactly where you left off.
Terrain objects in the current sceneHideFlags.DontSave and are never written to the scene fileEditorPrefs — grid spacing, sphere size, and percentile range are restored on next openObject.FindObjectsOfType, TerrainData.GetInterpolatedHeight, and EditorPrefs, all standard since 2018.4+; tested and recommended on 2020.3+)Universal Render Pipeline/Lit shader. The tool will not correctly color spheres in Built-in or HDRP projects without shader adjustment.UnityEngine, UnityEditor)Terrain object must be present in the active scene for sphere generation to produce outputTerrain Height Spheres ships as part of the Terrain Height Visualizer & Prefab Placer package. Full installation instructions — including the Package Manager flow, import steps, and the complete post-import file structure — are covered in TerrainHeightVisualizerAndPrefabPlacer_Documentation.html in the parent directory.
Terrain object.Navigate to Tools > BBB > Terrain Height Spheres in the Unity menu bar. The window is a standard dockable Editor window and can be placed alongside the Inspector, Scene view, or any other panel. The window title is “Terrain Height Spheres.”
The Grid Spacing slider controls the distance in meters between adjacent sphere sample points. Range: 10 m to 500 m. This setting is persisted in EditorPrefs and restored on next open.
Performance note: Small grid spacing values produce a very large number of spheres and can significantly slow the Editor. Start with a value of 100 m or higher and decrease as needed.
The Sphere Size slider controls the diameter of each visualization sphere in world units. Range: 0.5 m to 20 m. This setting is persisted in EditorPrefs.
The Bottom Percentile and Top Percentile sliders define which portion of the terrain's elevation range is visualized. Both values range from 0 to 100.
0 and top percentile of 100 visualizes the full elevation range.80 and top percentile of 100 shows only the highest 20% of terrain elevation.0 and top percentile of 30 shows only the lowest 30% of terrain elevation.Height percentile is computed against the global min/max elevation sampled across all terrains in the scene, so the filter is consistent even in multi-terrain setups.
Click Generate Spheres to run the visualization. The tool:
Terrain objects in the scene using Object.FindObjectsOfType<Terrain>.GameObject named __TerrainHeightSpheres_Container with HideFlags.DontSave.Sphere color is determined by the sphere's world Y position relative to the global height range:
Materials are created with the Universal Render Pipeline/Lit shader and assigned HideFlags.DontSave.
Click Remove Spheres to immediately destroy the container and all child spheres. The button is disabled when no visualization is active. The window status line will return to Inactive.
Note: Closing the scene or entering Play Mode will also remove the spheres, as they are marked
HideFlags.DontSave.
The window displays a Status line that reads Active when a sphere container is present in the scene and Inactive when it is not. This is determined by checking whether the container GameObject exists via GameObject.Find.
Namespace: BleBike.Editor
Inherits: UnityEditor.EditorWindow
Location: Editor/TerrainHeightSpheres.cs
Description: The main Editor window class. This is an editor-only class and is not available at runtime.
| Menu Path | Method | Description |
|---|---|---|
| Tools > BBB > Terrain Height Spheres | Open() |
Opens or focuses the Terrain Height Spheres window. |
| Field | Type | Default | Description |
|---|---|---|---|
_gridSpacing | float | 100 | Distance in meters between sphere sample points on both axes. |
_sphereSize | float | 2 | Diameter in world units of each visualization sphere. |
_bottomPercentile | float | 0 | Lower bound of the height filter (0–100). Points below this percentile are skipped. |
_topPercentile | float | 100 | Upper bound of the height filter (0–100). Points above this percentile are skipped. |
| Method | Description |
|---|---|
Open() | Static [MenuItem] method that opens or focuses the window. Sets minimum window size to 300×100. |
OnEnable() | Loads persisted EditorPrefs values for all four settings fields and calls FindExistingContainer(). |
OnGUI() | Draws the full window UI: setting sliders, EditorPrefs persistence on change, status label, and Generate/Remove buttons. |
FindExistingContainer() | Uses GameObject.Find(CONTAINER_NAME) to detect whether a visualization is already present in the scene. |
GenerateSpheres() | Removes any existing container, finds all scene terrains, computes global height range, creates the container, and delegates per-terrain sphere creation to GenerateSpheresForTerrain. |
GenerateSpheresForTerrain(Terrain, float, float, float, float, float) | Iterates the grid for one terrain, samples height at each point, applies the percentile filter, creates and parents a colored sphere, and returns the count of spheres placed. |
RemoveSpheres() | Calls DestroyImmediate on the container if it exists and nulls the reference. |
GetHeightColor(float, float, float) | Returns a Color along the yellow-to-red gradient by computing the normalized height value and reducing the green channel linearly. |
| Constant | Value | Description |
|---|---|---|
CONTAINER_NAME | "__TerrainHeightSpheres_Container" | Name of the transient root GameObject that parents all visualization spheres. |
DEBUG_ENABLED | false | Master switch for all non-error debug output in this class. Set to true to enable logging. |
DBG_OUT_PREPEND | "[TerrainHeightVisualizer/TerrainHeightSpheres]" | Prefix string prepended to all debug log messages from this class. |
PREF_GRID_SPACING | "TerrainHeightSpheres_GridSpacing" | EditorPrefs key for persisting grid spacing. |
PREF_BOTTOM_PERCENTILE | "TerrainHeightSpheres_BottomPercentile" | EditorPrefs key for persisting the bottom percentile filter value. |
PREF_TOP_PERCENTILE | "TerrainHeightSpheres_TopPercentile" | EditorPrefs key for persisting the top percentile filter value. |
PREF_SPHERE_SIZE | "TerrainHeightSpheres_SphereSize" | EditorPrefs key for persisting sphere size. |
Start with a coarse grid. Use a grid spacing of 100 m or more for your first pass to get a quick overview without flooding the scene with geometry. Refine downward once you know which area you want to examine more closely.
Use percentile filters to isolate features. Setting the bottom percentile to 85–100 highlights ridgelines and peaks. Setting it to 0–15 isolates valley floors and water-adjacent areas. Narrow bands reveal subtle elevation transitions that are hard to read when the full range is shown.
Regenerate freely. Because spheres are never saved to the scene, you can click Generate Spheres as many times as you like with different settings. Each generation pass automatically removes the previous set first.
The spheres are scene-view only. Entering Play Mode will destroy the visualization (due to HideFlags.DontSave). This is expected behavior. Re-generate after exiting Play Mode if needed.
Multi-terrain height ranges are global. The percentile filter is computed against the combined min/max of all terrains in the scene. This ensures consistent coloring across terrain tiles but means that an isolated low tile will not show the full yellow-to-red gradient if the adjacent tiles reach much higher elevations.
Q: I clicked Generate Spheres but nothing appeared in the scene.
A: The most common cause is that there is no Terrain object in the active scene. The tool searches for terrains using Object.FindObjectsOfType<Terrain>. Ensure at least one terrain is present and active in the Hierarchy. Also check your percentile filter settings — if the bottom and top percentile values are very close together, few or no points may fall within the band.
Q: The spheres all appear the same color (all red or all yellow).
A: This occurs when the terrain's height variation is very small relative to the global range, causing all sampled points to cluster at one end of the gradient. Try using the percentile filter to narrow the band to the range where variation exists.
Q: Sphere colors look wrong — they appear pink, magenta, or solid gray.
A: The sphere materials are created using the Universal Render Pipeline/Lit shader. If your project uses the Built-in Render Pipeline or HDRP, this shader will not be found and Unity will fall back to a default error/pink material. This tool requires URP.
Q: The Editor became slow after generating spheres.
A: A very small grid spacing produces a very large number of GameObjects. Each is a full primitive sphere with a mesh renderer and a dynamically created material. Increase grid spacing or use Remove Spheres to restore normal Editor performance.
Q: The spheres were removed when I entered Play Mode. Is that a bug?
A: No, this is by design. The container and all sphere objects are created with HideFlags.DontSave, which prevents them from persisting across Play Mode transitions and from being saved into the scene file. Re-generate after exiting Play Mode.
Q: The status line says Inactive but I can see spheres in the scene.
A: The status is determined by a GameObject.Find call for the container name. If the container name was changed manually in the Hierarchy, or if the tool window was closed and reopened after the spheres were generated in a different session, the Find call may not locate it. Click Remove Spheres to clean up, then Generate Spheres again.
Q: Can I use this at runtime?
A: No. Terrain Height Spheres is an Editor-only tool. The class is in an Editor folder and depends on UnityEditor APIs that are not available in builds.
For questions, bug reports, or feature requests, please contact us through the Discord channel linked below.
Publisher: BigBuffaloBill
Discord: BigBuffaloBill & Friends Gaming + (bbb-unity-support-forum-public)