Tabletopkit

TabletopKit

Build visionOS board games whose synchronized state changes flow through TabletopAction and render with RealityKit. The availability matrix below owns version details.

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

Simulator supports single-player layout testing, 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 table, piece, card, and dice USDZ assets in a RealityKit content bundle.

Key Types Overview

Game Configuration

Build and validate a game in this order:

1. Define the tabletop, equipment, and seats.
2. Configure TableSetup and register every custom action type.
3. Create the game, attach its observer and renderer, claim a seat, and establish automatic or manual update handling.
4. Inspect the current snapshot for required equipment IDs, parents, seats, and counters before starting multiplayer. Fix the setup and rebuild if an invariant fails.

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

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:

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
• .restrictedCurrent([seatID1, seatID2]) -- specific seats only while they are in turn
• .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