3D Physics Wave Simulator

An interactive Python wave simulator using only the standard library. It renders a 3D water surface with a directional Gerstner-style gravity wave and live controls for:

• Wave speed
• Wave height
• Wave length
• Wave direction
• Water mesh resolution
• Object-wave coupling
• STL geometry floating on the wave surface
• Object scale, relative density, and inertia
• Object mesh detail for large STL files

The simulator computes the surface from:

eta(x, y, t) = A sin(k * dot(direction, position) - omega * t)
k = 2*pi / wavelength
omega = speed * k

It also includes horizontal particle displacement, which gives wave crests a more physical shape than a simple vertical sine surface.

STL files can be loaded from the control panel. The simulator accepts ASCII and binary STL files, normalizes the mesh to fit the scene, and models buoyancy by sampling the mesh against the live wave surface. Density is relative to water: values below 1.0 float, while values above 1.0 sink lower.

The floating object also feeds back into the rendered water. Object-wave coupling controls the strength of the displaced-water mound, hull shadow, and heave-driven ripples around the mesh.

Object motion includes simple translational and rotational inertia. The inertia model uses the STL's dimensions, object scale, and density so larger/heavier meshes respond more slowly to wave slope and direction changes.

Yaw alignment is calculated from the STL geometry: the simulator finds the object's horizontal minimum-inertia axis and rotates that axis toward the wave crest direction instead of assuming the mesh's local X axis is the important one.

Large STL files are automatically downsampled for display. Object mesh detail sets the triangle budget used when loading an STL; lower values keep the simulator responsive, while higher values show more geometry at the cost of frame rate. If a large file feels slow, reduce Object mesh detail and load the STL again.

Run

If Python is on your PATH:

python wave_simulator.py

In this Codex workspace, the bundled Python runtime can run it directly:

& 'C:\Users\User\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe' wave_simulator.py

Controls

• Drag on the water surface to rotate the 3D camera.
• Use the mouse wheel to zoom.
• Use the sliders to adjust wave speed, height, length, and travel direction.
• Adjust Mesh resolution for a coarser or smoother water surface.
• Adjust Object-wave coupling from 0.0 to 4.0 to control how strongly the floating mesh disturbs the water.
• Click Load STL to place your own geometry onto the waves.
• Adjust Object scale, Density, and Object inertia to change the floating behavior.
• Adjust Object mesh detail before loading a large STL to control rendering speed.
• Press Pause to freeze or resume the simulation.

sample_float.stl is included as a simple buoyancy test mesh. simple_helicopter.stl is included as a low-poly helicopter object.