Products/SuperDataOpen Source · CC BY-NC 4.0
07 · Cross-Platform Sync Protocol

SuperData
跨平台同步协议

开源跨引擎数据共享协议（v2.1），"群聊"架构——中央 SuperDataServer.exe 作为路由器， Vectorworks / GrandMA2 / MA3 / UE5 / Unity 通过 TCP 5966 连接， 灯具位置、DMX 地址修改一处、全局同步，坐标系自动标准化转换。

TCP 5966JSON Payload"SPDT" 魔数TCP_NODELAY8 语言 SDK零配置自启动CC BY-NC 4.0
GitHub 仓库协议规范 →
Protocol Specification

协议规范 v2.1

24 字节固定头 + UTF-8 JSON 负载混合协议。 魔数 "SPDT"（0x53504454）校验，Little Endian，毫秒时间戳，递增序列号。

Protocol Params

协议版本v2.1.0
传输层TCP localhost:5966
魔数 (Magic)"SPDT" (0x53504454)
包头大小24 字节固定
负载格式JSON (UTF-8)
字节序Little Endian
心跳间隔3000 ms
心跳超时10000 ms
最大包体65536 字节
Nagle 算法必须禁用 (TCP_NODELAY)
粘包处理必须循环解析缓冲区
系统代理必须清除代理环境变量

Header Fields (24 Bytes)

0–3Magicchar[4] "SPDT"
4–5Versionuint16 LE
6–7PacketTypeuint16 LE
8–11Sequenceuint32 LE
12–19Timestampint64 LE (ms)
20–23PayloadLenuint32 LE
12 Packet Types

数据包类型

0x0010ConnectC → S
0x0011ConnectAckS → C
0x0012DisconnectC ↔ S
0x0013HeartbeatC ↔ S
0x0014ClientJoinedS → C
0x0015ClientLeftS → C
0x0020FixtureListRequestC → S
0x0021FixtureListResponseS → C
0x0022FixtureUpdateC → S
0x0023FixtureFullSyncC → S
0x0024FixtureDeleteC → S
0xFF00ErrorS → C

Implementation Notes

TCP 粘包TCP 是流式协议，多个小包可能合并。必须用循环解析：检查缓冲区长度 ≥ HEADER_SIZE + PayloadLength，提取完整包后继续解析剩余数据。
TCP_NODELAYNagle 算法会缓冲小包导致 200ms–5min 延迟。所有 TCP 连接必须设置 TCP_NODELAY = true，确保数据 <10ms 延迟立即发送。
禁用代理代理软件（Clash/V2Ray）可能拦截 localhost 连接。启动时必须清除 http_proxy / https_proxy / all_proxy 等环境变量，设置 no_proxy=*。
Group-Chat Architecture

"群聊"架构

SuperDataServer.exe 作为中央路由器（127.0.0.1:5966）， 所有客户端加入同一个"群"，共享各自的灯具数据，选择性导入，接收实时变更广播。

独立服务进程 (SuperDataServer.exe)C++ 17 + Asio 异步网络 + nlohmann/json。无窗口后台运行（Windows SUBSYSTEM:WINDOWS），系统级安装到 C:\Program Files\Yunsio\SuperData\，所有客户端共享。命名互斥锁防止重复启动。
群聊模式各客户端通过 TCP 5966 加入同一个"群"。Server 维护每个客户端的独立灯具数据缓存。新客户端加入时收到 ConnectAck（含群成员列表），Server 广播 ClientJoined 通知其他成员。
选择性导入客户端可浏览群内所有其他客户端的灯具数据。发送 FixtureListRequest 指定 sourceClientId，Server 返回该客户端的缓存数据，无需目标客户端在线响应。
增量变更广播FixtureUpdate 仅推送变更字段（position / universe / …），Server 更新缓存后转发给群内所有其他客户端。FixtureDelete 同理。实现低带宽实时同步。
Connection & Data Flow

连接 & 数据流

1

TCP 连接

客户端尝试连接 localhost:5966。失败则自动从注册表查找 exe 路径并启动 Server，轮询等待端口就绪（最多 5 秒）。

2

Connect 握手

发送 Connect (0x0010) 携带 clientId(UUID)、clientName、platform、protocolVersion。收到 ConnectAck (0x0011) 含群成员列表。

3

上报数据

发送 FixtureFullSync (0x0023) 上报自己的全量灯具数据。Server 缓存并更新 fixtureCount。

4

导入数据

发送 FixtureListRequest (0x0020) 指定源客户端 → Server 返回 FixtureListResponse (0x0021) 含该客户端的灯具列表。

5

实时同步

修改灯具 → FixtureUpdate (0x0022) → Server 更新缓存 → 广播给所有其他客户端。

6

心跳 & 清理

Heartbeat (0x0013) 每 3s 双向发送，10s 未收到则断开。Disconnect (0x0012) 或超时后 Server 清除缓存、广播 ClientLeft。连接数归零则 Server 退出。

Platform Integrations

平台集成

Unreal Engine

SuperStage 插件内置

✅ 已实现

  • ·SuperData Sync 面板：编辑器菜单 → SuperStage → SuperData Sync
  • ·一键连接，显示所有在线客户端（带平台图标）
  • ·Fetch Data → 选择源 → 类型映射（VW 型号 → SuperStage 资产）
  • ·Import 自动创建灯具 Actor + 配置 DMX + 设置位置/旋转
  • ·支持增量同步（只更新变化的灯具）

USuperDataSubsystem · C++ TCP · 坐标 X↔Y + Yaw±180°

Unity

SuperStageForUnity 插件

✅ 已实现

  • ·菜单 SuperStage → 工具 → SuperData 数据共享
  • ·双模式界面：Import / Export
  • ·按灯具类型分组显示 + 批量勾选/取消
  • ·类型映射：源型号 → 本地 Prefab
  • ·一键导入生成 GameObject + 自动配置 DMX

SuperDataService 单例 · SuperDataClient 线程安全 TCP

GrandMA2

SuperData.lua 插件

✅ 已实现

  • ·Lua 实现，读取 Fixture Layer 数据
  • ·提取 Channel、Patch Address、Fixture Type
  • ·自动上传灯具数据到群聊网络
  • ·典型场景：从 MA2 导入 Patch 到 UE5 预演

LuaSocket TCP · 注册表查找 Server · Plugin 1 运行

Vectorworks Spotlight

SuperStageForVw 插件

📋 计划中

  • ·Python 实现，读取 Lighting Device 数据
  • ·提取 3D 位置、旋转、DMX 地址、灯具型号
  • ·支持双向同步
  • ·一键发送灯位图数据到 SuperData 网络
8-Language SDK

8 语言 SDK

完整开源，内置粘包处理、心跳、代理禁用。

Pythonasyncio 异步、类型提示
JavaScriptNode.js、事件驱动
TypeScript强类型、完整定义
C#.NET 8、async/await
C++Asio 异步、跨平台
RustTokio 异步、安全内存
JavaMaven、Gson JSON
LuaLuaSocket、MA 兼容
Fixture Data Fields

灯具数据字段

标准右手 Z-up 厘米制（MVR/GDTF 兼容）。

uuidstring (UUID v4)跨平台唯一标识符
namestring灯具显示名称
fixtureTypestring灯具型号 (如 Robin 600)
universeint (1-256)DMX Universe
startAddressint (1-512)DMX 起始地址
fixtureIDint (1-65535)灯具编号
positionfloat[3] cm[X, Y, Z] 位置
rotationfloat[3] deg[X, Y, Z] 欧拉角
scalefloat[3][X, Y, Z] 缩放
customPropertiesobject任意扩展字段
Coordinate Systems

坐标系转换

自动处理手性、轴映射、单位换算。

Standard—

右手 Z-up · cm · X右 Y前 Z上

Unreal EngineX↔Y 交换

左手 Z-up · cm · X前 Y右 Z上

Unity×100 + 轴映射

左手 Y-up · m · X右 Y上 Z前

GrandMA2×100

右手 Z-up · m · X右 Y前 Z上

Vectorworks÷10

右手 Z-up · mm · X右 Y前 Z上

Workflows

典型工作流

Vectorworks → UE5

灯位图设计到 3D 预演

1.VW 设计师在 Vectorworks Spotlight 完成灯位图
2.运行 SuperStageForVw 插件
3.点击 "Sync" 发送灯具数据到群聊
4.UE 可视化师打开 SuperData Sync 面板
5.看到 VW 客户端在线 → 点击 "Fetch Data"
6.配置类型映射（VW 型号 → SuperStage 资产）
7.点击 "Import" → 灯具自动生成到场景

MA2 Patch → UE5

控台配置到可视化预演

1.灯光师在 GrandMA2 完成 Patch 配置
2.运行 SuperData.lua 插件（Plugin 1）
3.插件自动扫描 Fixture Layer 并上传
4.UE 可视化师打开 SuperData Sync
5.选择 MA2 客户端 → Fetch → Import
6.结果：UE 灯具自动具有正确 DMX 地址

多端实时协作

全链路零手动数据搬运

1.多个软件同时连接 SuperData 群聊
2.VW 设计师修改灯位 → FixtureUpdate 广播
3.UE5 实时接收变更 → 预演效果更新
4.MA 灯光师调整 Patch → 所有端自动更新
5.任何修改一处同步，全程零手动搬运
Server Specs

服务器规格

语言C++ 17
网络库Asio (standalone)
JSON 库nlohmann/json
构建系统CMake 3.21+
目标平台Windows 7+ / macOS / Linux
安装包大小~2.2 MB
安装路径C:\Program Files\Yunsio\SuperData
注册表HKLM\SOFTWARE\Yunsio\SuperData

Open Source Info

CC BY-NC 4.0可自由共享、修改、演绎。需保留署名，禁止商业使用。商业授权联系 Yunsio。
完整源码Server 源码 + 8 语言客户端库 + Inno Setup 安装脚本 + 协议文档，全部开放。
全平台测试附带 all_clients_test.ps1 八语言并发交互测试脚本，验证全平台兼容性。
社区贡献欢迎提交 Issue、Pull Request 或贡献新平台的客户端实现。
GitHub 仓库下载安装包