tabletopkit

TabletopKit Create multiplayer spatial board games on a virtual table surface using TabletopKit. Handles game layout, equipment interaction, player seating, turn management, state synchronization, and RealityKit rendering. visionOS 2.0+ only. Targets Swift 6.3. Contents Setup Game Configuration Table and Board Equipment (Pieces, Cards, Dice) Player Seats Game Actions and Turns Interactions RealityKit Rendering Group Activities Integration Common Mistakes Review Checklist References Setup Platform Requirement TabletopKit is exclusive to visionOS. It requires visionOS 2.0+. Multiplayer features using Group Activities require visionOS 2.0+ devices on a FaceTime call. The Simulator supports single-player layout testing but not multiplayer. Project Configuration import TabletopKit in source files that define game logic. import RealityKit for entity-based rendering. For multiplayer, add the Group Activities capability in Signing & Capabilities. Provide 3D assets (USDZ) in a RealityKit content bundle for tables, pieces, cards, and dice. Key Types Overview Type Role TabletopGame Central game manager; owns setup, actions, observers, rendering TableSetup Configuration object passed to TabletopGame init Tabletop / EntityTabletop Protocol for the table surface Equipment / EntityEquipment Protocol for interactive game pieces TableSeat / EntityTableSeat Protocol for player seat positions TabletopAction Commands that modify game state TabletopInteraction Gesture-driven player interactions with equipment TabletopGame.Observer Callback protocol for reacting to confirmed actions TabletopGame.RenderDelegate Callback protocol for visual updates EntityRenderDelegate RealityKit-specific render delegate Game Configuration Build a game in three steps: define the table, configure the setup, create the TabletopGame instance. import TabletopKit import RealityKit let table = GameTable ( ) var setup = TableSetup ( tabletop : table ) setup . add ( seat : PlayerSeat ( index : 0 , pose : seatPose0 ) ) setup . add ( seat : PlayerSeat ( index : 1 , pose : seatPose1 ) ) setup . add ( equipment : GamePawn ( id : . init ( 1 ) ) ) setup . add ( equipment : GameDie ( id : . init ( 2 ) ) ) setup . register ( action : MyCustomAction . self ) let game = TabletopGame ( tableSetup : setup ) game . claimAnySeat ( ) Call update(deltaTime:) each frame if automatic updates are not enabled via the .tabletopGame(:parent:automaticUpdate:) modifier. Read state safely with withCurrentSnapshot(:) . Table and Board Tabletop Protocol Conform to EntityTabletop to define the playing surface. Provide a shape (round or rectangular) and a RealityKit Entity for visual representation. struct GameTable : EntityTabletop { var shape : TabletopShape var entity : Entity var id : EquipmentIdentifier init ( ) { entity = try ! Entity . load ( named : "table/game_table" , in : contentBundle ) shape = . round ( entity : entity ) id = . init ( 0 ) } } Table Shapes Use factory methods on TabletopShape : // Round table from dimensions let round = TabletopShape . round ( center : . init ( x : 0 , y : 0 , z : 0 ) , radius : 0.5 , thickness : 0.05 , in : . meters ) // Rectangular table from entity let rect = TabletopShape . rectangular ( entity : tableEntity ) Equipment (Pieces, Cards, Dice) Equipment Protocol All interactive game objects conform to Equipment (or EntityEquipment for RealityKit-rendered pieces). Each piece has an id ( EquipmentIdentifier ) and an initialState property. Choose the state type based on the equipment: State Type Use Case BaseEquipmentState Generic pieces, pawns, tokens CardState Playing cards (tracks faceUp / face-down) DieState Dice with an integer value RawValueState Custom data encoded as UInt64 Defining Equipment // Pawn -- uses BaseEquipmentState struct GamePawn : EntityEquipment { var id : EquipmentIdentifier var initialState : BaseEquipmentState var entity : Entity init ( id : EquipmentIdentifier ) { self . id = id self . entity = try ! Entity . load ( named : "pieces/pawn" , in : contentBundle ) self . initialState = BaseEquipmentState ( parentID : . init ( 0 ) , seatControl : . any , pose : . identity , entity : entity ) } } // Card -- uses CardState (tracks faceUp) struct PlayingCard : EntityEquipment { var id : EquipmentIdentifier var initialState : CardState var entity : Entity init ( id : EquipmentIdentifier ) { self . id = id self . entity = try ! Entity . load ( named : "cards/card" , in : contentBundle ) self . initialState = . faceDown ( parentID : . init ( 0 ) , seatControl : . any , pose : . identity , entity : entity ) } } // Die -- uses DieState (tracks integer value) struct GameDie : EntityEquipment { var id : EquipmentIdentifier var initialState : DieState var entity : Entity init ( id : EquipmentIdentifier ) { self . id = id self . entity = try ! Entity . load ( named : "dice/d6" , in : contentBundle ) self . initialState = DieState ( value : 1 , parentID : . init ( 0 ) , seatControl : . any , pose : . identity , entity : entity ) } } ControllingSeats Restrict which players can interact with a piece via seatControl : .any -- any player .restricted([seatID1, seatID2]) -- specific seats only .current -- only the seat whose turn it is .inherited -- inherits from parent equipment Equipment Hierarchy and Layout Equipment can be parented to other equipment. Override layoutChildren(for:visualState:) to position children. Return one of: .planarStacked(layout:animationDuration:) -- cards/tiles stacked vertically .planarOverlapping(layout:animationDuration:) -- cards fanned or overlapping .volumetric(layout:animationDuration:) -- full 3D layout See references/tabletopkit-patterns.md for card fan, grid, and overlap layout examples. Player Seats Conform to EntityTableSeat and provide a pose around the table: struct PlayerSeat : EntityTableSeat { var id : TableSeatIdentifier var initialState : TableSeatState var entity : Entity init ( index : Int , pose : TableVisualState . Pose2D ) { self . id = TableSeatIdentifier ( index ) self . entity = Entity ( ) self . initialState = TableSeatState ( pose : pose , context : 0 ) } } Claim a seat before interacting: game.claimAnySeat() , game.claimSeat(matching:) , or game.releaseSeat() . Observe changes via TabletopGame.Observer.playerChangedSeats . Game Actions and Turns Built-in Actions Use TabletopAction factory methods to modify game state: // Move equipment to a new parent game . addAction ( . moveEquipment ( matching : pieceID , childOf : targetID , pose : newPose ) ) // Flip a card face-up game . addAction ( . updateEquipment ( card , faceUp : true ) ) // Update die value game . addAction ( . updateEquipment ( die , value : 6 ) ) // Set whose turn it is game . addAction ( . setTurn ( matching : TableSeatIdentifier ( 1 ) ) ) // Update a score counter game . addAction ( . updateCounter ( matching : counterID , value : 100 ) ) // Create a state bookmark (for undo/reset) game . addAction ( . createBookmark ( id : StateBookmarkIdentifier ( 1 ) ) ) Custom Actions For game-specific logic, conform to CustomAction : struct CollectCoin : CustomAction { let coinID : EquipmentIdentifier let playerID : EquipmentIdentifier init ? ( from action : some TabletopAction ) { // Decode from generic action } func validate ( snapshot : TableSnapshot ) -> Bool { // Return true if action is legal true } func apply ( table : inout TableState ) { // Mutate state directly } } Register custom actions during setup: setup . register ( action : CollectCoin . self ) Score Counters setup . add ( counter : ScoreCounter ( id : . init ( 0 ) , value : 0 ) ) // Update: game.addAction(.updateCounter(matching: .init(0), value: 42)) // Read: snapshot.counter(matching: .init(0))?.value State Bookmarks Save and restore game state for undo/reset: game . addAction ( . createBookmark ( id : StateBookmarkIdentifier ( 1 ) ) ) game . jumpToBookmark ( matching : StateBookmarkIdentifier ( 1 ) ) Interactions TabletopInteraction.Delegate Return an interaction delegate from the .tabletopGame modifier to handle player gestures on equipment: . tabletopGame ( game . tabletopGame , parent : game . renderer . root ) { value in if game . tabletopGame . equipment ( of : GameDie . self , matching : value . startingEquipmentID ) != nil { return DieInteraction ( game : game ) } return DefaultInteraction ( game : game ) } Handling Gestures and Tossing Dice class DieInteraction : TabletopInteraction . Delegate { let game : Game func update ( interaction : TabletopInteraction ) { switch interaction . value . phase { case . started : interaction . setConfiguration ( . init ( allowedDestinations : . any ) ) case . update : if interaction . value . gesture ? . phase == . ended { interaction . toss ( equipmentID : interaction . value . controlledEquipmentID , as : . cube ( height : 0.02 , in : . meters ) ) } case . ended , . cancelled : break } } func onTossStart ( interaction : TabletopInteraction , outcomes : [ TabletopInteraction . TossOutcome ] ) { for outcome in outcomes { let face = outcome . tossableRepresentation . face ( for : outcome . restingOrientation ) interaction . addAction ( . updateEquipment ( die , rawValue : face . rawValue , pose : outcome . pose ) ) } } } Tossable Representations Dice physics shapes: .cube (d6), .tetrahedron (d4), .octahedron (d8), .decahedron (d10), .dodecahedron (d12), .icosahedron (d20), .sphere . All take height:in: (or radius:in: for sphere) and optional restitution: . Programmatic Interactions Start interactions from code: game.startInteraction(onEquipmentID: pieceID) . See references/tabletopkit-patterns.md for group toss, predetermined outcomes, interaction acceptance/rejection, and destination restriction patterns. RealityKit Rendering Conform to EntityRenderDelegate to bridge state to RealityKit. Provide a root entity. TabletopKit automatically positions EntityEquipment entities. class GameRenderer : EntityRenderDelegate { let root = Entity ( ) func onUpdate ( timeInterval : Double , snapshot : TableSnapshot , visualState : TableVisualState ) { // Custom visual updates beyond automatic positioning } } Connect to SwiftUI with .tabletopGame(:parent:automaticUpdate:) on a RealityView : struct GameView : View { let game : Game var body : some View { RealityView { content in content . entities . append ( game . renderer . root ) } . tabletopGame ( game . tabletopGame , parent : game . renderer . root ) { value in GameInteraction ( game : game ) } } } Debug outlines: game.tabletopGame.debugDraw(options: [.drawTable, .drawSeats, .drawEquipment]) Group Activities Integration TabletopKit integrates directly with GroupActivities for FaceTime-based multiplayer. Define a GroupActivity , then call coordinateWithSession(:) . TabletopKit automatically synchronizes all equipment state, seat assignments, actions, and interactions. No manual message passing required. import GroupActivities struct BoardGameActivity : GroupActivity { var metadata : GroupActivityMetadata { var meta = GroupActivityMetadata ( ) meta . type = . generic meta . title = "Board Game" return meta } } @Observable class GroupActivityManager { let tabletopGame : TabletopGame private var sessionTask : Task < Void , Never

? init ( tabletopGame : TabletopGame ) { self . tabletopGame = tabletopGame sessionTask = Task { @MainActor in for await session in BoardGameActivity . sessions ( ) { tabletopGame . coordinateWithSession ( session ) } } } deinit { tabletopGame . detachNetworkCoordinator ( ) } } Implement TabletopGame.MultiplayerDelegate for joinAccepted() , playerJoined(:) , didRejectPlayer(:reason:) , and multiplayerSessionFailed(reason:) . See references/tabletopkit-patterns.md for custom network coordinators and arbiter role management. Common Mistakes Forgetting platform restriction. TabletopKit is visionOS-only. Do not conditionally compile for iOS/macOS; the framework does not exist there. Skipping seat claim. Players must call claimAnySeat() or claimSeat(:) before interacting with equipment. Without a seat, actions are rejected. Mutating state outside actions. All state changes must go through TabletopAction or CustomAction . Directly modifying equipment properties bypasses synchronization. Missing custom action registration. Custom actions must be registered with setup.register(action:) before creating the TabletopGame . Unregistered actions are silently dropped. Not handling action rollback. Actions are optimistically applied and can be rolled back if validation fails on the arbiter. Implement actionWasRolledBack(:snapshot:) to revert UI state. Using wrong parent ID. Equipment parentID in state must reference a valid equipment ID (typically the table or a container). An invalid parent causes the piece to disappear. Ignoring TossOutcome faces. After a toss, read the face from outcome.tossableRepresentation.face(for: outcome.restingOrientation) rather than generating a random value. The physics simulation determines the result. Testing multiplayer in Simulator. Group Activities do not work in Simulator. Multiplayer requires physical Apple Vision Pro devices on a FaceTime call. Review Checklist import TabletopKit present; target is visionOS 2.0+ TableSetup created with a Tabletop / EntityTabletop conforming type All equipment conforms to Equipment or EntityEquipment with correct state type Seats added and claimAnySeat() / claimSeat(:) called at game start All custom actions registered with setup.register(action:) TabletopGame.Observer implemented for reacting to confirmed actions EntityRenderDelegate or RenderDelegate connected .tabletopGame(:parent:automaticUpdate:) modifier on RealityView GroupActivity defined and coordinateWithSession(_:) called for multiplayer Group Activities capability added in Xcode for multiplayer builds Debug visualization ( debugDraw ) disabled before release Tested on device; multiplayer tested with 2+ Apple Vision Pro units References references/tabletopkit-patterns.md -- extended patterns for observer implementation, custom actions, dice simulation, card overlap, and network coordination Apple Documentation: TabletopKit Creating tabletop games (sample code) Synchronizing group gameplay with TabletopKit (sample code) Simulating dice rolls as a component for your game (sample code) Implementing playing card overlap and physical characteristics (sample code) WWDC24 session 10091: Build a spatial board game