OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add dpearson2699/swift-ios-skills --skill tabletopkit
Builds multiplayer spatial board games using TabletopKit on visionOS. Use when creating tabletop game experiences with boards, pieces, cards, or dice; managing seats, turns, equipment state, TabletopAction flows, or TabletopInteraction delegates; synchronizing gameplay through FaceTime Group Activities; rendering with RealityKit; or implementing snapping, tosses, and physics on a virtual table surface.
npx skills add dpearson2699/swift-ios-skills --skill tabletopkit
Build visionOS board games whose synchronized state changes flow through TabletopAction and render with RealityKit. The availability matrix below owns version details.
| Tier | APIs |
|---|---|
| visionOS 2.0+ | Core gameplay, equipment, seats, actions, rendering, Group Activities |
| visionOS 2.2+ | TabletopInteraction.Configuration |
| visionOS 26.0+ | Custom actions/state, registration, advanced toss outcomes, discarded-action observation |
Simulator supports single-player layout testing, not multiplayer.
import TabletopKit in source files that define game logic.import RealityKit for entity-based rendering.| 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 |
Build and validate a game in this order:
TableSetup and register every custom action type.Call update(deltaTime:) each frame if automatic updates are not enabled via
the .tabletopGame(_:parent:automaticUpdate:) modifier. Read state safely with
withCurrentSnapshot(_:).
Conform to EntityTabletop to define the playing surface. Provide a shape
(round or rectangular) and a RealityKit Entity for visual representation.
Use factory methods on TabletopShape:
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 |
CustomEquipmentState | Custom state with a BaseEquipmentState plus game data; see the availability matrix |
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 equipmentEquipment 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 layoutSee references/tabletopkit-patterns.md for card fan, grid, and overlap layout examples.
Conform to EntityTableSeat and provide a pose around the table:
Claim a seat before interacting: game.claimAnySeat(), game.claimSeat(matching:),
or game.releaseSeat(). Observe changes via TabletopGame.Observer.playerChangedSeats.
Use TabletopAction factory methods to modify game state:
For game-specific logic, conform to CustomAction when the availability matrix permits it.
Custom action application and validation must depend only on the action data and
the supplied TableState / TableSnapshot so every peer resolves the same
result. Register custom action types during setup before dispatching them:
Register each custom action type before dispatching it. See references/tabletopkit-patterns.md for full custom action and custom state examples.
Save and restore game state for undo/reset:
Bookmark restoration is asynchronous and network ordered. Wait for
stateDidResetToBookmark, then read withCurrentSnapshot, rebuild local UI from
that authoritative callback state, and validate the restored invariant. Do not
inspect immediately after jumpToBookmark or enqueue another jump on mismatch.
Load State Bookmarks and Undo
for the observer reconciliation pattern.
Return an interaction delegate from the .tabletopGame modifier to handle
player gestures on equipment:
Use interaction.value.gesture for gesture-specific state. Avoid deprecated
gesturePhase. For destination control, prefer
interaction.setConfiguration(.init(allowedDestinations: ...)) when available
rather than deprecated setAllowedDestinations(_:) or
value.allowedDestinations.
Basic toss(equipmentID:as:) is core TabletopKit; the availability matrix owns
advanced toss outcomes.
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:.
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.
Conform to EntityRenderDelegate to bridge state to RealityKit. Provide a
root entity. TabletopKit automatically positions EntityEquipment entities.
Connect to SwiftUI with .tabletopGame(_:parent:automaticUpdate:) on a
RealityView:
Debug outlines: game.tabletopGame.debugDraw(options: [.drawTable, .drawSeats, .drawEquipment])
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.
Implement TabletopGame.MultiplayerDelegate for joinAccepted(),
playerJoined(_:), didRejectPlayer(_:reason:), and
multiplayerSessionFailed(reason:). See
references/tabletopkit-patterns.md for custom
network coordinators and arbiter role management.
claimAnySeat() or claimSeat(_:)
before interacting with equipment. Without a seat, actions are rejected.TabletopAction or CustomAction. Directly modifying equipment properties
bypasses synchronization.setup.register(action:) before use.actionWasRolledBack(_:snapshot:) to revert UI state.actionWasDiscarded(_:) when local action queue pressure matters; it is
called for local actions that cannot be enqueued.parentID in state must reference a
valid equipment ID (typically the table or a container). An invalid parent
causes the piece to disappear.outcome.tossableRepresentation.face(for: outcome.restingOrientation) rather
than generating a random value. The physics simulation determines the result.TableSetup created with a Tabletop/EntityTabletop conforming typeEquipment or EntityEquipment with correct state typeclaimAnySeat() / claimSeat(_:) called at game startsetup.register(action:)TabletopGame.Observer reconciles confirmed, rolled-back, discarded, and
bookmark-reset outcomes with the current snapshotEntityRenderDelegate or RenderDelegate connected.tabletopGame(_:parent:automaticUpdate:) modifier on RealityViewGroupActivity defined and coordinateWithSession(_:) called; multiplayer described as Group Activities/SharePlay synchronizationdebugDraw) disabled before releasestruct 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)
}
}// 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)// 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
)
}
}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)
}
}// 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)))setup.register(action: CollectCoin.self)
game.addAction(CollectCoin(coinID: coinID, playerID: playerID))setup.add(counter: ScoreCounter(id: .init(0), value: 0))
// Update: game.addAction(.updateCounter(matching: .init(0), value: 42))
// Read: snapshot.counter(matching: .init(0))?.valuegame.addAction(.createBookmark(id: StateBookmarkIdentifier(1)))
game.jumpToBookmark(matching: StateBookmarkIdentifier(1)).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)
}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
))
}
}
}class GameRenderer: EntityRenderDelegate {
let root = Entity()
func onUpdate(timeInterval: Double, snapshot: TableSnapshot,
visualState: TableVisualState) {
// Custom visual updates beyond automatic positioning
}
}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)
}
}
}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() }
}