/crypto-racer

Primary LanguageTypeScript

🏎️ Crypto Racer

A React-based racing game where players earn ERC-20 tokens based on their racing performance. Built with Next.js and integrated with thirdweb API for authentication and token distribution.

🎮 Features

  • Real-time Racing Game: Smooth 2D racing with obstacle avoidance
  • Performance-based Rewards: Earn tokens based on race completion time and performance
  • Anti-cheat System: Server-side verification before token distribution
  • thirdweb Integration: Secure authentication and smart contract interactions
  • Modern UI: Beautiful, responsive design with Tailwind CSS
  • Achievement System: Track progress and unlock milestones

🚀 Getting Started

Prerequisites

  • Node.js 18+
  • npm or yarn
  • thirdweb account and API keys

Installation

  1. Clone the repository

    git clone <your-repo-url>
cd crypto-racer

  2. Install dependencies

    npm install

  3. Set up environment variables Create a .env.local file in the root directory:

    # Thirdweb API Configuration
THIRDWEB_SECRET_KEY=your_secret_key_here
TOKEN_CONTRACT_ADDRESS=0x...your_token_contract_address
CHAIN_ID=84532
ADMIN_ADDRESS=0x...your_admin_wallet_address

# Game Configuration
GAME_REWARD_BASE=100
GAME_REWARD_MAX=500
GAME_VERIFICATION_WINDOW=86400000

  4. Run the development server

    npm run dev

  5. Open your browser Navigate to http://localhost:3000

🎯 How to Play

  1. Login: Enter your email to authenticate with thirdweb
  2. Start Racing: Press SPACE to begin a race
  3. Control: Use A/D or Arrow Keys to move left/right
  4. Objective: Avoid red obstacles and reach 1000 points
  5. Earn Tokens: Complete races to earn ERC-20 tokens
  6. Claim Rewards: Use the reward system to claim your tokens

🏗️ Architecture

Frontend Components

  • RacingGame: Main game logic with collision detection and scoring
  • AuthComponent: thirdweb authentication integration
  • RewardSystem: Token claiming and distribution
  • GameStats: Performance tracking and achievements

Backend API

  • /api/claim-rewards: Server-side verification and token distribution
  • Anti-cheat Protection: Validates game performance before rewards
  • thirdweb Integration: Secure smart contract interactions

Game Mechanics

  • Scoring System: Points based on survival time and obstacle avoidance
  • Difficulty Scaling: Obstacles move faster as score increases
  • Performance Tracking: Records best times and total races
  • Reward Calculation: Tokens based on time, performance, and race count

🔐 Security Features

  • Server-side Verification: All game completions verified before rewards
  • Timestamp Validation: Prevents replay attacks
  • Performance Validation: Ensures reasonable game statistics
  • Rate Limiting: Built-in protection against abuse

🪙 Token System

Reward Structure

  • Base Reward: 100 tokens per completed race
  • Time Bonus: Up to 50 tokens for faster completion
  • Performance Bonus: 10 tokens per race completed
  • Maximum Reward: Capped at 500 tokens per session

Distribution Process

  1. Game completion data sent to server
  2. Server verifies performance and calculates rewards
  3. thirdweb API called to mint/transfer tokens
  4. Transaction hash returned to user

🛠️ Configuration

Environment Variables

  • THIRDWEB_SECRET_KEY: Your thirdweb API secret key
  • TOKEN_CONTRACT_ADDRESS: ERC-20 token contract address
  • CHAIN_ID: Target blockchain network ID
  • ADMIN_ADDRESS: Admin wallet for token distribution

Game Settings

  • GAME_REWARD_BASE: Base tokens per race
  • GAME_REWARD_MAX: Maximum tokens per session
  • GAME_VERIFICATION_WINDOW: Time window for valid sessions

🚧 Development

Project Structure

crypto-racer/
├── app/                    # Next.js app directory
│   ├── api/               # API routes
│   ├── components/        # React components
│   ├── globals.css        # Global styles
│   ├── layout.tsx         # Root layout
│   └── page.tsx           # Main page
├── components/             # Shared components
├── package.json            # Dependencies
├── tailwind.config.ts      # Tailwind configuration
└── tsconfig.json           # TypeScript configuration

Available Scripts

  • npm run dev: Start development server
  • npm run build: Build for production
  • npm run start: Start production server
  • npm run lint: Run ESLint

🔧 Customization

Game Difficulty

Modify obstacle spawn rates and speeds in RacingGame.tsx:

// Obstacle spawn rate
if (Math.random() < 0.02) { ... }

// Speed increase
setObstacleSpeed(prev => Math.min(prev + 0.5, 8))

Reward System

Adjust token calculations in RewardSystem.tsx:

const baseReward = 100
const timeBonus = Math.max(0, 50 - Math.floor(gameStats.bestTime / 1000))
const performanceBonus = Math.floor(gameStats.totalRaces * 10)

Visual Styling

Customize colors and animations in tailwind.config.ts:

colors: {
  'race-red': '#e74c3c',
  'race-blue': '#3498db',
  'race-green': '#2ecc71',
}

🚀 Deployment

Vercel (Recommended)

  1. Connect your GitHub repository
  2. Set environment variables in Vercel dashboard
  3. Deploy automatically on push

Other Platforms

  1. Build the project: npm run build
  2. Set environment variables
  3. Deploy the out directory

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

  • Issues: Create a GitHub issue
  • Documentation: Check the thirdweb API docs
  • Community: Join our Discord server

🔮 Future Enhancements

  • Multiplayer racing
  • NFT car skins
  • Leaderboards
  • Tournament system
  • Mobile optimization
  • More game modes

Built with ❤️ using Next.js, React, and thirdweb