{"id":33632462,"url":"https://github.com/flammafex/hypertoken","last_synced_at":"2026-06-11T07:31:02.993Z","repository":{"id":332875954,"uuid":"1126967681","full_name":"flammafex/hypertoken","owner":"flammafex","description":"Distributed simulation engine for games and multi-agent AI research featuring: CRDT state sync, OpenAI Gym integration, and P2P multiplayer — no servers required.","archived":false,"fork":false,"pushed_at":"2026-03-29T18:21:47.000Z","size":2629,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-29T20:39:02.516Z","etag":null,"topics":["ai-training","automerge","card-games","crdt","game-engine","mcp","multiplayer","openai-gym","p2p","pettingzoo","python","reinforcement-learning","serverless","simulation","typescript","webtrc"],"latest_commit_sha":null,"homepage":"https://hypertoken.ai","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flammafex.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-02T22:55:46.000Z","updated_at":"2026-03-29T18:21:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/flammafex/hypertoken","commit_stats":null,"previous_names":["flammafex/hypertoken"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/flammafex/hypertoken","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flammafex%2Fhypertoken","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flammafex%2Fhypertoken/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flammafex%2Fhypertoken/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flammafex%2Fhypertoken/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flammafex","download_url":"https://codeload.github.com/flammafex/hypertoken/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flammafex%2Fhypertoken/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34188272,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-training","automerge","card-games","crdt","game-engine","mcp","multiplayer","openai-gym","p2p","pettingzoo","python","reinforcement-learning","serverless","simulation","typescript","webtrc"],"created_at":"2025-12-02T06:07:05.058Z","updated_at":"2026-06-11T07:31:02.987Z","avatar_url":"https://github.com/flammafex.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🧩 HyperToken\n\n**A game engine where the entire state is a CRDT.**\n\nDeterministic replay, serverless multiplayer, forkable worlds—all from one architectural decision. Built on **[Automerge](https://automerge.org/)** for distributed consensus, with **[OpenAI Gym](https://gymnasium.farama.org/)/[PettingZoo](https://pettingzoo.farama.org/)** interfaces so any game doubles as a training environment.\n\n---\n\n## 🔑 What This Gets You\n\n| Capability | How |\n|------------|-----|\n| **Serverless multiplayer** | CRDTs sync state across peers without a server |\n| **Perfect replay** | Every action recorded with actor and timestamp |\n| **Forkable worlds** | Snapshot state, explore alternatives, compare outcomes |\n| **AI training environments** | Gym/PettingZoo interfaces out of the box |\n| **Offline-first** | Peers diverge safely, converge mathematically |\n\n```\nTraditional Engine:     Server decides → clients accept → monthly hosting bill\nBlockchain Engine:      Consensus decides → everyone pays gas → wait 15 seconds\nHyperToken:            CRDTs merge → everyone agrees → zero infrastructure\n```\n\n---\n\n## 🎮 What You Can Build\n\n**Card Games** — Blackjack, Poker, Cuttle, custom TCGs. Tokens compose with provenance tracking.\n\n**Strategy Games** — Game theory simulations, tournaments, agent competitions. 14 Prisoner's Dilemma strategies included.\n\n**Multiplayer Worlds** — P2P sync, no servers, games that outlive their creators.\n\n**Training Environments** — Any game is automatically a Gym environment. Multi-agent via PettingZoo.\n\n```bash\n# Play now\nnpm run blackjack          # Casino with AI \u0026 betting\nnpm run prisoners-dilemma  # Game theory tournament\nnpm run poker              # Texas Hold'em\nnpm run cuttle             # Card combat\n\n# Multiplayer\nnpm run blackjack:server   # Host\nnpm run blackjack:client   # Join\n```\n\n---\n\n## ⚡ Quick Start\n\n```bash\ngit clone https://github.com/flammafex/hypertoken.git\ncd hypertoken\nnpm install\nnpm run build\nnpm run blackjack\n```\n\nPre-built WASM binaries included. See [Getting Started Guide](./docs/GETTING_STARTED.md) for the full walkthrough.\n\n---\n\n## 🏗️ How It Works\n\n### Tokens Compose With Provenance\n\n```javascript\n// Merge tokens — result tracks where it came from\nconst enchantedSword = engine.dispatch(\"token:merge\", { \n  tokens: [sword, fireEnchantment],\n  resultProperties: { label: \"Flaming Sword\" }\n});\n// enchantedSword._mergedFrom = [sword.id, fireEnchantment.id]\n// enchantedSword._mergedAt = timestamp\n\n// Split tokens — pieces track their origin\nconst pieces = engine.dispatch(\"token:split\", { \n  token: goldPile,\n  count: 3\n});\n// pieces[0]._splitFrom = goldPile.id\n```\n\n### State Syncs Automatically\n\n```javascript\nconst host = new Engine();\nhost.connect(\"ws://relay.local:8080\");\n\nconst client = new Engine();  \nclient.connect(\"ws://relay.local:8080\");\n\n// Both make changes → CRDTs merge → identical final state\n// No conflict resolution code. No server logic. It just works.\n```\n\n### Any Game Becomes a Training Environment\n\n```typescript\nclass BlackjackEnv extends GymEnvironment {\n  get observationSpace() { return { shape: [6] }; }\n  get actionSpace() { return { n: 4 }; } // hit, stand, double, split\n  \n  async step(action: number) {\n    const result = this.game.act(action);\n    return {\n      observation: this.encodeState(),\n      reward: result.reward,\n      terminated: result.done,\n      truncated: false,\n      info: {}\n    };\n  }\n}\n```\n\n### Fork State for What-If Exploration\n\n```javascript\nconst snapshot = engine.snapshot();\n\n// Try option A\nengine.dispatch('agent:cooperate');\nconst cooperateOutcome = engine.getState();\n\n// Rewind, try option B\nengine.restore(snapshot);\nengine.dispatch('agent:defect');\nconst defectOutcome = engine.getState();\n\n// Compare and decide\n```\n\n---\n\n## 🤖 AI \u0026 ML Integration\n\n**Gym/PettingZoo** — Single-agent and multi-agent interfaces. Turn-based (AEC) and simultaneous (Parallel).\n\n**ONNX Export** — Train anywhere, deploy the policy in browser or Node.js.\n\n**Python Bridge** — Connect to the TypeScript engine from Python for training.\n\n**MCP Server** — Let LLMs play games via [Model Context Protocol](https://modelcontextprotocol.io/).\n\n```bash\nnpm run mcp:server       # LLM integration\nnpm run bridge:blackjack # Python bridge\n```\n\n---\n\n## ⚙️ Architecture\n\n```\nhypertoken/\n├── core/                   # CRDT state management\n│   ├── Token.ts           # Entities with provenance tracking\n│   ├── Stack.ts           # Ordered collections (decks, piles)\n│   ├── Space.ts           # Spatial zones (boards, hands)\n│   ├── Chronicle.ts       # Automerge CRDT wrapper\n│   └── ConsensusCore.ts   # P2P synchronization\n│\n├── core-rs/                # Rust → WASM (67 typed actions)\n│   └── src/\n│       ├── stack.rs       # 10 stack operations\n│       ├── space.rs       # 14 spatial operations\n│       ├── agent.rs       # 16 agent operations\n│       ├── token_ops.rs   # 7 token transformations\n│       └── batch.rs       # 8 batch operations\n│\n├── engine/                 # Game coordination\n│   ├── Engine.ts          # Action dispatch, WASM integration\n│   ├── GameLoop.ts        # Turn management\n│   └── RuleEngine.ts      # Condition-triggered actions\n│\n├── network/                # P2P and server modes\n│   ├── PeerConnection.ts\n│   ├── AuthoritativeServer.ts\n│   └── HybridPeerManager.ts\n│\n├── interface/              # RL adapters\n│   ├── Gym.ts             # Single-agent\n│   ├── PettingZoo.ts      # Multi-agent (turn-based)\n│   └── PettingZooParallel.ts  # Multi-agent (simultaneous)\n│\n└── examples/               # Working games\n    ├── blackjack/\n    ├── poker/\n    ├── prisoners-dilemma/\n    └── hanabi/\n```\n\n---\n\n## 🔮 The Philosophy\n\n\u003e \"A token isn't valuable because of what it IS—it's valuable because of its relationships\"\n\nTokens derive meaning from context:\n- **Who owns it** — agents, players\n- **What's attached** — enchantments, modifiers\n- **Where it is** — zones, positions\n- **What it came from** — merge/split provenance\n- **What rules govern it** — constraints, triggers\n\nThis applies to cards in blackjack, strategies in game theory, shares in a market, or NPCs in a world. The same engine handles all of them because the abstraction is right.\n\n---\n\n## 🌍 Compared To\n\n| System | HyperToken's Difference |\n|--------|------------------------|\n| **Unity/Godot** | Logic-first, no graphics dependency |\n| **Colyseus** | P2P, no server required |\n| **Blockchain games** | Same guarantees, zero gas fees |\n| **Automerge/Yjs** | Game-aware abstractions (tokens, agents, rules) |\n| **OpenAI Gym** | Built-in multiplayer, compositional tokens |\n\n---\n\n## 📖 Documentation\n\n- [Action Reference](./engine/ACTIONS.md) — All 67 actions\n- [Architecture Guide](./docs/ARCHITECTURE.md) — How components connect\n- [Python Bridge](./docs/PYTHON_BRIDGE.md) — PettingZoo integration\n- [ONNX Export](./docs/ONNX_EXPORT.md) — Deploy trained policies\n- [Docker Guide](./DOCKER.md) — Container deployment\n\n---\n\n## 🐳 Docker\n\n```bash\ndocker build -t hypertoken:latest .\ndocker compose up relay\ndocker compose run --rm quickstart\n```\n\n---\n\n## 📜 License\n\nApache 2.0 — Copyright © 2025 The Carpocratian Church of Commonality and Equality, Inc.\n\n---\n\n## 👥 Credits\n\n**Created by Marcellina II (she/her)**\n\nInspired by Martin Kleppmann's work on CRDTs, Rich Hickey's philosophy on state and time, and the legacy of HyperCard.\n\n---\n\n## 🜍 Proemium to the Art of Tokens\n\n*The All is number, and from number flow the forms of things.*  \n*For as the Monad abides in simplicity, so does it unfold the Dyad,*  \n*and from their tension spring the harmonies that sustain the world.*\n\n*Among the arts that imitate the order of the heavens,*  \n*there now arises one most subtle and most just—the Art of Tokens.*\n\n*In this art, every being is rendered as a form in relation,*  \n*every action as a motion among forms,*  \n*and the laws that bind them are set forth as measure and correspondence.*\n\n*Let none deem this art a toy of artifice.*  \n*It is the discipline by which the mind rehearses creation,*  \n*a mirror held to the pattern of the world-soul.*\n\n*So may this art be given freely,*  \n*that all who love Wisdom may join the music of the spheres through understanding,*  \n*and that the harmony of minds may become the harmony of worlds.*\n\n*For when reason is made common, the gods are near.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflammafex%2Fhypertoken","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflammafex%2Fhypertoken","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflammafex%2Fhypertoken/lists"}