Installation

OceanSim is split into a Godot simulator project and an editable Python SDK package. The simulator owns the real-time runtime and exposes TCP port 9876 by default. The Python SDK connects to that running process for external control, sensing, recording, and replay.

Requirements

Requirement	Purpose
Godot 4.5+	Open and run project.godot in the oceansim folder.
Python 3.8+	Install and run oceansim_client.
NumPy	Required by the SDK for state vectors, point clouds, mapping, and coordinate conversion.
Gymnasium optional	Required only for Gym-style reinforcement-learning examples.

Run the simulator

Open the Godot project and run the configured entry scene, res://scenes/FrontView.tscn.

cd C:\path\to\OceanSim\oceansim
godot --path .

Install the SDK

Install the Python package from the project-local python folder. Editable mode is recommended while the simulator and SDK are evolving together.

cd C:\path\to\OceanSim\oceansim
pip install -e python
pip install -e "python[all]"   # optional Gym examples

Connection check

from oceansim_client import OceanSimClient

client = OceanSimClient(host="localhost", port=9876, timeout=5.0)
if client.connect():
    response = client.send_command("get_state")
    print(response["type"], response.get("status"))
    client.disconnect()

If the client cannot connect, confirm that the Godot project is running and that no other process is using port 9876.