Skip to Content
defold-typescript libraries
selimanac

selimanac/defold-wave/wave

Wave simulation that floats, pitches and rolls game objects on a water surface.

  • GitHub: selimanac/defold-wave — pinned to 76ff0c9
    1. This repo publishes no releases or tags. Add a commit archive URL — for the pinned commit, https://github.com/selimanac/defold-wave/archive/76ff0c9780730a7e7cc4f3e0a8752d8c1f426def.zip — to game.project under [project] dependencies, then Fetch Libraries in the Defold editor.
    2. Run bunx @defold-typescript/cli resolve to materialize its types.
    3. Import it under a namespace alias of your choice:
      import * as wave from "wave"

Functions

init(wave1_direction: number, wave1_amplitude: number, wave1_wavelength: number, wave1_speed: number, wave2_direction: number, wave2_amplitude: number, wave2_wavelength: number, wave2_speed: number, time_speed: number, gameobject_capacity: number)

Initialize the wave simulation. Call it once before any other wave function, with the same parameters the water shader uses.

Parameters

  • wave1_direction: number — Wave 1 direction (0.0 to 2.0, multiplied by π internally).
  • wave1_amplitude: number — Wave 1 height in world units.
  • wave1_wavelength: number — Wave 1 distance between peaks.
  • wave1_speed: number — Wave 1 animation speed.
  • wave2_direction: number — Wave 2 direction (0.0 to 2.0).
  • wave2_amplitude: number — Wave 2 height in world units.
  • wave2_wavelength: number — Wave 2 distance between peaks.
  • wave2_speed: number — Wave 2 animation speed.
  • time_speed: number — Global time multiplier.
  • gameobject_capacity: number — Pre-allocated entity table size (for example 256), fixed at init time.

add_gameobject(instance: SceneGameObjectAddress | Hash | Url, float_offset: number, water_base_y: number, sample_distance: number, rotation_smoothing?: number, use_world_transform?: boolean, forward?: Vector3): number

Add a floating game object to the wave simulation.

The model must face -Z in its unrotated state: wave sampling, pitch, roll and movement all assume it. To face another way at runtime, call set_yaw after registration, or pass the matching forward.

Parameters

  • instance: SceneGameObjectAddress | Hash | Url — The game object.
  • float_offset: number — Vertical offset from the water surface.
  • water_base_y: number — Y coordinate of the flat water plane.
  • sample_distance: number — Probe offset used to compute the pitch and roll normals.
  • rotation_smoothing?: number — SLERP factor: 0 or omitted disables rotation, 1 snaps instantly.
  • use_world_transform?: boolean — true for objects nested under another moving object, false for root objects.
  • forward?: Vector3 — World-space direction the model's nose faces at registration. Default is vmath.vector3(0, 0, -1).

Returns

  • number — The floater ID used by every later call, or 0 on error such as exceeded capacity.

update_wave1(direction: number, amplitude: number, wavelength: number, speed: number)

Live-update the wave 1 parameters. Call it in sync with the water shader's wave 1 update to keep visuals and physics aligned.

Parameters

  • direction: number — Wave direction.
  • amplitude: number — Wave height.
  • wavelength: number — Distance between peaks.
  • speed: number — Animation speed.

update_wave2(direction: number, amplitude: number, wavelength: number, speed: number)

Live-update the wave 2 parameters. Call it in sync with the water shader's wave 2 update to keep visuals and physics aligned.

Parameters

  • direction: number — Wave direction.
  • amplitude: number — Wave height.
  • wavelength: number — Distance between peaks.
  • speed: number — Animation speed.

get_wave1_height(pos_x: number, pos_z: number, time: number): number

Sample the wave 1 height at a world position, at the simulation's current time.

Parameters

  • pos_x: number — World X.
  • pos_z: number — World Z.
  • time: number — Required by the runtime; the sample uses the simulation's own clock instead.

Returns

  • number — The wave height.

get_wave2_height(pos_x: number, pos_z: number, time: number): number

Sample the wave 2 height at a world position, at the simulation's current time.

Parameters

  • pos_x: number — World X.
  • pos_z: number — World Z.
  • time: number — Required by the runtime; the sample uses the simulation's own clock instead.

Returns

  • number — The wave height.

set_yaw(id: number, yaw: number)

Override the yaw (heading) of a floater, for steering such as a boat turning.

Parameters

  • id: number — Floater ID.
  • yaw: number — Yaw in radians.

move(id: number, max_speed: number, speed_factor: number)

Begin moving a floater forward at up to max_speed, accelerating by speed_factor per second.

Parameters

  • id: number — Floater ID.
  • max_speed: number — Target and maximum speed in world units per second.
  • speed_factor: number — Acceleration factor; higher ramps up faster.

stop(id: number)

Stop a floater. Its target speed becomes 0 and it decelerates smoothly by its speed factor.

Parameters

  • id: number — Floater ID.

pause(state: boolean)

Pause or resume the wave update loop without removing entities.

Parameters

  • state: boolean — true to pause, false to resume.

is_pause(): boolean

Whether the wave update loop is paused.

Returns

  • boolean — true when paused.

shutdown()

Shut down the wave simulation and free all resources. The extension finalizer calls it automatically; call it yourself only to reinitialize.

On this page