Using OceanSim

OceanSim is designed around an external-controller workflow. Godot owns the real-time world state and sensor simulation. Python clients query state, issue controls, visualize plans, and export datasets through the TCP protocol.

Runtime model

Layer	Responsibilities
Godot runtime	Scene update, AUV physics, water/current effects, map generation, sensors, UI, TCP server, and export commands.
TCP protocol	Stable command boundary using newline-delimited JSON messages with protocol versioning and request IDs.
Python SDK	Connection lifecycle, typed AUV wrapper, sensor validation, coordinate utilities, mapping helpers, and recording/replay tools.

Coordinate frames

AUVState.position uses the OceanSim user frame, which is compatible with ROS ENU: x=east/right, y=north/forward, and z=up. Godot uses a Y-up world frame internally.

Conversion	Mapping
Godot XYZ to OceanSim / ENU	`[X, -Z, Y]`
OceanSim / ENU to Godot XYZ	`[x, z, -y]`
OceanSim / ENU to ROS NED	`[y, x, -z]`

Use the SDK helpers in oceansim_client.coordinates instead of hand-writing sign flips in controller code.

Workflow patterns

Workflow	Recommended API surface
Scripted control	`AUV.set_force()`, `AUV.set_pose()`, `AUV.get_state()`, and `AUV.get_sensors()`.
LLM or MPC navigation	`get_lidar_2d()`, `get_terrain_grid()`, `set_nav_path()`, `set_pred_trajectory()`, and `set_force()`.
RL online training	`AUV.reset()` and `AUV.step(action)`, where each step updates state and sensor observations.
Dataset capture	`OceanSimPklRecorder`, `AUV.export_dataset()`, `OceanSimRunReplay`, and robotics export helpers.

Minimal loop

from oceansim_client import AUV

with AUV(host="localhost", port=9876) as auv:
    state = auv.get_state()
    print(state.position, state.depth)
    auv.set_force(0.0, 120.0, 0.0)
    sensors = auv.get_sensors()
    print(sensors.keys())