BlATBall 🥜⚾🌪️#

Interdimensional Baseball on AT Protocol — A live blaseball simulation publishing structured game data to the decentralized social web.

BlATBall transforms Blaseball from a standalone simulation into queryable, real-time data records on AT Protocol (Bluesky). Experience chaos-enhanced baseball with player modifications, reality-altering weather, and interdimensional events—all published as structured lexicon records for anyone to build on.

🌟 What Makes This Special#

• 📊 Records-Only Architecture: All game data published as AT Protocol lexicon records (not social posts!)
• 🔴 Real-time Game Updates: Live game state published as queryable records across the network
• ⭐ Complete Data Schemas: Custom lexicons for players, teams, games, seasons, and leagues
• 🌪️ Chaos Event System: Reality-altering events with player modifications and interdimensional effects
• 🎯 Build Your Own Client: Anyone can read records and build custom Blaseball experiences
• 🎮 Rich Frontend: Full-featured React application with profiles, analytics, and live game viewing
• 🔌 WebSocket Activity Feed: Real-time local updates for connected clients

🏗️ Architecture#

Records-Only Philosophy#

"Publish data, not content. Let others create the experience."

Instead of broadcasting play-by-play as social media posts, we publish structured AT Protocol records. Clients can then:

• Read live game state from records
• Subscribe to real-time updates via firehose
• Build custom UIs, feeds, and visualizations
• Aggregate data across multiple Blaseball leagues

What Gets Published#

Player Records (com.blatball.player)

• Complete stats (batting, power, speed, defense, pitching, accuracy, luck, chaos, vibes)
• Active modifications with effects (On Fire, Cursed, Unstable, Scattered, etc.)
• Position, appearance, biography, secrets, favorite foods

Team Records (com.blatball.team)

• Roster (array of player AT URIs)
• Lineup, rotation, bullpen organization
• Team statistics (wins, losses, runs, chaos events)
• Ballpark, motto, mascot, colors

Game Records (com.blatball.game)

• Live game state (inning, outs, count, score)
• Full play-by-play log with chaos indicators
• Weather conditions and effects
• Chaos events with intensity levels
• Updates via putRecord (replaces existing records in-place)

📁 Repository Structure#

atproto-blaseball/
├── src/                    # Backend (Node/TypeScript)
│   ├── core/              # Game engine and orchestration
│   ├── game/              # Blaseball simulation logic
│   │   ├── generators/    # Player and team generation
│   │   ├── events/        # Chaos events system
│   │   └── types/         # Game type definitions
│   ├── atproto/           # AT Protocol integration
│   │   ├── AtProtoClient.ts
│   │   ├── GameBroadcaster.ts
│   │   └── BlaseballRecordPublisher.ts
│   ├── lexicon/           # AT Protocol lexicon types
│   ├── store/             # In-memory data storage
│   ├── web/               # WebSocket activity feed
│   └── server.ts          # Express API server
│
├── frontend/              # Frontend (React/Vite)
│   ├── src/
│   │   ├── components/    # React components
│   │   ├── pages/         # Page components
│   │   ├── services/      # API and AT Protocol services
│   │   ├── hooks/         # Custom React hooks
│   │   └── contexts/      # React contexts
│   └── dist/              # Built frontend assets
│
├── lexicons/              # AT Protocol lexicon schemas
│   └── com/atproto/blaseball/
│       ├── player.json
│       ├── team.json
│       ├── game.json
│       ├── season.json
│       ├── league.json
│       └── playerStats.json
│
├── docs/                  # Additional documentation
│   └── LEXICON_SCHEMAS.md
│
├── ROADMAP.md            # Future development plans
└── RAILWAY_DEPLOYMENT.md # Deployment guide

🚀 Quick Start#

Prerequisites#

• Node.js 22+
• npm 10+
• AT Protocol account (Bluesky) for live broadcasting (optional)

Installation#

# Clone and install
git clone https://github.com/tigwyk/atproto-blaseball.git
cd atproto-blaseball
npm install

# Install frontend dependencies
cd frontend && npm install && cd ..

# Configure environment (optional - for AT Protocol publishing)
cp .env.example .env
# Edit .env with your AT Protocol credentials

Environment Variables (Optional)#

For publishing to AT Protocol:

ATPROTO_SERVICE=https://bsky.social
ATPROTO_IDENTIFIER=your-handle.bsky.social
ATPROTO_PASSWORD=your-app-password

PORT=3000
NODE_ENV=development

🎮 Running the Application#

Development Mode (Recommended)#

Terminal 1 — Backend:

npm run dev
# API server: http://localhost:3000
# WebSocket: ws://localhost:3000/api/live-feed

Terminal 2 — Frontend:

cd frontend
npm run dev
# Frontend: http://localhost:5173

Production Mode#

# Build frontend
cd frontend && npm run build && cd ..

# Build backend
npm run build

# Start production server
npm start
# Serves everything at http://localhost:3000

Test Live Broadcasting#

# Run without AT Protocol publishing (local only)
npx ts-node src/examples/liveBlaseballDemo.ts test

# Start live broadcasting to AT Protocol (requires credentials)
npx ts-node src/examples/liveBlaseballDemo.ts live

📜 Available Scripts#

Backend#

Frontend#

🎯 Key Features#

Backend#

• Game Engine: Complete Blaseball simulation with chaos events, modifications, weather
• Player Generation: Interdimensional names, 9 stats, 12+ modifications, chaos levels
• Team Management: Auto-generation, roster organization, team themes, rivalries
• Chaos Events: 15+ reality-altering events with intensity levels (mild → reality-ending)
• Weather System: 14 weather types with stat effects and chaos multipliers
• AT Protocol Publishing: Structured record publishing with type validation
• RESTful API: Game data, activities, teams, players, status endpoints
• WebSocket Feed: Real-time activity updates for connected clients
• Record Store: In-memory data storage with mock data generation

Frontend#

• Live Game Viewer: Real-time game updates with team data and chaos events
• Player Browser: Search and filter players with detailed stats and modifications
• Team Pages: Rosters, lineups, team statistics
• User Profiles: Achievements, statistics, activity feeds, customizable bios/banners
• Advanced Analytics: Historical trends, season comparisons, activity heatmaps
• Social Features: Public profiles, leaderboards, activity sharing
• Theme Support: Dark, light, and chaos themes with animations
• AT Protocol Auth: OAuth integration for user authentication

🌐 API Endpoints#

Base URL: http://localhost:3000/api

🔧 Building Clients#

Anyone can read published Blaseball records and build custom clients:

Read Game State#

import { BskyAgent } from '@atproto/api';

const agent = new BskyAgent({ service: 'https://bsky.social' });

// Get live game
const { data } = await agent.com.atproto.repo.getRecord({
  repo: 'did:plc:blaseball',
  collection: 'com.blatball.game',
  rkey: 's1-d1-game'
});

console.log('Score:', data.value.score);
console.log('Inning:', data.value.inning);

Subscribe to Updates#

import { Firehose } from '@atproto/api';

const firehose = new Firehose();

firehose.on('commit', (evt) => {
  for (const op of evt.ops) {
    if (op.collection === 'com.blatball.game' && op.action === 'update') {
      console.log('Game update!', op.uri);
      // Fetch and display updated game
    }
  }
});

await firehose.start();

🧪 Testing#

# Backend tests
npm test

# Frontend linting
cd frontend && npm run lint

# Integration test (no AT Protocol publishing)
npx ts-node src/examples/liveBlaseballDemo.ts test

🚢 Deployment#

Configured for Railway deployment. See RAILWAY_DEPLOYMENT.md for detailed instructions.

# Railway build command
cd frontend && npm ci && npm run build && cd .. && npm ci && npm run build

# Start command
npm start

📚 Documentation#

• Roadmap - Future development plans and features
• Lexicon Schemas - Complete AT Protocol schema documentation
• Railway Deployment - Deployment instructions

🧬 Technology Stack#

Backend:

• Node.js 22+ with TypeScript
• Express.js for HTTP API
• WebSocket (ws) for real-time updates
• AT Protocol SDK (@atproto/api) for record publishing
• Lexicon validation for schema enforcement

Frontend:

• React 18 with TypeScript
• Vite for fast development and optimized builds
• CSS Modules for scoped styling
• AT Protocol SDK for authentication
• Custom SVG charts (no external chart libraries)
• localStorage for data persistence

🤝 Contributing#

This is an experimental project exploring structured data publishing on decentralized social media. Contributions welcome!

📄 License#

MIT

Experience interdimensional baseball on the decentralized web. This isn't just a simulation—it's a living sports universe that exists as queryable, real-time data on AT Protocol.

The Peanut watches. The Peanut publishes. 🥜⚾🌪️