Water

20 tools. Back to the index.

add_water_body_to_zone

Additive.

Link an existing water body actor to an existing AWaterZone.

Parameter	Type	Required	Description
water_body_label	string	yes	Label of the existing AWaterBody actor to link
water_zone_label	string	yes	Label of the existing AWaterZone actor to link into

Returns: { water_body_label: string, water_zone_label: string, linked: bool }

configure_water_zone

Destructive, idempotent.

Set an AWaterZone's planar extent and/or water-info render-target resolution, then RE-READ both from the actor (extent, world bounds, texel density) instead of echoing the request back.

Parameter	Type	Required	Description
water_zone_label	string	yes	Label of the AWaterZone actor
extent	array	no	Optional [X, Y] planar zone extent. !!! THIS IS THE COMPLETE EXTENT, NOT THE HALF-EXTENT / SEMI-AXIS !!! The engine halves it itself (AWaterZone::GetZoneBounds2D: "GetZoneExtents returns the full extent of the zone but BoxSphereBounds expects a half-extent"), so passing 4000000 gives world bounds of [-2000000, +2000000] around the actor -- a 40 km sea, not 80 km. Reading it as a semi-axis gives a sea of DOUBLE the intended size with bounds off the map; the world_bounds_extent field in the response is what disambiguates it (half of zone_extent_actual).
render_target_resolution	array	no	Optional [X, Y] water-info render target resolution. Read back by reflection as render_target_resolution_actual (the getter is not exported, so this is the raw UPROPERTY, i.e. BEFORE the r.Water.WaterInfo.RenderTargetResolutionMax clamp).

Returns: { water_zone_label: string, zone_extent: [x,y] (RE-READ, kept for compatibility), zone_extent_actual: [x,y] (RE-READ, COMPLETE extent), world_bounds_extent: [x,y,z] (HALF-extent of the real actor bounds), world_bounds_origin: [x,y,z], world_bounds_min: [x,y,z], world_bounds_max: [x,y,z], actor_scale: [x,y,z], render_target_resolution_actual: [x,y] (omitted if unreadable), render_target_resolution_verified: bool, water_info_texel_size_uu: number (zone_extent / render_target_resolution; omitted if the resolution is unreadable or zero), applied: bool (DERIVED from read-back == request), requested: { extent, render_target_resolution } }

create_lake_water_body

Additive.

Spawn a Lake AWaterBody actor, optionally link to a WaterZone, and READ BACK the wave height the factory attached (a lake is born with the OCEAN's waves and nothing else reveals it).

Parameter	Type	Required	Description
actor_label	string	yes	Label to assign to the new water body actor
location	array	no	Optional [X, Y, Z] world location (defaults to origin)
water_zone_label	string	no	Optional label of an existing AWaterZone to auto-link the body to. If given and the zone is not found, success is FALSE (the body is still spawned; linked_to_zone says so).
affects_landscape	boolean	no	When true the body carves the existing landscape via the water landscape brush; defaults to FALSE (non-destructive)
disable_waves	boolean	no	OPT-IN, default FALSE. Sets water_waves = None right after the spawn and RE-READS GetMaxWaveHeight() to prove it went to 0. Use it on any basin shallower than ~5 m: the engine's Lake factory attaches the ocean's wave asset (measured 508.125 uu = 5.08 m of crest), which on a pond a few meters deep breaks the water surface -- crest above the lip of the basin, trough below the bed -- with every property of the actor reading green.

Returns: { actor_label: string, actor_name: string, body_type: string, water_zone_label: string, linked_to_zone: bool, affects_landscape: bool, max_wave_height: number (RE-READ from UWaterBodyComponent::GetMaxWaveHeight() AFTER any disable_waves), max_wave_height_on_spawn: number (RE-READ as the factory left it), has_waves: bool, waves_disabled: bool, warning?: string (emitted when a lake was born with waves), requested: { actor_label, location, water_zone_label, affects_landscape, disable_waves } }

create_ocean_water_body

Additive.

Spawn an Ocean AWaterBody actor, optionally link to a WaterZone, and read back its wave height (on an ocean the factory's waves are CORRECT -- ~508 uu -- so no warning is emitted here).

Parameter	Type	Required	Description
actor_label	string	yes	Label to assign to the new water body actor
location	array	no	Optional [X, Y, Z] world location (defaults to origin)
water_zone_label	string	no	Optional label of an existing AWaterZone to auto-link the body to. If given and the zone is not found, success is FALSE (the body is still spawned; linked_to_zone says so).
affects_landscape	boolean	no	When true the body carves the existing landscape via the water landscape brush; defaults to FALSE (non-destructive)
disable_waves	boolean	no	OPT-IN, default FALSE. Sets water_waves = None right after the spawn and RE-READS GetMaxWaveHeight(). On an ocean you almost certainly do NOT want this.

Returns: { actor_label: string, actor_name: string, body_type: string, water_zone_label: string, linked_to_zone: bool, affects_landscape: bool, max_wave_height: number (RE-READ), max_wave_height_on_spawn: number (RE-READ), has_waves: bool, waves_disabled: bool, requested: { actor_label, location, water_zone_label, affects_landscape, disable_waves } }

create_river_water_body

Additive.

Spawn a River AWaterBody actor, optionally link to a WaterZone, and read back its wave height (a river is born at 0.000 -- that is the control case for the lake defect).

Parameter	Type	Required	Description
actor_label	string	yes	Label to assign to the new water body actor
location	array	no	Optional [X, Y, Z] world location (defaults to origin)
water_zone_label	string	no	Optional label of an existing AWaterZone to auto-link the body to. If given and the zone is not found, success is FALSE (the body is still spawned; linked_to_zone says so).
affects_landscape	boolean	no	When true the body carves the existing landscape via the water landscape brush; defaults to FALSE (non-destructive)
disable_waves	boolean	no	OPT-IN, default FALSE. Sets water_waves = None right after the spawn and RE-READS GetMaxWaveHeight(). A river has no waves to begin with, so this is normally a no-op here.

Returns: { actor_label: string, actor_name: string, body_type: string, water_zone_label: string, linked_to_zone: bool, affects_landscape: bool, max_wave_height: number (RE-READ), max_wave_height_on_spawn: number (RE-READ), has_waves: bool, waves_disabled: bool, requested: { actor_label, location, water_zone_label, affects_landscape, disable_waves } }

create_water_body_exclusion_volume

Additive.

Spawn an AWaterBodyExclusionVolume (a brush volume that excludes water bodies), build its cube brush, set the exclusion mode, and optionally bind specific water bodies by label.

Parameter	Type	Required	Description
actor_label	string	yes	Label to assign to the new exclusion volume actor
location	array	no	Optional [X, Y, Z] world location (defaults to origin)
size	number	no	Optional cube brush size in uu (defaults to 200)
exclusion_mode	string	no	Optional "remove" (default) or "add": whether water_body_labels are removed from or added to the exclusion
water_body_labels	array	no	Optional array of AWaterBody labels to bind into the volume's WaterBodies list

Returns: { actor_label: string, actor_name: string, exclusion_mode: string, water_body_count: int, brush_built: bool }

create_water_zone

Additive.

Spawn a new AWaterZone actor in the editor world at location, unrotated, and label it. Not idempotent: every call adds another zone, even with a label already in use. Nothing is saved. Returns actor_label, actor_name and has_water_mesh; link bodies via water_zone_label of create_lake_water_body and its siblings.

Parameter	Type	Required	Description
actor_label	string	yes	Label to assign to the new AWaterZone actor
location	array	no	World location [X, Y, Z] in cm; anything but a 3-number array means the origin.

Returns: { actor_label: string, actor_name: string, has_water_mesh: bool }

get_river_spline_points

Read-only.

Read back a water body's spline path as world points.

Parameter	Type	Required	Description
water_body_label	string	yes	Label of the AWaterBody actor

Returns: { water_body_label: string, point_count: int, points: [[number, number, number]] }

get_water_body_gerstner_wave_detail

Read-only.

Read the computed individual Gerstner waves of a water body (wavelength, amplitude, steepness, direction).

Parameter	Type	Required	Description
water_body_label	string	yes	Label of the AWaterBody actor

Returns: { water_body_label: string, wave_count: int, waves: [{ wavelength: number, amplitude: number, steepness: number, direction: [number, number, number] }] }

get_water_body_info

Read-only.

Read back a water body's type, linked zone, surface material, and max wave height.

Parameter	Type	Required	Description
water_body_label	string	yes	Label of the AWaterBody actor

Returns: { actor_label: string, actor_name: string, body_type: string, water_zone_label: string, material: string, max_wave_height: number }

get_water_body_wave_info

Read-only.

Read a water body's wave state: whether waves are supported, whether they are present, the max wave height, and the active waves class + wave count.

Parameter	Type	Required	Description
water_body_label	string	yes	Label of the AWaterBody actor

Returns: { water_body_label: string, wave_supported: bool, has_waves: bool, max_wave_height: number, waves_class: string, num_waves: int, generator_class: string }

get_water_zone_info

Read-only.

Read info about an existing AWaterZone and count its linked water bodies.

Parameter	Type	Required	Description
water_zone_label	string	yes	Label of the existing AWaterZone actor

Returns: { actor_label: string, actor_name: string, has_water_mesh: bool, linked_body_count: number, zone_extent: [number, number], overlap_priority: int }

remove_water_body_from_zone

Destructive.

Unlink an existing water body actor from an existing AWaterZone (inverse of add_water_body_to_zone).

Parameter	Type	Required	Description
water_body_label	string	yes	Label of the existing AWaterBody actor to unlink
water_zone_label	string	yes	Label of the existing AWaterZone actor to unlink from

Returns: { water_body_label: string, water_zone_label: string, removed: bool, note: string }

set_river_spline_points

Destructive, idempotent.

Set ANY water body's spline path from world points, then synchronize the water spline metadata and RE-READ the spline (point count + closed-loop) to prove it landed.

Parameter	Type	Required	Description
water_body_label	string	yes	Label of the AWaterBody actor. DESPITE THE COMMAND NAME THIS IS NOT RIVER-ONLY: it works on any water body that has a UWaterSplineComponent -- lake, ocean, river, custom -- and it is the only way to give a LAKE its real shoreline, because the spline the actor factory creates is an arbitrary CLOSED triangle (3 points) that has nothing to do with the basin. closed_loop is a property of the spline and is NOT touched here: set 12 points on a factory-made lake and you get 12 points still closed.
points	array	yes	Array of [X, Y, Z] WORLD points (>= 2) defining the spline. Entries that are not a >= 3-element numeric array are skipped silently; requested_point_count reports how many survived parsing.

Returns: { water_body_label: string, point_count: int (RE-READ), spline_point_count_actual: int (RE-READ, same value, unambiguously named), closed_loop_actual: bool (RE-READ), requested_point_count: int, applied: bool (DERIVED: read-back count == requested count) }

set_river_width_depth_at_point

Destructive, idempotent.

Set a river's width and/or depth at a spline input key (river water bodies only); reads them back.

Parameter	Type	Required	Description
water_body_label	string	yes	Label of the AWaterBodyRiver actor
input_key	number	yes	Spline input key at which to set width/depth
width	number	no	Optional new river width at the key
depth	number	no	Optional new river depth at the key

Returns: { water_body_label: string, input_key: number, width: number, depth: number, applied: bool }

set_river_widths_depths

Destructive, idempotent.

Set a river's width and/or depth at EVERY spline point in one call (bulk taper authoring) with a single metadata-sync at the end — avoids one MCP round-trip per point. Arrays are indexed by spline point (point i maps to spline input key i) and, when provided, MUST have exactly point_count entries. River water bodies only. Reads back the applied per-point arrays.

Parameter	Type	Required	Description
water_body_label	string	yes	Label of the AWaterBodyRiver actor
widths	array	no	Optional array of per-point river widths (length must equal point_count)
depths	array	no	Optional array of per-point river depths (length must equal point_count)

Returns: { water_body_label: string, point_count: int, applied_widths: bool, applied_depths: bool, widths: [number], depths: [number] }

set_water_body_gerstner_waves

Destructive, idempotent.

Build a Gerstner wave set (UGerstnerWaterWaves + simple parametric generator) and apply it to a wave-supporting water body (Lake/Ocean; rivers are rejected). The generator ramps per-wave Steepness from large_wave_steepness to small_wave_steepness; the no-self-intersection (no fold, no black-crest) criterion is total_steepness (returned) <= 1 — lower the two steepness params and/or num_waves if it exceeds 1.

Parameter	Type	Required	Description
water_body_label	string	yes	Label of the AWaterBody actor (must support waves: Lake or Ocean)
num_waves	number	no	Optional wave count for the generator (>= 1; default 16)
min_wavelength	number	no	Optional minimum wavelength in uu
max_wavelength	number	no	Optional maximum wavelength in uu
min_amplitude	number	no	Optional minimum wave amplitude in uu
max_amplitude	number	no	Optional maximum wave amplitude in uu
wind_angle	number	no	Optional dominant wind angle in degrees
small_wave_steepness	number	no	Optional steepness of the smallest wave (generator default 0.4)
large_wave_steepness	number	no	Optional steepness of the largest wave (generator default 0.2)
steepness_falloff	number	no	Optional exponent shaping the small->large steepness ramp (generator default 1.0)

Returns: { water_body_label: string, wave_supported: bool, has_waves: bool, num_waves: int, max_wave_height: number, total_steepness: number, applied: bool }

set_water_body_gerstner_waves_spectrum

Destructive, idempotent.

Build a Gerstner wave set using the oceanology spectrum generator (octaves of a known wave spectrum) and apply it to a wave-supporting water body (Lake/Ocean).

Parameter	Type	Required	Description
water_body_label	string	yes	Label of the AWaterBody actor (Lake/Ocean)
spectrum_type	string	no	Wave spectrum: Phillips (default), PiersonMoskowitz, or JONSWAP
octaves	array	no	Optional array of octaves, each { num_waves?, amplitude_scale?, main_direction?, spread_angle?, uniform_spread? }; one default octave is used if omitted

Returns: { water_body_label: string, wave_supported: bool, has_waves: bool, num_waves: int, max_wave_height: number, spectrum_type: string, octave_count: int, applied: bool, note: string }

set_water_body_material

Destructive, idempotent.

Set the surface water material on a water body (resolved by asset path).

Parameter	Type	Required	Description
water_body_label	string	yes	Label of the AWaterBody actor
material_path	string	yes	Asset path of the UMaterialInterface to assign

Returns: { water_body_label: string, material: string, set: bool }

set_water_body_properties

Destructive, idempotent.

Partial-update a water body's properties (only the keys present are applied); each applied field is read back with already_set when it already matched.

Parameter	Type	Required	Description
water_body_label	string	yes	Label of the AWaterBody actor (Lake/Ocean/River)
input_key	number	yes	Spline input key for water_velocity/audio_intensity (required only when either is set)
water_velocity	number	no	River/spline water velocity to set at input_key (requires input_key)
audio_intensity	number	no	Spline audio intensity to set at input_key (requires input_key)
target_wave_mask_depth	number	no	Water depth at which waves start being attenuated
max_wave_height_offset	number	no	Offset added to the automatically calculated max wave height bounds
collision_height_offset	number	no	Distance above the water surface where collision checks still occur
shape_dilation	number	no	Shape dilation in uu
affects_landscape	boolean	no	Whether the landscape is deformed by this water body
post_process_blend_weight	number	no	Underwater post-process blend weight (0..1)
water_height_offset	number	no	Ocean-only additional water height (errors on non-ocean bodies)

Returns: { water_body_label: string, body_type: string, applied: [string], fields: { <name>: { value, already_set } } }