Water Depth Maps and Bathymetry in Godot 2D

One depth field for the lake

Your top-down lake in Godot looks shallow near the shore, but the boat crosses it without slowing down. You add an Area2D for the shallows, then move the shoreline and have to update the artwork and the movement rule separately. The swimming transition can drift out of sync in the same way.

In top-down 2D water, a depth map stores the vertical distance from the water surface to the bed at each position. The shape of that bed is its bathymetry. In Godot, your shader and gameplay code can read the same map to colour the shallows, set swimming transitions and check clearance beneath a boat. Each use still needs its own rules.

We'll use one lake with a shallow shore and a deep trench. The Lake Depth Lab example lets you inspect the data, move two gameplay probes and compare CPU samples with the shader.

Download the Godot example (MIT, 53 KB ZIP). Open the setup instructions to run it alongside the article.

What water depth can decide in a game

Depth becomes useful when it affects a choice the player makes or the way you draw the underwater space. Here are some mechanics you could build around it.

Two categories may be enough. Shallow water can be crossed, while deep water stays off limits. A few regions or tile types can handle that. The amount of data should follow the decision you're trying to make.

What an interpolated map adds

A depth map can describe the slope between a shallow shelf and a deeper basin. That slope has a width, so hull clearance can change gradually along it. A swimming threshold then cuts across the same field at the relevant depth.

You can also place a trench diagonally through the lake or put a narrow crossing where it serves the player's route. Texture resolution limits the detail, but the shape doesn't have to follow the boundaries of your gameplay tiles.

When you move the slope, the visual and the grounding rule can read its new position together. That requires matching coordinates and synchronized updates. A separate, manually maintained shallow-water region can still drift out of sync.

Tiles can store numeric depths, support interpolation and supply several systems too. A texture is a practical way to author and sample the field. Calling it continuous doesn't remove its finite resolution or storage precision.

Where it earns its place

Depth can shape routes in naval and pirate games, organize resources in island survival or fishing games, and separate wading from swimming in an exploration adventure. Colony simulations can use it in crossing costs. In a tactical game, a shallow ford can make one stretch of river worth defending.

For decorative surface colour, ripples or foam, a visual shader may be enough. Rendering a shaped lake bed or hiding an underwater object behind a trench lip can justify depth data even if no gameplay rule uses it.

Consider a depth map when:

• A character's movement state or contact with the floor depends on local depth.
• Boats need routes with a measurable amount of clearance.
• Underwater placement or visibility depends on the shape of the bed.
• You edit slopes and shallows that both rendering and gameplay need to read.

These are reasons to consider a shared depth field. If a few discrete zones cover your requirements, start there.

Bathymetry in a 2D scene

Bathymetry describes underwater terrain through its depths and shape. It includes the shallows, slopes and depressions beneath a body of water. NOAA's definition of bathymetry.

Keep these three quantities separate:

In this project, positions across the lake use Godot's local X/Y plane. Depth is a separate value measured vertically down from the water surface, in metres. Local +Y points down the plan view. It doesn't represent vertical depth.

The map covers 32 × 32 m, centred at the origin. At 32 Godot units per horizontal metre, its local rectangle runs from (-512, -512) across 1024 × 1024 units. A 256 × 256 texture gives us 0.125 m per texel.

Water coverage is stored separately as a 64-vertex polygon. The rectangular texture includes land outside that polygon. A value in the texture doesn't make that position water.

Store a water depth map in an 8-bit texture

The project uses an RGB8 PNG and reads depth from its red channel. The generator writes the same byte to all three channels so the source is easy to inspect as grayscale. A normalized value of 1.0 represents the reference depth of 8 m.

byte_value = floor(depth_m / reference_depth_m * 255 + 0.5)
decoded_depth_m = byte_value / 255 * reference_depth_m

There are 256 byte values, including zero. Across 0–8 m, adjacent values differ by 8 / 255, about 3.14 cm. Our design targets therefore decode as follows.

Those differences matter near a gameplay threshold. We'll return to B when the character starts swimming. Linear filtering interpolates between stored values, but it can't recover precision or detail lost when the map was encoded.

Keep the reference depth with the data. Changing it from 8 m to 16 m without re-encoding the PNG doubles every decoded depth. The authoring tool, CPU sampler and shader need the same scale.

Import the numeric data

The supplied .png.import files select Godot's Image importer. The loader keeps that Image for CPU queries and creates an ImageTexture from it for rendering. Both consumers start from the same pixels. The loader also checks the dimensions, RGB8 format and that the image is readable before replacing the current field. See Godot's documentation for the Image importer and ImageTexture.create_from_image().

The depth sampler has no source_color hint. Its channel contains numeric data, so we preserve those values through sampling. Godot documents the distinction between sRGB colour textures and data such as height textures in its source_color guidance.

If the water level changes

This example has a fixed surface. For a changing level, you can store bed height relative to a fixed datum and calculate:

water_depth = water_level - bed_height

With a depth map authored for a known initial water level, the equivalent is current_depth = original_depth + water_level_change. Raising the surface by 0.5 m adds 0.5 m above the same bed wherever water is present. It doesn't change the PNG's decoding scale.

Flooding beyond the old shore also requires terrain data outside the lake and updated coverage. The companion project's fixed polygon and underwater map don't provide that extension.

Shaping the shore, slope and trench

The generator starts with the distance to the shoreline. It builds a gentle descent to the 0.4 m shelf, continues to the 1.2 m shelf, then reaches the 3 m basin. Holding the same drop over a wider horizontal distance gives you a gentler slope.

The trench is a separate, elongated shape cut diagonally into that basin. Its position doesn't follow distance from the shore. Two points equally far inland can have different depths because one lies over the trench.

You could paint these shapes, generate them from curves or bake them from a terrain description. The companion uses tools/generate_lake.py so the two PNGs and their metadata can be reproduced exactly. The second map shifts the trench by (-3, +3) m while retaining the shoreline.

Choose resolution around the smallest feature you need to preserve. A narrow channel needs enough texels across its width. More pixels improve horizontal detail, while more channel precision improves the available vertical depth values. Increasing one doesn't automatically improve the other.

Read the same depth map in GDScript and a Godot shader

The shared field owns the image, the coverage polygon and the map bounds. In scripts/lake_surface.gd, a world-position query first enters the lake's local coordinate system:

func query_global(world_point: Vector2) -> Dictionary:
	return field.query_local(to_local(world_point))

Godot's Node2D.to_local() handles that conversion. The field then calculates uv = (point - bounds.position) / bounds.size and checks the rectangle and polygon before sampling. Its query result contains inside_water, depth_m, uv and revision. Use depth_m only when inside_water is true.

Bilinear sampling on the CPU

The CPU uses four neighbouring texels to match the GPU's linear filtering. This is the sampler from scripts/depth_field.gd. The image and reference depth are members initialized by the field loader.

func sample_uv(uv: Vector2) -> float:
	# Rectangle sampler, deliberately separate from the water-coverage query.
	if image == null or not uv.is_finite() or uv.x < 0.0 or uv.y < 0.0 or uv.x >= 1.0 or uv.y >= 1.0:
		return -1.0
	var size := image.get_size()
	var pixel := uv * Vector2(size) - Vector2(0.5, 0.5)
	var base := Vector2i(pixel.floor())
	var weight := pixel - Vector2(base)
	var x0 := clampi(base.x, 0, size.x - 1)
	var x1 := clampi(base.x + 1, 0, size.x - 1)
	var y0 := clampi(base.y, 0, size.y - 1)
	var y1 := clampi(base.y + 1, 0, size.y - 1)
	var top := lerpf(image.get_pixel(x0, y0).r, image.get_pixel(x1, y0).r, weight.x)
	var bottom := lerpf(image.get_pixel(x0, y1).r, image.get_pixel(x1, y1).r, weight.x)
	return lerpf(top, bottom, weight.y) * reference_depth_m

Subtracting half a texel aligns interpolation with the centres of the stored samples. The edge indices clamp to the image. UVs outside [0, 1), including exactly 1, are rejected before that clamp can turn them into edge samples.

The -1 return belongs to this rectangle helper. Gameplay uses the water query above it, so land inside the texture rectangle is still reported as outside water. The CPU keeps its image in memory rather than reading pixels back from the GPU each frame.

Mapping the polygon to the texture

The visible lake is a Polygon2D built from the same outline. The preview shader derives its map coordinates from local vertex positions, following Godot's CanvasItem vertex convention. Here is the relevant section of shaders/depth_preview.gdshader:

uniform vec2 map_origin = vec2(-512.0);
uniform vec2 map_extent = vec2(1024.0);
uniform int display_mode = 0; // 0 palette, 1 grayscale, 2 raw measurement.
varying vec2 map_uv;

void vertex() {
    map_uv = (VERTEX - map_origin) / map_extent;
}

The material sets those bounds from the shared field. Its included file, shaders/depth_sampling.gdshaderinc, performs the depth read:

uniform sampler2D depth_map : filter_linear, repeat_disable;
uniform float reference_depth_m = 8.0;

float read_depth_m(vec2 map_uv) {
    return textureLod(depth_map, map_uv, 0.0).r * reference_depth_m;
}

These are excerpts from the complete project shaders. The fragment stage uses that depth to choose the palette, display grayscale or produce raw measurements. The polygon controls where water is drawn.

The CPU sampler and shader both read the original texture level, LOD 0. The shader selects it explicitly with textureLod. If the shader sampled a smaller mipmap while the CPU kept the original image, they could disagree around the trench lip as you zoom out. Filtering a distant visual can be useful, but the gameplay depth still needs a defined sampling rule.

Press Shift trench to load the alternate map. The project replaces the CPU image, binds its matching GPU texture and updates both probes before another frame renders. Each query carries the field's revision. A failed load retains the previous valid field. This is a switch between two prepared maps, not a live painting tool.

Using bathymetry to draw the bed and underwater objects

A palette is the simplest visual use. You can keep the shallows light and give the trench a darker colour, making the field easy to inspect. A fuller water renderer can use depth to control how much of the bed remains visible.

For that renderer, distinguish the loss of the object's direct light from the backscatter added along the viewing path. They contribute differently to the underwater image. The distinction is described in Akkaynak and Treibitz's Sea-Thru paper. The companion's palette doesn't implement that optical model.

The trench also has geometry. A renderer can follow a viewing ray until it intersects the bed described by the depth field. Ray–height-field intersection is the basis of techniques such as relief mapping. Refraction would change the ray direction at the water surface and would need to be included in a renderer that models it.

Two fish at the same depth

The following section uses the actual profile at Y = 0. Both hypothetical fish are 5 m below the water surface. The trench reaches 8 m, while the surrounding basin has a 3 m target depth, decoded as about 3.012 m.

The left fish sits at X = 0.25 m. Its ray meets the basin lip before reaching it. The fish at X = 1.5 m has a clear ray through the water. Both fish positions are above the local floor. Their shared depth alone doesn't determine visibility.

With a strictly vertical view and no refraction, this lateral occlusion by the lip wouldn't occur for a fish above a single-valued bed. The projection matters. Putting a sprite beneath a water layer doesn't calculate the ray's intersection with the floor.

The fish also has its own depth. Assigning it the 8 m floor value would place it at the bottom. Its shorter path to the surface can justify different attenuation from the bed below it, depending on the optical model you choose.

The section explains a rendering calculation. The running project implements the depth preview and gameplay probes, with no fish occlusion, relief mapping or refraction shader. The figure generator checks the two ray cases against the source data and records their geometry separately from the GPU tests.

Use water depth for swimming and boat clearance

The two markers sample independently. P represents a character and V a vessel. You can place either freely. The labels show when each marker would switch state. The example doesn't move or stop a character or boat for you.

Swimming needs the previous state

For this example, a character enters swimming at sampled depth ≥ 1.2 m. Once swimming, it returns to wading only below 1.0 m. Outside the water polygon, it is dry.

The gap between the two thresholds is hysteresis. It prevents a small depth change near one boundary from repeatedly switching the character's state. The rule in scripts/water_rules.gd receives the previous state explicitly:

static func character(sample: Dictionary, previous: String) -> Dictionary:
	var state := "dry"
	if sample.inside_water:
		if previous == "swimming":
			state = "wading" if sample.depth_m < SWIM_EXIT_M else "swimming"
		else:
			state = "swimming" if sample.depth_m >= SWIM_ENTER_M else "wading"
	return {"state": state, "sample": sample.duplicate()}

That file defines SWIM_ENTER_M = 1.2 and SWIM_EXIT_M = 1.0. On shelf B, the sampled depth is 1.192157 m. A wading character won't start swimming there. A character arriving from deeper water while already swimming will keep swimming. The same sample gives different results because history is part of the rule.

While a character stands on the bed, local depth can help position the body relative to the surface. Once swimming, body immersion depends on the character's position and pose. Crossing the 8 m trench doesn't automatically pull the swimmer eight metres down.

Clearance below the hull

The vessel has a fixed 0.8 m draft. Its signed clearance is:

clearance_m = sampled_depth_m - draft_m

At B, that leaves about 0.392 m. At A, the result is about −0.392 m, meaning the assumed hull extends into the bed. These values use the decoded depths, which is why they differ slightly from subtracting the design targets.

The bottom_drag margin is a gameplay choice. The probe reports the state, but doesn't apply drag forces or stop the vessel. A larger hull would need several sample positions because its bow can reach the shore while its centre remains in deep water. A movement controller must also account for the path travelled between samples.

What the project verifies

The source ZIP was extracted into a new folder without a Godot cache, imported and run on Godot 4.7.2-stable, using Compatibility / OpenGL 3.3 on Windows with an NVIDIA GeForce RTX 3060. The data generator then reproduced both PNGs and the metadata with identical hashes.

The CPU checks include known plateau bytes, an independent 2 × 2 interpolation fixture, coverage, edge handling and transformed lake queries. Gameplay checks exercise the swimming thresholds from both directions, state history, hull clearance boundaries and leaving the water. The UI checks cover probe movement, independence, map refresh, reset and pan/zoom consistency.

The GPU test draws the actual polygon with the preview shader's diagnostic mode. It packs depth into two byte channels and uses alpha for coverage. The CPU query is evaluated at the corresponding pixel-centre position. Depth isn't inferred from the presentation colours.

Rendering at 256² tests source texel centres. The 320² view also tests positions that require interpolation. The 0.016 m tolerance belongs to this CPU/GPU filtering and readback comparison. The PNG's rounding error is a separate issue.

The checks compare CPU and shader depth readings and test the probe states. They don't measure frame time.

These results apply to the recorded engine, renderer and device. They don't establish compatibility or performance on every target. The verification JSON contains the detailed results and the SHA-256 of the exact source ZIP used for the clean extraction.

Limits of the field

A depth map assigns one floor depth to each horizontal position. It can describe this lake and trench, but a cave under an overhang needs more geometry because several surfaces occupy the same X/Y position.

Higher resolution increases storage and update work. More precision needs a format and sampling path that preserve it. If you edit or regenerate the bed, update the CPU and GPU consumers together. Any baked representation needs to be refreshed too.

Flow direction, waves, buoyancy and collision response require their own data or calculations. Bathymetry can inform them without specifying the complete behaviour. The example keeps its water level fixed and its gameplay probes limited to one point each.

Open the companion project

Lake Depth Lab 1.0.0 is a standalone educational source project. It includes the lake data, generator, sampler, preview shader, movable probes and verification tools. The original code, data and documentation use the MIT licence, © 2026 Vav Labs.

Download the source ZIP and read the verification results.

Extract the ZIP, import project.godot and press F5. No addon, Python or network connection is needed to run the scene. The UI is built at runtime, so the editor initially shows the root Control.

Try this sequence:

1. Drag P into the trench, then back to B. It keeps swimming at B until you take it below 1 m depth. Reset returns it to wading on the inner shelf.
2. Drag V from the trench towards the shore. Watch the signed clearance and the transitions through free, bottom_drag and grounded.
3. Put a probe outside the shoreline. P becomes dry. V becomes outside_water with no valid clearance.
4. Leave a probe near (2, 0) m in the original trench and press Shift trench. Its position stays fixed while the sampled bed changes underneath it.

Select Sample and click to pin the inspector. You can also select Character or Vessel and click to place that probe. The wheel zooms, middle or right drag pans, G switches grayscale, and R resets the map, probes and view.

To repeat the checks with godot on your PATH, run these commands from the extracted project directory:

godot --headless --editor --path . --quit
godot --headless --path . --script res://tools/verify_cpu.gd
godot --path . --resolution 1400x900 -- --verify

The last command needs a GPU renderer. It writes the GPU report and runtime screenshots, then exits. Python is only needed for the optional data, figure and package regeneration tools described in the project's README.

The verified source ZIP is 52,893 bytes. Its SHA-256 is:

5f97b754ba7b47ebbd7b89ce23607c1879298a3a8b6dfd0e0b4e4a3dddb5e740

The separate checksum file and verification report identify the same archive. A rebuilt or edited ZIP needs a matching new receipt.