Skip to content

README.md

Latest commit

 

History

History
381 lines (273 loc) · 10.2 KB

README.md

File metadata and controls

381 lines (273 loc) · 10.2 KB

QuadClue

A blockchain-based word puzzle game built on the Dojo engine, where players solve puzzles by guessing words based on image clues.

Table of Contents

Overview

QuadClue is a decentralized puzzle game where:

  • Players view 4 images and guess the connecting word
  • Each puzzle has available letters that can be used to form the answer
  • Players earn points and coins for correct answers
  • Game state is stored on the Starknet blockchain via Dojo
  • Features include hints, scoring system, and level progression

How to Play

Step 1: Study the Images

  • Look at all 4 pictures carefully
  • Find the common theme or connection between them
  • Think about what word could describe or relate to all images

Step 2: Check the Word Length

  • Look at the word slots (empty boxes)
  • Count how many letters the answer has
  • This gives you a clue about the word length

Step 3: Use Available Letters

  • You'll see 12 letters at the bottom of the screen
  • These are the only letters you can use to form your answer
  • Drag and drop or tap letters to spell your guess
  • You can only use each letter once (unless it appears multiple times)

Step 4: Submit Your Guess

  • Once you've spelled out your word, submit your guess
  • If correct: ✅ You earn points and solve the puzzle!
  • If wrong: ❌ Try again with different letters

Prerequisites

Before you begin, make sure you have the following installed:

Installing Dojo

If you don't have Dojo installed:

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

Local Development Setup

Step 1: Clone the Repository

git clone <repository-url>
cd QuadClue

Step 2: Set Up the Dojo Contract

Navigate to the contract directory and set up the blockchain infrastructure:

cd contract

Terminal 1: Start Katana (Local Starknet Node)

katana --dev --http.api dev,starknet --dev.no-fee --http.cors_origins '*'

Keep this terminal running. Katana will output several important details:

  • Account addresses and private keys
  • RPC URL (typically http://localhost:5050)
  • World address (generated after migration)

Terminal 2: Build and Deploy Contracts

# Build the contracts and generate TypeScript bindings
sozo build --typescript

# Deploy the contracts to Katana
sozo migrate

Important: After running sozo migrate, note the WORLD_ADDRESS from the output. You'll need this for the next steps.

Terminal 3: Start Torii (Dojo Indexer)

# Replace <WORLD_ADDRESS> with the actual world address from sozo migrate
torii --world <WORLD_ADDRESS> --http.cors_origins "*"

Step 3: Set Up the Frontend

Open a new terminal and navigate to the frontend directory:

cd ../front-end

# Install dependencies (use legacy peer deps to resolve conflicts)
npm install --legacy-peer-deps

Update Frontend Configuration

  1. Update Manifest File

After running sozo migrate, copy the generated manifest file to the frontend:

# From the contract directory
cp manifest_dev.json ../front-end/
  1. Update Dojo Configuration

Open front-end/src/lib/dojo/dojoConfig.ts and update the master address and private key to match your Katana instance:

export const dojoConfig = createDojoConfig({
    // Replace these with the account details from your Katana output
    masterAddress: "0x127fd5f1fe78a71f8bcd1fec63e3fe2f0486b6ecd5c86a0466c3a21fa5cfcec",
    masterPrivateKey: "0xc5b2fcab997346f3ea1c00b002ecf6f382c5f9c9659a3894eb783c5320f912",
    
    // These usually don't need to change for local development
    accountClassHash: "0x07dc7899aa655b0aae51eadff6d801a58e97dd99cf4666ee59e704249e51adf2",
    feeTokenAddress: "0x4718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d",
    manifest,
});

Step 4: Start the Frontend

# From the front-end directory
npm run dev

The application will be available at http://localhost:3000.

Project Structure

QuadClue/
├── contract/                 # Dojo smart contracts
│   ├── src/
│   │   ├── lib.cairo        # Main contract library
│   │   ├── models.cairo     # Data models
│   │   └── systems/         # Contract systems
│   ├── dojo_dev.toml        # Dojo development config
│   └── manifest_dev.json    # Generated contract manifest
│
├── front-end/               # Next.js frontend application
│   ├── src/
│   │   ├── app/            # Next.js app router pages
│   │   ├── components/     # React components
│   │   ├── lib/            # Utilities and Dojo integration
│   │   └── types/          # TypeScript type definitions
│   ├── public/             # Static assets
│   └── package.json        # Frontend dependencies
│
└── README.md               # This file

Configuration

Key Configuration Files

  1. contract/dojo_dev.toml - Dojo world configuration
  2. contract/manifest_dev.json - Generated contract manifest (auto-generated)
  3. front-end/src/lib/dojo/dojoConfig.ts - Frontend Dojo configuration
  4. front-end/manifest_dev.json - Copy of contract manifest for frontend

Environment Variables

The app uses these default configurations:

  • RPC URL: http://localhost:5050 (Katana)
  • Torii URL: http://localhost:8080 (Torii indexer)

Game Flow

1. Connect Wallet

When you first open the app:

  1. The app will prompt you to connect a wallet
  2. Use one of the pre-deployed Katana accounts
  3. The app supports Katana's built-in accounts for local development

2. Create Test Puzzles (Dashboard)

Navigate to http://localhost:3000/dashboard to create puzzles:

  1. Quick Test: Click "Create Test Puzzle (PAINT)" to create a pre-configured puzzle
  2. Custom Puzzle:
    • Fill in 4 image hashes or URLs
    • Provide an answer (3+ characters)
    • Click "Create Puzzle"

Example test puzzle data:

  • Images: 4 URLs or hashes representing the concept
  • Answer: The word that connects all images (e.g., "PAINT")

3. Play the Game

Navigate to http://localhost:3000/game to play:

  1. View the 4 images for each puzzle
  2. Use available letters to spell the answer
  3. Letters are shuffled - use the shuffle button to rearrange
  4. Complete puzzles to earn points and advance levels

4. Game Features

  • Hints: Use hints to reveal letters (limited per puzzle)
  • Scoring: Based on time and hints used
  • Progression: Unlock new levels by completing puzzles
  • Persistence: Game state is saved on the blockchain

Troubleshooting

Common Issues

1. "Failed to Initialize Dojo SDK"

Symptoms: App shows initialization error

Solutions:

  • Ensure Katana is running on http://localhost:5050
  • Verify Torii is running and connected to the correct world address
  • Check that manifest_dev.json is up to date in both contract and frontend directories
  • Restart all services in order: Katana → Deploy → Torii → Frontend

2. Wallet Connection Issues

Symptoms: Cannot connect wallet or transactions fail

Solutions:

  • Use the correct account address/private key from Katana output
  • Ensure the account has sufficient balance (Katana provides prefunded accounts)
  • Check browser console for connection errors

3. Contract Interaction Errors

Symptoms: Puzzle creation or game actions fail

Solutions:

  • Verify the world address in Torii matches the deployed world
  • Ensure all contracts are properly migrated
  • Check that the account has necessary permissions

4. "Module not found" or Dependency Issues

Symptoms: Build errors or import failures

Solutions:

# Clear dependencies and reinstall
cd front-end
rm -rf node_modules package-lock.json
npm install --legacy-peer-deps

Starting Fresh

To completely reset your local environment:

  1. Stop all services (Katana, Torii, Frontend)
  2. Restart Katana with a fresh state
  3. Rebuild and redeploy contracts: 
    cd contract
sozo build --typescript
sozo migrate
  4. Update manifest in frontend: 
    cp manifest_dev.json ../front-end/
  5. Restart Torii with new world address
  6. Update dojoConfig.ts with new account details
  7. Restart frontend

Architecture

Technology Stack

  • Blockchain: Starknet with Cairo smart contracts
  • Game Engine: Dojo framework for autonomous worlds
  • Frontend: Next.js 15 with TypeScript
  • Styling: Tailwind CSS
  • State Management: Zustand + Dojo SDK
  • Wallet Integration: Starknet React

Key Components

  • Smart Contracts: Handle game logic, puzzle storage, and player progression
  • Dojo SDK: Provides blockchain integration and state synchronization
  • React Components: UI components for game interface
  • Katana: Local Starknet node for development
  • Torii: Dojo indexer for efficient data querying

Development Commands

Contract Commands

cd contract

# Build contracts
sozo build

# Build with TypeScript bindings
sozo build --typescript

# Deploy to local Katana
sozo migrate

# Start local node
katana --dev --http.api dev,starknet --dev.no-fee --http.cors_origins '*'

# Start indexer (replace <WORLD_ADDRESS>)
torii --world <WORLD_ADDRESS> --http.cors_origins "*"

Frontend Commands

cd front-end

# Install dependencies
npm install --legacy-peer-deps

# Development server
npm run dev

# Production build
npm run build

# Start production server
npm start

# Lint code
npm run lint

For more information about Dojo development, visit the official documentation.

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Test locally following the setup guide
  5. Submit a pull request

License

[Add your license information here]