Merge pull request #30 from D-Shestak/patch-5

Patch 5

Author: pixelplex

docs/v3/guidelines/dapps/tutorials/web3-game-example.md

@@ -1,53 +1,52 @@
 # TON blockchain for games
 
 ## What’s in the tutorial
-In this tutorial we will consider how to add the TON blockchain to a game. For our example, we will use a Flappy Bird clone written in Phaser and will add GameFi features step by step. In the tutorial we will use short code pieces and pseudocode to make it more readable. Also, we will provide links to real code blocks to help you understand better. The whole implementation can be found in the [demo repo](https://github.com/ton-community/flappy-bird).
+In this tutorial, we will explore how to integrate the TON blockchain into a game. As an example, we will use a Flappy Bird clone built with Phaser and gradually add GameFi features. To improve readability, we will use short code snippets and pseudocode. Additionally, we will provide links to real code blocks for better understanding. The complete implementation can be found in the [demo repo](https://github.com/ton-community/flappy-bird).
 
 ![Flappy Bird game without GameFi features](/img/tutorials/gamefi-flappy/no-gamefi-yet.png)
 
-We are going to implement the following:
-- Achievements. Let’s reward our users with [SBTs](/v3/concepts/glossary#sbt). The achievement system is a great tool to increase user engagement.
-- Game currency. In TON blockchain it’s easy to launch your own token (jetton). The token can be used to create an in-game economy. Our users will be able to earn the game coins to spend them later.
-- Game shop. We will provide users with the possibility to purchase in-game items using either in-game currency or the TON coin itself.
-
+We will implement the following:
+- Achievements. Let’s reward our users with [SBTs](/v3/concepts/glossary#sbt). The achievement system is a great tool for increasing user engagement.
+- Game currency. On the TON blockchain, it’s easy to launch your own token (jetton). The token can be used to create an in-game economy. Our users will be able to earn game coins and spend them later.
+- Game shop. We will allow users to purchase in-game items using either in-game currency or TON coins.
+  
 ## Preparations
 
 ### Install GameFi SDK
-First, we will set up the game environment. To do that we need to install `assets-sdk`. The package is designed to prepare everything developers need to integrate the blockchain into games. The lib can be used either from CLI or from Node.js scripts. In this tutorial we stick with the CLI approach.
+First, we need to set up the game environment by installing `assets-sdk`. This package is designed to provide developers with everything required to integrate the blockchain into games. The library can be used either from the CLI or within Node.js scripts. In this tutorial, we will use the CLI approach.
 ```sh
 npm install -g @ton-community/assets-sdk@beta
 ```
 
 ### Create a master wallet
-Next, we need to create a master wallet. The master wallet is a wallet we will use to mint the jetton, collections, NFTs, SBTs and receive payments.
+Next, we need to create a master wallet. This wallet will be used to mint jettons, collections, NFTs, and SBTs, as well as to receive payments.
 ```sh
 assets-cli setup-env
 ```
-You will be asked a few questions:
+You will be asked a few questions during the setup.
 
 Field | Hint
 :----- | :-----
-Network | Select `testnet` as far it’s a test game.
-Type | Select `highload-v2`type of wallet as far it’s the best, performant option to use as a master wallet.
-Storage | The storage will be used to store `NFT`/`SB`T files. `Amazon S3` (centralized) or `Pinata` (decentralized).  For the tutorial let’s use `Pinata` as far as decentralized storage will be more illustrative for the Web3 game.
-IPFS gateway | Service to load assets metadata from: `pinata`, `ipfs.io` or enter other service URL.
+Network | Select `testnet` since this is a test game.
+Type | Select `highload-v2`wallet type, as it offers the best performance for use as a master wallet.
+Storage | Storage is used to hold `NFT`/`SB`T files. You can choose between `Amazon S3` (centralized) or `Pinata` (decentralized).  For this tutorial, we'll use Pinata since decentralized storage is more illustrative for a Web3 game.
+IPFS gateway | This service loads asset metadata from  `pinata`, `ipfs.io,  or a custom service URL.
 
-The script outputs the link you can open to see the created wallet state.
+The script will output a link where you can view the created wallet's state.
 
 ![New wallet in Nonexist status](/img/tutorials/gamefi-flappy/wallet-nonexist-status.png)
 
-As you can see the wallet is not actually created yet. To the wallet be really created we need to deposit some funds into it. In the real-world scenario, you can deposit the wallet any way you prefer using the wallet address. In our case we will use [Testgiver TON Bot](https://t.me/testgiver_ton_bot). Please open it to claim 5 test TON coins.
-
-A bit later you could see 5 TON on the wallet and its status became `Uninit`. The wallet is ready. After the first usage it changes status to `Active`.
+As you can see, the wallet has not actually been created yet. To finalize the creation, we need to deposit funds into it. In a real-world scenario, you can fund the wallet however you prefer using its address. In our case, we will use the [Testgiver TON Bot](https://t.me/testgiver_ton_bot). Open it to claim 5 test TON coins.
 
+A little later, you should see 5 TON in the wallet, and its status will change to Uninit. The wallet is now ready. After the first transaction, its status will change to Active.
 ![Wallet status after top-up](/img/tutorials/gamefi-flappy/wallet-nonexist-status.png)
 
 ### Mint in-game currency
-We are going to create in-game currency to reward users with it:
+We are going to create an in-game currency to reward users.
 ```sh
 assets-cli deploy-jetton
 ```
-You will be asked a few questions:
+You will be asked a few questions during the setup:
 
 Field | Hint
 :----- | :-----
@@ -57,12 +56,12 @@ Image | Download prepared [jetton logo](https://raw.githubusercontent.com/ton-co
 Symbol | `FLAP` or enter any abbreviation you want to use.
 Decimals | How many zeros after the dot your currency will have. Let’ it be `0` in our case.
 
-The script outputs the link you can open to see the created jetton state. It will have `Active` status. The wallet status will change the status from `Uninit` to `Active`.
+The script will output a link where you can view the created jetton's state. It will have an **Active** status. The wallet’s status will change from **Uninit** to **Active**.
 
 ![In-game currency / jetton](/img/tutorials/gamefi-flappy/jetton-active-status.png)
 
 ### Create collections for SBTs
-Just for example, in the demo game we will reward users for the first and the fifth games. So, we will mint two collections to put SBTs into them when users achieve related conditions – play first and fifth time:
+For our demo game, we will reward users after their first and fifth games. To do this, we will mint two collections, where SBTs will be assigned when users meet the required conditions—playing for the first and fifth time:
 ```sh
 assets-cli deploy-nft-collection
 ```
@@ -74,14 +73,17 @@ Name | Flappy First Flight | Flappy High Fiver
 Description | Commemorating your inaugural journey in the Flappy Bird game! | Celebrate your persistent play with the Flappy High Fiver NFT!
 Image | You can download [the image](https://raw.githubusercontent.com/ton-community/flappy-bird/article-v1/scripts/tokens/first-time/image.png) here | You can download [the image](https://raw.githubusercontent.com/ton-community/flappy-bird/article-v1/scripts/tokens/five-times/image.png) here
 
-We are fully prepared. So, let’s go to the logic implementation.
+Now that we are fully prepared, let's proceed to implementing the game logic.
 
 ## Connecting wallet
-The process begins with the user connecting their wallet. So, let’s add wallet connect integration. To work with the blockchain from the client side we need to install GameFi SDK for Phaser:
+The process begins with the user connecting their wallet. Let's integrate wallet connectivity.
+
+To interact with the blockchain from the client side, we need to install the GameFi SDK for Phaser:
 ```sh
 npm install --save @ton/phaser-sdk@beta
 ```
-Now let’s setup GameFi SDK and create an instance of it:
+Now, let's set up GameFi SDK and create an instance of it:
+
 ```typescript
 import { GameFi } from '@ton/phaser-sdk'
 
@@ -118,7 +120,8 @@ const gameFi = await GameFi.create({
 
 > To learn what `tonconnect-manifest.json` is please check ton-connect [manifest description](/v3/guidelines/ton-connect/guidelines/creating-manifest).
 
-Now we are ready to create a wallet connect button. Let’s create a UI scene in Phaser which will contain the connect button:
+Next, we are ready to create a **Wallet Connect** button. Let’s create a UI scene in Phaser that will contain the **Connect** button:
+
 ```typescript
 class UiScene extends Phaser.Scene {
     // receive gameFi instance via constructor
@@ -143,7 +146,7 @@ class UiScene extends Phaser.Scene {
 
 > Read how to create [connect button](https://github.com/ton-community/flappy-bird/blob/article-v1/workspaces/client/src/connect-wallet-ui.ts#L82) and the [UI scene](https://github.com/ton-community/flappy-bird/blob/article-v1/workspaces/client/src/connect-wallet-ui.ts#L45).
 
-To watch when a user connects or disconnects his wallet let’s use the following piece of code:
+To monitor when a user connects or disconnects their wallet, use the following code snippet:
 ```typescript
 function onWalletChange(wallet: Wallet | null) {
     if (wallet) {
@@ -157,29 +160,29 @@ const unsubscribe = gameFi.onWalletChange(onWalletChange)
 
 > To learn about more complex scenarios please check out the full implementation of [wallet connect flow](https://github.com/ton-community/flappy-bird/blob/article-v1/workspaces/client/src/index.ts#L16).
 
-Read how [game UI managing](https://github.com/ton-community/flappy-bird/blob/article-v1/workspaces/client/src/index.ts#L50) might be implemented.
+Read how [game UI managing](https://github.com/ton-community/flappy-bird/blob/article-v1/workspaces/client/src/index.ts#L50) can be implemented.
 
-Now we have the user wallet connected and we can move forward.
+Now that we have the user's wallet connected, we can move forward.
 
 ![Connect wallet button](/img/tutorials/gamefi-flappy/wallet-connect-button.png)
 ![Confirm wallet connection](/img/tutorials/gamefi-flappy/wallet-connect-confirmation.png)
 ![Wallet is connected](/img/tutorials/gamefi-flappy/wallet-connected.png)
 
 
 ## Implementing achievements & rewards
-To implement achievements and reward system we need to prepare an endpoint which will be requested per user try.
+To implement the achievements and reward system, we need to set up an endpoint that will be triggered each time a user plays.
 
 ### `/played` endpoint
-We need to create an endpoint `/played ` which must do the following:
-- receive a body with a user wallet address and Telegram initial data passed to Mini App during the app launch. The initial data needs to be parsed to extract authentication data and ensure a user sends the request only on its behalf.
-- the endpoint must calculate and store the number of games a user played.
-- the endpoint must check if it’s the first or fifth game for a user and if so, reward a user with related SBT.
-- the endpoint must reward a user with 1 FLAP for each game.
+We need to create an endpoint `/played ` which does the following:
+- receives a request body containing the user’s wallet address and Telegram initial data, which is passed to the Mini App during launch. The initial data must be parsed to extract authentication details and verify that the user is sending the request on their own behalf.
+- tracks and stores the number of games a user has played.
+- checks whether this is the user’s first or fifth game. If so, it rewards the user with the corresponding SBT.
+- rewards the user with 1 FLAP for each game played.
 
 > Read [/played endpoint](https://github.com/ton-community/flappy-bird/blob/article-v1/workspaces/server/src/index.ts#L197) code.
 
 ### Request `/played` endpoint
-Every time the bird hits a pipe or falls down the client code must call `/played` endpoint passing the correct body:
+Every time the bird hits a pipe or falls, the client code must call the `/played` endpoint, passing the correct request body:
 ```typescript
 async function submitPlayed(endpoint: string, walletAddress: string) {
     return await (await fetch(endpoint + '/played', {
@@ -199,38 +202,39 @@ const playedInfo = await submitPlayed('http://localhost:3001', wallet.account.ad
 
 > Read [submitPlayer function](https://github.com/ton-community/flappy-bird/blob/article-v1/workspaces/client/src/game-scene.ts#L10) code.
 
-Let’s play the first time and ensure we will be rewarded with a FLAP token and SBT. Click the Play button, fly through a pipe or two and then hit into a tube. Alright, everything works!
+Let’s play for the first time and ensure we receive a FLAP token and an SBT. Click the Play button, fly through a pipe or two, then crash into a pipe. Everything works!
 
 ![Rewarded with token and SBT](/img/tutorials/gamefi-flappy/sbt-rewarded.png)
 
-Play 4 more times to get the second SBT, then open your Wallet, TON Space. Here your collectibles are:
-
+Play four more times to earn the second SBT, then open your TON Space Wallet. Here are your collectibles:
 ![Achievements as SBT in Wallet](/img/tutorials/gamefi-flappy/sbts-in-wallet.png)
 
-## Implementing game shop
-To have an in-game shop we need to have two components. The first is an endpoint that provides info about users purchases. The second is a global loop to watch user transactions and assign game properties to its owners.
+## Implementing the game shop
+To set up an in-game shop, we need two components. The first is an endpoint that provides information about users' purchases. The second is a global loop that monitors user transactions and assigns game properties to item owners.
 
 ### `/purchases` endpoint
 The endpoint does the following:
-- receive `auth` get param with Telegram Mini Apps initial data.
-- the endpoint gets items a user purchased and responds with the items list.
+- receive `auth` query parameter containing Telegram Mini App initial data.
+- retrieves the items a user has purchased and responds with a list of those items.
 
 > Read [/purchases](https://github.com/ton-community/flappy-bird/blob/article-v1/workspaces/server/src/index.ts#L303) endpoint code.
 
 ### Purchases loop
-To know when users make payments, we need to watch the master wallet transactions. Every transaction must contain a message `userId`:`itemId`. We will remember the last processed transaction, get only new ones, assign users properties they bought using `userId` and `itemId`, rewrite the last transaction hash. This will work in an infinite loop.
+o track user payments, we need to monitor transactions in the master wallet. Each transaction must include a message in the format `userId`:`itemId`. We will store the last processed transaction, retrieve only new ones, assign purchased properties to users based on `userId` and `itemId`, and update the last transaction hash. This process will run in an infinite loop.
 
-> Read [purchase loop](https://github.com/ton-community/flappy-bird/blob/article-v1/workspaces/server/src/index.ts#L110) code.
+> Read the [purchase loop](https://github.com/ton-community/flappy-bird/blob/article-v1/workspaces/server/src/index.ts#L110) code.
 
 ### Client side for the shop
 
-On the client side we have the Shop button.
+On the client side, we have a **Shop** button.
+
 
 ![Enter shop button](/img/tutorials/gamefi-flappy/shop-enter-button.png)
 
-When a user clicks the button, the shop scene is opened. The shop scene contains the list of items a user can buy. Each item has a price and a Buy button. When a user clicks the Buy button, the purchase is made.
+When a user clicks this button, the **Shop Scene** opens. The shop contains a list of items available for purchase. Each item has a price and a Buy button. When a user clicks the Buy button, the purchase is processed.
+
+Opening the **Shop Scene** will trigger the loading of purchased items and refresh the list every 10 seconds.
 
-Opening the Shop will trigger purchased items loading and updating it every 10 seconds:
 ```typescript
 // inside of fetchPurchases function
 await fetch('http://localhost:3000/purchases?auth=' + encodeURIComponent((window as any).Telegram.WebApp.initData))
@@ -240,7 +244,7 @@ setTimeout(() => { fetchPurchases() }, 10000)
 
 > Read [showShop function](https://github.com/ton-community/flappy-bird/blob/article-v1/workspaces/client/src/ui.ts#L191) code.
 
-Now we need to implement the purchase itself. To do that, we will create GameFi SDK instance first and then use `buyWithJetton` method:
+Now, we need to implement the purchase process. To do this, we will first create a GameFi SDK instance and then use the `buyWithJetton` method:
 ```typescript
 gameFi.buyWithJetton({
     amount: BigInt(price),
@@ -253,7 +257,7 @@ gameFi.buyWithJetton({
 ![Purchase confirmation](/img/tutorials/gamefi-flappy/purchase-confirmation.png)
 ![Property is ready to use](/img/tutorials/gamefi-flappy/purchase-done.png)
 
-It's also possible to pay with the TON coin:
+It is also possible to pay with TON coins:
 ```typescript
 import { toNano } from '@ton/phaser-sdk'
 
@@ -265,11 +269,11 @@ gameFi.buyWithTon({
 
 ## Afterword
 
-That’s it for this tutorial! We considered the basic GameFi features, but the SDK delivers more functionality like transfers between players, utils to work NFTs and collections, etc. We will deliver even more features in the future.
+TThat’s it for this tutorial! We explored the basic GameFi features, but the SDK offers additional functionality, such as player-to-player transfers and utilities for working with NFTs and collections. More features will be introduced in the future.
 
-To learn about all the GameFi features you can use read the docs of [ton-org/game-engines-sdk](https://github.com/ton-org/game-engines-sdk) and [@ton-community/assets-sdk](https://github.com/ton-community/assets-sdk).
+To learn about all available GameFi features, read the documentation for [ton-org/game-engines-sdk](https://github.com/ton-org/game-engines-sdk) and [@ton-community/assets-sdk](https://github.com/ton-community/assets-sdk).
 
-So, let us know what you think in the [Discussions](https://github.com/ton-org/game-engines-sdk/discussions)!
+et us know your thoughts in [Discussions](https://github.com/ton-org/game-engines-sdk/discussions)!
 
 
-The complete implementation is available in [flappy-bird](https://github.com/ton-community/flappy-bird) repo.
+The complete implementation is available in the [flappy-bird](https://github.com/ton-community/flappy-bird) repository.