buddy-battle 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/package.json +1 -1
  2. package/readme.md +22 -77
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "buddy-battle",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
4
  "license": "MIT",
5
5
  "bin": "dist/cli.js",
6
6
  "type": "module",
package/readme.md CHANGED
@@ -8,80 +8,38 @@ Buddy Battle brings your Claude Code companion to life in a real-time, turn-base
8
8
 
9
9
  ## ✨ Features
10
10
 
11
- - **🎮 Real-Time PvP** — Fight other Claude Code users over Supabase Realtime
11
+ - **🎮 Real-Time PvP** — Fight other Claude Code users globally over Supabase Realtime
12
12
  - **🧬 Deterministic Buddies** — Your buddy's species, rarity, and stats are derived from your Anthropic account via `Bun.hash`
13
- - **⚔️ 4-Move Combat System** — Debug Smash, Chaos Bomb, Firewall, and Reboot — each powered by your buddy's unique stats
13
+ - **⚔️ 4-Move Combat System** — Debug Smash, Chaos Bomb, Firewall, and Reboot — each scaled mathematically to your buddy's unique stats
14
14
  - **💥 Battle Animations** — Projectiles fly across the terminal, hits shake the screen
15
- - **🏆 Global Leaderboard** — ELO-tracked rankings stored in Supabase Postgres
16
- - **🔐 Cloud Profiles** — Choose a Trainer Name, synced across all your machines via SHA-256 hashed Anthropic UUID
17
- - **📡 Disconnect Protection** — Supabase Presence detects ragequits and awards the survivor a win
18
- - **🛡️ Privacy First** — No Anthropic credentials or account IDs ever leave your machine
19
-
20
- ## 📋 Prerequisites
21
-
22
- - **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** — You need a hatched buddy (`/buddy` command)
23
- - **[Node.js](https://nodejs.org/) 18+**
24
- - **[Bun](https://bun.sh/)** — Required for accurate buddy stat extraction (Claude Code already installs this)
25
- - **A Supabase project** — Free tier works fine
15
+ - **🏆 Global Leaderboard** — ELO-tracked rankings
16
+ - **🔗 X (Twitter) Integration** — Brag about your knockout victories directly to X from the terminal
17
+ - **🔐 Secure Architecture** — Match validation tokens prevent forged wins, and your real Anthropic UUID is SHA-256 hashed to protect your identity.
26
18
 
27
19
  ## 🚀 Quick Start
28
20
 
29
- ### 1. Clone & Install
21
+ Ensure you have [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed and have hatched a buddy using the `/buddy` command.
30
22
 
31
- ```bash
32
- git clone https://github.com/Grenghis-Khan/buddy-battle.git
33
- cd buddy-battle
34
- npm install
35
- ```
36
-
37
- ### 2. Set Up Supabase
38
-
39
- Create a new [Supabase](https://supabase.com) project, then run this SQL in the SQL Editor:
40
-
41
- ```sql
42
- CREATE TABLE public.leaderboard (
43
- id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
44
- trainer_name text UNIQUE NOT NULL,
45
- hashed_id text UNIQUE,
46
- wins integer DEFAULT 0,
47
- losses integer DEFAULT 0,
48
- elo integer DEFAULT 1000,
49
- created_at timestamptz DEFAULT now()
50
- );
51
-
52
- ALTER TABLE public.leaderboard ENABLE ROW LEVEL SECURITY;
53
- CREATE POLICY "Public read" ON public.leaderboard FOR SELECT USING (true);
54
- CREATE POLICY "Public insert" ON public.leaderboard FOR INSERT WITH CHECK (true);
55
- CREATE POLICY "Public update" ON public.leaderboard FOR UPDATE USING (true);
56
- ```
57
-
58
- ### 3. Configure Environment
23
+ Then just jump right into the arena:
59
24
 
60
25
  ```bash
61
- cp .env.example .env
26
+ npx buddy-battle
62
27
  ```
63
28
 
64
- Edit `.env` with your Supabase project URL and anon key (found in Settings → API).
65
-
66
- ### 4. Build & Play!
67
-
68
- ```bash
69
- npm run build
70
- node dist/cli.js
71
- ```
29
+ *Note: For the most accurate buddy stats, ensure [Bun](https://bun.sh/) is installed on your machine so the client can perfectly match Anthropic's internal hashing algorithm.*
72
30
 
73
31
  ## 🎯 Combat System
74
32
 
33
+ Every match is different because every buddy has unique stats! Combat has been completely mathematically balanced to ensure that even a level 100 stat won't instantly one-shot a level 0 buddy, but it will give you a major thematic advantage.
34
+
75
35
  | Move | Stat | Effect |
76
36
  |------|------|--------|
77
- | **Debug Smash** | DEBUGGING | Reliable damage |
78
- | **Chaos Bomb** | CHAOS | Massive damage, 30% miss chance |
79
- | **Firewall** | WISDOM | Blocks 50% of next incoming hit |
80
- | **Reboot** | PATIENCE | Heals your buddy |
37
+ | **Debug Smash** | DEBUGGING | Fast, highly reliable light attack. |
38
+ | **Chaos Bomb** | CHAOS | Heavy attack with a high chance to miss. |
39
+ | **Firewall** | WISDOM | Defensive block. The higher your wisdom, the larger the percentage of the next incoming hit you block. |
40
+ | **Reboot** | PATIENCE | Heals your buddy for a burst of HP. |
81
41
 
82
- Each buddy's stats are unique and deterministic — a high-CHAOS buddy will devastate with Chaos Bombs, while a high-PATIENCE buddy can outlast opponents with Reboots.
83
-
84
- ## 🏗️ Architecture
42
+ ## 🏗️ Technical Architecture
85
43
 
86
44
  ```
87
45
  buddy-battle/
@@ -92,33 +50,20 @@ buddy-battle/
92
50
  │ ├── config/
93
51
  │ │ └── reader.ts # Reads ~/.claude.json + shells out to Bun
94
52
  │ ├── engine/
95
- │ │ ├── companion.ts # Deterministic buddy generation (mirrored from Claude Code)
96
53
  │ │ ├── types.ts # Species, rarities, stats
97
54
  │ │ └── sprites.ts # ASCII art for all 18 species
98
55
  │ ├── network/
99
- │ │ └── client.ts # Supabase Realtime + Presence + Cloud Profiles
56
+ │ │ └── client.ts # Supabase RPCs + Match Validators
100
57
  │ └── ui/
101
58
  │ ├── Arena.tsx # Battle screen with animations
102
- │ ├── Menu.tsx # Main menu
103
- │ ├── Matchmaking.tsx # Lobby + opponent discovery
104
- │ ├── Leaderboard.tsx # Global rankings
105
- │ ├── Setup.tsx # First-time Trainer Name registration
106
- │ └── Shared.tsx # Sprites + projectile components
59
+ │ ├── Matchmaking.tsx # Lobby + Match Validator Handshake
60
+ │ └── ...
107
61
  ```
108
62
 
109
- ### Key Technical Decisions
110
-
111
- - **Bun.hash bridge**: Claude Code runs on Bun and uses `Bun.hash()` (wyhash) to seed buddy generation. Since Node.js uses a different hash, we shell out to `bun source/extract-bones.ts` at boot to get bit-identical results.
112
- - **SHA-256 identity**: Your Anthropic `accountUuid` is hashed before touching the network — Supabase never sees your real account ID.
113
- - **Peer-to-peer combat**: No server-side game logic. Both clients independently compute damage from broadcast payloads, keeping the architecture simple.
63
+ ### Key Security Decisions
114
64
 
115
- ## ⚠️ Bun Warning
116
-
117
- If Bun is not installed, the game will still work but your buddy's species, rarity, and combat stats may not match what Claude Code shows. Install Bun to fix this:
118
-
119
- ```bash
120
- curl -fsSL https://bun.sh/install | bash
121
- ```
65
+ - **Match Validator Handshake**: To prevent ELO spoofing, players generate and exchange a cryptographic `battle_token` upon connecting. The winner must submit their opponent's token to securely claim the win via a locked-down PostgreSQL RPC.
66
+ - **Embedded Client**: Server-side credentials are safely embedded right in the package — zero setup required for players. The database is strictly protected by Row Level Security (RLS) so the `anon` key cannot be abused.
122
67
 
123
68
  ## 📄 License
124
69