Skip to content

README.md

Latest commit

 

History

History
300 lines (230 loc) · 9.53 KB

README.md

File metadata and controls

300 lines (230 loc) · 9.53 KB

🐍 Snake Race - On-Chain Dojo Game

A fully on-chain competitive snake game built with Dojo and deployed on Starknet. Race against AI opponents, collect power-ups, and compete for the top spot on the leaderboard across multiple difficulty modes!

🎮 Game Overview

Snake Race is a multiplayer-style snake game where you compete against an AI opponent. The goal is to:

  • Collect apples to grow and increase your score
  • Race against time (2-minute rounds)
  • Beat the AI by having a higher score when time runs out
  • Win bonus: Your score doubles when you win, and your highscore is updated immediately!
  • Avoid hitting walls or yourself (your score resets to 0 on collision)

✨ Features

🎯 Game Mechanics

  • Real-time Snake Gameplay: Classic snake mechanics with smooth controls
  • AI Opponent: Smart AI that adapts to difficulty settings
  • Power-ups System:
    • Double Points: Doubles your score per apple for 10 seconds
    • Freeze: Freezes the AI for 10 seconds, giving you an advantage
  • Score System: Points for eating apples, with bonus multipliers
  • Time Limit: 2-minute rounds for fast-paced gameplay

🤖 AI Difficulty Modes

  • Easy Mode: Slower AI speed (1.2s per move) - Perfect for beginners
  • Medium Mode: Balanced AI speed (0.9s per move) - Good challenge
  • Hard Mode: Fast AI speed (0.45s per move) + Smart AI that chases power-ups
    • Hard AI can collect power-ups and use them against you!
    • Double Points doubles AI's score too
    • Freeze power-up will freeze YOUR movement when AI collects it

📊 Leaderboard System

  • Per-Mode Leaderboards: Separate leaderboards for Easy, Medium, and Hard modes
  • Top 10 Rankings: Compete for top positions across all difficulty levels
  • Real-time Updates: Leaderboard updates automatically after each game
  • Highscore Tracking: Personal best scores tracked per difficulty mode

💻 Technical Features

  • Fully On-Chain: All game state stored on Starknet blockchain
  • Real-time Sync: Torii indexer provides instant state updates
  • Responsive UI: Beautiful, modern interface that works on all screen sizes
  • Wallet Integration: Cartridge Controller for seamless wallet management

🏗️ Architecture

This project is built in two main parts:

1. Contracts (/contracts)

Dojo smart contracts deployed on Starknet that manage all game state:

  • Models (src/models.cairo):

    • PlayerState: Tracks player score, alive status, powerups, and mode
    • Position: Player/AI snake positions and lengths
    • Apple: Apple spawn location
    • PowerUp: Power-up spawn location and type
    • Highscore: Player highscores per difficulty mode
    • LeaderboardEntry: Top 10 leaderboard entries per mode

  • Systems (src/systems/actions.cairo):

    • start: Initialize game with selected AI mode
    • move: Handle player movement
    • eat_apple: Increase score and grow snake
    • activate_powerup: Apply power-up effects
    • update_highscore: Update player's best score
    • double_score_on_win: Double score when player wins
    • clear_powerup: Clear expired power-up states

2. Client (/client)

Frontend application that interacts with the contracts:

  • HTML/CSS/JavaScript: Vanilla frontend (no React)
  • Tailwind CSS: Modern, responsive styling
  • Dojo SDK: Connects to world contract and Torii indexer
  • Cartridge Controller: Wallet connection and transaction signing

🛠️ Prerequisites

Before you begin, ensure you have the following installed:

  • Node.js (v18 or higher) and pnpm package manager
  • asdf (version manager) - for installing Dojo toolchain
  • Google Chrome (recommended for Cartridge Controller support)

📦 Installation & Setup

Step 1: Install Dojo Toolchain

Install the Dojo toolchain using the official installer:

curl -L https://install.dojoengine.org | bash

After installation, restart your terminal or run:

source ~/.bashrc  # or ~/.zshrc depending on your shell

Verify installation:

sozo --version
katana --version
torii --version

Step 2: Clone and Navigate

cd dojo-intro

Step 3: Install Client Dependencies

cd client
pnpm install
cd ..

🚀 Running Locally

Step 1: Start the Development Environment

From the contracts directory, run the development script:

cd contracts
scarb run dev

This script will:

  1. Start Katana: Local Starknet development network
  2. Build Contracts: Compile Dojo contracts
  3. Deploy World: Deploy the world contract and all systems
  4. Start Torii: Start the indexing service on http://localhost:8080

You should see output like:

🚀 Starting Katana...
✅ Katana started
🔨 Building contracts...
✅ Contracts built
🌍 Deploying world...
✅ World deployed
📡 Starting Torii...
✅ Torii started

Keep this terminal running!

Step 2: Start the Client

Open a new terminal and run:

cd client
pnpm run dev

The client will start on https://localhost:5173 (HTTPS required for Cartridge Controller).

Step 3: Play the Game!

  1. Open your browser and navigate to https://localhost:5173
  2. Click "Connect Wallet" to connect with Cartridge Controller
  3. Select your AI difficulty mode (Easy, Medium, or Hard)
  4. Click "Start Game" to begin
  5. Use arrow keys or WASD to control your snake
  6. Collect apples, avoid walls/yourself, and beat the AI!

🎮 How to Play

Controls

  • Arrow Keys or WASD: Move your snake
  • Spacebar: Pause/Resume game
  • H: Toggle help modal
  • L: Toggle leaderboard modal

Game Rules

  1. Collect Apples: Each apple increases your score by 10 points (20 with Double Points active)
  2. Power-ups:
    • 🟢 Double Points: Active for 10 seconds, doubles your score per apple
    • 🔵 Freeze: Freezes AI for 10 seconds (or you if Hard AI collects it)
  3. Winning: Player wins if they have a higher score than AI when time runs out
  4. Losing: Player loses if:
    • They hit a wall (score resets to 0)
    • They hit themselves (score resets to 0)
    • They have lower score than AI when time runs out
  5. Score Doubling: When you win, your score is automatically doubled and your highscore is updated!

Scoring

  • Regular apple: 10 points
  • Apple with Double Points: 20 points
  • Score doubles on win: 2x multiplier
  • Highscore tracked separately for each difficulty mode

📁 Project Structure

dojo-intro/
├── contracts/              # Dojo smart contracts
│   ├── src/
│   │   ├── models.cairo   # Data models (PlayerState, Position, etc.)
│   │   ├── systems/
│   │   │   └── actions.cairo  # Game logic systems
│   │   └── lib.cairo       # Library exports
│   ├── Scarb.toml         # Cairo package configuration
│   ├── katana.toml        # Katana devnet configuration
│   ├── torii_dev.toml     # Torii indexer configuration
│   └── dev.sh             # Development script
│
├── client/                # Frontend application
│   ├── index.html         # Main HTML file
│   ├── game.js            # Game logic and Dojo integration
│   ├── controller.js      # Cartridge Controller configuration
│   ├── style.css          # Custom styles
│   ├── tailwind.config.js # Tailwind CSS configuration
│   └── package.json       # Node.js dependencies
│
└── README.md              # This file

🔧 Development

Building Contracts

cd contracts
sozo build

Testing Contracts

cd contracts
sozo test

Deploying to Devnet

The dev.sh script handles deployment automatically. For manual deployment:

cd contracts
sozo build
sozo migrate --name dev

Torii Indexer

Torii provides GraphQL and REST APIs for querying on-chain data:

  • GraphQL: http://localhost:8080/graphql
  • REST API: http://localhost:8080/entities

🐛 Troubleshooting

"Insufficient funds" error

  • The Cartridge Controller creates its own account that may need manual funding
  • You can fund it using Katana's prefunded accounts or faucet

Contracts not deploying

  • Ensure Katana is running: katana --allowed-origins "*"
  • Check that ports 5050 (Katana) and 8080 (Torii) are available

Client not connecting

  • Ensure you're using HTTPS (https://localhost:5173)
  • Chrome is recommended for Cartridge Controller support
  • Check browser console for connection errors

Torii not syncing

  • Restart Torii: pkill torii then run scarb run dev again
  • Wait a few seconds after transactions for Torii to index

🛡️ Security Notes

  • This is a development/demo project for learning Dojo
  • Never use production secrets or keys in development
  • Katana devnet uses deterministic accounts for testing

📚 Resources

🎉 Features Showcase

What Makes This Special?

  • ✅ Fully On-Chain: Every game action is a blockchain transaction
  • ✅ Real-time Updates: Torii indexer provides instant state sync
  • ✅ Multiple Difficulty Modes: Separate leaderboards for each mode
  • ✅ Smart AI: Hard mode AI can collect and use power-ups
  • ✅ Responsive Design: Beautiful UI that works on all devices
  • ✅ Score Doubling: Exciting win mechanic that doubles your score

Happy Gaming! 🎮🐍