add-websocket-command

name	add-websocket-command
description	Add a new WebSocket command to the simulation control service. Use when: adding a new runtime control command, exposing simulation state via WebSocket, adding a new service endpoint.

Add a New WebSocket Command

Procedure for adding a new command to the SimulationControlService or creating a new WebSocket service endpoint.

When to Use

• Adding a new runtime control command (e.g., pause, step, teleport)
• Exposing new simulation state via the WebSocket API
• Creating an entirely new WebSocket service endpoint

Option A: Add Command to Existing Service

1. Define Request/Response DTOs

Edit Assets/Scripts/Core/Services/SimulationControlService.cs:

// If the response needs a custom shape, add a new response class:
private class SimulationControlResponseMyData : SimulationControlResponseBase
{
	[JsonProperty("result")]
	public MyDataType result;
}

Standard responses use SimulationControlResponseNormal (has string result).

2. Add the Command Case

In the OnMessage() method's switch statement:

case "my_new_command":
	// Simple response:
	output = new SimulationControlResponseNormal();
	(output as SimulationControlResponseNormal).result = ComputeMyResult();
	break;

	// Or with custom data:
	output = new SimulationControlResponseMyData();
	(output as SimulationControlResponseMyData).result = GetMyData();
	break;

The response is automatically serialized and sent:

output.command = request.command;
Send(JsonConvert.SerializeObject(output));

3. Wire to Main.cs (If Needed)

If the command needs access to Main instance methods:

// In SimulationControlService, access Main via the singleton:
case "my_command":
	Main.Instance.MyNewMethod();
	output = new SimulationControlResponseNormal();
	(output as SimulationControlResponseNormal).result = SimulationService.SUCCESS;
	break;

Constants: SimulationService.SUCCESS = "ok", SimulationService.FAIL = "fail".

For multi-part request data, use SimulationService.Delimiter = "!%!" to split values.

Option B: Create a New Service Endpoint

1. Create the Service Class

Create Assets/Scripts/Core/Services/MyNewService.cs:

/*
 * Copyright (c) 2026 LG Electronics Inc.
 *
 * SPDX-License-Identifier: MIT
 */

using System;
using Newtonsoft.Json;
using WebSocketSharp;
using WebSocketSharp.Server;

public class MyNewService : WebSocketBehavior
{
	// Inject dependencies via public properties (set by factory lambda)
	public MyDependency Dependency { get; set; }

	protected override void OnMessage(MessageEventArgs e)
	{
		try
		{
			var request = JsonConvert.DeserializeObject<MyRequest>(e.Data);
			var response = ProcessRequest(request);
			Send(JsonConvert.SerializeObject(response));
		}
		catch (Exception ex)
		{
			var error = new { error = ex.Message };
			Send(JsonConvert.SerializeObject(error));
		}
	}

	protected override void OnOpen()
	{
		// Connection opened
	}

	protected override void OnClose(CloseEventArgs e)
	{
		// Connection closed
	}

	private MyResponse ProcessRequest(MyRequest request)
	{
		// Handle the request
		return new MyResponse();
	}
}

2. Register the Endpoint

Edit Assets/Scripts/Core/Modules/SimulationService.cs, in InitializeServices():

_wsServer.AddWebSocketService<MyNewService>("/my_endpoint", () =>
	new MyNewService()
	{
		Dependency = myDependencyInstance
	});

3. Clean Up on Dispose

In SimulationService.Dispose(), add removal:

_wsServer.RemoveWebSocketService("/my_endpoint");

JSON Patterns

Request format (convention from existing services):

{
    "command": "my_command",
    "value": "optional_parameter"
}

Response format:

{
    "command": "my_command",
    "result": "ok"
}

Use [JsonProperty("field_name")] attributes on DTO properties for explicit JSON field naming.

Checklist

• Request/response DTOs defined with [JsonProperty] attributes
• Command case added to OnMessage() switch
• Uses SimulationService.SUCCESS / FAIL constants for status
• Error handling wraps the command logic
• New endpoints registered in SimulationService.InitializeServices()
• New endpoints removed in SimulationService.Dispose()
• License header on new files