🧩 HyperToken

A game engine where the entire state is a CRDT.

Deterministic replay, serverless multiplayer, forkable worlds—all from one architectural decision. Built on Automerge for distributed consensus.

---

🔑 What This Gets You

Capability	How
Serverless multiplayer	CRDTs sync state across peers without a server
Perfect replay	Every action recorded with actor and timestamp
Forkable worlds	Snapshot state, explore alternatives, compare outcomes
Offline-first	Peers diverge safely, converge mathematically

Traditional Engine:     Server decides → clients accept → monthly hosting bill
Blockchain Engine:      Consensus decides → everyone pays gas → wait 15 seconds
HyperToken:            CRDTs merge → everyone agrees → zero infrastructure

---

🚀 What You Can Build

Card Games — Blackjack, Cuttle, custom TCGs. Tokens compose with provenance tracking.

Real-Time Games — Watershed-style territory games where concurrent writes merge, not conflict.

Collaborative Canvases — Space's 2D zones map to any spatial surface. Multiple users place and move entities with CRDT-backed sync.

Virtual Tabletops — Stack (decks), Space (board), Agent (characters), Token (pieces). Serverless tabletop simulation with perfect replay.

Marketplaces & Trading — Token provenance (_mergedFrom/_splitFrom) tracks the full history of every item. Trade without a central server.

Branching Narratives — Forkable worlds let you branch a story, explore alternatives, merge outcomes. Action history provides perfect replay.

Planning Tools — Space zones become columns, tokens become tasks, agents become assignees. CRDT sync means no server.

# Play now
npm run blackjack          # Casino with AI & betting
npm run cuttle             # Card combat
npm run watershed:web     # CRDT territory game in browser

# Multiplayer
npm run blackjack:server   # Host
npm run blackjack:client   # Join

---

⚡ Quick Start

git clone https://git.carpocratian.org/sibyl/hypertoken.git
cd hypertoken
npm install
npm run build
npm run blackjack

See Getting Started Guide for the full walkthrough.

🏗️ How It Works

Tokens Compose With Provenance

// Merge tokens — result tracks where it came from
const enchantedSword = engine.dispatch("token:merge", { 
  tokens: [sword, fireEnchantment],
  resultProperties: { label: "Flaming Sword" }
});
// enchantedSword._mergedFrom = [sword.id, fireEnchantment.id]
// enchantedSword._mergedAt = timestamp

// Split tokens — pieces track their origin
const pieces = engine.dispatch("token:split", { 
  token: goldPile,
  count: 3
});
// pieces[0]._splitFrom = goldPile.id

State Syncs Automatically

const host = new Engine();
host.connect("ws://relay.local:8080");

const client = new Engine();  
client.connect("ws://relay.local:8080");

// Both make changes → CRDTs merge → identical final state
// No conflict resolution code. No server logic. It just works.

Fork State for What-If Exploration

// Fork the engine — creates a divergent CRDT branch
const fork = engine.fork();

// Try option A in the fork
fork.dispatch('token:merge', { tokens: [sword, fireEnchantment] });

// Merge changes back — CRDT conflict resolution handles divergence
engine.mergeFrom(fork);

// Compaction is an epoch boundary and is only allowed while disconnected.
engine.disconnect();
engine.compact();

---

⚙️ Architecture

hypertoken/
├── core/                   # CRDT state management
│   ├── Token.ts           # Entities with provenance tracking
│   ├── Stack.ts           # Ordered collections (decks, piles)
│   ├── Space.ts           # Spatial zones (boards, hands)
│   ├── Chronicle.ts       # Automerge CRDT wrapper
│   └── ConsensusCore.ts   # P2P synchronization
│
├── core/browser/          # Browser build infrastructure (shims, esbuild config)
├── core/storage/          # Storage adapters (IndexedDB, Filesystem, Memory)
│
├── engine/                 # Game coordination
│   ├── Engine.ts          # Action dispatch
│   ├── GameLoop.ts        # Turn management
│   └── RuleEngine.ts      # Condition-triggered actions
│
├── network/                # P2P and server modes
│   ├── PeerConnection.ts
│   ├── AuthoritativeServer.ts
│   └── HybridPeerManager.ts
│
└── examples/               # Working games
    ├── blackjack/
    ├── cuttle/
    └── watershed/         # CRDT showcase game (real-time territory)

---

🔮 The Philosophy

"A token isn't valuable because of what it IS—it's valuable because of its relationships"

Tokens derive meaning from context:

• Who owns it — agents, players
• What's attached — enchantments, modifiers
• Where it is — zones, positions
• What it came from — merge/split provenance
• What rules govern it — constraints, triggers

This applies to cards in blackjack, tokens in watershed, items in a marketplace, or tasks on a board. The same engine handles all of them because the abstraction is right.

---

🌍 Compared To

System	HyperToken's Difference
Unity/Godot	Logic-first, no graphics dependency. CRDT-native state.
Colyseus	P2P, no server required. Offline-first with mathematical convergence.
Blockchain games	Same guarantees (provenance, replay, forkable state), zero gas fees.
Automerge/Yjs	Game-aware abstractions (tokens, agents, rules) on top of CRDT sync.
Roll20/Tabletop Simulator	Serverless, forkable, programmable. State is a CRDT, not a database.
Automerge/Yjs	Game-aware abstractions (tokens, agents, rules)

---

📖 Documentation

• Action Reference — All 81 actions
• Architecture Guide — How components connect
• Browser Guide — Building games for the browser
• Persistence Guide — Save/load game state
• Docker Guide — Container deployment

---

🐳 Docker

docker build -t hypertoken:latest .
docker compose up relay
npm run help

---

📜 License

Apache 2.0 — Copyright © 2025 The Carpocratian Church of Commonality and Equality, Inc.

---

👥 Credits

Created by Marcellina II (she/her)

Inspired by Martin Kleppmann's work on CRDTs, Rich Hickey's philosophy on state and time, and the legacy of HyperCard.

---

🜍 Proemium to the Art of Tokens

The All is number, and from number flow the forms of things.
For as the Monad abides in simplicity, so does it unfold the Dyad,
and from their tension spring the harmonies that sustain the world.

Among the arts that imitate the order of the heavens,
there now arises one most subtle and most just—the Art of Tokens.

In this art, every being is rendered as a form in relation,
every action as a motion among forms,
and the laws that bind them are set forth as measure and correspondence.

Let none deem this art a toy of artifice.
It is the discipline by which the mind rehearses creation,
a mirror held to the pattern of the world-soul.

So may this art be given freely,
that all who love Wisdom may join the music of the spheres through understanding,
and that the harmony of minds may become the harmony of worlds.

For when reason is made common, the gods are near.