Agents and Runtime

OceanSim agents are runtime-controlled participants in a marine scenario. The main AUV is a physical vehicle with thrusters, buoyancy, hydrodynamic terms, and onboard sensors. Dynamic proxy agents are lightweight moving participants used for obstacle-avoidance, communication, tracking, and multi-target experiments.

The goal is to keep experiment setup explicit: scenario files describe the map, vehicle roles, initial placement, motion policy, and sensor expectations; Python code controls the run through typed wrappers and protocol actions.

Agent roles

Role	Description
main_auv	The controllable physical AUV. It owns the primary state, sensors, force control, thruster control, dataset export hooks, and navigation overlays.
proxy_auv	A lightweight dynamic participant. It can move autonomously or accept an external velocity command and is included in occupancy grids and agent summaries.
static_obstacle	Non-moving map geometry managed by the obstacle system rather than the agent system.

Control contracts

OceanSim documents each control mode as an action contract. The contract names the vector fields, units, and coordinate frame so controllers, RL policies, and dataset replays can be compared without reading simulator internals.

Control scheme	Action vector	Use
force_3d	[fx, fy, fz] in Newtons	Main AUV force control through the world-frame set_force_world entry.
body_force_3d	[fx, fy, fz] in Newtons	Main AUV force control through the body-frame set_force_body entry.
thrusters	[thruster_0, thruster_1, thruster_2, thruster_3, thruster_4, thruster_5]	Direct actuator experiments using vehicle-profile ordering.
external_velocity	[vx, vy, vz] in m/s	Proxy AUV motion in the Godot world frame.
waypoint_pid	[world_x, world_z, depth]	High-level target tracking through Python control utilities.
body_wrench_6dof	[fx, fy, fz, tx, ty, tz]	Body-frame force/torque contract for six-degree controller research.
body_velocity_6dof	[u, v, w, p, q, r]	Body-frame linear/angular velocity contract.
custom_dynamics_6dof	[lin_ax, lin_ay, lin_az, ang_ax, ang_ay, ang_az]	Reserved for model-driven six-degree dynamics research.

Python example

from oceansim_client import AUV, AgentDefinition, AgentFactory

with AUV() as auv:
    main = AgentFactory.build_agent(
        auv,
        AgentDefinition(agent_name="auv/main", control_scheme="force_3d"),
        spawn=False,
    )
    main.act([0.0, 120.0, 0.0])

    target = AgentFactory.build_agent(
        auv,
        {
            "agent_name": "target_01",
            "agent_type": "proxy_auv",
            "is_main_agent": False,
            "location": [4.0, -7.0, 6.0],
            "control_scheme": "external_velocity",
            "metadata": {"role": "moving_target"},
        },
    )
    target.act([0.2, 0.0, -0.1])

Scenario definition

Scenario files keep agent configuration explicit and versioned. Every public scenario declares the main AUV in an agents array; dynamic proxy agents can be added with the same shape and are spawned by the scenario loader when is_main_agent is false.

{
  "schema_version": 1,
  "id": "Dynamic_Map",
  "display_name": "Dynamic Obstacle Benchmark Field",
  "generator": "benchmark_dynamic_field",
  "map_size_m": [40.0, 40.0],
  "agents": [
    {
      "schema_version": 1,
      "agent_name": "auv/main",
      "agent_type": "main_auv",
      "is_main_agent": true,
      "profile": "oceansim_torpedo_auv",
      "location": [0.0, -6.0, -17.0],
      "rotation": [0.0, 0.0, 0.0],
      "control_scheme": "force_3d",
      "sensors": [
        "depth",
        "imu",
        "dvl",
        "camera",
        "rgbd_dense_cloud",
        "lidar_2d",
        "lidar_3d",
        "imaging_sonar",
        "multibeam_sonar",
        "side_scan_sonar"
      ],
      "metadata": {
        "role": "ego_vehicle",
        "semantic_label": "auv",
        "tags": ["main", "controlled", "dynamic_benchmark"]
      }
    },
    {
      "schema_version": 1,
      "agent_name": "target_01",
      "agent_type": "proxy_auv",
      "is_main_agent": false,
      "location": [4.0, -7.0, 6.0],
      "rotation": [0.0, 0.0, 0.0],
      "control_scheme": "external_velocity",
      "metadata": {
        "role": "moving_target",
        "semantic_label": "auv",
        "tags": ["dynamic", "vehicle"]
      }
    }
  ]
}

Scenario agent fields

Field	Meaning
schema_version	Version of the agent definition format.
agent_name	Stable runtime identifier, for example auv/main or target_01.
agent_type	Logical role such as main_auv or proxy_auv.
is_main_agent	true for the scene-owned physical AUV; false for spawned proxy agents.
profile	Vehicle or runtime profile name.
location / rotation	Initial pose fields in Godot-world coordinates and degrees.
control_scheme	Action contract used by the agent.
sensors	Sensor names or typed sensor declaration dictionaries.
metadata	Role, semantic label, tags, and experiment annotations.

Runtime state fields

get_agents exposes a versioned runtime summary. Dynamic proxy agents are reported by the agent manager; the main AUV can be represented with the same field names for replay and dataset tooling.

Field	Meaning
schema_version	Runtime state schema version.
id / agent_name	Stable runtime identifier.
agent_type / profile	Logical role and vehicle/runtime profile.
shape / semantic_label / tags	Visualization shape, semantic class, and grouping labels.
position / pose.position / pose.rotation_rpy	Runtime pose in the simulator frame.
pose.rotation_quat_xyzw	Optional quaternion rotation, currently provided by the main AUV.
velocity / angular_velocity	Linear velocity summary and optional body angular velocity.
mode / speed	Motion mode and scalar speed summary.
size_m / proxy_auv	Runtime footprint and whether the entry is a lightweight proxy.
control_scheme / control_mode	Active control contract.
action_space / available_action_spaces	Machine-readable shape, fields, units, frame, optional bounds, and main AUV alternatives.
sensors	Sensor declarations or sensor summaries associated with the agent.
last_command / last_command_time / control_status	Runtime diagnostics for replay and debugging.
controller_state	Recordable controller diagnostics such as waypoint error, integral, target, and saturation flags.
depth_min / depth_max	Optional proxy-agent depth limits.
metadata	Role, tags, semantic label, and experiment-specific annotations.

Export trace fields

agent_timeline.jsonl links each agent sample to the frame-level state, command, sensor summary, and frame identifiers used by replay tools.

Field	Meaning
state	Full agent state snapshot for that timeline row.
command	Last recorded command envelope, including the command frame when present.
sensor_sequences	Per-agent sensor declarations or main-AUV sensor sequence summaries.
frame_trace	world_frame, base_frame, sensor_frames, and command_frame used to connect data exports back to the runtime agent.

Multi-agent workflow

The recommended workflow keeps configuration, launch, control, recording, and replay separated:

1. Configure the scenario JSON with the main AUV and any proxy agents needed by the experiment.

2. Start OceanSim and select the scenario through set_scenario or the UI.

3. Use AgentFactory.build_agent for typed Python bindings.

4. Send actions through OceanSimAgent.act so vector length and bounds are checked before TCP dispatch.

5. Record the run with the dataset tools when sensor payloads, commands, and replay metadata are needed.

6. Re-open the export with OceanSimRunReplay for offline inspection.

Recommended release checks

• Verify that get_agents returns every dynamic agent with position, mode, size, role metadata, action space, and control scheme.

• Verify that each documented action vector is accepted or rejected according to its ActionSpace.

• Verify that python tools\scenario_agent_schema_smoke.py accepts every scenario JSON file.

• Verify that dynamic agents appear in occupancy grids when include_dynamic_agents is enabled.

• Verify that acoustic communication tests cover latency, range, bandwidth, and packet-drop settings.