tabletopkit
Builds multiplayer spatial board games using TabletopKit on visionOS
Install / Use
npx skills add dpearson2699/swift-ios-skills --skill tabletopkitInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
OtherSupported Platforms
Tags
Our assessment of tabletopkit
tabletopkit scores 86/100 on our quality scale, 171st of 329 Other skills we index.
Its SKILL.md is 18 KB long, well organised into 30 sections with 14 code examples: a thorough specification that gives an agent plenty to work with.
With 1,143 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 4 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
- Our last check on 2026-11-03 found the source still online.
- No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
- Its trust signals score 86/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-06. Automated pattern scan on 2026-10-05. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
tabletopkit compared with similar skills
All 4 of these similar skills score higher than tabletopkit; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| tabletopkit (this skill)by dpearson2699 | 86 | 1.1k | 4mo ago | SKILL.md |
| x402by browser-use | 100 | 121.0k | 3d ago | SKILL.md |
| algorithmic-artby anthropics | 100 | 177.9k | 55d ago | SKILL.md |
| pptxby anthropics | 100 | 177.9k | 55d ago | SKILL.md |
| designby nextlevelbuilder | 100 | 149.0k | 6d ago | SKILL.md |
Frequently asked questions
- How do I install tabletopkit?
- Run
npx skills add dpearson2699/swift-ios-skills --skill tabletopkit. The install tabs above show the steps for each supported agent. - Which AI agents does tabletopkit work with?
- It is written for Zed, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is tabletopkit safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 86/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is tabletopkit still maintained?
- The repository was last updated about 4 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
Skill content
View source on GitHubname: tabletopkit description: "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."
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
| 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.
Project Configuration
import TabletopKitin source files that define game logic.import RealityKitfor entity-based rendering.- For multiplayer, add the Group Activities capability in Signing & Capabilities.
- Provide table, piece, card, and dice USDZ assets in a RealityKit content bundle.
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 and validate a game in this order:
- Define the tabletop, equipment, and seats.
- Configure
TableSetupand register every custom action type. - Create the game, attach its observer and renderer, claim a seat, and establish automatic or manual update handling.
- 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:
| 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 |
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
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 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:
setup.register(action: CollectCoin.self)
game.addAction(CollectCoin(coinID: coinID, playerID: playerID))
Register each custom action type before dispatching it. See references/tabletopkit-patterns.md for full custom action and custom state examples.
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))
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.
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)
}
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.
Handling Gestures and Tossing Dice
Basic toss(equipmentID:as:) is core TabletopKit; the availability matrix owns
advanced toss outcomes.
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(
Truncated for display — read the full file on GitHub.
Related Skills
x402
121.0kSet up Browser Use Cloud payments with x402 — pay per request from a crypto wallet (USDC on Base mainnet), no signup or API key.
algorithmic-art
177.9kCreating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems.
pptx
177.9kUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an em…
design
149.0kComprehensive design skill: brand identity, design tokens, UI styling, logo generation (55 styles, Gemini, Atlas Cloud, or MuAPI AI), corporate identity program (50 deliverables, CIP mockups), HTML presentations (Chart.js), banner design (22 styles, social/ads/web/print), icon design (15 styles, SVG…
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
