用途:在 RivetKit 应用中实现多人实时光标与临场感(presence),单个房间 Actor 将光标位置按房间键分发给所有已连接客户端,并同步画布上的文本标签。
主要能力:提供两个可用模板。cursors 变体走 RivetKit 的类型化 actions/events,光标存于每连接的 connState,无需自行跟踪连接;cursors-raw-websocket 变体使用 onWebSocket 处理原始连接与自定义 JSON 消息协议,socket 存于 createVars 的 map。两者共用同一协作光标画布,仅传输方式不同。
使用方式:先阅读该技能目录下的 BASE_SKILL.md。默认推荐 cursors 变体;需要完全控制线格式或客户端不使用 RivetKit 客户端库时选 raw 变体。Actor 键为 cursorRoom[roomId],前端默认 roomId 为 general。标准变体动作含 updateCursor、updateText、removeText、getRoomState,事件含 cursorMoved、cursorRemoved、textUpdated、textRemoved。raw 变体动作含 getOrCreate、getRoomState,消息类型为客户端 updateCursor/updateText/removeText,服务端 init/cursorMoved/textUpdated/textRemoved/cursorRemoved。
状态与生命周期:光标属临时数据,放每连接存储(connState 或 vars.websockets map),连接断开即丢弃;textLabels 存持久 Actor 状态,可跨断连与重启。加入时 raw 变体推送 init 快照,标准变体由客户端连接后调用 getRoomState 播种;移动时写入连接状态并广播;离开时在 onDisconnect(或 socket close)广播 cursorRemoved。
限制:两个示例均未实现节流,前端每次 mousemove 都发送,建议生产环境客户端限流至 20-30Hz 并在服务端按连接限速。示例也未做鉴权,userId 由客户端随机生成,任何客户端都可冒充或删除光标;updateText/removeText 接受任意 id 与 userId,缺少所有权校验。建议绑定连接身份、校验输入边界与文本长度、严格校验 raw 协议消息。为避免过期临场累积,应始终从活跃连接派生光标快照。
适用场景:协作白板、多人编辑器、共享画布等需要实时在场指示的应用。