DEV Community: Caleb Coyote

Building a full-stack Aavegotchi minigame - Part 3: Deploying your game

Caleb Coyote — Tue, 03 Aug 2021 13:20:35 +0000

In part 1 of the tutorial we created gameplay using Phaser 3, then in part 2 we created a server to verify the scores submitted to the leaderboard.

All we got to do now is deploy it! However, due to the nature of our app, it isn't as simple as uploading a HTML file to a web hosting service.

Instead, our backend server and front end application have different requirements to be hosted and accessed on the World Wide Web, and therefore need different solutions.

You can follow along from the previous lesson by cloning the end result of the previous lesson. Bare in mind you will need to set up a firebase project and assign the project keys in the repo to get it to work.

End result

By the end of this tutorial your game will be accessible to the Aavegotchi masses to play and compete!

We will be using Google Clouds Compute Engine to host and deploy our web-socket server onto a Virtual Machine. We will then use Firebase to host our React app and ensure that both the Server and Front end can communicate with each other.

Unless you have coded it to work otherwise, you wont be able to play the game without owning an Aavegotchi. You can buy one here or you could remove the development mode requisite within app/src/pages/Home to allow everyone to be able to select Use Default Gotchi without the requirement of owning an Aavegotchi.

Step 1) Setting up a virtual machine

First you will need to get set up on Google Cloud Platform, you can use my referral code to get $50 credit, which should be more than enough for this project.

If you have a Google account, go to Google Clouds Console and in the top right select CREATE PROJECT.

Then set the name of your project to whatever you like.

It will take a couple of seconds to create the project, but once it does you will be presented with your Projects dashboard.

In the side menu, navigate to Compute Engine -> VM Instances.

Enable the Compute Engine API.

Then select Create Instance.

Give it a name, select your region.

For machine configuration, select what works best for you depending on your app. Flappigotchis server is very simple so I will be selecting the smallest machine of the E2 series.

Then for the Firewall select allow HTTP and HTTPS traffic so that the browser is able to connect.

Then click create. It will take a minute or so to set up.

Step 2) Set up domain

Later on we will be setting up TLS (Transport Layer Security) for our server. For that we are going to need a domain name.

If you already have one to hand then great, otherwise you can get one from Google Domains.

Once you’ve got your domain name. Go back to your VM instances and copy the External IP to your clipboard.

Now go to the side menu, scroll down, and under Networking select Network services -> Cloud DNS.

Enable the API if you haven’t done so already, then create Zone.

Set your name and your DNS name to the domain. Ensure that DNSSEC is off.

After clicking create, a zone will be populated with NS and SOA records.

To point your registered domain name to the IP address of the hosting server, you must set an A record to your zone.

To do this:

Click Add Record Set
Select A from the Resource Record Type menu
In DNS name put server
Under IPv4 Address, paste the External IP address from your instance
Click create

It will take a few minutes to become active.

To update the name servers in Google domains:

Go to Google Domains
Click the domain you set up prior
Click DNS from the left side menu
At the top click Custom
Copy all 4 NS records from the Zone details page one at a time and paste them into the Name server inputs.
Click save
Click switch to these settings

To verify your changes were successful in your terminal run
dig +trace server.example.com where example.com is the domain you registered.

You should see at the end of the output the IP_Address of your virtual machine

server.example.com. 300 IN  A   34.105.146.34
;; Received 68 bytes from 216.239.36.109#53(ns-cloud-d3.googledomains.com) in 51 ms

Step 3) Installing dependencies on Virtual Machine

Now we need to prepare our Virtual machine. To do this we use the Cloud Shell to access the machines terminal.

To log into the virtual machine, in the Cloud shell terminal run (replacing zone and name with the zone and name of your VM instance):

gcloud compute ssh --zone [zone] [name]

The rest of the tutorial assumes that the distribution of of linux the virtual machine uses is Debian. To check what distribution you are running, in your cloud shell invoke lsb_release -a. If it is different, the concepts will remain the same, it's just some syntax may or may not be different.

At the moment our virtual machine is very vanilla. We are going to have to install a bunch of dependencies to get it to be able to clone and run our application.

These will be

Git - So we can clone our project
NGINX - To proxy the web requests to the node server
Certbot - To provision a TLS certificate
UFW - user-friendly front-end for managing iptables firewall rules.

To install them, in your cloud shell run:

sudo apt-get install git nginx certbot python-certbot-nginx ufw

Next we will install Node. For this we need to install the latest Node repository which you can find here, for me the latest stable release is Node.js v16.x so I will run:

curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -

Once its installed run:

sudo apt-get install -y nodejs

To install NodeJS and npm.

The final thing we will need to install is ts-node due to the fact our server is written in typescript, because we have downloaded npm. This command is as simple as running:

sudo npm install -g ts-node

Step 4) Config NGINX

First we got to config the NGINX so that it can proxy requests to the Node server. To do this, in the Cloud Shell terminal create a new file sudo nano /etc/nginx/sites-available/server.[domainname].com and inside it paste (replacing domainname with the domain you set up earlier):

server {
    listen 80;
    listen [::]:80;
    root /var/www/html;
    server_name server.[domainname].com; 
}

Press CONTROL + X to save the changes then Y to confirm, then ENTER to exit.

Enable the config file by running:

sudo ln -s /etc/nginx/sites-available/server.[domainname].com  /etc/nginx/sites-enabled/

Then because you edited the config, restart NGINX by running:

sudo systemctl restart nginx

You can then check NGINX status by running:

sudo systemctl status nginx

Step 5) Set up Firewall

As we have installed UFW (Uncomplicated firewall) this step is as simple as running

sudo ufw allow ssh
sudo ufw allow http
sudo ufw allow https

and then enabling it using

sudo ufw enable

Finally, we can check that the rules have configured properly by running:

sudo ufw status

You should hopefully get a response that looks like this:

Status: active

To                         Action      From
--                         ------      ----
22/tcp                     ALLOW       Anywhere
80/tcp                     ALLOW       Anywhere
443/tcp                    ALLOW       Anywhere
22/tcp (v6)                ALLOW       Anywhere (v6)
80/tcp (v6)                ALLOW       Anywhere (v6)
443/tcp (v6)               ALLOW       Anywhere (v6)

Step 6) Provisioning the TLS certificate

Now we have our NGINX and Firewall setup, we can run certbot to create our HTTPS certificates and config the rest of our NGINX.

In your cloud shell terminal run

sudo certbot --nginx

Enter your email, agree to the terms of service, choose whether you want to share information or not.
Enter domain of the app including the sub domain.
Last choice is whether we want to redirect HTTP traffic to HTTPS, which we do so select option 2.

Your private certificate and chain will now be saved onto your virtual machine.

Now all we need to do is add a reverse proxy into our
nginx/sites-available/server.[domainname].com file, so open it up again using:

sudo nano /etc/nginx/sites-available/server.[domainname].com

at the end of the top server object add location:

server {
    ...
    location / {
        # we're actually going to proxy all requests to
        # a Nodejs backend

        proxy_pass http://localhost:8080/;

        proxy_http_version 1.1;

        proxy_set_header Upgrade $http_upgrade;

        proxy_set_header Connection 'upgrade';

        proxy_set_header Host $host;

        proxy_cache_bypass $http_upgrade;

    }
}
server {
    ...
}

Step 7) Preparing app for deployment

We have everything we need, we can now prepare our app to deploy both front end and the backend.

First thing we want to do is let our app know which url to target when initiating socket.io.

For this we can make use of .env and processes to target the create variables depending on if the app is run in development or production.

If you are carrying on from the previous tutorial, in the app directory you should already have a .env.development file in the app directory. What you should do is create a new file in the app directory called .env.production and copy all the firebase variables over as they will be the same in both development and production.

In .env.development create a new variable called REACT_APP_SERVER and assign it a value of the url of your server when ran on local host. It should look like this.

// app/.env.development
...

REACT_APP_COLLECTION_NAME="test"
REACT_APP_SERVER_PORT="http://localhost:8080"

Now in .env.production we add in two different variables for the COLLECTION_NAME and the SERVER_PORT.

The collection name should be the name of the Database we want our app to target on production mode, therefore it should be different to the one used in development.

The SERVER_PORT should be the url of our servers domain. This by default will connect to port 443 which points to our NGINX setup, which in turns encrypts the request and connects to port 8080 on our virtual machine where our web-socket server will be listening.

// app/.env.production

...

REACT_APP_COLLECTION_NAME="highscores"
REACT_APP_SERVER_PORT="https://server.[domainname].com"

In app/src/game/main.tsx you should see our .env variable is already being used to initiate the socket, so no more needs to be done here with the socket.

However our ServerProvider in app/src/server-store is still only fetching data from the "test" collection, so we need to update it to use the .env variables like so:

// app/src/server-store

...

 export const ServerProvider = ({
  children,
 }: {
  children: React.ReactNode;
 }) => {
  ...

  const snapshotListener = (
    ...
  ) => {
    return database
      .collection(process.env.REACT_APP_COLLECTION_NAME || "test")
      ...
  };

  useEffect(() => {
    const getHighscores = async (_firebase: fb.app.App) => {
      ...
      const highscoreRef = db
        .collection(process.env.REACT_APP_COLLECTION_NAME || "test")
        ...
    }
  }, [firebase]);

  ...
 };

Preparing server

For the server we are also going to want to create some .env variables for the names of the Collections we set earlier. So create another .env.development and .env.production and inside put the variables for the collection name:

// server/.env.development

DB_COLLECTION="test"

// server/.env.production

DB_COLLECTION="highscores"

REACT_APP is not necessary as the server isn't a React app.

Then in server.ts replace the collection name with process.env.DB_COLLECTION

// server/server.ts
...

const submitScore = async ({tokenId, score, name}: ScoreSubmission) => {
 const collection = db.collection(process.env.DB_COLLECTION);
 const ref = collection.doc(tokenId);
 ...

Now run the app locally and ensure everything is still working correctly.

Step 8) Deploying the front end

To host the front end up your app feel free to use any hosting service. Im going to be using firebase hosting purely due to the fact my database is on firebase and my backend is hosted on Google Cloud.

To get started visit the Firebase CLI documentation to learn how to install the Firebase CLI.

Once you have it installed, initiate hosting for the app by going into the app directory in your terminal and running:

firebase init hosting

Select Use an existing project (as you should already have a project set up for your leaderboard in the previous tutorial), and select your project.

For your public directory, type in "build" as thats the folder react constructs after building the app.

For configure as single-page app select Yes as it is a React app and therefore is a single-page app.

And finally for set up automatic build, choose what ever you fancy. Il select no, but if you want to do an automatic redeploy every time you push your code to your main directory in GitHub then select yes.

Your app will now configure itself automatically.

Now to deploy the site, first you have to build your application by running:

npm run build

in your app directory. This will compile your app into an optimised production build in the build folder. Then after it's compiled run:

firebase deploy --only hosting

Once it's deployed the terminal will return the URL to the deployed web app.

If you go to your deployed site, you should have an empty leaderboard, abd when you try running the game the loading bar should get stuck on connecting to server. Thats because we haven't deployed our server app on the virtual machine yet.

Step 9) Deploying the back end

We are going to be using git to clone our app into the virtual machine. Therefore we need to ensure our code is up to date on GitHub.

If you were following from the start you should have your own GitHub rep setup for your app. So just run:

git add .
git commit -m "Ready for deployment"
git push

If you haven't got a GitHub repository setup yet, then do so by following these instructions to import project to Github here.

Once that is done, go back to the cloud shell of your app, and log back into your virtual machine.

Press up ↑ on your keyboard to get previously used commands.

Now get the url to your GitHub project:

And clone your Github project into your virtual machine by running:

git clone https://github.com/[username]/[example].git`

You may notice that we have cloned both the app and the server into the virtual machine with this method which is not ideal. You can just clone the server directory, but in terms of ease of managing different versions of your app, this way saves a lot of headache.

If you find your project ends up taking up too much space in your machine, then opt to remove the app from the virtual machine. Or create a separate repo for your server and app directories.

You can now in your virtual machine go to your server directory and install its dependencies:

cd flappigotchi/server
npm install

Now before we can run the app there are a few things we need to add to the project. Those with keen eyes may notice that both our service-account.json and our .env variables are in the .gitignore file. Therefore when we pushed and pulled our code from github, these files wouldn't of been included. Therefore we need to rewrite them within the cloud shell.

Because we only run our server in production mode with the virtual machine, we will just add the .env.production file. To do this, run sudo nano .env.production within the server directory to create and open up a .env file. Then inside copy and paste your variable from before:

DB_COLLECTION="highscores"

Now do the same for the service-account JSON file. Run sudo nano service-account.json and paste in your service account key.

If you are to run sudo npm run start:prod now, then your server should hopefully output a message saying its listening on port:8080!

Hopefully now, when you open your deployed app, it should connect to your server without a hitch and you will be able to play and submit a score to the leaderboard!

10) Set domain name for front end

Your game is now live and ready to be tested by the Aavegotchi community! Now we just want to set up our domain name from earlier to point to the front end of our application.

To do this, go to your firebase console, and in the side menu select Hosting:

Click Add custom domain
Type in the domain name that you used for the server but without the added server subdomain.
Go back to the Cloud DNS from before and add in both of the A records

A records in Firebase

A records inputted into Google Cloud DNS

The status should now go to pending as it verifies ownership of the domain. This process can take anywhere from a couple of minutes to 24 hours.

Once its verified you should now be able to play your game at your given domain!

Conclusion

That's it! Your game is live and ready to be played!

In this lesson you learnt how to securely set up a web-socket server on Google Cloud, as well as deploy your front end application.

This 3 part series has been a high level overview of the concepts that go into building a game. There is still more that can be done, so if there is any concepts that you want to see tackled in a future tutorial, comment them down below.

If you have just deployed your own game. Message me on Twitter or Discord to see about running an Aavegotchi EXP event!

Part 4 of the series will likely be how to add a Pay2Play/Play2Earn system into your game. So make sure to follow me @ccoyotedev or @gotchidevs on Twitter for updates on future tutorials.

If you have any questions about Aavegotchi or want to work with others to build Aavegotchi minigames, then join the Aavegotchi discord community where you can chat and collaborate with other Aavegotchi Aarchitects!

If you own an Aavegotchi, you can play the end result of this tutorial series at flappigotchi.com.

Building a full-stack Aavegotchi minigame - Part 2: Server + Leaderboard

Caleb Coyote — Tue, 06 Jul 2021 20:05:19 +0000

In Part 1 of the tutorial series, we created an Aavegotchi flappigotchi clone using Phaser3. Now let’s say we want to make our game competitive so that each player can compete for the top spot of the leaderboard to earn Aavegotchi rewards.

If we was to do the score submission on the client side, then a malicious player could open up the dev tools, intercept the network request and submit whatever score they like. This is a big no no.

To prevent this we need some server side logic that can verify whether a score is legitimate or not, and if so, store the score in the database. For that to work, the game needs to have an idea of the gameplay session that took place. That's where WebSockets come in!

End result

By the end of Part 2 you will be equipped with the knowledge you need to set up a server that can verify and submit a user's score to a database.

We will be building off of the Flappigotchi game from part 1, and will write our server-side logic in Express + NodeJs, and use Socket.io to handle our WebSocket connection.

We will also be learning how to use Google's Firestore to store and view leaderboard data. However feel free to use a database preference of your choice, the concept remains the same.

Step 1) Ensure game is working

Optional: Starting fresh

If you are starting here, make sure to clone the Part 1 repo to get up to speed.

If on Windows, ensure your package.json scripts are correct:

// app/package.json

  "scripts": {
    ...
-   "start:offchain": "REACT_APP_OFFCHAIN=true react-scripts start",
+   "start:offchain": "set REACT_APP_OFFCHAIN=true && react-scripts start",
    ...
  },

// server/package.json

  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
-   "start:prod": "NODE_ENV=production nodemon server.ts",
+   "start:prod": "set NODE_ENV=production && nodemon server.ts",
-   "start": "NODE_ENV=development nodemon server.ts"
+   "start": "set NODE_ENV=development && nodemon server.ts"
  },

Open up a terminal, and within the server directory run npm run start, your server should be successfully running in port:8080.

In another terminal, open the app directory run npm run start (or npm run start:offchain if you want to run the app without a Web3 connection or you don't own any Aavegotchi's), to run your app on http://localhost:3000/.

If you have only just downloaded the repo, ensure you have installed the dependencies by running npm install in both the server and app directories.

Server connection events

When you start the game, in the terminal in which you are running the server, you should receive a message upon connecting and disconnecting from the game.

In the template, all the Phaser code is wrapped by a React component called Main in app/src/game/main.tsx. When this component renders, a useEffect React hook handles the connection to the WebSocket using the socket.io-client, and then when the component unmounts it fires an event called “handleDisconnect”.

// app/src/game/main.tsx

useEffect(() => {
  if (usersAavegotchis && selectedAavegotchiId) {
    // Socket is called here so we can take advantage of the useEffect hook to disconnect upon leaving the game screen
    const socket = io(process.env.REACT_APP_SERVER_PORT || 'http://localhost:8080');

    ...

    return () => {
      socket.emit("handleDisconnect");
    };
  }
)

If you open server/server.ts you can see the order of logic on the server's side.

// server/server.ts

io.on('connection', function (socket: Socket) {
    const userId = socket.id;

    console.log('A user connected: ' + userId);
    connectedGotchis[userId] = {id: userId};

    socket.on('handleDisconnect', () => {
      socket.disconnect();
    })

    socket.on('setGotchiData', (gotchi) => {
      connectedGotchis[userId].gotchi = gotchi;
    })

    socket.on('disconnect', function () {
      console.log('A user disconnected: ' + userId);
      delete connectedGotchis[userId];
    });
});

When the user connects, it assigns the randomly generated id to a userId constant, logs it to the console, and then stores it in as a key-value pair in an object called connectedGotchis. Every concurrent connection will be stored within the same connectedGotchis instance.

To prove this, add a console.log(connectedGotchis) after the key-value pair has been assigned in the socket connection:

io.on('connection', function (socket: Socket) {
    const userId = socket.id;

    console.log('A user connected: ' + userId);

    connectedGotchis[userId] = {id: userId};
    console.log(connectedGotchis);


    ...
});

Then open the game in another tab and try and start both games at the same time. You should see the 2 connections.

This also touches on how you can add a simple form of multiplayer to your games. Every connected user will have access to the same server instance and therefore will be able to send each other events through the server.

When the app fires the ”handleDisconnect” event, the server listens for it and fires socket.disconnect() which in turn fires the "disconnect" event. This uses the userId to delete the correct key-value pair in the connectedGotchis object.

Step 2) Handling in game events

To handle in game events, we first need a way to access to the Socket we initialised within Main. Luckily in Main we have passed a config object into the IonPhaser component.

In this config object, we used the callbacks property to set some items in the games registry at the start of the games bootsequence.

// app/src/game/main.tsx

...

const Main = () => {
  ...

  const startGame = async (socket: Socket, selectedGotchi: AavegotchiObject) => {
    ...

    setConfig({
      type: Phaser.AUTO,
      physics: {
        default: "arcade",
        arcade: {
          gravity: { y: 0 },
          debug: process.env.NODE_ENV === "development",
        },
      },
      scale: {
        mode: Phaser.Scale.NONE,
        width,
        height,
      },
      scene: Scenes,
      fps: {
        target: 60,
      },
      callbacks: {
        preBoot: (game) => {
          // Makes sure the game doesnt create another game on rerender
          setInitialised(false);
          game.registry.merge({
            selectedGotchi,
            socket
          });
        },
      },
    });
  }

  ...

  return <IonPhaser initialize={initialised} game={config} id="phaser-app" />;
};

export default Main;

The registry is essentially the apps global state which you can use to store a variety of global variables between Scenes.

In app/game/scenes/boot-scene.ts you can see how we then access this socket instance to check if we are connected to the server, and then fire own custom event within the handleConnection function:

// app/game/scenes/boot-scene

...

export class BootScene extends Phaser.Scene {
  ...

  public preload = (): void => {
    ...

    // Checks connection to the server
    this.socket = this.game.registry.values.socket;
    !this.socket?.connected
      ? this.socket?.on("connect", () => {
          this.handleConnection();
        })
      : this.handleConnection();

    ...
  };

  /**
   * Submits gotchi data to the server and attempts to start game
   */
  private handleConnection = () => {
    const gotchi = this.game.registry.values.selectedGotchi as AavegotchiObject;
    this.connected = true;
    this.socket?.emit("setGotchiData", {
      name: gotchi.name,
      tokenId: gotchi.id,
    });

    this.startGame();
  };

  ...
}

This event sends information to our server about the selected Aavegotchi. In server.ts you can see that we use this data to attach a gotchi property to our key-value pairing.

// server/server.ts

socket.on('setGotchiData', (gotchi: Gotchi) => {
  connectedGotchis[userId].gotchi = gotchi;
})

This data will be used later to assign the correct Aavegotchi data to the leaderboard.

Now that we have seen an example of how to send events to the server, let's add our own custom events.

Session time validation

As our game is simple, for our server validation, we are going to create one simple rule to check if a users score is legitimate or not. We will use the duration of the playtime to determine whether or not a score is possible.

For this, we need the game to send 2 events, one for when the game starts, and one for when the game ends.

// app/game-scene.ts
...
import { Player, Pipe, ScoreZone } from 'game/objects';
import { Socket } from "socket.io-client";

...
export class GameScene extends Phaser.Scene {
  private socket?: Socket;
  private player?: Player;
  ...
  private scoreText?: Phaser.GameObjects.Text;

  private isGameOver = false;

  ...

  public create(): void {
    this.socket = this.game.registry.values.socket;
    this.socket?.emit('gameStarted');

    // Add layout
    ...
  }

  ...

  public update(): void {
    if (this.player && !this.player?.getDead()) {
      ...
    } else { 
      if (!this.isGameOver) {
        this.isGameOver = true;
        this.socket?.emit('gameOver', {score: this.score});
      }

      ...
    }

    ...
  }
}

For our "gameStarted" event, we want to fire this upon the scenes creation.

We want to send our "gameOver" event once upon the players death, for this we added a isGameOver state so we can assure the event doesn't trigger multiple times.

We have also sent some data along with the "gameOver" event that corresponds to the users client side score.

Step 3) Server side logic

Now that our app is sending the events, we need to listen for them on the server.

// server/server.ts

...

io.on('connection', function (socket: Socket) {
  ...

  socket.on('gameStarted', () => {
    console.log('Game started: ', userId);
  })

  socket.on('gameOver', async ({ score }: { score: number }) => {
    console.log('Game over: ', userId);
    console.log('Score: ', score);
  }) 

  ...
});

...

If you was to play the game now, you should see in your server's terminal the console.log for the game starting and ending.

On gameStart we want to take a snapshot of the time in which the server receives the gameStarted event:

// server/server.ts

io.on('connection', function (socket: Socket) {
  const userId = socket.id;
  let timeStarted: Date;

  ...

  socket.on('gameStarted', () => {
    console.log('Game started: ', userId);
    timeStarted = new Date();
  })

  ...
});

Then on game over, we can get the difference between the time now and the timeStarted. Using this we should be able to calculate an approximation of what the users score should be.

When building the gameplay, we made it so addPipeRow() is called every 2 seconds. Therefore, the time between going through each pipe should also be 2 seconds.

At the start of the game, there is also a little bit of extra distance before reaching the first pipe row. You can get the time to travel this distance in a hacky way by console logging the time difference going through the first pipe row and starting, and then subtracting the 2 seconds. I got this time to be roughly 0.2 seconds.

Therefore, if we was to calculate the score, using only the time value, the equation will look like:

We also know that the score should be an integer as the score increases at intervals of 1. So if the server calculates a score of 2.8 for example, we should round the number down to 2 as that means the Player died somewhere between pipe 2 and 3.

What this looks like in code is the following:

// server/server.ts

socket.on('gameOver', async ({ score }:{ score: number }) => {
   console.log('Game over: ', userId);
   console.log('Score: ', score);

   const now = new Date();
   const dt = Math.round((now.getTime() - timeStarted.getTime())) / 1000;
   const timeBetweenPipes = 2;
   const startDelay = 0.2;
   const serverScore = dt / timeBetweenPipes - startDelay;

   if (score === Math.floor(serverScore)) {
     console.log("Submit score: ", score);
   } else {
     console.log("Cheater: ", score, serverScore);
   }
})

Now if you play the game a couple of times, and look at the server terminal, you can find out whether you are cheating or not.

Error margins

What you should find is some of the time the server is not accurate and is calling you out for being a cheater, this becomes more apparent the longer your run.

This is because the numbers we used to calculate the score are not 100% accurate. They were approximations. In reality there are numerous ways in which the server may be a bit out of sync, the client may have some minor spikes in their frame rate, or the latency between the client and server may be a bit slow.

Because of this we need to take into account a margin of error into our servers calculations.

This tutorial wont be going into how to calculate error margins (if you want to look into that there are plenty of maths resources and videos on the web).

Just take my word, that for the time between each pipe, there is approximately an error range of about 0.03s either direction.

This means, that the time between each pipe, is somewhere in the range of 1.97s and 2.03 seconds. Therefore, the higher the score, the higher the error of margin.

Thus, what we need to calculate is the lower and upper bound for our score, and see if the score sent from the client fits within their range:

// server/server.ts

socket.on('gameOver', async ({ score }:{ score: number }) => {
  console.log('Game over: ', userId);
  console.log('Score: ', score);

  const now = new Date();
  const dt = Math.round((now.getTime() - timeStarted.getTime())) / 1000;
  const timeBetweenPipes = 2;
  const startDelay = 0.2;
  const serverScore = dt / timeBetweenPipes - startDelay;
  const errorRange = 0.03;

  const lowerBound = serverScore * (1 - errorRange);
  const upperBound = serverScore * (1 + errorRange); 

   if (score >= Math.floor(lowerBound) && score <= upperBound) {
      console.log("Submit score: ", score, lowerBound, upperBound);
   } else {
     console.log("Cheater: ", score, serverScore);
   }
})

If you notice that a legitimate games score seems to be not within the server scores bounds some of the time, then you can always try increasing the errorRange slightly.

Fantastic! Now we have our server verifying whether a score is legitimate or not, we can send it to the server.

Of course, using this server side logic doesn't prevent our game from being completely hack proof. If a nefarious player figures out the server side logic, they could send a network request for ‘gameStart’ and then wait a set amount of time before sending the ‘gameOver’ event with the correct score.

They could also on the client side, edit the code so that collisions with the pipes don't end the game, and just easy-mode their way to the top.

It's up to you to think of the various ways in which the user could exploit the game, and write some more server events to prevent them by mirroring a real game session as much as possible. Flappigotchi being a simple game, there is only so much you can do, however one potential task you could do for homework is write an event that triggers every time the player goes through 5 pipe rows. Then on the server end, if you are not receiving this event approximately every 10 seconds then you know the user must be doing something dastardly.

Step 4) Setting up Firebase (Optional)

In this part of the tutorial I will guide you through the steps of setting up a Firestore database. If you want to use a different database, feel free to skip ahead. For more detailed explanations of the setup, you can follow the official firebase steps found here.

Assuming you have already got a Google account signed up to Firebase, go to your firebase console and create a new project.

It will guide you through 2 or 3 steps:

1) Name your project: This can be whatever you want to use to identify the project
2) Enable Google Analytics: Not used in the scope of this tutorial, but may be useful if you want to take this project further.

Once that is done your project will be created and you will be presented with the project dashboard.

To have your server be able to connect with your Firebase, you need to generate a service account key.

To do this, in your console, click on the cog next to Project Overview and select Project Settings.

Then under the Service Accounts tab, click on the Generate New Private Key button.

It’s very important that you have this json file only be accessible to you and your team. However, it also needs to be accessible by your code.

For this tutorial, call the newly downloaded file “service-account.json” and save it to the root of the server directory.

To ensure that this key doesn't upload to Github, in the ‘.gitignore’ file add in the name of the service-account.json file:

// .gitignore

service-account.json

Next, we need to install firebase-admin within your server directory, so open up a new terminal, and in your server directory run:

npm install firebase-admin

Once installed, you should have everything you need to connect your server to firebase. Simply import in both firebase-admin and your service-account key and initialise the app:

// server/server.ts

const serviceAccount = require('./service-account.json');
const admin = require('firebase-admin');
admin.initializeApp({
 credential: admin.credential.cert(serviceAccount)
});

To set up a Firestore database, go back to your firebase console. Click on Firestore Database in the side menu, and then click on the Create Database button.

Opt for Start in production mode and select the location you want your database to live.

You should now have access to your firestore like so:

// server/server.ts

const db = admin.firestore();

Step 5) Sending data to database

Now that we have access to our database, lets create a function in server.ts called SubmitScore():

// server/server.ts

const db = admin.firestore();

interface ScoreSubmission {
  tokenId: string,
  score: number,
  name: string
}

const submitScore = async ({tokenId, score, name}: ScoreSubmission) => {
 const collection = db.collection('test');
 const ref = collection.doc(tokenId);
 const doc = await ref.get().catch(err => {return {status: 400, error: err}});

 if ('error' in doc) return doc;

 if (!doc.exists || doc.data().score < score) {
   try {
     await ref.set({
       tokenId,
       name,
       score
     });
     return {
       status: 200,
       error: undefined
     }
   } catch (err) {
     return {
       status: 400,
       error: err
     };
   }
 } else {
   return {
     status: 400,
     error: "Score not larger than original"
   }
 }
}

The beauty of Firestore is it is very flexible and simple to use. The collection is essentially the database which we want to send data to. It's important to use a different collection for your highscores in development mode to separate your scores whilst testing from the live leaderboard. Therefore we will call our collection “test”. We then label our data by the Aavegotchi's tokenId.

Before we submit the data to the database, we want to add a simple logic gate. Essentially we don't want to submit data to the Highscore database if the score being submitted isn’t higher than the score that currently exists for the given Aavegotchi. Therefore we have 2 checks

1) If data doesn't exist, push the given score to the database
2) If data exists, but the score is less than the new score, override the data with a new score.

Firestore has a useful .set() method which allows you to either post the data if it doesn't exist, or override it if it does.

Now all we have to do is call this method within the ‘gameOver’ event:

// server/server.ts

socket.on('gameOver', async ({ score }:{ score: number }) => {
    ...
  if (score >= Math.floor(lowerBound) && score <= upperBound) {
    const highscoreData = {
      score,
      name: connectedGotchis[userId].gotchi.name,
      tokenId: connectedGotchis[userId].gotchi.tokenId,
    }
    console.log("Submit score: ", highscoreData);

    try {
      const res = await submitScore(highscoreData);
      if (res.status !== 200) throw res.error;
      console.log("Successfully updated database");
    } catch (err) {
      console.log(err);
    }
  } else {
    console.log("Cheater: ", score, lowerBound, upperBound);
  }
})

Now when you play the game, whatever score you get should be posted to the database.

Step 6) Setting up Firebase App side

Before we can retrieve the data, we need to first get some more Firebase API keys so our app can view data from Firebase. To get this, go to your on the Project Overview page and click on the web button.

Then register your app with your name of choice.

(There is no need to setup Firebase hosting at this point)

You will be presented with a chunk of code. The only bit that is relevant to us are the keys within the firebaseConfig variable:

Create a file in the /app directory called .env.development. Here paste in your keys and convert it to the following:

// app/.env.development

REACT_APP_FIREBASE_APIKEY=”API_KEY_HERE"
REACT_APP_FIREBASE_AUTHDOMAIN="AUTHDOMAIN_HERE"
REACT_APP_FIREBASE_PROJECTID="PROJECT_ID_HERE"
REACT_APP_FIREBASE_STORAGEBUCKET="STORAGE_BUCKET_HERE"
REACT_APP_FIREBASE_MESSAGINGSENDERID="STORAGE_BUCKET_HERE"
REACT_APP_FIREBASE_APPID="APP_ID_HERE

The REACT_APP is important to allow React to access the the variables.

Now inside the app directory, run:

npm install firebase

Step 7) Displaying Highscore data

We now need to be able to receive and display the Highscore data on the app. In the template, there is already a Context Provider set up to handle database logic within app/src/server-store/index.tsx. At the moment, it only stores data to the users localStorage, so the page can be rewritten to the following:

// app/src/server-store/index.tsx

import React, {
  createContext, useContext, useEffect, useState,
 } from 'react';
 import { HighScore } from 'types';
 import fb from 'firebase';

 const firebaseConfig = {
  apiKey: process.env.REACT_APP_FIREBASE_APIKEY,
  authDomain: process.env.REACT_APP_FIREBASE_AUTHDOMAIN,
  databaseURL: process.env.REACT_APP_FIREBASE_DATABASEURL,
  projectId: process.env.REACT_APP_FIREBASE_PROJECTID,
  storageBucket: process.env.REACT_APP_FIREBASE_STORAGEBUCKET,
  messagingSenderId: process.env.REACT_APP_FIREBASE_MESSAGINGSENDERID,
  appId: process.env.REACT_APP_FIREBASE_APPID,
  measurementId: process.env.REACT_APP_FIREBASE_MEASUREMENTID,
 };

 interface IServerContext {
  highscores?: Array<HighScore>;
 }

 export const ServerContext = createContext<IServerContext>({});

 export const ServerProvider = ({
  children,
 }: {
  children: React.ReactNode;
 }) => {
  const [highscores, setHighscores] = useState<Array<HighScore>>();
  const [firebase, setFirebase] = useState<fb.app.App>();

  const sortByScore = (a: HighScore, b: HighScore) => b.score - a.score;

  const converter = {
    toFirestore: (data: HighScore) => data,
    fromFirestore: (snap: fb.firestore.QueryDocumentSnapshot) =>
      snap.data() as HighScore,
  };

  useEffect(() => {
    const getHighscores = async (_firebase: fb.app.App) => {
      const db = _firebase.firestore();
      const highscoreRef = db
        .collection("test")
        .withConverter(converter);
      const snapshot = await highscoreRef.get();

      const highscoreResults: Array<HighScore> = [];
      snapshot.forEach((doc) => highscoreResults.push(doc.data()));
      setHighscores(highscoreResults.sort(sortByScore));
    };

    if (!firebase) {
      const firebaseInit = fb.initializeApp(firebaseConfig);
      setFirebase(firebaseInit);
      getHighscores(firebaseInit);
    }
  }, [firebase]);

  return (
    <ServerContext.Provider
      value={{
        highscores,
      }}
    >
      {children}
    </ServerContext.Provider>
  );
 };

 export const useServer = () => useContext(ServerContext);

This will initiate firebase on initial render of the app, and then fetch all the highscore's from the collection set in your .env file.

The convertor is used so we can assign types to the data received from Firebase.

The last thing we need to do before we can view the data from Firebase is give our app viewing permissions.

To do this, go to your Firebase console, navigate to the Firestore Database, then click on the rules tab:

As we don’t care if a 3rd party wants to view our Highscore data, we set our rules as:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} {
      allow read: if true;
      allow write: if false;
    }
  }
}

This will allow anyone to read the data, but writing permissions is not allowed. Our server has access to write as it has the service-account key that is only available to the projects admin.

The template has already hooked up the Context Provider to the apps UI, so now by running the app you should see your scores on the leaderboard.

You may need to restart the app in the terminal so the new .env variables can take effect.

If you was to beat your score now, you may notice the scores in the leaderboard do not update. If you refresh, you should see the database is working as intended. The problem is, we are only updating the apps state on initial load of the app. Therefore, we need to set up a listener, so when one of the users Aavegotchi's scores update, the apps state updates with it.

Thankfully Firebase has an eventListener just for this situation called onSnapshot. For this to work, we need to first have access to the users Aavegotchi's, therefore we need to write a new useEffect that initiates a snapshot listener when the users Aavegotchi's are updated. We need to to also ensure that this happens after the firebase has initiated.

// app/src/server-store/index.tsx

import React, {
  createContext,
  useContext,
  useEffect,
  useState,
  useRef,
} from "react";
import { HighScore, AavegotchiObject } from "types";
import { useWeb3 } from "web3/context";
import fb from "firebase";

...

export const ServerProvider = ({ children }: { children: React.ReactNode }) => {
  const {
    state: { usersAavegotchis },
  } = useWeb3();
  const [highscores, setHighscores] = useState<Array<HighScore>>();
  const [firebase, setFirebase] = useState<fb.app.App>();
  const [initiated, setInitiated] = useState(false);

  const sortByScore = (a: HighScore, b: HighScore) => b.score - a.score;

  const myHighscoresRef = useRef(highscores);

  const setMyHighscores = (data: Array<HighScore>) => {
    myHighscoresRef.current = data;
    setHighscores(data);
  };

  const converter = {
    toFirestore: (data: HighScore) => data,
    fromFirestore: (snap: fb.firestore.QueryDocumentSnapshot) =>
      snap.data() as HighScore,
  };

  const snapshotListener = (
    database: fb.firestore.Firestore,
    gotchis: Array<AavegotchiObject>
  ) => {
    return database
      .collection("test")
      .withConverter(converter)
      .where(
        "tokenId",
        "in",
        gotchis.map((gotchi) => gotchi.id)
      )
      .onSnapshot((snapshot) => {
        snapshot.docChanges().forEach((change) => {
          const changedItem = change.doc.data();
          const newHighscores = myHighscoresRef.current
            ? [...myHighscoresRef.current]
            : [];
          const itemIndex = newHighscores.findIndex(
            (item) => item.tokenId === changedItem.tokenId
          );
          if (itemIndex >= 0) {
            newHighscores[itemIndex] = changedItem;
            setMyHighscores(newHighscores.sort(sortByScore));
          } else {
            setMyHighscores([...newHighscores, changedItem].sort(sortByScore));
          }
        });
      });
  };

  useEffect(() => {
    if (usersAavegotchis && usersAavegotchis.length > 0 && firebase && initiated) {
      const db = firebase.firestore();
      const gotchiSetArray = [];
      for (let i = 0; i < usersAavegotchis.length; i += 10) {
        gotchiSetArray.push(usersAavegotchis.slice(i, i + 10));
      }
      const listenerArray = gotchiSetArray.map((gotchiArray) =>
        snapshotListener(db, gotchiArray)
      );

      return () => {
        listenerArray.forEach((listener) => listener());
      };
    }
  }, [usersAavegotchis, firebase]);

  useEffect(() => {
    const getHighscores = async (_firebase: fb.app.App) => {
      ...

      setMyHighscores(highscoreResults.sort(sortByScore));
      setInitiated(true);
    };

    ...
  }, [firebase]);

  ...
};

export const useServer = () => useContext(ServerContext);

There are 2 strange things worth noting about this implementation that may seem confusing at first read.

One is the setting up of multiple listeners in sets of 10.

const gotchiSetArray = [];
for (let i = 0; i < usersAavegotchis.length; i += 10) {
  gotchiSetArray.push(usersAaveGotchis.slice(i, i + 10));
}
const listenerArray = gotchiSetArray.map((gotchiArray) =>
  snapshotListener(db, gotchiArray)
);

This is because the onSnapshot can only listen out for a maximum of 10 documents, and there are a bunch of Aavegotchi maxis with a lot more than 10 Aavegotchi's that we need to account for. Therefore we split their Aavegotchi's into groups of 10 so we can set up a listener for all of them.

The second thing is instead of changing the state directly, we have created a new function called setMyHighscores that assigns the value of Mutable Ref Object.

const myHighscoresRef = useRef(highscores);

const setMyHighscores = (data: Array<HighScore>) => {
  myHighscoresRef.current = data;
  setHighscores(data);
};

In the snapshot we have then used the refs value to retrieve the highscore data instead of the state.

.onSnapshot((snapshot) => {
  snapshot.docChanges().forEach((change) => {
    const changedItem = change.doc.data();
    const newHighscores = myHighscoresRef.current
      ? [...myHighscoresRef.current]
      : [];
    const itemIndex = newHighscores.findIndex(
      (item) => item.tokenId === changedItem.tokenId
    );
    if (itemIndex >= 0) {
      newHighscores[itemIndex] = changedItem;
      setMyHighscores(newHighscores.sort(sortByScore));
    } else {
      setMyHighscores([...newHighscores, changedItem].sort(sortByScore));
    }
  });
});

This is necessary as the snapshot listener is assigned on the initial load of the app, therefore the onSnapshot callback uses the highscores state value at initiation as its value, even if it changes later. This leads to confusing instances, where getting a highscore on one of your Aavegotchis, then switching to another and getting a highscore, the second Aavegotchis score will override the first. This only affects the UI of course, but it can lead to panic for your users.

Therefore by using Reacts useRef, we can create a constant that is the same on every render, but contains a property called current that is mutable.

Therefore, when the callback triggers, the reference for the highscores data remains the same, so the code can then access it and retrieve the current value.

If you didn't understand all of that don't worry. I don't think many people do, nor is it critical information for the development of minigames. Just thought it would be interesting to tell you none the less.

Conclusion

Congratz, you have concluded Part 2 of the tutorial! If you play the game now, you should have a fully functioning app that is worthy of the Aavegotchi Aarcade.

In this lesson you have learnt how to implement basic server side validation, as well as how to read and write data on Firebase. All that is left to do is deploy both sides of your applications to the world wide web so people can play your game with their own Aavegotchis!

Building a full-stack Aavegotchi minigame - Part 3: Deploying your game

Caleb Coyote ・ Aug 3 '21

#websocket #gamedev #web3 #node

The end result for the code can be found here. However, please bear in mind the Firebase infrastructure is necessary to have a working leaderboard.

If you have any questions about Aavegotchi or want to work with others to build Aavegotchi minigames, then join the Aavegotchi discord community where you can chat and collaborate with other Aavegotchi Aarchitects!

Make sure to follow me @ccoyotedev or @gotchidevs on Twitter for updates on future tutorials.

If you own an Aavegotchi, you can play the end result of this tutorial series at flappigotchi.com.

Building a full-stack Aavegotchi minigame - Part 1: Set up + Phaser 3

Caleb Coyote — Tue, 29 Jun 2021 16:42:24 +0000

In this 3 part tutorial series, I will be taking you through each step required to build and deploy an Aavegotchi minigame. There is a lot to cover, so each section will have to be very high-level.

Aavegotchi's are de-fi staked NFT collectibles that exist fully within the Polygon network. The beauty of this is it allows anyone to build games or apps that utilise these Aavegotchi's as playable avatars with their own unique traits and identities.

We will be using the Aavegotchi Minigame Template as a starting block for this series, as it already sets up the structure of the repo, as well as handles the Web3 logic required to retrieve the players Aavegotchi's from the polygon network.

If you don't own an Aavegotchi, or don't have a wallet to connect to Web3 that also isn't a problem, as in dev mode the template gives you an option to run the app off-chain, therefore allowing you to use a default (but not real) Aavegotchi. (However, its always more fun when you get to build alongside your digital frens).

End result

As all great game developers have started before you, the end result of this multipart series will be a full stack Flappy Bird clone (Flappigotchi).

Part 1 will take you through the basics of setting up the Aavegotchi Minigame template and using Phaser 3 to create riveting gameplay.

You can find the code for the end result of Part 1 here

Step 1) Prerequisites

A basic understanding of React & Phaser3 is recommended but not compulsory.

The bulk of the app is written in Typescript, so I would suggest first acquiring a foundational understanding of Typescript before starting.

The stack

The minigame template consists of both a frontend and a backend directory.

The frontend directory consists of both ReactJs + Phaser3 and is where you will most likely spend the bulk of your time building your game.

React Js allows for a more intuitive main menu design + hooks for both web3 and database hookups.

Phaser3 is a 2D game framework for building games in JS on the HTML5 canvas. It has a very active community and is also the framework in which the Aavegotchi Reaalm is being built.

The backend directory is written in nodejs and utilises socket.io to take advantage of websockets. This is necessary for building multiplayer games. If you are building a single player game, a server is still necessary if you want to introduce some sort of Leaderboard + Reward system into your game. This is due to the fact users of your game can easily exploit the client side code to tamper and send false scores to your database. So if you handle the score submissions server side, with some logic to flush out illegitimate scores, then your games leaderboard will be safer.

Step 2) Getting started

To get started using the template, first install GitHub client, so you can simply run the following command to create your own GitHub project using the template:

gh repo create flappigotchi --template="https://github.com/aavegotchi/aavegotchi-minigame-template.git"
cd flappigotchi
git pull origin main

If you are authenticated, you will be presented with various options for setting up your repo. Just press Enter to go through each step. You will now have your own flappigotchi repo setup on Github.

Now in your code editor of choice (I personally use VSCode) open up the new Flappigotchi directory where you should see the following folder structure.

For this stage of the tutorial we will be only working in the app directory. So go into app and install the dependencies:

cd flappigotchi/app
npm install

Once everything is installed, you can start the app either by running npm run start or npm run start:offchain depending if you want to connect to web3 and use your personal Aavegotchi's or not.

If you are Windows and you want to run the app offchain, you will need to update app/package.json with the following:

  "scripts": {
    ...
-   "start:offchain": "REACT_APP_OFFCHAIN=true react-scripts start",
+   "start:offchain": "set REACT_APP_OFFCHAIN=true && react-scripts start",
    ...
  },

You should now be able to view the app running in your browser at http://localhost:3000/.

You will be greeted with the menu screen which includes a home, a leaderboard and a settings page. For the scope of part 1 of the tutorial we wont be touching too much React, so don't worry about these pages for now. Instead, click START on the Game page to boot up your game.

You will notice that the loading bar gets stuck at connecting to server. This is because the game is waiting for a connection to the server before starting the game.

To run the server, open up a new terminal, and go into the server directory and run npm install to install the dependencies:

cd flappigotchi/server
npm install

If this is your first time using Typescript in nodejs, then you will need to run npm i -g ts-node to install ts-node on your machine.

Then when everything is installed, you run npm run start to run the server on port 443.

If you are on a Windows, you will need to update server/package.json to the following:

  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
-   "start:prod": "NODE_ENV=production nodemon server.ts",
+   "start:prod": "set NODE_ENV=production && nodemon server.ts",
-   "start": "NODE_ENV=development nodemon server.ts"
+   "start": "set NODE_ENV=development && nodemon server.ts"
  },

You should now be able to run the game without any problems!

Step 3) Acquiring assets

For Flappigotchi we need to acquire two different sprites. The Aavegotchi and the Pipes. Due to the magic of blockchain and more importantly Aavegotchi, the Aavegotchi svg comes straight from the Aavegotchi Smart Contract (Unless of-course you are using the default Aavegotchi, they just exist on your computer unfortunately).

For the pipe sprite-sheet, you have to download it from here and place it into a app/public/assets/sprites directory so that the Phaser scenes have access to it.

To use your asset within your Phaser game scenes, go into src/game/assets/index.ts and assign a unique key that will reference the pipe spritesheet. This is used within the Phaser scenes to fetch the correct assets.

Now add an object with your key, src, and asset type into the assets array. Assets of type SPRITESHEET also require a frameWidth and frameHeight value. This is the size of the frame of each sprite. So seeing as our spritesheet is 80x217, but it is 1 tile across and 3 tiles down, we can set the frame data to frameWidth: 80 /1 and frameHeight: 217 / 3.

Our file should now look like the following:

// src/game/assets/index.tsx

export interface Asset {
  key: string;
  src: string;
  type: 'IMAGE' | 'SVG' | 'SPRITESHEET' | 'AUDIO';
  data?: {
    frameWidth?: number;
    frameHeight?: number;
  };
}

export interface SpritesheetAsset extends Asset {
  type: 'SPRITESHEET';
  data: {
    frameWidth: number;
    frameHeight: number;
  };
}

export const BG = 'bg';
export const FULLSCREEN = 'fullscreen';
export const LEFT_CHEVRON = 'left_chevron';
export const CLICK = 'click';
export const PIPES = 'pipes';

// Save all in game assets in the public folder
export const assets: Array<Asset | SpritesheetAsset> = [
  {
    key: BG,
    src: 'assets/images/bg.png',
    type: 'IMAGE',
  },
  {
    key: LEFT_CHEVRON,
    src: 'assets/icons/chevron_left.svg',
    type: 'SVG',
  },
  {
    key: CLICK,
    src: 'assets/sounds/click.mp3',
    type: 'AUDIO',
  },
  {
    key: PIPES,
    src: 'assets/sprites/spritesheet.png',
    type: 'SPRITESHEET',
    data: {
      frameWidth: 80 / 1,
      frameHeight: 217 / 3,
    }
  }
];

The boot-scene uses the assets array to ensure each asset is loaded in before starting the game.

Step 4) Object Pooling

The way we are going to simulate movement in this game is to have the pipes move. Therefore, every 2 seconds or so we need to add a new pipe row to the right of the screen, which then move towards the left of the screen.

We are also going to be utilising a game dev mechanic called Object Pooling. This is so that when people play the game and get ridiculous scores, all the pipes don't accumulate in memory and slow down their machine.

To do this we we first create the Pipe game object that we want to construct in our group. So inside game/objects create a new typescript file called pipe.ts and inside it put:

// src/game/objects/pipe.ts

import { getGameHeight } from '../helpers';
import { PIPES } from 'game/assets';

export class Pipe extends Phaser.GameObjects.Image {
 constructor(scene: Phaser.Scene) {
   super(scene, -100, -100, PIPES, 0);
   this.setOrigin(0, 0);
   this.displayHeight = getGameHeight(scene) / 7;
   this.displayWidth = getGameHeight(scene) / 7;
 }
}

This class extends the Phaser.GameObjects.Image class. When this object is constructed the x and y value of its placement is both -100. This means that the pipe will be rendered off the screen. This is useful for object pooling as it means we can load in all the pipes we need at the start of the game and not have it interfere with the gameplay.

For tidy codebase reasons I tend to export the class from game/objects/index.ts so that we can import all our objects from the same file:

// src/game/object/index.ts

export * from './pipe';
export * from './player';

Now we have our Pipe class, we can import it into game-scene.ts and construct our group within the create() method:

// src/game/scenes/game-scene.ts

...
import { Player, Pipe } from 'game/objects';

...

export class GameScene extends Phaser.Scene {
  private player?: Player;
  private selectedGotchi?: AavegotchiGameObject;
  private pipes?: Phaser.GameObjects.Group;

  ...

  public create(): void {
    ...

    // Add pipes
    this.pipes = this.add.group({
      maxSize: 25,
      classType: Pipe,
    });

    ...
  }

...

This will construct a maximum of 25 pipes using our Pipe class.

If you was to run the game now, nothing will happen and you will be disappointed. What we have to do is use these pre-constructed pipes to create a Pipe Row with a randomly generated gap for the Aavegotchi to fly through. To do this lets create a new function in our GameScene called addPipeRow():

// src/game/scenes/game-scene.ts

...

export class GameScene extends Phaser.Scene {
  ...

  private addPipeRow = () => {   
    const size = getGameHeight(this) / 7;
    const x = getGameWidth(this);
    const velocityX = -getGameWidth(this) / 5;
    const gap = Math.floor(Math.random() * 4) + 1;

    for (let i = 0; i < 7; i++) {
      if (i !== gap && i !== gap + 1) {
        const frame = i === gap - 1 ? 2 : i === gap + 2 ? 0 : 1;
        this.addPipe(x, size * i, frame, velocityX);
      }
    }
  };

  ...

Our pipe rows are made up of 5 pipes and a gap the size of two pipes. You may also notice for all size and velocity related things I create it in proportion to the game screen dimensions. This is so that the game will work automatically on all screen sizes.

Essentially what this function is doing, is randomly generating a number between 1 and 4 and using that number to determine the gaps placement. Then it loops through from 0 to 6 constructing a pipe with its position and spritesheet frame depending on its placement. On the gap indexes, it does nothing (for now).

Now that we have our logic to construct the pipes, let's create our addPipe() function:

// src/game/scenes/game-scene.ts

...

export class GameScene extends Phaser.Scene {
  ...

  private addPipe = (x: number, y: number, frame: number, velocityX: number): void => {
    const pipe: Pipe = this.pipes?.get();
    pipe.activate(x, y, frame, velocityX);
  }; 

  ...

As our pipes already exist in a group, we need to use Phaser's get() method to pull an active pipe object from our object pool. We then need to activate it by setting its position, frame and velocity.

For this lets go back into our Pipe class and add the activate method:

// src/game/objects/pipe.ts

...

export class Pipe extends Phaser.GameObjects.Image {
  ...

  public activate = (x: number, y: number, frame: number, velocityX: number) => {
    // Physics
    this.scene.physics.world.enable(this);
    (this.body as Phaser.Physics.Arcade.Body).setVelocityX(velocityX);

    this.setPosition(x, y);
    this.setFrame(frame);
  }
}

All we got to do now is call the addPipeRow() method upon the games start as well as in intervals of 2 seconds:

// src/game/scenes/game-scene.ts

...
export class GameScene extends Phaser.Scene {
  ...

  public create(): void {
    ...

    this.addPipeRow();

    this.time.addEvent({
      delay: 2000,
      callback: this.addPipeRow,
      callbackScope: this,
      loop: true,
    });
  }
  ...
}

Now run the game again.

You should notice that after 5 rows have been constructed the game crashes. At this point you are either panicking, or nodding to yourself smugly as you remember that we set the maxSize of the pipe pool to 25. Therefore when our game tries activating pipe number 26, it cannot, as it does not exist. Therefore we need a way to deactivate our pipes and add them back into the pool.

Therefore, in our Pipe class we need to add a method that allows the Pipe to destroy itself upon going off the screen:

// src/game/objects/pipe.ts

...

export class Pipe extends Phaser.GameObjects.Image {
  ...

  public update = () => {
    if (this.x < -2 * this.displayWidth) {
      this.destroy()
    }
  }
}

We need to call this method every time GameScene updates. To do this, inside the object where we constructed out group add runChildUpdate: true:

// src/game/scenes/game-scene.ts

// Add pipes
this.pipes = this.add.group({
  maxSize: 25,
  classType: Pipe,
  runChildUpdate: true,
});

We will now be able to construct pipes for all eternity, hurrah!

Step 5) Player Controls

Out the box, the aavegotchi-minigame-template comes with basic controls and an idle animation for your Aavegotchi. However for our Flappigotchi game, all we want is click/space bar to flap.

So every time we press the space bar or click, we want our Player to move up. However we only want this to occur on the initial press. So we also need an isFlapping property that toggles on press and release.

With this being said, update player.ts with the following:

// src/game/objects/player.ts

import { getGameHeight } from 'game/helpers';

interface Props {
  scene: Phaser.Scene;
  x: number;
  y: number;
  key: string;
  frame?: number;
}

export class Player extends Phaser.GameObjects.Sprite {
  private jumpKey: Phaser.Input.Keyboard.Key;
  private pointer: Phaser.Input.Pointer;
  private isFlapping = false;

  constructor({ scene, x, y, key }: Props) {
    super(scene, x, y, key);

    // sprite
    this.setOrigin(0, 0);

    // physics
    this.scene.physics.world.enable(this);

    // input
    this.jumpKey = this.scene.input.keyboard.addKey(Phaser.Input.Keyboard.KeyCodes.SPACE);
    this.pointer = this.scene.input.activePointer;

    this.scene.add.existing(this);
  }

  update(): void {
    // handle input
    if ((this.jumpKey.isDown || this.pointer.isDown) && !this.isFlapping) {
      // flap
      this.isFlapping = true;

      (this.body as Phaser.Physics.Arcade.Body).setVelocityY(-getGameHeight(this.scene) * 0.6);

    } else if (this.jumpKey.isUp && !this.pointer.isDown && this.isFlapping) {
      this.isFlapping = false;
    }
  }
}

If you was to play the game now, upon pressing jump, the Player will continue to fly up. This is because we have nothing to counteract the upwards velocity. For that we need to add gravity to our Player. Luckily, Phaser handles the physics for us, we just need to apply it to our Player like so:

// src/game/objects/player.ts

...

export class Player extends Phaser.GameObjects.Sprite {
  ...

  constructor({ scene, x, y, key }: Props) {
    ...

    // physics
    this.scene.physics.world.enable(this);
    (this.body as Phaser.Physics.Arcade.Body).setGravityY(getGameHeight(this.scene) * 1.5);

    ...
  }

  ...
}

Step 6) Aavegotchi animations

Now that we have the controls down, let's bring our Aavegotchi to life with some animations. As our Aavegotchi's image data comes straight from the blockchain, we construct our spritesheet on the client side when the user loads in the other assets. To assist with this, there is a swanky custom built constructSpritesheet() function that takes a spriteMatrix as an argument. We can add different poses to the spriteMatrix using the customiseSvg() function.

Inside boot-scene.ts we are going to construct two animations for our Aavegotchi, one for flapping and one for death. (Don't worry, the Aavegotchi is a ghost so can't actually die).

// src/game/scenes/boot-scene.ts

...

export class BootScene extends Phaser.Scene {
  ...

  /**
   * Constructs and loads in the Aavegotchi spritesheet, you can use customiseSvg() to create custom poses and animations
   */
  private loadInGotchiSpritesheet = async (
    gotchiObject: AavegotchiGameObject
  ) => {
    const svg = gotchiObject.svg;
    const spriteMatrix = [
      // Flapping animation
      [
        customiseSvg(svg, {
          armsUp: true,
          removeBg: true,
          removeShadow: true
        }),
        customiseSvg(svg, { removeBg: true, removeShadow: true }),
      ],
      // Dead frame
      [
        customiseSvg(svg, { removeBg: true, removeShadow: true, eyes: 'sleeping', mouth: 'neutral' }),
      ]
    ];

    const { src, dimensions } = await constructSpritesheet(spriteMatrix);
    this.load.spritesheet(gotchiObject.spritesheetKey, src, {
      frameWidth: dimensions.width / dimensions.x,
      frameHeight: dimensions.height / dimensions.y,
    });
    this.load.start();
  };
}

As you develop your game, you may want to add more frames into your Aavegotchi animation repertoire. To do that you can just add extra options into customiseSvg() with your own custom SVG manipulations.

Now that we are loading in our new spritesheet, in the Player object, let's add in our two new animations:

// src/game/objects/player.ts

...

export class Player extends Phaser.GameObjects.Sprite {
  ...

  constructor({ scene, x, y, key }: Props) {
    super(scene, x, y, key);

    // Animations
    this.anims.create({
      key: 'flap',
      frames: this.anims.generateFrameNumbers(key || '', { frames: [ 1, 0 ]}),
      frameRate: 2,
    });
    this.anims.create({
      key: 'dead',
      frames: this.anims.generateFrameNumbers(key || '', { frames: [ 2 ]}),
    });

    ...
  }

  ...
}

To play the animation, all you have to do is call this.anims.play('ANI_KEY'). We want to call the 'flap' animation when the Player flaps, and we want to call the 'dead' animation upon death. For that we want to add in setDead() method and call this method upon the Player flying too high or too low.

The final result of the Player class will look like this:

// src/game/objects/player.ts

import { getGameHeight } from 'game/helpers';

interface Props {
  scene: Phaser.Scene;
  x: number;
  y: number;
  key: string;
  frame?: number;
}

export class Player extends Phaser.GameObjects.Sprite {
  private jumpKey: Phaser.Input.Keyboard.Key;
  private pointer: Phaser.Input.Pointer;
  private isFlapping = false;
  private isDead = false;

  constructor({ scene, x, y, key }: Props) {
    super(scene, x, y, key);

    // Animations
    this.anims.create({
      key: 'flap',
      frames: this.anims.generateFrameNumbers(key || '', { frames: [ 1, 0 ]}),
      frameRate: 2,
    });
    this.anims.create({
      key: 'dead',
      frames: this.anims.generateFrameNumbers(key || '', { frames: [ 2 ]}),
    });

    // physics
    this.scene.physics.world.enable(this);
    (this.body as Phaser.Physics.Arcade.Body).setGravityY(getGameHeight(this.scene) * 1.5);
    (this.body as Phaser.Physics.Arcade.Body).setSize(90, 120);

    // sprite
    this.setOrigin(0, 0);
    this.setDisplaySize(this.displayHeight * getGameHeight(scene) / 1200, this.displayHeight * getGameHeight(scene) / 1200);

    // input
    this.jumpKey = this.scene.input.keyboard.addKey(Phaser.Input.Keyboard.KeyCodes.SPACE);
    this.pointer = this.scene.input.activePointer;

    this.scene.add.existing(this);
  }

  public getDead(): boolean {
    return this.isDead;
  }

  public setDead(dead: boolean): void {
    this.isDead = dead;
    this.anims.play('dead');
  }

  update(): void {
    // handle input
    if ((this.jumpKey.isDown || this.pointer.isDown) && !this.isFlapping) {
      // flap
      this.isFlapping = true;
      this.anims.play('flap');

      (this.body as Phaser.Physics.Arcade.Body).setVelocityY(-getGameHeight(this.scene) * 0.6);

    } else if (this.jumpKey.isUp && !this.pointer.isDown && this.isFlapping) {
      this.isFlapping = false;
    }

    // check if off the screen
    if (this.y > getGameHeight(this.scene) || this.y < 0) {
      this.setDead(true);
    }
  }
}

I also added a change to the body size, to reduce the hitbox and make the game more fair. You will be able to see this by playing the game with debug mode on (this is on by default whilst running the app in development mode).

Step 7) Adding collisions

At the moment, our Aavegotchi fittingly floats through the pipes. However this doesn't make for a very fun game, so we need to add collisions between the Player and the Pipes object:

// src/game/scenes/game-scene.ts

...

export class GameScene extends Phaser.Scene {

  ...

  public update(): void {
    if (this.player && !this.player?.getDead()) {
      this.player.update();
      this.physics.overlap(
        this.player,
        this.pipes,
        () => {
          this.player?.setDead(true);
        },
        undefined,
        this,
      );
    } else {   
      Phaser.Actions.Call(
        (this.pipes as Phaser.GameObjects.Group).getChildren(),
        (pipe) => {
          (pipe.body as Phaser.Physics.Arcade.Body).setVelocityX(0);
        },
        this,
      );
    }

    if (this.player && this.player.y > this.sys.canvas.height) {
      window.history.back();
    }
  }
}

In the update method, we are checking if there is an overlap between the player and the pipes. If so, set the player to dead using setDead(true). If the player is dead, then we prevent the player from updating and set the pipes velocity to 0.

The Aavegotchi will then drop off the bottom of the scene, which is when we will call some sort of GameOver method, however for the scope of this tutorial we are using native Javascript to go back to the home screen.

To give the player more feedback on this brutal collision, we can add a sound to play on collision.

Within src/assets/sounds we already have a bunch of mp3 files. So what we will do is copy boop.mp3 from src/assets/sounds and paste it into the public/assets/sounds directory. Like we did before with the pipes spritesheet, we can import our sound into the game by adding it to the assets array in src/game/assets/index.tsx:

// src/game/assets/index.tsx

...

export const BOOP = 'boop';

export const assets: Array<Asset | SpritesheetAsset> = [
  ...
  {
    key: BOOP,
    src: 'assets/sounds/boop.mp3',
    type: 'AUDIO',
  },
];

Now on collision we can play our boop sound.

// src/game/scenes/game-scene.ts

import { LEFT_CHEVRON, BG, CLICK, BOOP } from 'game/assets';

...

export class GameScene extends Phaser.Scene {
  ...

  // Sounds
  private back?: Phaser.Sound.BaseSound;
  private boop?: Phaser.Sound.BaseSound;

  ...

  public create(): void {
    ...
    this.back = this.sound.add(CLICK, { loop: false });
    this.boop = this.sound.add(BOOP, { loop: false });

    ...
  }

  ...

  public update(): void {
    if (this.player && !this.player?.getDead()) {
      this.player.update();
      this.physics.overlap(
        this.player,
        this.pipes,
        () => {
          this.player?.setDead(true);
          this.boop?.play();
        },
        undefined,
        this,
      );
    } 

  ...

Step 8) Adding scores

Now that we have a losing condition, let's add in our scoring logic. First, we need a visual indicator of the players current score. For this we are going to create some simple text in the GameScene. Then we can add a function to add to the score and edit the text like so:

// src/game/scenes/game-scene.ts

...

export class GameScene extends Phaser.Scene {
  ...

  // Score
  private score = 0;
  private scoreText?: Phaser.GameObjects.Text;

  ...

  public create(): void {
    ...
    this.scoreText = this.add
      .text(getGameWidth(this) / 2, getGameHeight(this) / 2 - getRelative(190, this), this.score.toString(), {
        color: '#FFFFFF',
      })
      .setFontSize(getRelative(94, this))
      .setOrigin(0.5)
      .setDepth(1);

    ...
  }

  ...

  private addScore = () => {
    if (this.scoreText) {
      this.score += 1;
      this.scoreText.setText(this.score.toString());
    }
  };

  ...

To make sure we can see the score in front of the Pipes, we set the depth to 1.

In our game, we want to call addScore() every time the Player passes through the gaps in the pipes. Therefore we need to add an invisible game object called a Zone:

// src/game/objects/scoreZone.ts

interface Props {
  scene: Phaser.Scene;
  x: number;
  y: number;
  width: number;
  height: number;
  velocityX: number;
}

export class ScoreZone extends Phaser.GameObjects.Zone {
  constructor({ scene, x, y, width, height, velocityX }: Props) {
    super(scene, x, y);
    this.setOrigin(0, 0);
    this.displayHeight = height;
    this.displayWidth = width;

    // Physics
    this.scene.physics.world.enable(this);
    (this.body as Phaser.Physics.Arcade.Body).setVelocityX(velocityX);

    this.scene.add.existing(this);
  }

  public handleOverlap = () => {
    this.destroy();
  }
}

Now let's create a new group in GameScene for the ScoreZone. We then construct a ScoreZone and add to this group for every gap in addPipeRow():

/// src/game/objects/index.ts

export * from './player';
export * from './pipes';
export * from './scoreZone';

// src/game/scenes/game-scene.ts

...
import { Player, Pipe, ScoreZone } from 'game/objects';

...
export class GameScene extends Phaser.Scene {
  ...
  private scoreZone?: Phaser.GameObjects.Group;

  public create(): void {
    ...
    this.scoreZone = this.add.group({ classType: ScoreZone });

    this.addPipeRow();

    ...
  }

  private addPipeRow = () => {   
    const size = getGameHeight(this) / 7;
    const x = getGameWidth(this);
    const velocityX = -getGameWidth(this) / 5;
    const gap = Math.floor(Math.random() * 4) + 1;

    for (let i = 0; i < 7; i++) {
      if (i !== gap && i !== gap + 1) {
        const frame = i === gap - 1 ? 2 : i === gap + 2 ? 0 : 1;
        this.addPipe(x, size * i, frame, velocityX);
      } else if (i === gap) {
        this.addScoreZone(x, size * i, velocityX);
      }
    }
  };

  private addScoreZone = (x: number, y: number, velocityX: number): void => {
    const height = 2 * getGameHeight(this) / 7;
    const width = getGameHeight(this) / 7;
    this.scoreZone?.add(
      new ScoreZone({
        scene: this,
        x,
        y,
        width,
        height,
        velocityX
      })
    )
  }

  ...
}

The ScoreZone is 2 times the height of the pipe to fill the space.

Despite the ScoreZone being invisible, you will still be able to see the hit-box in debug mode.

Finally, all we have to do it add a new collision callback in the update() method between the Player and the ScoreZone to add to score:

// src/game/scenes/game-scene.ts

public update(): void {
    if (this.player && !this.player?.getDead()) {
      this.player.update();
      this.physics.overlap(
        this.player,
        this.pipes,
        () => {
          this.player?.setDead(true);
          this.boop?.play();
        },
        undefined,
        this,
      );
      this.physics.overlap(
        this.player,
        this.scoreZone,
        (_, zone) => {
          (zone as ScoreZone).handleOverlap();
          this.addScore();
        }
      )
    } 

    ...
  }

This overlap function has extra parameters in the callback function, as we need to remove the correct ScoreZone from the group upon coming into contact with it to avoid duplicate points.

Conclusion

In this lesson you have learnt how to use the aavegotchi-minigame-template, had a high level overview of Phaser3 and have been introduced to game development concepts such as Object Pooling.

Huzzuh! You now have the knowledge you need to create the singleplayer game of your dreams.

Now that you have your scores it would be great if you could store them in a leaderboard so you can compete with yourself and other Aavegotchi owners. To handle this, we will need to handle some server side logic:

Building a full-stack Aavegotchi minigame - Part 2: Server + Leaderboard

Caleb Coyote ・ Jul 6 '21

#web3 #aavegotchi #tutorial #gamedev

You can find the code for the end result of Part 1 here

Make sure to follow me @ccoyotedev or @gotchidevs on Twitter for updates on future tutorials.

If you have any questions about Aavegotchi or want to work with others to build Aavegotchi minigames, then join the Aavegotchi discord community where you can chat and collaborate with other Aavegotchi Aarchitects!

Building an Aavegotchi DApp using React + Web3

Caleb Coyote — Tue, 20 Apr 2021 06:42:43 +0000

Welcome fren! In this tutorial, I will be guiding you through the process of building a DApp (decentralised app) that is connected to the Aavegotchi blockchain. The tutorial will be in React and Typescript, however, don't worry if you do not have any React experience as the real meat of the tutorial is using Web3 and the Aavegotchi Subgraph.

You can find the completed code here:
https://github.com/cgcbrown/aavegotchi-dex-tutorial

What is Web3?

When developing an app on the blockchain, there are 2 sides to it.

Smart contract development - writing code that gets deployed to the blockchain with the Solidity programming language.
Developing websites or clients that interact with the blockchain via smart contracts.

As the Aavegotchi smart contract is already deployed on the Matic network, all we have to worry about is using Web3 to fulfil the second responsibility. Essentially you can think of Web3 as an API for the blockchain where all you need is the address of the smart contract, an ABI and a Provider.

What is the Aavegotchi Subgraph?

The Subgraph is a GraphQL API built by the Pixelcraft team on The Graph that allows you to more efficiently get data from the Aavegotchi blockchain without having to worry about any Web3 setup. It is useful for viewing data from the contract, however, it has its limitations. You cannot call methods that require gas (like petting your Aavegotchi) and some data that you want may not be integrated into the subgraph yet.

The Build

For this tutorial, we are going to build an Aavegotchi Pokédex that allows the user to search and view all of the summoned Aavegotchis. The end result will look something like this:

Initial setup

Before you can start you will need to make sure you have node >= 10.16 and npm >= 5.6 installed on your machine. You will also need an Ethereum compatible browser (if you are using Chrome or Firefox you will need to install the Metamask browser extension) connected to the Matic Network.

Now that is done, let us create our React app. To do this, open up your terminal, and run the following lines:

mkdir tutorials
cd tutorials
npx create-react-app aavegotchi-dex --template typescript

This will build a react app for you called aavegotchi-dex inside a newly created directory called tutorials. using --template typescript configures the React app to use Typescript.

After it's done installing, in your terminal run:

cd aavegotchi-dex
npm start

This should automatically open up your browser and you should see your app running on localhost:3000/. If not open up your browser and manually put http://localhost:3000/ in the address bar.

Now in your code editor of choice (I personally use Visual Studio code) open up aavegotchi-dex

In src/App.tsx replace all the code with the following and save:

//App.tsx

import { useEffect } from 'react';
import './App.css';

function App() {

 const fetchGotchis = () => {
   console.log('Hello fren');
 }

 useEffect(() => {
   fetchGotchis();
 }, [])

 return (
   <div className="App">
   </div>
 );
}

export default App;

Your screen in the browser should now be blank. However, if you open up your dev tools in the browser, you should see Hello fren in the console.

This isn’t a React tutorial, so don't worry if you don't fully understand what is happening. All you need to know is when the component is rendered, the useEffect() hook is triggered which in turn is triggering the fetchGotchis() function. This is where we are going to put our logic to fetch the Aavegotchi logic from the blockchain.

Using the Aavegotchi Subgraph

Now with the boring bits out of the way, let us start pulling in data from the blockchain!

The Subgraph

To make our lives easier we can use the Aavegotchi Subgraph to pull in our list of Aavegotchi's data. What's handy about the subgraph is you can open up the playground here to get your graphQL query before even writing any lines of code.

On the right, there is a Schema that allows you to visualise the data we can fetch.

The subgraph has a hard limit of 1000 on the amount of data you can fetch with a single query. This is not a problem as for performance reasons we will fetch 100, and then later, you can add the ability to fetch more data as you scroll.

We can now pick and choose what data we want to be returned from the query. For the Aavegotchidex we know we want the:

name
id
collateral
numeric traits

We are ordering the data by gotchiId instead of id because gotchiId is numeric. Try ordering it by id and you will see why this is important.

So how come we also aren’t getting the SVG data? Well if you look at the Aavegotchi schema you will see that there is no corresponding property for the SVG (at the time of writing this tutorial that is). This is an example of where we will be using Web3 later.

Using our query in React

Now that we have our query let's use it in our app. For this, we need to install 2 packages, graphQL and graphql-request as our graphQL client. So open up a new terminal, and inside your aavegotchi-dex directory run:

npm install graphql-request graphql

Once they have installed, in App.tsx put in the following new lines of code

//App.tsx

import { useEffect } from 'react';
import { request } from "graphql-request"; // <-- New line
import './App.css';

const uri = 'https://api.thegraph.com/subgraphs/name/aavegotchi/aavegotchi-core-matic';

function App() {

// Make sure this function is now Asynchronous
const fetchGotchis = async () => {
   const query = `
   {
     aavegotchis(first: 100, orderBy: gotchiId) {
       id
       name
       collateral
       withSetsNumericTraits
     }
   }
 `
 const response = await request(uri, query);
 console.log(response);
}
...

If you are getting a Typescript runtime error, run npm install @types/react --dev.

If you have done everything correctly you should now see the aavegotchi data logged in your console exactly as you requested it. So what's happening?

Well, the imported request function requires 2 arguments, the target URL and the query. We get the URL from thegraph.com under Queries (HTTP), this tells the GraphQL request where to target.

The query is what we mocked up earlier and have now converted into a string. We then asynchronously waited for the response to return and logged it in the console.

Now that we know our request works, we need to store it in the Apps state so we can display it in the UI. For this, we use a React hook called useState(). However, because we are using Typescript we need to first set up our interface.

Let us create a new folder under src called types and inside create an index.ts file. Now in src/types/index.ts put in the following code:

//types/index.ts

export interface Gotchi {
 collateral: string;
 id: string;
 name: string;
 withSetsNumericTraits: Array<Number>;
}

export interface QueryResponse {
 aavegotchis: Array<Gotchi>
}

Again, I'm not going to go over what the syntax of the Typescript means. You just need to understand that we are copying what we expect the response to look like from our Subgraph query.

Now at the top of App.tsx import our types and the useState hook from React, and edit the fetchGotchis function to store the response in the state:

//App.tsx

import { useEffect, useState } from 'react';
import { Gotchi, QueryResponse } from './types';
...

function App() {
  const [ gotchis, setGotchis ] = useState<Array<Gotchi>>([]);

  const fetchGotchis = async () => {
    const query = `
      {
        aavegotchis(first: 100, orderBy: gotchiId) {
          id
          name
          collateral
          withSetsNumericTraits
        }
      }
    `
    const response = await request<QueryResponse>(uri, query);
    setGotchis(response.aavegotchis)
  }
  ...
}

Now that we have stored the data, we can map it onto the screen. If you type this out manually within the App components return function you will be able to see Typescript coming into play and suggesting properties for you. It will also flag up any mistypes (the amount of time this will save you from bug fixing is dreamy).

//App.tsx

return (
  <div className="App">
    {gotchis.map((gotchi, i) => {
      return (
        <p key={i}>{gotchi.name}</p>
      )
    })}
  </div>
);

We should now see a list of names on the screen.

However, this doesn't look very interesting. So what we are gonna do is create a new component for the Aavegotchi listing, that allows you to select an Aavegotchi.

Structuring our code

In App.tsx replace the returned JSX with the following code:

//App.tsx

return (
  <div className="App">
    <div className="container">
      <div className="selected-container">
      </div>
      <div className="gotchi-list">
      </div>
    </div>
  </div>
);

and inside App.css replace the CSS with:

.App {
 display: block;
 text-align: center;
 height: 100vh;
 background-color: #FA34F3;
 box-sizing: border-box;
}

.container {
 display: grid;
 grid-template-rows: 50% 50%;
 box-sizing: border-box;
 height: 100%;
 width: 100%;
}

.gotchi-list {
 background-color: white;
 border-left: 5px solid black;
 border-right: 5px solid black;
 height: 100%;
 overflow-x: hidden;
 overflow-y: scroll;
 box-sizing: border-box;
}

@media (min-width: 768px) {
 .container {
   max-width: 1300px;
   margin: 0 auto;
   grid-template-columns: 1fr 1fr;
   grid-template-rows: revert;
 }
 .selected-container {
   box-sizing: border-box;
   padding: 16px;
   height: 100%;
 }
}

We now want to create a new component for each Aavegotchi listing as well as for the selected Aavegotchi.

So within src create a new folder called components and inside create two more folders called GotchiListing and SelectedGotchi which both have an index.tsx and a styles.css file.

Your folder structure should now look like this:

Render our Aavegotchi listing

Inside GotchiListing/index.tsx copy and paste in the following content:

//GotchiListing/index.tsx

import "./styles.css"

interface Props {
  id: string;
  name: string;
  collateralColor: string;
  selected: boolean;
  selectGotchi: () => void;
}

export const GotchiListing = ({ id, name, collateralColor, selected, selectGotchi }: Props) => {
 return (
   <div className={`gotchi-listing ${selected && 'selected'}`} onClick={() => selectGotchi()}>
     <div className="collateral-container">
       <div className="collateral" style={{ backgroundColor: collateralColor }} />
       </div>
     <p className="id">{id}</p>
     <p className="name">{name}</p>
   </div>
 )
}

The interface tells the editor that the GotchiListing component expects the following properties:

name - Name of the Aavegotchi
Id - Id of the Aavegotchi
collateralColor - Primary color of the collateral (more on this later)
selected - boolean of whether the item is selected or not
selectGotchi - Function that passes the click event to the parent

Inside GotchiListing/styles.css put:

.gotchi-listing {
  display: flex;
  cursor: pointer;
}
.gotchi-listing.selected,
.gotchi-listing:hover {
  background-color: #fffa65;
}

.collateral-container {
  width: 54px;
  display: grid;
  place-items: center;
}

.collateral {
  width: 32px;
  height: 32px;
  border-radius: 50%;
}

.id {
  padding-right: 12px;
  width: 60px;
  text-align: right;
}

.name {
  text-transform: uppercase;
  white-space: nowrap;
  text-overflow: ellipsis;
  overflow: hidden;
}

Now inside App.tsx lets import in and render our new component!

At the top with the other imports put:

//App.tsx

import { GotchiListing } from './components/GotchiListing';

And inside the div with a className of gotchi-list we should map out our <GotchiListing /> component for each Aavegotchi stored in our state:

//App.tsx

<div className="gotchi-list">
  {
     gotchis.map((gotchi, i) => (
       <GotchiListing
         key={gotchi.id}
         id={gotchi.id}
         name={gotchi.name}
         collateralColor="black"
         selectGotchi={() => null}
         selected={false}
       />
     ))
   }
</div>

If you are getting a run time error, inside SelectedGotchi/index.tsx type and save export {} as a temporary fix.

By doing this you should now be able to scroll through the list of Aavegotchis.

You may have noticed that we are not passing the gotchi.collateral to the collateralColor. That's because the collateral we get returned isn't a hex code, but a unique ID for the collateral. We will have to use Web3 later to call the aavegotchi contract to receive what the corresponding color should be.

Selecting an Aavegotchi

Time to put in our selection logic. First, we create another state within App.tsx for the selected Aavegotchi's index:

//App.tsx

const [ selectedGotchi, setSelectedGotchi ] = useState<number>(0);

Now when we click on a listing, we want to set the index position of the selected gotchi inside the state. And then we can use that information to check whether a listed gotchi is selected or not:

//App.tsx

<GotchiListing
  ...
  selectGotchi={() => setSelectedGotchi(i)}
  selected={i === selectedGotchi}
/>

Great! When you click a listing you should now see the listing is highlighted.

Now let us display the selection in a new component called SelectedGotchi. Inside SelectedGotchi/index.tsx paste in the following code:

//SelectedGotchi/index.tsx

import './styles.css'

interface Props {
 name: string;
 traits: Array<Number>;
}

export const SelectedGotchi = ({ name, traits }: Props) => {
  return (
    <div className="selected-gotchi-container">
      <div className="name-container">
        <h2>{name}</h2>
      </div>
      <div className="svg-container" />
      <div className="traits-container">
        <div className="trait">
          <p>⚡ Energy</p>
          <p>{traits[0]}</p>
        </div>
        <div className="trait">
          <p>👹 Aggression</p>
          <p>{traits[1]}</p>
        </div>
        <div className="trait">
          <p>👻 Spookiness</p>
          <p>{traits[2]}</p>
        </div>
        <div className="trait">
          <p>🧠 Brain size</p>
          <p>{traits[3]}</p>
        </div>
        <div className="trait">
          <p>👀 Eye shape</p>
          <p>{traits[4]}</p>
        </div>
        <div className="trait">
          <p>👁 Eye color</p>
          <p>{traits[5]}</p>
        </div>
      </div>
    </div>
  )
}

Inside SelectedGotchi/styles.css:

.selected-gotchi-container {
  display: grid;
  grid-template-rows: 15% 35% 50%;
  width: 100%;
  height: 100%;
  max-height: 100%;
}

.name-container {
  display: grid;
  place-items: center;
  border: 5px solid #e5df40;
  background-color: #fffa65;
  text-transform: uppercase;
}
.name-container h2 {
  margin: 0;
}

.svg-container {
  display: grid;
  place-items: center;
}
.svg-container > svg {
  height: 100%;
}

.traits-container {
  padding: 0.4rem;
  background-color: white;
  border: 5px solid black;
  display: grid;
  grid-template-columns: 1fr 1fr;
  row-gap: 12px;
  column-gap: 16px;
}
.trait {
  display: flex;
  align-items: center;
  justify-content: space-between;
}
.trait p {
  margin: 0;
  text-transform: uppercase;
}

@media (min-width: 768px) {
  .selected-gotchi-container {
    grid-template-rows: 72px 1fr 170px;
  }

  .svg-container > svg {
    height: revert;
    max-height: 450px;
  }

  .traits-container {
    padding: 1.6rem;
  }
}

Now we render our new component in App.tsx like so:

//App.tsx

...

import { SelectedGotchi } from './components/SelectedGotchi';

...

function App() {

 ...

 return (
  <div className="App">
    ...
      <div className="selected-container">
        {gotchis.length > 0 && (
          <SelectedGotchi
            name={gotchis[selectedGotchi].name} 
            traits={gotchis[selectedGotchi].withSetsNumericTraits}
          />
        )}
      </div>
      ...
  </div>
 );
}

export default App;

What we are doing is checking if any gotchis' exist in the array, then we're rendering in our <SelectedGotchi /> component. We then use the selectedGotchi index to get the target gotchis name and traits from the gotchis array.

You should now be able to select a gotchi and see the name and traits change in our new component!

Great! Well done for making it this far, for the final part of the tutorial we will be using Web3 to fetch the data that we couldn't get from the subgraph.

Using Web3

To view information on the blockchain you need 3 things:

A provider
The provider is your choice of the node which talks to the Matic Network. If you have Metamask installed or are you using an Ethereum compatible browser then that will be used as your line of communication.
The smart contracts address
This is essentially the URL of the target smart contract, we can find what this is by going on the Aavegotchi Contracts GitHub for the contracts.
We want the Aavegotchi diamond address as it has access to all the facets we need.
The ABI (application binary interface)
This is a JSON file whose job is to encode and decode the calls to and from the Solidity contract. We also can download/copy this from the Aavegotchi Github here.

Once we have located everything we need, we can start using it within our App.

Setting up the contract

Let us start by installing web3:

npm install web3

Now within the src folder of our app lets create a new folder called abi and inside it create a JSON file called diamondABI.json. In this file, we want to copy and paste the whole JSON object from the Github.

Inside App.tsx we can now import the following:

//App.tsx

import Web3 from 'web3';
import diamondABI from './abi/diamondABI.json';
import { Contract } from 'web3-eth-contract';
import { AbiItem } from 'web3-utils/types'

const diamondAddress = '0x86935F11C86623deC8a25696E1C19a8659CbF95d';

Contract and AbiItem are used only for Typescript purposes.

We also set the diamondAddress as a const using the address we found in the Aavegotchi Contract Github.

Now we have everything we need to view data from the Aavegotchi Blockchain. Inside App() let's create a new function called connectToWeb3() that will create our contract and save it in our state.

We want to call this function when the page first renders, therefore we put it in the useEffect() after fetchGotchis().

// App.tsx

function App() {
  ...
  const [ contract, setContract ] = useState<Contract | null>(null);

  const connectToWeb3 = () => {
    const web3 = new Web3(Web3.givenProvider);
    const aavegotchiContract = new web3.eth.Contract(diamondABI as AbiItem[], diamondAddress);
    setContract(aavegotchiContract);
  }

  ...

  useEffect(() => {
    fetchGotchis();
    connectToWeb3();
  }, [])

For the provider we have used Web3.givenProvider, this is automatically available if you are using an Ethereum compatible browser. If you don't have an Ethereum compatible browser then instead you can set up a remote or local node and use that as your provider.

Calling methods from the contract

Now that our contract is set up we can start calling methods off of it. You may be aware that calling methods on a contract may require gas. However, this only applies to methods that have to add, delete or change information on the contract. Just viewing data requires no manipulation of the contract and is therefore completely gas-free!

The first method we want to call is one to fetch the collateral primary colors so we can pass each <GotchiListing /> the correct color. By visiting the Aavegotchi Developer Documentation you can find the methods names for the various contracts. We want the getCollateralInfo() function as located here.

You can also find all of the contracts functions as well as their outputs and inputs within the ABI!

We want to fetch all of the collateral information in one request, however, we need to make sure that the contract is set up first.

To do this, create a new useEffect() hook within App.tsx which has the contract as a dependency:

//App.tsx

useEffect(() => {
  if (!!contract) {
    const fetchAavegotchiCollaterals = async () => {
      const collaterals = await contract.methods.getCollateralInfo().call();
      console.log(collaterals);
    };
    fetchAavegotchiCollaterals();
  }
}, [contract]);

As you can see, the fetchAavegotiCollaterals() function will only be triggered if contract is truthy. Therefore on initial render, it will not trigger as the contract wouldn't be set up yet. Therefore by adding contract as a dependency, useEffect() will now trigger as a side effect to the contract changing.

If everything has been put in correctly you should now see the different collaterals logged in your browser's console.

We can use the logged output to create our type definition so our code editor knows what we are expecting. So inside src/types/index.ts let's create a new interface for Collateral like so:

// types/index.ts

export interface Collateral {
  collateralType: string;
  collateralTypeInfo: {
    cheekColor: string;
    conversionRate: string;
    delisted: boolean;
    eyeShapeSvgId: string;
    modifiers: Array<string>;
    primaryColor: string;
    secondaryColor: string;
    svgId: string;
  }
}

In App.tsx lets import our new interface and create a new state which expects an array of collaterals and in our fetchAavegotchiCollaterals() function we can set the state:

//App.tsx

function App() {
  ...
  const [ collaterals, setCollaterals ] = useState<Array<Collateral>>([]);
  ...

 useEffect(() => {
  if (!!contract) {
    const fetchAavegotchiCollaterals = async () => {
      const collaterals = await contract.methods.getCollateralInfo().call();
      setCollaterals(collaterals); // <- Replaced console.log()
    };

    fetchAavegotchiCollaterals();
  }
}, [contract]);

We should now have all the collaterals stored in the state, so let's create a function that takes the gotchi.collateral, finds it within collaterals and returns the corresponding primaryColor.

//App.tsx

function App() {

  ...

  const getCollateralColor = (gotchiCollateral: string) => {
    const collateral = collaterals.find(item => item.collateralType.toLowerCase() === gotchiCollateral);
    if (collateral) {
      return collateral.collateralTypeInfo.primaryColor.replace("0x", '#');
    }
    return "white";
  }

  ...

  return (
    <div className="App">
        ...
        <div className="gotchi-list">
          {
            gotchis.map((gotchi, i) => (
              <GotchiListing
                ...
                collateralColor={getCollateralColor(gotchi.collateral)}
                ...
              />
            ))
          }
        </div>
        ...
    </div>
  );
}

The replace operation correctly formats the primaryColor value into a hex code that the CSS can interpret.

Your gotchi listing should now have the color that represents the gotchis collateral (If you wanted to go a step further you could see if you can put in the logic to display the correct collateral icon).

Displaying the Aavegotchi SVG

All we have left to do is display the selected Aavegotchis image. This is arguably my favourite thing about Aavegotchi as all the SVG’s are stored within the blockchain itself!

If you go back to the Aavegotchi developer wiki you can locate the method we want, which is getAavegotchiSvg(tokenId). This method requires passing an Aavegotchis Id as a parameter.

Since writing this tutorial, the Aavegotchi's side and back SVG's are also available via calling getAavegotchiSideSvgs(tokenId). This will return an Array of each SVG.`

Every time we select a gotchi we want to render the SVG within our SelectedGotchi component. Therefore we need a new useEffect() hook that will trigger every time selectedGotchi, gotchis or contract changes:

`javascript
//App.tsx

function App() {
...
const [ gotchiSVG, setGotchiSVG ] = useState('');

...

useEffect(() => {
const getAavegotchiSVG = async (tokenId: string) => {
const svg = await contract?.methods.getAavegotchiSvg(tokenId).call();
setGotchiSVG(svg);
};

if (contract && gotchis.length > 0) {
  getAavegotchiSVG(gotchis[selectedGotchi].id)
}

}, [selectedGotchi, contract, gotchis]);

If you were to console.log(gotchiSVG) you would see that the output is HTML code. This is the SVG data that we want to inject into our code.

We then pass the SVG data into our <SelectedGotchi /> component like so:

`jsx
//App.tsx

svg={gotchiSVG}
name={gotchis[selectedGotchi].name}
traits={gotchis[selectedGotchi].withSetsNumericTraits}
/>
`

Within the SelectedGotchi component, we need to add the svg property to the interface so we can use it as a prop.

So go to src/components/SelectedGotchi/index.tsx and add the following changes:
`jsx
// SelectedGotchi/index.tsx

import './styles.css'

interface Props {
name: string;
traits: Array;
svg: string; //<-- New prop
}

export const SelectedGotchi = ({ name, traits, svg }: Props) => {
return (

...

...

If everything is done correctly you should now be able to see your selected Aavegotchi!

As the SVG data is being rendered in the DOM you can use your browsers element inspector to identify the class names of the different layers of the SVG. This is useful if you want to animate or hide certain layers of the Aavegotchi SVG.

To show this we are going to hide the SVG background by pasting into SelectedGotchi/styles.css:

css .svg-container .gotchi-bg,.wearable-bg { display: none; }

The background should now be hidden!

Conclusion

Nice one fren! In this tutorial, you have learnt how to use both the Subgraph and Web3 to create a decentralised React App!

You should now be equipped with the knowledge you need to take the app a step further. You could add in an infinite scroll that concats more Aavegotchi data into the listing... Or perhaps some filter or sorting functionality that sends a new query to the subgraph to fetch more data?

If you have any questions about Aavegotchi or want to build more DApps, then join Aavegotchi discord community where you will be welcomed with open arms!

You can find the completed code here:
https://github.com/cgcbrown/aavegotchi-dex-tutorial