Node Stream

WebSocket server that streams real-time vehicle node positions to connected clients. Also serves initial node positions and flexbody mapping data on request.

Overview

util_nodeStream creates a WebSocket server on port 8088 that broadcasts vehicle node positions at a configurable interval (default 100ms). Clients can request initial node positions, flexbody mapping data, or load extensions remotely. Designed for external visualization tools.

Extension path: lua/ge/extensions/util/nodeStream.lua

Exports (M)

Internals

WebSocket Protocol

Clients send JSON messages with a type field:

Node Position Format

Positions are converted to Z-up coordinates:

{
  "type": "vehicleNodes",
  "nodes": {
    "0": {"x": 1.0, "y": 0.5, "z": -0.3},
    "1": {"x": 1.2, "y": 0.6, "z": -0.2}
  }
}

Conversion: x = x, y = z, z = -y

Initial Node Positions

Returned relative to the reference node (usually node 0):

{
  "type": "initialNodePositions",
  "nodes": {
    "0": {"x": 0, "y": 0, "z": 0},
    "1": {"x": 0.2, "y": 0.1, "z": 0.1}
  }
}

Flexbody Mapping Data

Includes mesh name, group nodes, position/rotation/scale, and flatMap:

{
  "type": "flexbodyMappingData",
  "flexbodies": {
    "0": {
      "mesh": "pickup_body",
      "groupNodes": [...],
      "pos": {...},
      "rot": {...},
      "scale": {...}
    }
  }
}

Stream Interval

Default: 0.1 seconds (10 Hz). The timer accumulates dt and broadcasts when threshold is reached.

Event Handling

The server processes peer events each frame:

• "C": Client connected (logged).
• "DC": Client disconnected (logged).
• "D": Data received - decoded as JSON and routed to handlers.
• "ping" messages receive "pong" responses.

Unrecognized messages are forwarded via extensions.hook("onWebSocketHandlerMessage", ...).

How It Works

1. Load: extensions.load('util_nodeStream').
2. Connect a WebSocket client to ws://127.0.0.1:8088.
3. Send {"type": "startNodeStream"} to begin receiving position updates.
4. Optionally request initial positions or flexbody data.
5. Unload the extension to stop the server.

Lua Examples

-- Load the node stream server
extensions.load('util_nodeStream')

-- Server starts automatically on port 8088
-- Connect with any WebSocket client:
-- ws://127.0.0.1:8088

-- Example client messages (JSON):
-- {"type": "startNodeStream"}
-- {"type": "getInitialNodePositions"}
-- {"type": "getFlexbodyMappingData"}
-- {"type": "loadExtension", "extensionName": "util_someExtension"}

Additional Exports

• M.onExtensionLoaded - (undocumented)
• M.onExtensionUnloaded - (undocumented)
• M.onUpdate - (undocumented)

See Also

• Auto Annotation - Related reference
• Booster - Related reference
• Calibrate ESC - Related reference
• Game Engine Overview - Guide