# Lucky Races — Complete Reference

> Lucky Races is a fully on-chain multiplayer racing game built on Ethereum. Created by Lucky Machines LLC.

## Overview

Lucky Races is a turn-based, deterministic multiplayer racing game where every action — from lobby creation to race completion — is executed and recorded on the Ethereum blockchain. The game uses the Diamond proxy pattern (EIP-2535) for upgradeable smart contracts, ensuring long-term extensibility and composability.

Players create or join open lobbies, select their racers, and compete on configurable tracks using card-based strategy, items, terrain effects, and lane positioning. All outcomes are deterministic and verifiable — given the same inputs, the same results are always produced.

The frontend is the **Lucky Races Board Game Edition**: a cinematic 3D isometric client built with React, Three.js, and React Three Fiber, featuring a 19-camera broadcast system, weather effects, terrain gameplay, and a full card-based turn UI.

## Links and Resources

- **Main Website**: https://luckyraces.com
- **Racerverse Platform**: https://racerverse.com
- **3D Viewer**: https://viewer.racerverse.com
- **OpenSea Collection**: https://opensea.io/collection/racerverse-lucky-races-original-racers
- **Documentation**: https://docs.luckyraces.com
- **GitHub**: https://github.com/LuckyMachines
- **Discord**: https://discord.gg/luckyraces
- **Contact**: https://racerverse.com/contact

## Gameplay Mechanics

### Race Flow

1. **Lobby Creation**: A player creates a lobby specifying track configuration (length, laps, lanes, racer limit). The lobby is an on-chain entity.
2. **Joining**: Other players join the lobby with their racer. Players can join and leave freely until the race starts.
3. **Race Start**: Once the lobby creator starts the race, all positions are initialized on-chain.
4. **Turn Submission**: Each round, every racer submits a turn using the card-based UI:
   - **Speed Mode** — Cruise (safe), Push (+1 space), or Overdrive (+2 spaces, collision risk)
   - **Lane Choice** — Stay in lane or move to a target lane
   - **Item Usage** — Use an item from inventory (offensive or defensive)
   - **Shield Activation** — Block the next incoming hit
   - **Block Drafters** — Prevent trailing racers from slipstreaming you (costs -1 space)
5. **Turn Processing**: The smart contract processes all turns deterministically. Movement, terrain, item effects, drafting, collisions, and lane changes are all resolved on-chain.
6. **Race Completion**: When a racer crosses the finish line, final positions are recorded on-chain.
7. **Replay**: The entire race can be replayed turn-by-turn from on-chain data.

### Items

Players acquire and use items during races:
- **Speed Boost**: +2 movement this turn
- **Missiles**: Fire at a specified lane — hit the closest racer in that lane (-2 position, -1 speed)
- **Bananas**: Drop a hazard at your current position; slows followers who hit it
- **Mushrooms**: +1 movement burst
- **Invincibility Shield**: Absorbs the next incoming hit then breaks
- **Mystery Box**: Opens immediately, gives a random item

### Terrain Effects

Track terrain actively affects movement each turn:
- **Sand / Slime**: Sticky surface — movement cap reduced (uses `/4` instead of `/3` divisor)
- **Slick Ice**: Handling penalty doubled when changing lanes
- **Speed Boost Pads**: +1 free space when a racer rolls over the pad

### Drafting & Blocking

- A racer within 3 spaces behind a same-lane leader gets +1 bonus movement (drafting)
- The leader can activate **Block Drafters** to stop this — but it costs the leader -1 space that turn
- Both choices are strategic: trailing racers want to draft; leading racers must decide whether blocking is worth the speed cost

### Weather Effects

Weather modes affect handling and speed:
- **Rain / Storm**: Handling penalty multiplied by 1.5
- **Wind (headwind)**: -1 maximum speed cap
- All weather modes include visual effects (particles, sky gradient, storm bands)

### Racer Stats

All three stats are used in movement calculation:
- **Speed** — Base movement rate (`ceil(currentSpeed / 3)` spaces per turn)
- **Acceleration** — How quickly speed recovers after a slowdown
- **Handling** — Reduces penalty for multi-lane changes

### Track Configuration

Tracks are fully configurable:
- **Track Length**: Total spaces from start to finish
- **Laps**: Number of laps around the track (1+)
- **Lanes**: Number of parallel lanes (affects drafting and strategy)
- **Terrain**: Per-track terrain type affecting movement and handling

## Board Game Edition — Frontend Features

The Lucky Races Board Game Edition is a full-featured 3D race client:

### 3D Board View
- Isometric Three.js scene with React Three Fiber
- Three.js 0.183, React Three Fiber 9.5, @react-three/drei 10.7
- Three track types: Segment (curved splines), Tile (Kenney GLB kit), Toroidal-Lemniscate (3D figure-8)
- Active terrain rendering (sand color, ice shimmer, speed pad glow)

### 19-Camera Broadcast System
- **Onboard**: Cockpit, T-Cam, Bumper, Rear-Facing, Mirror
- **Trackside**: Corner Low, Corner High, Start/Finish, Pit Lane
- **Moving**: Helicopter, Drone, Cable/SkyCam, Rail, Chase
- **Specialty**: Speed Ramp, Whip Pan, Compression, Dutch Angle, Wide Establishment
- Race Director auto-selects cameras by scoring proximity to events, variety, and race phase
- Picture-in-picture (PiP) panel overlay toggled via `P` key

### Visual Effects
- Night mode with headlights and taillights per racer
- Weather particles (rain, storm, wind)
- Boost particle bursts, shield bubbles, banana slip animations, mystery box reveal
- Slipstream speed-line ribbons for drafting (reduced-motion aware)
- Persistent skid marks, crowd reaction bursts on overtakes
- Photo mode with depth-of-field post-processing

### HUD & UI
- Card-based turn UI: Speed, Lane, Item, Shield, Block Drafters
- Animated leaderboard with position swap animations
- Minimap with gliding racer dots
- Notification toasts with `aria-live` for screen readers
- SpeedControls panel with full ARIA labelling (`aria-pressed`, `aria-expanded`, `aria-controls`)
- Controller icon prompts for 14 platforms (Xbox, PlayStation, Switch, keyboard, etc.)

### Game Modes
- **Single Race** — Quick Start drops into a 4-bot race in mock mode instantly
- **Tournament** — Best-of-3 bracket with bracket view before the first race
- **Spectate** — Follow any live race by room code (LIVE badge)
- **Replay** — Full turn-by-turn replay with shareable link and auto-generated race summary
- **Race History** — Past results with narrative summaries and leaderboard

### Accessibility
- ARIA labels on all interactive elements
- `aria-live="polite"` on notification toasts and zoom readout
- `prefers-reduced-motion` respected — particles and animations disabled when OS setting is on
- Focus-visible rings on all keyboard-focusable elements

## Original Racers (NFTs)

Original Racers are ERC-721 NFTs on Ethereum. Each racer is procedurally assembled from over 70 hand-modeled 3D parts created by professional artists, making every racer visually unique.

### Racer Properties
- **Speed**: Base movement rate
- **Acceleration**: How quickly the racer reaches top speed
- **Handling**: Effectiveness of lane changes and item use
- **Visual Parts**: Body, wheels, spoiler, engine, decals, and more — all 3D modeled

### Ownership
- Racers are owned on-chain via standard ERC-721
- 3D model and artwork are licensed to the holder
- Racers can be displayed, driven in the Racerverse, shared, gifted, or sold
- Viewable in the interactive 3D Viewer at https://viewer.racerverse.com

## Racer Personalities

Each racer ID maps to a named personality with catchphrases for overtakes, hits, lap completions, and finishing first:

| Racer | Name | Archetype | Icon |
|-------|------|-----------|------|
| 1 | Bolt | Speed Demon | ⚡ |
| 2 | Nitro | Aggressive | 💥 |
| 3 | Flash | Trickster | 🌟 |
| 4 | Grip | Strategist | 🎯 |

Example — Bolt wins: *"BOLT: Too fast, too flawless! ⚡"*
Example — Flash overtakes: *"FLASH: Blink and you miss me!"*

## Race Credits & Custodial Play

Race credits are the primary way to play Lucky Races without a crypto wallet. Players buy credits with a regular credit card via Stripe, then race without ever seeing a wallet prompt or a gas fee. The custodial service handles all on-chain transactions on the player's behalf.

### How Credits Work

1. Player purchases a credit pack via Stripe Checkout
2. Credits are added to their account balance
3. When submitting a race turn, the frontend calls the custody API instead of a wallet
4. The custody API deducts credits, enqueues a turn job, and submits `submitTurnChoices()` on Sepolia
5. The frontend polls for job completion (~1.5s intervals, 60s timeout)
6. On failure, credits are automatically refunded

### Credit Packs

| SKU | Credits | Price |
|-----|---------|-------|
| `credits-500` | 500 | $5.00 |
| `credits-2000` | 2,000 | $17.00 |
| `credits-5000` | 5,000 | $35.00 |

Payments are processed via Stripe (live mode). Credits are granted instantly on `checkout.session.completed` webhook.

### Custody Architecture

| Layer | Component | Role |
|-------|-----------|------|
| Frontend | `custodyApiClient.ts` | Balance queries, turn submission, Stripe checkout |
| Backend API | `custody-api` (Railway) | Auth, credit deduction, job enqueue |
| Worker | `custody-game-worker` (Railway) | Dequeues jobs, submits turns on-chain |
| Database | Railway Postgres | Credit balances, turn jobs, audit log |
| Queue | Railway Redis + BullMQ | `game-turn-queue` |
| Chain | Sepolia (→ mainnet) | Lucky Races Diamond contract |

### Client API (custodyApiClient.ts)

The board game frontend exposes these functions for credits mode:

- `getCreditsBalance(customerId)` → `{ balance: number }`
- `submitTurnAndWait(params)` → polls until `confirmed | failed`
- `startCreditsCheckout(sku, customerId, successUrl)` → Stripe Checkout session URL
- `CREDIT_PACKS` — exported constant array with SKU, credits, price, Stripe price ID

### Enabling Credits Mode

Set `VITE_DEFAULT_MODE=credits` and `VITE_CUSTODY_API_URL=https://custody-api-production.up.railway.app` in the board app environment. In credits mode the game uses local mock simulation for race rendering but routes all turn submissions through the custody service to Sepolia.

## Bot System

Seven built-in AI strategies:
- **aggressive** — Push/Overdrive, missiles at nearest racer ahead, opens mystery box immediately
- **defensive** — Normal speed, invincibility priority, always blocks drafters
- **balanced** — Adaptive speed, offensive when behind / defensive when ahead
- **chaotic** — Fully random choices
- **sniper** — Saves missiles for the leader only, ignores other items
- **turtle** — Normal speed, drafts the leader, always blocks
- **opportunist** — Aggressive when trailing, defensive when leading

Bots execute turns in parallel before each tick. Custom strategies can be added via the open bot API.

## Smart Contract Architecture

Lucky Races uses the **Diamond proxy pattern (EIP-2535)**:

- **Diamond Proxy**: Single entry point contract that delegates calls to facets
- **Facets**: Modular contracts handling specific game logic (lobby management, race processing, item effects, etc.)
- **Upgradeable**: New facets can be added and existing ones replaced without losing state
- **Track Contract**: Separate UUPS-upgradeable contract (ERC1967Proxy) for track management

Built with:
- Solidity 0.8.34
- OpenZeppelin v5
- Foundry for testing and deployment

## The Racerverse Ecosystem

The Racerverse is the broader ecosystem created by Lucky Machines LLC:

- **Lucky Races**: The on-chain multiplayer racing game
- **Racerverse Platform** (racerverse.com): User accounts, authentication, collection management
- **3D Viewer** (viewer.racerverse.com): Interactive 3D inspection of racers — spin, zoom, inspect
- **Global Collection**: Browse all Original Racers across the collection
- **Explorable World**: Take your racer for a cruise through a vibrant 3D environment

Racerverse is a trademark of Lucky Machines LLC. It is not affiliated with Hot Wheels or Mattel.

## Automation and Composability

Lucky Races is designed for composability:
- **Bot Integration**: Build custom AI strategies that submit turns programmatically
- **AutoLoop**: Automated race processing for hands-free racing
- **Chainlink Compatible**: Supports Chainlink automation for decentralized race orchestration
- **Open Contracts**: Smart contracts are on-chain and composable with other protocols

## Team

- **James Pollack** — Creative Technology
- **Max Meier** — Platform Engineering
- **Daniel Dugan** — Lead Designer
- **Tom Donaldson** — Lead Artist

## Company

- **Developer**: Lucky Machines LLC
- **Website**: https://luckymachines.io
- **Email**: hello@luckyraces.com

## Frequently Asked Questions

**What is Lucky Races?**
Lucky Races is a fully on-chain multiplayer racing game built on Ethereum with a cinematic 3D board game view. Every race, turn, and outcome is recorded on the blockchain, ensuring transparent, verifiable competition.

**Do I need a crypto wallet to play?**
No. You can buy race credits with a regular credit card and play immediately — no wallet, no gas fees, no setup. If you want to use your own racer NFTs or interact directly with the blockchain, you can optionally connect a wallet like MetaMask.

**How do races work?**
Races are turn-based. Each round, you submit your choices using a card-based UI — speed mode, lane, items, shield, and block-drafters. The smart contracts process all turns deterministically, so outcomes are fair and auditable.

**What are items and how do I use them?**
During a race, you can pick up items like Speed Boosts, Missiles, Bananas, Mushrooms, Invincibility Shields, and Mystery Boxes. Each item has a unique effect — boost your speed, slow down opponents, or protect yourself from attacks. Mystery Boxes open immediately and give a random item.

**What are terrain effects?**
Tracks have active terrain types that change the rules each turn. Sand and Slime reduce your movement cap (sticky surface). Slick Ice doubles handling penalties when changing lanes. Speed Boost pads give a free +1 space when you roll over them.

**What is drafting and blocking?**
If you trail within 3 spaces of a racer in the same lane, you get a free +1 space (drafting). Leading racers can activate Block Drafters to stop this — but it costs them -1 space that turn, making it a genuine strategic tradeoff.

**Is there a gas fee for each race?**
Not if you use race credits. The credits path is completely gasless — the custody service handles all blockchain transactions on your behalf. If you connect your own wallet and race directly on-chain, standard Ethereum gas fees apply.

**How is fairness guaranteed?**
Every race uses deterministic smart contracts. Given the same inputs, the same outputs will always be produced. There's no randomness controlled by any single party — all game logic lives on-chain.

**What are Original Racers?**
Original Racers are unique NFTs assembled from 70+ handcrafted 3D parts. Each racer has distinct stats (speed, acceleration, handling) that affect gameplay. They're yours forever on Ethereum.

**What is the Board Game Edition?**
The Board Game Edition is the full-featured 3D race client. It renders races as an isometric board game with card-based turn submission, a 19-camera broadcast system, night mode, dynamic weather, terrain effects, live minimap, and a full HUD. You can also spectate live races or replay any past race turn-by-turn.

**What is Tournament mode?**
Tournament mode is a best-of-3 bracket format. A bracket is displayed before the first race. Wins are tracked across all three races and the racer who wins two is crowned champion. The third race only runs if needed as a tiebreaker.

**Can I watch someone else race live?**
Yes. Spectate mode lets you follow any live race by entering its room code. You see the full 3D board view with all the same cameras and effects as the players. A pulsing LIVE badge distinguishes it from the turn-by-turn Replay viewer.

**Can I build bots or automate my racing?**
Yes. Lucky Races supports bot AI strategies and automation. Seven built-in strategies are provided (aggressive, defensive, balanced, chaotic, sniper, turtle, opportunist), and custom strategies can be added. The game is designed to be composable — you can build your own strategies, automate race participation, or integrate with other on-chain systems.

## API Access for AI Agents (x402 Payment Protocol)

Lucky Races implements the x402 payment protocol (HTTP 402 Payment Required) for programmatic access by AI agents, bots, and automated systems. Agents pay USDC per request on the Base network via the standard x402 flow.

### How x402 Works

1. Agent sends a request to a protected endpoint
2. Server responds with HTTP 402 and payment requirements in headers
3. Agent signs a USDC payment and retries the request with the payment signature
4. Server verifies payment via Coinbase facilitator, processes the request, and settles payment
5. Agent receives the response data

### Endpoints

#### GET /api/x402/race-data — $0.001 per request

Query game data. Use the `type` parameter to select data:

- `?type=stats` — Global game statistics (total races, active lobbies, etc.)
- `?type=leaderboard` — Top racers ranked by win rate
- `?type=race&id=<raceId>` — Full race data: track config, racers, winner, turn count, timestamps, tx hash
- `?type=replay&id=<raceId>` — Turn-by-turn replay: positions, lanes, items used per turn
- `?type=racer&id=<racerId>` — Racer stats: speed/acceleration/handling, race history, win rate, 3D viewer link

#### POST /api/x402/bot-entry — $0.01 per entry

Register an AI agent or bot for race participation. Request body:

```json
{
  "botAddress": "0x...",          // Bot's Ethereum wallet address
  "racerId": "42",               // Racer token ID to race with
  "lobbyId": "0x...",            // Existing lobby ID to join (optional)
  "trackConfig": {               // Required only when creating a new lobby
    "length": 100,
    "laps": 3,
    "lanes": 4,
    "maxRacers": 8
  }
}
```

Returns an entry ticket with:
- Signed authorization token (SHA-256)
- Step-by-step instructions for the on-chain lobby join/create
- 5-minute expiration window

### Payment Configuration

- **Network**: Base (chain ID 8453)
- **Currency**: USDC (ERC-20)
- **Protocol**: x402 v2 (HTTP 402 Payment Required)
- **Facilitator**: Coinbase CDP (`https://api.cdp.coinbase.com/platform/v2/x402`)
- **Pay To**: `0x776a39ad55Bf647B804A7ad42C93d3a9e3569f5b`
- **Discovery**: `https://luckyraces.com/.well-known/x402.json`

### Client Libraries

Any x402-compatible client can interact with these endpoints:
- TypeScript: `@x402/fetch` or `@x402/axios`
- Python: `x402`
- Go: `github.com/coinbase/x402/go`

## Privacy

Lucky Races marketing site uses GDPR-compliant analytics:
- No cookies
- No personal data stored
- IP addresses are SHA-256 hashed (one-way) for unique visitor counting
- All data stays on own infrastructure (no third-party analytics services)