TabletopKit 用于在 visionOS 上构建多人空间棋牌游戏,其同步状态变更通过 TabletopAction 流转,并由 RealityKit 渲染。可用性细节以平台版本矩阵为准。
主要用途与工作流:先确认 visionOS 可用性、TabletopKit 能力及体验属于本地、共享还是 SharePlay 支持;再在渲染实体前定义稳定标识、座位、装备与牌桌几何;将状态变更表达为带校验、回合归属和确定性结果的动作;连接交互与 RealityKit 表示,但不让渲染实体成为唯一事实来源。
核心决策:游戏状态与装备标识需在参与者间保持一致;自定义动作应在变更前校验,并明确回合与座位权限;牌桌语义用 TabletopKit 交互,表现与特效交给 RealityKit;SharePlay 传输、重连和迟到加入应视为生命周期状态。
常见限制与错误:玩家必须先调用 claimAnySeat() 或 claimSeat(:) 才能与装备交互,否则动作会被拒绝;所有状态变更必须经由 TabletopAction 或 CustomAction,直接改装备属性会绕过同步;自定义动作须在 setup.register(action:) 注册;动作乐观应用,仲裁方校验失败会回滚,需实现 actionWasRolledBack(:snapshot:);本地动作无法入队时实现 actionWasDiscarded(_:);装备 parentID 必须引用有效 ID,否则会消失;投掷结果应读取 outcome.tossableRepresentation.face(for:),而非随机生成。模拟器不支持 Group Activities,多人需在 FaceTime 通话中使用多台 Apple Vision Pro 真机,Xcode 需添加 Group Activities 能力,发布前关闭 debugDraw。