Skip to content

Commit

Permalink
update readmew
Browse files Browse the repository at this point in the history
  • Loading branch information
@Kagwep
Kagwep committed Sep 20, 2024
1 parent f91b209 commit 3d529a2
Showing 1 changed file with 115 additions and 111 deletions.
226 changes: 115 additions & 111 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,179 +5,183 @@

Oware is a two-player game belonging to the Mancala family of board games. The game is played on a board with 12 pits (or houses) arranged in two rows of six, with each player controlling the six pits on their side of the board.

<img src="https://res.cloudinary.com/dydj8hnhz/image/upload/v1726751708/st2hf6gvjfaqgqqvufbo.png" alt="Detailed view of Oware board setup" />

## Game Setup

1. The board starts with 4 seeds in each of the 12 pits.
2. Players sit on opposite sides of the board, each controlling the row closest to them.


## Basic Rules

1. **Objective**: The goal is to capture more seeds than your opponent.

2. **Turn Structure**:
- On their turn, a player chooses one of their six pits containing seeds.
- The player then distributes these seeds, one by one, counterclockwise into the subsequent pits.

<img src="https://res.cloudinary.com/dydj8hnhz/image/upload/v1726751708/utv4wuff6ev4bodkmuzw.png" alt="Animation of seed distribution during a turn" />

3. **Capturing**:
- If the last seed dropped lands in an opponent's pit and brings the total seeds in that pit to 2 or 3, the player captures all seeds in that pit.
- The player also captures seeds from any preceding adjacent opponent's pits that also contain 2 or 3 seeds.

4. **Special Rules**:
- If a move would capture all of the opponent's seeds, the capture is forfeit.
- A player must make a move that gives their opponent seeds if possible.

5. **Game End**:
- The game ends when one player has captured more than 24 seeds, or when only one player can make a move.

## Our Implementation

Our version of Oware enhances the traditional gameplay with several unique features:

1. **AI Opponents**: Players can challenge AI opponents of varying difficulty levels, trained using machine learning techniques on the Cartesi Virtual Machine.

<img src="https://res.cloudinary.com/dydj8hnhz/image/upload/v1726751708/st2hf6gvjfaqgqqvufbo.png" alt="Detailed view of Oware board setup" />

2. **3D Visualization**: The game board and pieces are rendered in stunning 3D graphics using Babylon.js, providing an immersive gaming experience.
### Developer and User Guides

3. **Tournaments**: Players can participate in automated tournaments with smart contract-managed reward distribution.
# Project Setup and Running Guide

<img src="https://res.cloudinary.com/dydj8hnhz/image/upload/v1726751707/jrzlclitjt7askyufdvx.png" alt="Tournament lobby and bracket visualization" />
This guide provides instructions for setting up and running the backend, frontend, and Oware Rewards contract of the project locally.

## Table of Contents

4. **Blockchain Integration**: Game results, player statistics, and achievements are securely recorded , ensuring transparency and enabling a rich ecosystem of rewards and progression.
1. [Project Setup and Running Guide](#project-setup-and-running-guide)
- [Running the Backend](#running-the-backend)
- [Running the Frontend](#running-the-frontend)
2. [Interacting with the DApp](#interacting-with-the-dapp)
- [Connect Your Wallet](#1-connect-your-wallet)
- [Ensure You're on the Local Network](#2-ensure-youre-on-the-local-network)
- [Explore and Interact](#3-explore-and-interact)
3. [Optional: Deploying the Oware NFT Contract](#optional-deploying-the-oware-nft-contract)
4. [Troubleshooting](#troubleshooting)

## Project Setup and Running Guide

## Strategy Tips
### Running the Backend

1. Plan several moves ahead, considering both offensive and defensive strategies.
2. Try to keep your pits with low seed counts to limit your opponent's capturing opportunities.
3. Use the special rules to your advantage, sometimes forcing your opponent into suboptimal moves.
4. In the endgame, count carefully to ensure you're on track to capture the majority of seeds.
1. **Navigate to the oware-dapp Folder**
- Open your terminal and `cd` into the `oware-dapp` folder.

2. **Build and Run the Application**
- Run the following commands:
```bash
cartesi build
cartesi run
```

### Running the Frontend

## Project Documentation
1. **Open a new terminal and navigate to the Oware Frontend Folder**
- `cd` into the `oware-frontend` folder.

### Developer and User Guides
2. **Install Dependencies**
```bash
npm install
```

# Project Setup and Running Guide
3. **Set Up Environment Variables**
- Create a `.env` file with the following content:
```
VITE_MODE=local
```

This guide provides instructions for setting up and running the backend, relayer, frontend, and Oware Rewards contract of the project locally.
4. **Start the Frontend**
```bash
npm run dev
```

## Table of Contents
## Interacting with the DApp

- [Running the Backend](#running-the-backend)
- [Running the Frontend](#running-the-frontend)
- [Running the Oware NFT Contract](#running-the-nebula-contract)
After successfully running the frontend, you'll want to interact with the DApp. Follow these steps:
## Running the Backend
### 1. Connect Your Wallet
1. **Navigate to the App Folder**
1. Open your web browser and navigate to the frontend URL (typically `http://localhost:5173`).
2. Look for a "Connect Wallet" button, top right corner of the page.
3. Click on the button and select your preferred wallet (e.g., MetaMask).
4. Follow the prompts in your wallet to connect it to the DApp.
- Open your terminal and `cd` into the `oware-dapp` folder.
### 2. Ensure You're on the Local Network

1. Open your wallet (e.g., MetaMask) and check the network selection.
2. Make sure you're connected to your local network (Hardhat node running on `http://localhost:8545`).
3. If not on the correct network, add a new network with these details:
- Network Name: Hardhat Local
- New RPC URL: http://localhost:8545
- Chain ID: 31337
- Currency Symbol: ETH
2. **Build and Run the Application**
### 3. Explore and Interact
- Run the following commands:
```bash
cartesi build
cartesi run
```
1. Once connected and on the correct network, you should see your wallet address and be able to interact with the DApp.
2. Explore all the Oware game features thoroughly:
- Start a new challenge
- Start a new tournament
- Make moves in the game
- View your game profile
- Check out any leaderboards
3. Play multiple games to get a full experience of the DApp's functionality.
4. Test all available features and interactions to ensure everything is working as expected.


## Running the Frontend
## Optional: Deploying the Oware NFT Contract

1. **Navigate to the Frontend Folder**

`cd` into the `oware-frontend` folder.
1. **Open a new terminal and open the oware NFT rewards Folder**
- `cd` into the `oware-nft` folder.

2. **Install Dependencies**

- Run the following command:

```bash
npm install
```
```bash
npm install
```

3. **Set Up Environment Variables**
- Create a `.env` file with the following content:
```
WALLET_KEY=<your_wallet_private_key>
```

- Create a `.env` file with the following details:

4. **Deploy Locally**
- Start a local node:
```bash
npx hardhat node --port 8546
```
VITE_MODE=local
- Deploy the contract locally:
```bash
npx hardhat ignition deploy ./ignition/modules/OwareNFTReward.ts --network base-local
```

5. **Interact with the NFT Contract (if applicable)**
- After deployment, return to the DApp frontend.
- Look for any new sections or features related to NFT rewards or minting.

## Game Setup

4. **Start the Frontend**
1. The board starts with 4 seeds in each of the 12 pits.
2. Players sit on opposite sides of the board, each controlling the row closest to them.

- Run the following command:

```bash
npm run dev
```
## Basic Rules

## Running the Oware NFT Rewards Contract
1. **Objective**: The goal is to capture more seeds than your opponent.

1. **Navigate to the Dynamic_NFT Folder**
2. **Turn Structure**:
- On their turn, a player chooses one of their six pits containing seeds.
- The player then distributes these seeds, one by one, counterclockwise into the subsequent pits.

- `cd` into the `oware-nft` folder.
<img src="https://res.cloudinary.com/dydj8hnhz/image/upload/v1726751708/utv4wuff6ev4bodkmuzw.png" alt="Animation of seed distribution during a turn" />

2. **Install Dependencies**
3. **Capturing**:
- If the last seed dropped lands in an opponent's pit and brings the total seeds in that pit to 2 or 3, the player captures all seeds in that pit.
- The player also captures seeds from any preceding adjacent opponent's pits that also contain 2 or 3 seeds.

- Run the following command:
4. **Special Rules**:
- If a move would capture all of the opponent's seeds, the capture is forfeit.
- A player must make a move that gives their opponent seeds if possible.
```bash
npm install
```
5. **Game End**:
- The game ends when one player has captured more than 24 seeds, or when only one player can make a move.
3. **Set Up Environment Variables**
## Our Implementation
- Create a `.env` file with the following details:
Our version of Oware enhances the traditional gameplay with several unique features:
```
WALLET_KEY=<your_wallet_private_key>
1. **AI Opponents**: Players can challenge AI opponents of varying difficulty levels, trained using machine learning techniques on the Cartesi Virtual Machine.
```
4. **Deploy Locally**
2. **3D Visualization**: The game board and pieces are rendered in stunning 3D graphics using Babylon.js, providing an immersive gaming experience.
- Start a local node by running:
3. **Tournaments**: Players can participate in automated tournaments with smart contract-managed reward distribution.
```bash
npx hardhat node --port 8546
```
<img src="https://res.cloudinary.com/dydj8hnhz/image/upload/v1726751707/jrzlclitjt7askyufdvx.png" alt="Tournament lobby and bracket visualization" />
- Deploy the contract locally and run the scripts:
```bash
npx hardhat ignition deploy ./ignition/modules/OwareNFTReward.ts --network base-local
```
4. **Blockchain Integration**: Game results, player statistics, and achievements are securely recorded , ensuring transparency and enabling a rich ecosystem of rewards and progression.
- You should get an output similar to:
```
Deployed Addresses
## Strategy Tips
OwareNFTRewardModule#OwareNFTReward - 0x8464135c8F25Da09e49BC8782676a84730C318bC
```
1. Plan several moves ahead, considering both offensive and defensive strategies.
2. Try to keep your pits with low seed counts to limit your opponent's capturing opportunities.
3. Use the special rules to your advantage, sometimes forcing your opponent into suboptimal moves.
4. In the endgame, count carefully to ensure you're on track to capture the majority of seeds.
Copy and paste this URL into your browser.
5. **Deploy to a Live Network**
- Ensure the necessary `.env` requirements are provided for the specific network.
- Deploy the contract to a live network (e.g., base-sepolia) by running:
## Project Documentation
```bash
npx hardhat ignition deploy ./ignition/modules/OwareNFTReward.ts --network base-sepolia
```
<br>
<br>

0 comments on commit 3d529a2

Please sign in to comment.