water kit

22 tools. Generated from the plugin source; do not edit by hand.

Guide

The water kit authors UE 5 Water-plugin content in the editor world: water bodies (river, lake, ocean, custom), water zones, the water spline and its per-point metadata, landscape carving, buoyancy and surface queries. Every tool needs UE 5.0+ and the Water plugin enabled; the kit module is only loaded when the plugin is on, so when edit.search_tools shows no water.* tool, enable the plugin (Edit > Plugins > Water) and restart the editor. All water tooling lives here — the landscape kit has no water tools.

Actors are referenced with actor: the outliner label, the object name, or the actor path (the same resolver as every other kit; zero or several matches are an error).

1. Bodies and zones

• water.list_bodies / water.get_body report label, path, class, type (River, Lake, Ocean, Custom), location, owning zone (5.1+), splinePoints, affectsLandscape and material.
• water.add_body {type, name, location, rotation} spawns a body with the class default spline; water.remove_body deletes it.
• A water zone renders every body inside its extent: water.add_zone {name, location}, water.list_zones, water.get_zone, water.remove_zone. After large edits call water.rebuild_zone to force the water mesh and water info texture to regenerate.
• water.audit_world lists bodies and zones with warnings (no bodies, bodies without a material, fewer than two spline points, bodies outside any zone and zones rendering nothing on 5.1+). It never fails on an empty world; read warnings.

2. Settings, material and landscape carving

• water.get_settings {actor, keys} reads reflected properties. For a body they are read from its WaterBodyComponent (where all body settings live in UE 5); for a zone from the zone actor. Empty keys returns every editable top-level property with its current text value — use it to discover names.
• water.set_settings {actor, settings:[{key,value}]} writes values in engine text form; dotted paths reach struct members (WaterHeightmapSettings.FalloffSettings.FalloffWidth, CurveSettings.ChannelDepth, zone ZoneExtent, OverlapPriority...). Every key is resolved before the first write, and each write runs the editor change notification, so the body or zone rebuilds as in the details panel. A value that does not parse restores the values already written and returns E_INVALID_ARG.
• water.set_material {actor, material} assigns the surface material.
• water.get_carve / water.set_carve expose the landscape interaction as one typed struct: affectsLandscape, blendMode (AlphaBlend, Min, Max, Additive), falloffMode (Angle, Width), falloffAngle, falloffWidth, edgeOffset, zOffset, useCurveChannel, channelDepth, channelEdgeOffset, curveRampWidth. set_carve writes all fields: read, modify, write back.

3. Spline and river metadata

• water.list_spline_points returns each point's body-relative and world location plus its water metadata (depth, width, velocity, audioIntensity) and whether the spline is closed.
• water.add_spline_point {actor, index, location, world} inserts at index (-1 appends); water.set_spline_point moves a point; water.remove_spline_point removes one (a body keeps at least two points). world:false (default) means relative to the water body.
• water.set_river_point {actor, index, depth, width, velocity, audioIntensity} writes the per-point metadata in one call (all four values). Width and velocity matter for rivers; depth for every spline body.
• Every spline edit runs the water spline's change path (metadata sync + data-changed broadcast), which rebuilds the body and its landscape carve.

4. Buoyancy and queries

• water.add_buoyancy {actor, pontoons:[{location, radius, socket}]} adds a BuoyancyComponent to a level actor, or replaces the pontoons of the one it already has (created tells which). The actor floats only when its root primitive simulates physics; the reply warns otherwise.
• water.query_surface {actor, location} returns the surface point, normal, velocity, depth and heightAboveSurface (negative = submerged) for a world location — useful to place floating props.

Recipe: a river that carves a landscape

1. water.add_zone {name:'WaterZone', location:{x:0,y:0,z:0}} (skip if water.list_zones has one).
2. water.add_body {type:'river', name:'River01', location:{x:0,y:0,z:100}}.
3. water.list_spline_points {actor:'River01'}; then water.set_spline_point / water.add_spline_point to lay out the course (body-relative centimetres).
4. water.set_river_point {actor:'River01', index:i, depth:200, width:1500, velocity:150} per point.
5. water.get_carve {actor:'River01'}, adjust (affectsLandscape:true, falloffWidth, channelDepth), water.set_carve with the full struct.
6. water.set_material if the default water material is not wanted.
7. water.rebuild_zone {actor:'WaterZone'} and water.audit_world to confirm no warnings.

Gotchas

• Without a WaterBodyCollision collision profile the Water editor logs a Load Errors entry whose "Add entry to DefaultEngine.ini?" action writes project config. The kit never writes config: add the profile to [/Script/Engine.CollisionProfile] yourself (QueryOnly, WorldStatic; Visibility and Camera ignored; WorldDynamic, Pawn, PhysicsBody, Vehicle, Destructible overlapped).
• UE 5.0 has no public accessor for a body's water zone: zone is empty and the zone checks of audit_world are skipped there.
• Ocean bodies need a water zone to render; landscape carving needs a landscape with edit layers (the Water brush is an edit-layer brush) — see landscape.list_edit_layers.
• UE 4.27 ships only an experimental Water plugin with a different API; the kit is UE 5 only.

Tools

Legend. risk 0 = read-only, 1 = harmless editor op, 2 = modifies asset, 3 = deletes/replaces asset, 4 = project/config/build op, 5 = potentially destructive (calls above MaxAutoRisk need "_confirm": true). mutates = runs in a transaction (edit.undo reverts). requires PIE / requires world = refused without a PIE session / an open level. requires plugin = unavailable while the plugin is disabled. dryRun = honours the dryRun argument. smoke = covered by edit.self_test.

water.add_body (risk 2, mutates, UE 5.0+, requires plugin Water, requires world, smoke)

Spawns a water body (river, lake, ocean or custom) with its default spline; returns it.

Argument	Type	Description
type	string	required. river, lake, ocean or custom.
name	string	required. Outliner label of the new actor.
location	{x,y,z}	World location in centimetres.
rotation	{x,y,z}	World rotation in degrees (pitch, yaw, roll).

Returns: items, count, warnings, message.

water.add_buoyancy (risk 2, mutates, UE 5.0+, requires plugin Water, requires world, smoke)

Gives a level actor a BuoyancyComponent with the given pontoons (replaces the pontoons when it already has one). The root must simulate physics to float.

Argument	Type	Description
actor	string	required. Level actor that receives (or already has) a BuoyancyComponent.
pontoons	array of UeaWaterPontoon	required. Pontoons, replacing any existing ones (at least one).

Returns: actor, component, created, pontoons, warnings.

water.add_spline_point (risk 2, mutates, UE 5.0+, requires plugin Water, requires world, smoke)

Inserts a spline point at index (-1 appends); location is relative to the body unless world is true.

Argument	Type	Description
actor	string	required. Water body actor.
index	integer	Zero-based spline point index; -1 appends (add only). Default -1.
location	{x,y,z}	Point location in centimetres.
world	boolean	true: location is in world space; false: relative to the water body. Default false.

Returns: water, points, closedLoop.

water.add_zone (risk 2, mutates, UE 5.0+, requires plugin Water, requires world, smoke)

Spawns a water zone (the actor that renders water bodies inside its extent); returns it.

Argument	Type	Description
name	string	required. Outliner label of the new water zone.
location	{x,y,z}	World location in centimetres.

Returns: items, count, warnings, message.

water.audit_world (risk 0, UE 5.0+, requires plugin Water, requires world, smoke)

Reports water setup problems: no bodies, bodies without a zone, bodies without a material, zones without bodies.

Argument	Type	Description
actor	string	Water body or water zone actor label, object name, or path.

Returns: items, count, warnings, message.

water.get_body (risk 0, UE 5.0+, requires plugin Water, requires world, smoke)

Returns one water body.

Argument	Type	Description
actor	string	Water body or water zone actor label, object name, or path.

Returns: items, count, warnings, message.

water.get_carve (risk 0, UE 5.0+, requires plugin Water, requires world, smoke)

Returns how a water body carves the landscape (affectsLandscape, brush blend and falloff, channel curve).

Argument	Type	Description
actor	string	Water body or water zone actor label, object name, or path.

Returns: water, carve.

water.get_settings (risk 0, UE 5.0+, requires plugin Water, requires world, smoke)

Reads reflected properties of a water body's WaterBodyComponent or of a water zone (empty keys: every editable top-level property).

Argument	Type	Description
actor	string	required. Water body (read from its WaterBodyComponent) or water zone actor.
keys	array of string	Property paths to read; empty returns every editable top-level property.

Returns: water, settings.

water.get_zone (risk 0, UE 5.0+, requires plugin Water, requires world, smoke)

Returns one water zone.

Argument	Type	Description
actor	string	Water body or water zone actor label, object name, or path.

Returns: items, count, warnings, message.

water.list_bodies (risk 0, UE 5.0+, requires plugin Water, requires world, smoke)

Lists water body actors (river, lake, ocean, custom) with type, zone, spline point count, carve flag and material.

Argument	Type	Description
actor	string	Water body or water zone actor label, object name, or path.

Returns: items, count, warnings, message.

water.list_spline_points (risk 0, UE 5.0+, requires plugin Water, requires world, smoke)

Lists the spline points of a water body with local/world location and per-point depth, width, velocity and audio metadata.

Argument	Type	Description
actor	string	Water body or water zone actor label, object name, or path.

Returns: water, points, closedLoop.

water.list_zones (risk 0, UE 5.0+, requires plugin Water, requires world, smoke)

Lists water zone actors.

Argument	Type	Description
actor	string	Water body or water zone actor label, object name, or path.

Returns: items, count, warnings, message.

water.query_surface (risk 0, UE 5.0+, requires plugin Water, requires world, smoke)

Queries a water body at a world location: surface point and normal, velocity, depth, and height above the surface.

Argument	Type	Description
actor	string	required. Water body actor.
location	{x,y,z}	World location to query, in centimetres.

Returns: surfaceLocation, surfaceNormal, velocity, depth, heightAboveSurface.

water.rebuild_zone (risk 2, mutates, UE 5.0+, requires plugin Water, requires world, smoke)

Forces a water zone to rebuild its water mesh and water info texture.

Argument	Type	Description
actor	string	Water body or water zone actor label, object name, or path.

Returns: items, count, warnings, message.

water.remove_body (risk 3, mutates, destructive, UE 5.0+, requires plugin Water, requires world, smoke)

Deletes a water body actor.

Argument	Type	Description
actor	string	Water body or water zone actor label, object name, or path.

Returns: items, count, warnings, message.

water.remove_spline_point (risk 3, mutates, destructive, UE 5.0+, requires plugin Water, requires world, smoke)

Removes a spline point (a body keeps at least two points).

Argument	Type	Description
actor	string	required. Water body actor.
index	integer	Zero-based spline point index. Default 0.

Returns: water, points, closedLoop.

water.remove_zone (risk 3, mutates, destructive, UE 5.0+, requires plugin Water, requires world, smoke)

Deletes a water zone actor.

Argument	Type	Description
actor	string	Water body or water zone actor label, object name, or path.

Returns: items, count, warnings, message.

water.set_carve (risk 2, mutates, UE 5.0+, requires plugin Water, requires world, smoke)

Writes the complete landscape carve settings of a water body (read them with water.get_carve first).

Argument	Type	Description
actor	string	required. Water body actor.
carve	UeaWaterCarve	Complete carve settings (read them first with water.get_carve).

Returns: water, carve.

water.set_material (risk 2, mutates, UE 5.0+, requires plugin Water, requires world, smoke)

Sets the water surface material of a water body.

Argument	Type	Description
actor	string	required. Water body actor.
material	string	required. Water surface material or material instance.

Returns: water, settings.

water.set_river_point (risk 2, mutates, UE 5.0+, requires plugin Water, requires world, smoke)

Writes the per-point water metadata of a spline point: depth, river width, flow velocity and audio intensity.

Argument	Type	Description
actor	string	required. Water body actor (river, lake or ocean spline).
index	integer	Zero-based spline point index. Default 0.
depth	number	Channel depth at the point in centimetres (>= 0). Default 100.
width	number	River width at the point in centimetres (> 0; rivers only). Default 1000.
velocity	number	Flow velocity scalar at the point (rivers). Default 100.
audioIntensity	number	Audio intensity at the point (0..1). Default 0.

Returns: water, points, closedLoop.

water.set_settings (risk 2, mutates, UE 5.0+, requires plugin Water, requires world, smoke)

Assigns reflected properties on a water body's WaterBodyComponent or on a water zone, then runs the editor change notification so the water rebuilds. All keys are validated before any is written.

Argument	Type	Description
actor	string	required. Water body (settings live on its WaterBodyComponent) or water zone actor.
settings	array of UeaKeyValue	Property assignments in engine text form; dotted paths reach struct members (e.g. WaterHeightmapSettings.FalloffSettings.FalloffWidth).

Returns: water, settings.

water.set_spline_point (risk 2, mutates, UE 5.0+, requires plugin Water, requires world, smoke)

Moves an existing spline point; location is relative to the body unless world is true.

Argument	Type	Description
actor	string	required. Water body actor.
index	integer	Zero-based spline point index; -1 appends (add only). Default -1.
location	{x,y,z}	Point location in centimetres.
world	boolean	true: location is in world space; false: relative to the water body. Default false.

Returns: water, points, closedLoop.