C2 WebSocket Handler

Core WebSocket server for the C2 (Command & Control) system. Provides a JSON message bus on localhost for external tools to communicate with the game engine.

Overview

Creates a WebSocket server on port 8088 that receives JSON messages, supports ping/pong keepalive, dynamic extension loading, and routes all other messages to registered plugins via the onC2WebSocketHandlerMessage hook.

Public API

Built-in Message Types

All other JSON messages are broadcast via:

extensions.hook("onC2WebSocketHandlerMessage", {
  event   = evt,
  message = jsonData,
  server  = server
})

Hook Interface

Plugins implement onC2WebSocketHandlerMessage(args) to receive messages:

-- args structure:
-- args.event   - WebSocket event (has peerId, type, msg)
-- args.message - Decoded JSON table
-- args.server  - Server object for sending responses

-- Example plugin handler (not part of this extension):
local function onC2WebSocketHandlerMessage(args)
  local msg = args.message
  if msg.type == "myCommand" then
    args.server:sendData(args.event.peerId, jsonEncode({type = "response", data = "ok"}))
  end
end

Server Details

Event Processing

-- Event types from server:getPeerEvents()
-- evt.type == "D" - Data message
-- evt.msg - Raw message string
-- evt.peerId - Unique peer identifier

-- Response pattern:
server:sendData(evt.peerId, jsonEncode({type = "info", msg = "..."}))

Notes

• Server is localhost-only (127.0.0.1) - not accessible from network
• Invalid JSON messages are logged as errors
• Extension loading errors are caught with pcall and reported to the client
• The wsUtils.createOrGetWS function reuses existing servers on the same port
• Server updates (flush/receive) happen via server:update() each frame

See Also

• C2 Tile Manager - Scene tile data plugin
• C2 Vehicle Manager - Vehicle streaming plugin