> For the complete documentation index, see [llms.txt](https://fury-racing.gitbook.io/fury-racing/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://fury-racing.gitbook.io/fury-racing/architecture/frontend.md).

# Frontend

## Description:

The front end of Fury Racing has been built to make the interaction with the smart contracts as smooth as possible. Only one transaction is required to play a game, even as a new player. All racing modes are accessible directly from the front end.

This comes as a PWA (Progressive Web App) with a responsive design, allowing it to be played on any device, from desktop to mobile to be accessible to as many users as possible. And because it is a PWA, you can even install it on your device in one click!

Dark mode, sound, and Fullscreen are also available to enhance the user experience and make it feel like a real game.

And the best part... To make it even cooler, we have integrated some beautiful 3D animations with BabylonJS to make the game more immersive and fun!

## Built With:

* [Next.js v14.2](https://nextjs.org/)
* [TypeScript v5.4.5](https://www.typescriptlang.org/)
* [Babylon.js](https://www.babylonjs.com/)
* [ChakraUI](https://chakra-ui.com/)
* [Viem](https://viem.sh/)
* [Wagmi](https://wagmi.sh/)
* [RainbowKit](https://github.com/rainbow-me/rainbowkit#readme)

## BabylonJS implementation

The following features of the BabylonJS engine were used:

* Loading all assets (meshes, textures) in batch, with a loading screen during processing, with `AssetsManager`.
* Loading `glTF` meshes specifically with the built-in BabylonJS loader.
* Using a `FollowCamera` to automatically follow the vehicle as it moves.
* Using `Animation` and `AnimationGroup` classes to animate the vehicle's movement.
* Generating shadows for the vehicle with `ShadowGenerator` and a `DirectionalLight`.
* Generating a skybox with the `Scene.createDefaultSkybox()` helper function.
* Generating rain particles with a `ParticleSystem`.
* Generating fog via the `Scene.fogMode` property.

<figure><img src="/files/Hd5o4E5Gk3rFli7xQk66" alt=""><figcaption><p>3D car animation made with Babylon.js</p></figcaption></figure>

### **Third-party assets**

All 3D assets were found on [SketchFab](https://sketchfab.com) ([all credits are listed there](https://fury-racing.gitbook.io/fury-racing/appendices/credits)). However, not all assets were perfectly centered on the origin `(0, 0, 0)`. Furthermore, many of the assets varied greatly in size.

As such, an array of metadata constants was created to specify the offset and scale of each asset. The meshes are therefore correspondingly offset and re-scaled during initialization.

<figure><img src="/files/FlRD1a2aaMwQUC3owTZV" alt=""><figcaption><p>Third-party assets allow to create beautiful environments for the race animation</p></figcaption></figure>

### **Programming the race track layout**

In order to quickly implement a simple, flexible race track builder system, we opted to allow the coding of tracks using plain ASCII. This allows us to embed the layout of race tracks directly in the code and makes it easy to visualize the end result in advance, without any third-party tools. Furthermore, this greatly facilitates the creation/addition of new tracks, if desired.

By going with a grid/tile-based approach, it also simplifies the automation of the vehicle animation. The engine simply gets the vehicle to move from the current tile to the next tile in the appropriate direction through a looping process.

We ended up choosing Monaco as the sole race track of the first release. You can see its ASCII equivalent below:

<figure><img src="/files/5gR2djPnmANE5YorFdLJ" alt="Monaco circuit in ASCII"><figcaption><p>Monaco track in ASCII</p></figcaption></figure>

With the corresponding character legend:

* `0`: Blank (grass) tile.
* `V`: Tree (vegetation) tile.
* `─`, `│`, `┌`, `┐`, `└` and `┘`: Road tiles.
* `├`, `┤`, `┴` and `┬`: House tiles, each representing a particular orientation.
* `╠`, `╣`, `╩` and `╦`: Building tiles, each representing a particular orientation.
* `˼`, `˻`, `˹` and `˺`: Billboards, each representing a particular orientation.

## Installation

### Prerequisites

Make sure you have the following ready:

* [node.js](https://nodejs.org/) installed (developed on LTS v18)
* [typescript](https://www.typescriptlang.org/) installed (developed on v5.3.3)
* [bun](https://bun.sh/) or [pnpm](https://pnpm.io/) or [yarn](https://yarnpkg.com/) or [npm](https://www.npmjs.com/) installed
* [MetaMask](https://metamask.io/) (or any web3 compatible wallet) installed in your browser

### Clone the repo:

Once your config is ready, create a new repo, open your favorite code editor, and clone the repo with the following cmd:

```bash
git clone https://github.com/Pedrojok01/fury-racing.git .
```

### Install all package dependencies:

Depending on your favorite package manager, run one of the following commands in your terminal to install all the dependencies needed for the project:

```bash
bun install
# or
pnpm install
# or
yarn install
# or
npm install
```

### Add your API keys in the .env file:

Remove the `.example` from the `.env.example` file name at the root of the project and add your API keys inside. The WalletConnect project ID is now required since the v2 update. You can create one easily on the [WalletConnect dashboard](https://cloud.walletconnect.com/).

And for the weather API key, you can get one for free on \[[www.weatherapi.com\]\\(sign](https://fury-racing.gitbook.io/fury-racing/architecture/http:/www.weatherapi.com]\\\(sign) up at <https://www.weatherapi.com/>.).

```js
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID = "Project ID needed for WalletConnect v2 here";

WEATHER_API_KEY = "Your OpenWeatherMap API key here";
```

### To start Fury Racing:

First, run the development server:

```bash
bun dev
# or
pnpm dev
# or
yarn dev
# or
npm run dev
```

Open <http://localhost:3000> with your browser to see the result.