Add a read-only active GAMA experiment validation API to the existing Monitor WebSocket

[FlorianBarbe]

Context

Before entering Play Mode or generating a preview, the SIMPLE Unity package needs a Webplatform API operation to determine whether the current GAMA environment can be used safely.

Unity must distinguish between:

• the Webplatform not being connected to GAMA;
• no active GAMA experiment being available;
• an active experiment not exposing the SIMPLE Unity contract;
• a validation that could not be completed because of a timeout, stale state, malformed response, or technical error.

The Webplatform must return technical, machine-readable information only. Unity remains responsible for deciding whether the operation may continue and for displaying and localizing the appropriate popup.

Goal

Add one read-only request/response API operation over the existing Monitor WebSocket, answering:

Is the currently active GAMA experiment ready to be used by SIMPLE Unity?

The operation must validate:

1. the Webplatform-to-GAMA connection;
2. the presence of an active experiment or simulation;
3. the runtime capabilities required by SIMPLE Unity;
4. whether the result can be considered reliable.

This must extend the existing Monitor WebSocket API and reuse its targeted response mechanism. It must not introduce a new HTTP API or another WebSocket server.

Suggested Monitor WebSocket API request

The exact message names can follow the repository conventions, but the request should contain a unique identifier generated by Unity.

{
  "type": "validate_active_experiment",
  "request_id": "unity-validation-123",
  "context": "play_mode"
}

Fields:

• type: identifies this operation;
• request_id: required opaque identifier used to correlate the response;
• context: optional diagnostic value such as play_mode or preview_mode.

An invalid request must return a structured error without closing the Monitor WebSocket.

Suggested Monitor WebSocket API response

The response should keep the overall status separate from the technical reason.

Suggested statuses:

Status	Meaning
ready	The active environment can be used by SIMPLE Unity.
blocked	A known blocking condition was detected.
error	The validation could not be completed reliably.

Suggested reasons:

Reason	Meaning
gama_disconnected	The Webplatform is not connected to GAMA.
no_active_experiment	No usable active experiment or simulation can be queried.
incompatible	The active experiment does not expose the required SIMPLE Unity capabilities.
invalid_request	The Unity request is malformed.
timeout	The read-only GAMA probe did not complete in time.
invalid_probe_response	GAMA returned a response that cannot be interpreted.
probe_failed	GAMA rejected the probe or returned a technical error.
experiment_changed	The active experiment changed while validation was pending.
unknown	An unexpected technical error occurred.

Example response:

{
  "type": "active_experiment_validation",
  "request_id": "unity-validation-123",
  "context": "play_mode",
  "status": "blocked",
  "reason": "incompatible",
  "experiment": {
    "id": "0",
    "name": "main_experiment",
    "state": "PAUSED"
  },
  "checks": {
    "gama_connection": {
      "status": "ready"
    },
    "active_experiment": {
      "status": "ready"
    },
    "simple_unity_compatibility": {
      "status": "blocked",
      "reason": "missing_required_capabilities",
      "details": {
        "capabilities": {
          "create_player": false,
          "remove_player": false,
          "unity_linker_species": false,
          "unity_linker": false
        },
        "missing_capabilities": [
          "create_player",
          "remove_player",
          "unity_linker_species",
          "unity_linker"
        ]
      }
    }
  }
}

The exact JSON shape may be adapted to existing project conventions. The important requirements are:

• preserve the original request_id;
• echo context when provided;
• send the response only to the requesting socket;
• expose an immediately usable overall result;
• retain technical details for diagnostics.

Validation sequence

The Webplatform should process the request in this order:

1. Validate the Monitor request.
2. Check the existing GAMA connection state.
3. If GAMA is disconnected, respond immediately without probing GAMA.
4. Evaluate the currently known experiment state.
5. If that state is authoritative and proves there is no active experiment, respond immediately.
6. If the state is ambiguous or an active experiment exists, send one bounded read-only compatibility probe.
7. Correlate the GAMA reply with the pending Unity request.
8. Reject stale replies if the GAMA connection or active experiment changed.
9. Convert the result into the structured Monitor response.
10. Send it only to the requesting Unity socket.

A NONE or empty local state must only be treated as authoritative when the current experiment-tracking implementation guarantees it. An externally started GAMA experiment may otherwise require a read-only liveness probe before returning no_active_experiment.

The term “active experiment” should be used instead of “selected experiment”: GAMA Server may not distinguish between nothing being selected and an experiment being selected but not instantiated or started.

Unity → Webplatform → GAMA action mapping

Message received by Webplatform	Webplatform action	Outgoing message
Valid validation request while GAMA is disconnected.	Read the current connection state and stop immediately.	Targeted Unity response: status: "blocked", reason: "gama_disconnected".
Valid request and authoritative local state proves that no experiment is active.	Return without sending a capability probe.	Targeted Unity response: status: "blocked", reason: "no_active_experiment".
Valid request with an active experiment, or with local state that is not authoritative enough to prove absence.	Register a pending validation with a timeout and stale-response protection, then send one read-only probe.	GAMA request: { "type": "expression", "exp_id": "<active-experiment-id>", "expr": "<centralized SIMPLE Unity capability probe>", "<internal-correlation>": "..." }.
Malformed request or missing request_id.	Reject it without contacting GAMA and without closing the socket.	Targeted Unity response: status: "error", reason: "invalid_request".

GAMA → Webplatform → Unity action mapping

GAMA event or local timeout	Webplatform action	Targeted Unity response
Matching CommandExecutedSuccessfully with all required capabilities present.	Parse the payload, cancel the timeout, remove the pending entry, and confirm the experiment has not changed.	status: "ready", reason: null, with detected capabilities.
Matching CommandExecutedSuccessfully with required capabilities missing.	Compute the missing-capability list and remove the pending entry.	status: "blocked", reason: "incompatible".
Matching CommandExecutedSuccessfully with malformed or unreadable content.	Remove the pending entry and retain sanitized diagnostics.	status: "error", reason: "invalid_probe_response".
Matching UnableToExecuteRequest explicitly indicating that no experiment or simulation can be found.	Treat this as no usable active experiment.	status: "blocked", reason: "no_active_experiment".
Matching UnableToExecuteRequest, MalformedRequest, RuntimeError, GamaServerError, or another GAMA technical failure.	Remove the pending entry and retain the exact sanitized GAMA error type for diagnostics.	status: "error", reason: "probe_failed".
SimulationStatus: NONE for the experiment being validated.	Cancel the pending validation because the experiment is no longer active.	status: "blocked", reason: "no_active_experiment".
A different experiment becomes active before the reply is processed.	Reject the result as stale and remove the pending entry.	status: "error", reason: "experiment_changed".
The GAMA WebSocket closes while validations are pending.	Cancel every affected validation and clear the corresponding entries.	For each requester: status: "blocked", reason: "gama_disconnected".
The bounded local timeout expires.	Remove the pending entry and ignore any later matching reply.	status: "error", reason: "timeout".

Implementation constraints and expected behavior

• Compatibility should be determined from the SIMPLE Unity runtime contract, not only from the experiment name.
• Validation must remain strictly read-only and must not control or modify the experiment, players, active model, or workspace.
• The response should preserve the Unity request_id and be sent only to the requesting Monitor socket.
• GAMA disconnection, no active experiment, incompatibility, timeout, and technical failure should produce distinct machine-readable results.
• Pending validations should be cleared after completion, timeout, experiment change, or socket closure. Late responses should be ignored.
• Existing Monitor messages and clients should remain unaffected.

Unity remains responsible for allowing or cancelling Play Mode or preview generation and for displaying the corresponding popup.

Workspace exploration, experiment launching, player-state validation, simulation-data monitoring, and automatic experiment conversion are outside the scope of this issue.

Unity integration and feedback

The Unity-side request flow has been designed but is not implemented yet. Therefore, the request and response examples in this issue are proposals rather than a frozen contract. Field names and the exact JSON structure may be adapted to fit the Webplatform architecture and conventions.

I can update the Unity package to match the resulting Monitor WebSocket API where necessary, provided that the essential guarantees remain available: targeted request correlation, distinct technical outcomes, bounded validation, and no side effects on the active GAMA experiment.

Once the Webplatform implementation is available, I will perform the Unity-side and end-to-end integration tests myself. If the API response does not cover a required popup case or if an integration problem is found, I will document it in this issue with the corresponding Unity and Webplatform logs.