TabletopKit 用于在 visionOS 上构建多人空间桌面游戏。其核心是通过 TabletopAction 驱动同步的状态变更,并借助 RealityKit 进行实体渲染。游戏逻辑需在源文件中 import TabletopKit,渲染相关代码 import RealityKit。若要支持多人,需在 Signing & Capabilities 中添加 Group Activities 能力,并在 RealityKit 内容包中提供桌面、棋子、卡牌和骰子的 USDZ 资源。
主要能力包括:定义桌面(Tabletop/EntityTabletop 协议,支持圆形或矩形),配置各类装备(Equipment/EntityEquipment,使用 BaseEquipmentState、CardState、DieState、RawValueState 等状态类型),设置玩家座位(TableSeat/EntityTableSeat),通过内置动作移动装备、翻牌、更新骰子点数、切换回合、更新计数器,以及通过 TabletopAction 或 CustomAction 修改状态。还支持座位控制、装备层级与布局、分数计数器和状态书签(用于撤销/重置)、交互委托处理手势与掷骰、RealityKit 渲染委托,以及通过 Group Activities 实现 FaceTime 多人同步。
典型用法:先创建 TableSetup 并注册自定义动作类型,再用其初始化 TabletopGame,随后 claimAnySeat() 或 claimSeat(_:) 认领座位。未启用自动更新时,每帧调用 update(deltaTime:)。自定义动作需在分发前通过 setup.register(action:) 注册。观察者需处理已确认、回滚、丢弃和书签重置等结果。
限制:模拟器仅支持单人布局测试,多人需要至少两台 Apple Vision Pro 设备并通过 FaceTime 连接。所有状态变更必须经由动作进行,直接修改装备属性会绕过同步。掷骰结果应由物理模拟决定,读取 outcome.tossableRepresentation.face(for:),而非随机生成。书签恢复是异步且按网络顺序的,需等待 stateDidResetToBookmark 后再读取快照。具体版本与可用性以官方矩阵为准。