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

1. import TabletopKit

   in source files that define game logic.

2. import RealityKit

   for entity-based rendering.
3. For multiplayer, add the Group Activities capability in Signing & Capabilities.
4. Provide 3D assets (USDZ) in a RealityKit content bundle for tables, pieces, cards, and dice.

Key Types Overview

TabletopGame

TableSetup

TabletopGame

Tabletop

EntityTabletop

Equipment

EntityEquipment

TableSeat

EntityTableSeat

TabletopAction

TabletopInteraction

TabletopGame.Observer

TabletopGame.RenderDelegate

EntityRenderDelegate

Game Configuration

Build a game in three steps: define the table, configure the setup, create the

TabletopGame

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:)

.tabletopGame(_:parent:automaticUpdate:)

withCurrentSnapshot(_:)

Table and Board

Tabletop Protocol

Conform to

EntityTabletop

shape

Entity

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

EntityEquipment

id

EquipmentIdentifier

initialState

Choose the state type based on the equipment:

BaseEquipmentState

CardState

faceUp

DieState

value

RawValueState

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:)

• .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

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:)

game.releaseSeat()

TabletopGame.Observer.playerChangedSeats

Game Actions and Turns

Built-in Actions

Use

TabletopAction

// 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

.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

.tetrahedron

.octahedron

.decahedron

.dodecahedron

.icosahedron

.sphere

height:in:

radius:in:

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

root

EntityEquipment

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:)

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

coordinateWithSession(_:)

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

joinAccepted()

playerJoined(_:)

didRejectPlayer(_:reason:)

multiplayerSessionFailed(reason:)

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