diff --git a/docs/02-guides/01-platform/03-advanced-mechanics/07-hot-cold-inventories.md b/docs/02-guides/01-platform/03-advanced-mechanics/07-hot-cold-inventories.md index a5a0a6d..b90240d 100644 --- a/docs/02-guides/01-platform/03-advanced-mechanics/07-hot-cold-inventories.md +++ b/docs/02-guides/01-platform/03-advanced-mechanics/07-hot-cold-inventories.md @@ -170,5 +170,5 @@ Moving to hot melts a token from the player's wallet, which needs ENJ to pay them, or transfer them to an external wallet. -The project consists of two main components: +The sample comes in **two flavors that share the same backend**: - * **🎮 Unity Game (Client):** The front-end game that players interact with. It handles gameplay, visuals, and user input, communicating with the game server to perform blockchain actions. - * **🖥️ Game Server (Backend):** A .NET application that manages all Enjin Platform logic using the [Enjin Platform C# SDK](https://github.com/enjin/platform-csharp-sdk). It securely handles wallet creation, token minting, and other on-chain operations on behalf of the players. +- 🟦 **[Unity client](/02-guides/01-platform/05-enjin-farmer-sample-game/02-unity.md)** — built with Unity. +- 🟧 **[Godot client](/02-guides/01-platform/05-enjin-farmer-sample-game/03-godot.md)** — built with Godot. + +Both talk to the **same .NET game server**, so this page covers everything common to both: the architecture, prerequisites, and how to stand up the server, Enjin Platform, and Wallet Daemon. Once the server is running, head to the page for your engine to set up and run the client. + +### System Architecture + +The project consists of four main components that work together: + + - **Game Client ([Unity](https://github.com/enjin/platform-sample-game-client-unity) or [Godot](https://github.com/enjin/platform-sample-game-client-godot)):** The game itself, where you play and interact with items. + - **[Game Server (.NET)](https://github.com/enjin/platform-sample-game-server):** A backend API, built on the [Enjin Platform C# SDK](https://github.com/enjin/platform-csharp-sdk), that the game client communicates with to handle all NFT-related actions like minting and transferring. + - **:** The cloud-based service that provides the core NFT infrastructure. + - **Wallet Daemon:** A secure application that manages a wallet on behalf of the game to automatically sign and approve transactions. + +----- ### 💡 Important Considerations @@ -25,9 +38,104 @@ Before you begin, please keep the following in mind: ----- -## 🖥️ Game Server +## Prerequisites + +Before you begin, make sure you have the following. These are the requirements for the **shared server**; each engine page lists the extra tooling its client needs (Unity Hub, or the Godot editor). + + - ✅ The **[.NET 9 SDK](https://dotnet.microsoft.com/download/dotnet/9.0)** for running the game server. + - ✅ **Git** for cloning the repositories. + - ✅ An **Enjin Platform account**. If you don't have one, you can create it [here](https://platform.beta.enjin.io/). + - ✅ Some cENJ tokens (can be acquired from the [built-in Canary faucet](/01-getting-started/04-using-the-enjin-platform.md#canary-faucet) in the Platform UI). + +----- + +## Step 1: Download the Server & Wallet Daemon + +1. **Clone the Game Server:** Open a terminal and run: + + ```bash + git clone https://github.com/enjin/platform-sample-game-server.git + ``` + +2. **Download the Wallet Daemon:** Download the prebuilt daemon for your operating system from [https://enj.in/daemon](https://enj.in/daemon) and extract it into a dedicated directory. + +:::note +You'll clone your engine's **game client** (Unity or Godot) on its own setup page, after the server is running. +::: + +----- + +## Step 2: Configure Enjin Services + +Next, you'll set up your Enjin Platform account and the Wallet Daemon. + +### Enjin Platform + +1. Log in to your [Enjin Platform](https://platform.beta.enjin.io/) account. +2. Head over to your [account settings page](https://platform.beta.enjin.io/settings). +3. Navigate to the **Daemon Wallet** section and create a new API Token. +4. Copy the **API Token**; you will need this in the next step. + +### Wallet Daemon + +The Wallet Daemon is the signer that approves your game server's transactions. It runs from the command line and is configured with a `.env` file. + +1. In the daemon directory you extracted, copy the `.env.example` file to `.env`. +2. Open `.env` and set the two required values: + - `PLATFORM_KEY`: The **API Token** you just copied from the Enjin Platform. + - `KEY_PASS`: A unique, high-entropy password used to encrypt the wallet seed. Store it somewhere safe — you'll need it every time the daemon starts. +3. Start the daemon — `./wallet-daemon` (or `.\wallet-daemon.exe` on Windows). On first run it generates a new wallet, writes the encrypted seed to `wallet.seed`, and prints an SS58 address for each network. +4. From the printed addresses, **copy the Canary Matrixchain address** — that's the network this sample uses. You'll need it in the next step. + +:::tip +For a detailed guide — including Docker, AWS, importing an existing seed, and backup guidance — see the [Wallet Daemon documentation](/01-getting-started/06-using-wallet-daemon.md). +::: + +----- + +## Step 3: Configure and Run the Game Server + +Now, let's set up the backend server that powers the game's NFT features. + +:::warning Before you run: .NET SDK + internet +The server targets .NET 9, so install the **[.NET 9 SDK](https://dotnet.microsoft.com/download/dotnet/9.0)** — it provides both the build tools and the .NET 9 runtime the server runs on. After installing, open a **new** terminal and confirm with `dotnet --list-sdks` (you should see a `9.x` entry). + +If you only have a newer SDK such as .NET 10, the build will succeed but `dotnet run` fails with `You must install or update .NET … version '9.0.0'`, because the .NET 9 **runtime** is missing. Either install the .NET 9 SDK (simplest), or run on the newer runtime with `dotnet run --roll-forward Major`. + +The first `dotnet run` restores the server's dependencies — including the [Enjin Platform C# SDK](https://www.nuget.org/packages/Enjin.Platform.Sdk) — from NuGet, so you need internet access. If restore fails with `NU1100: Unable to resolve …`, your machine has no usable NuGet source. Run `dotnet nuget list source`: if it says `No sources found` (or `nuget.org` is `[Disabled]`), add it with: + +```bash +dotnet nuget add source https://api.nuget.org/v3/index.json -n nuget.org +``` +::: + +1. Navigate into the game server directory you cloned: `cd platform-sample-game-server`. +2. Copy the `appsettings.Sample.json` file and rename the copy to `appsettings.Local.json` (this file is gitignored, so your secrets stay out of version control). +3. Open `appsettings.Local.json` and fill in the following values: + - `Jwt.Secret`: A long, random string (32+ characters). This is used for authenticating players. + - `Enjin.ApiToken`: Paste the **API Token** from your Enjin Platform account. + - `Enjin.DaemonWalletAddress`: Paste the daemon's **Canary Matrixchain** address you copied in the previous step. + + The remaining settings have sensible defaults in `appsettings.json` (for example, `Server.Port` defaults to `3000`), so you can leave them as-is for testing. +4. Launch the server for the first time by running `dotnet run`. + +The server will now connect to the Enjin Platform, create a new NFT collection for your game (or reuse an existing one), and create the NFT tokens for the in-game resources. This can take a minute or two on first run while it waits for the on-chain transactions to finalize. + +:::info **Important** +The server stores the **Collection ID** it bootstraps in a `state.json` file and reuses it on every restart, so you no longer need to copy it by hand — you'll stamp it onto the game client automatically when you set up your engine's client. When you see `Now listening on: http://[::]:3000` (and `Application started`) in the logs, the server is ready. +::: + +:::note Windows firewall prompt +On Windows, the first time the server starts listening you may get a prompt to allow network access — click **Allow**. You don't need to restart the server afterwards; it keeps running and works right away. +::: + +Keep the server and the Wallet Daemon running in the background. + +----- + +## Server Implementation Breakdown -The game server is a .NET 9 minimal-API application that talks to the Enjin Platform through the [Enjin Platform C# SDK](https://github.com/enjin/platform-csharp-sdk). It serves as the secure bridge between the game client and the platform — it holds the Enjin Platform API token, which the Unity client never sees. The main entry point is the [`Program.cs` file](https://github.com/enjin/platform-sample-game-server/blob/64949d25394526ef478b81c06a5d1e36375e455e/Program.cs), where the host, dependency injection, JWT authentication, and on-chain bootstrap are wired up. +The game server is a .NET 9 minimal-API application that talks to the Enjin Platform through the [Enjin Platform C# SDK](https://github.com/enjin/platform-csharp-sdk). It serves as the secure bridge between the game client and the platform — it holds the Enjin Platform API token, which the game client never sees. The main entry point is the [`Program.cs` file](https://github.com/enjin/platform-sample-game-server/blob/64949d25394526ef478b81c06a5d1e36375e455e/Program.cs), where the host, dependency injection, JWT authentication, and on-chain bootstrap are wired up. ### Configuration @@ -39,9 +147,9 @@ The server is configured through `appsettings.json` (defaults) plus an `appsetti | `Enjin.ApiToken` | Your API token obtained from the Enjin Platform. | | `Enjin.DaemonWalletAddress` | The SS58 address of your . This wallet owns the collection, mints the resource tokens, and funds new player wallets. | | `Enjin.Network` / `Enjin.Chain` | The target network and chain. Defaults to `Canary` / `Matrix`. | -| `Server.Port` | The port the server listens on. Defaults to `3000` (the Unity client expects `3000`). | +| `Server.Port` | The port the server listens on. Defaults to `3000` (both the Unity and Godot clients default to `3000`). | | `Enjin.CollectionName` | Used to find or reuse an existing collection so a new one isn't created on every run. | -| `Enjin.ResourceTokens` | The resource tokens to create (Gold Coin, Gold Coin (Blue), Green Gem). The Unity client ships matching `EnjinItem` assets for token IDs `1`, `2`, and `3`. | +| `Enjin.ResourceTokens` | The resource tokens to create (Gold Coin, Gold Coin (Blue), Green Gem). Both the Unity and Godot clients ship matching item assets for token IDs `1`, `2`, and `3`. | | `Enjin.Ss58Prefix` | The prefix used to encode wallet public keys into addresses. `9030` = Canary Matrixchain, `1110` = Enjin Mainnet Matrixchain. | | `Enjin.DripEnjEnabled` / `Enjin.DripEnjAmount` | Whether to auto-fund each new managed wallet, and how much (default `1` ENJ). | @@ -149,53 +257,13 @@ The server exposes several endpoints to handle game actions. The `wallet` and `t #### Setup - * [`GET /api/setup/collection-id`](https://github.com/enjin/platform-sample-game-server/blob/64949d25394526ef478b81c06a5d1e36375e455e/Endpoints/SetupEndpoints.cs#L26): Returns the collection ID the server bootstrapped. This is called once by the Unity Editor's "Stamp Collection ID" menu (see [Setup Guide → Step 4](/02-guides/01-platform/05-enjin-farmer-sample-game/01-setup-guide.md#1-stamp-the-collection-id-onto-the-nft-items)) to write the ID onto the client's NFT item assets; the running game never calls it. + * [`GET /api/setup/collection-id`](https://github.com/enjin/platform-sample-game-server/blob/64949d25394526ef478b81c06a5d1e36375e455e/Endpoints/SetupEndpoints.cs#L26): Returns the collection ID the server bootstrapped. This is called once by the engine client's "Stamp Collection ID" tool to write the ID onto the client's NFT item assets; the running game never calls it. ----- -## 🎮 Unity Game - -The Unity game is the client-facing part of the project. It focuses on gameplay and user experience while offloading all sensitive blockchain operations to the game server. - -### Core Components - -The Enjin integration is managed by a few key scripts and a central prefab: - - * **`EnjinManager.prefab`**: The heart of the integration. This prefab is added to the `Farm_Outdoor` scene and configures the **Host URL** (e.g., `http://localhost:3000`) in the Inspector to connect to your game server. - * **[`EnjinManager.cs`](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/Core/EnjinManager.cs)**: A singleton controller that manages the player's session (auth token, wallet data) and exposes high-level methods like `MintToken()` for other game scripts to use. - * **[`EnjinApiService.cs`](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/API/EnjinApiService.cs)**: Handles all REST API communication with the game server using Unity's `UnityWebRequest`. - * **[`EnjinItem.cs`](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/Data/EnjinItem.cs)**: A `ScriptableObject` that represents the data of a blockchain item, such as its display name and its corresponding on-chain token ID. - * **[`StampCollectionIdMenu.cs`](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Editor/StampCollectionIdMenu.cs)**: An Editor utility that adds the **Enjin → Stamp Collection ID onto EnjinItem Assets** menu. It calls the server's `/api/setup/collection-id` endpoint and writes the returned ID onto every `EnjinItem` asset, so you don't have to paste it by hand. - * **UI Scripts** ([`BackpackUI.cs`](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/UI/BackpackUI.cs), [`BackpackItemController.cs`](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/UI/BackpackItemController.cs)): Scripts that manage the UI for viewing and interacting with the player's NFT inventory. - -### Initial Setup & Player Authentication - -1. **Health Check**: On launch, the client [calls the `/api/auth/health-check` endpoint](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/API/EnjinApiService.cs#L43) to ensure the server is available. -2. **Login/Register**: From the login screen, the player [clicks "Login"](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/HappyHarvest/Common/UI/SettingMenu/Script/SettingMenu.cs#L129), which calls the [`EnjinManager.Instance.RegisterAndLogin()` method](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/Core/EnjinManager.cs#L174). -3. **API Request**: This triggers `EnjinApiService` to [send a POST request to the `/api/auth/register` endpoint](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/API/EnjinApiService.cs#L72). -4. **Store Auth Token**: The server responds with a JWT authentication token. The client [saves this token locally using `PlayerPrefs`](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/Core/EnjinManager.cs#L208) and [loads it on subsequent launches](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/Core/EnjinManager.cs#L219) for a seamless experience. - -### In-Game NFT Interactions - -All blockchain actions are initiated by the client but securely executed by the server. - -#### Harvesting and Minting Tokens - -When a player [harvests a crop with the Hoe tool](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/HappyHarvest/Scripts/Items/Hoe.cs#L18), they have a chance to find a resource token. - -1. An `EnjinToken` GameObject [appears on the harvested tile](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/Core/EnjinManager.cs#L262). -2. When the player collects this GameObject, its [`InteractedWith()` method](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/Gameplay/EnjinToken.cs#L21) is triggered. -3. This calls [`EnjinItem.Collect()`](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/Data/EnjinItem.cs#L37), which in turn calls `EnjinManager.Instance.MintToken()`. -4. `EnjinManager` then uses `EnjinApiService` to [send a request to the `/api/token/mint` endpoint](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/API/EnjinApiService.cs#L97). - -#### Viewing the Wallet (Backpack UI) - -1. Clicking the backpack icon opens the inventory screen, managed by `BackpackUI.cs`. -2. The UI [calls `EnjinManager.Instance.GetManagedWalletTokens()`](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/UI/BackpackUI.cs#L117), which [sends a request to the `/api/wallet/get-tokens` endpoint](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/API/EnjinApiService.cs#L205). -3. The `BackpackUI` then [populates the view with the returned tokens](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/UI/BackpackUI.cs#L80). -4. The `BackpackUI` also [subscribes to the `EnjinManager.Instance.OnWalletUpdated` event](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/UI/BackpackUI.cs#L46) to automatically refresh the inventory after a token is [minted](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/Core/EnjinManager.cs#L116), [melted](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/Core/EnjinManager.cs#L132), or [transferred](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/Core/EnjinManager.cs#L148). +## Next: set up your client -#### Melting and Transferring Tokens +The server, Enjin Platform, and Wallet Daemon are now configured. Keep the **server** and the **Wallet Daemon** running, then continue to the page for your engine: - * **Melting**: The player [clicks "Melt" in the backpack](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/UI/BackpackItemController.cs#L53). This flows through [`EnjinManager.MeltToken()`](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/Core/EnjinManager.cs#L125) and sends a request to the [`/api/token/melt` endpoint](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/API/EnjinApiService.cs#L126). - * **Transferring**: The player [clicks "Send"](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/UI/BackpackItemController.cs#L75), which flows through [`EnjinManager.TransferToken()`](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/Core/EnjinManager.cs#L141) and sends a request to the [`/api/token/transfer` endpoint](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/API/EnjinApiService.cs#L155). + - 🟦 **[Set up the Unity client →](/02-guides/01-platform/05-enjin-farmer-sample-game/02-unity.md)** + - 🟧 **[Set up the Godot client →](/02-guides/01-platform/05-enjin-farmer-sample-game/03-godot.md)** diff --git a/docs/02-guides/01-platform/05-enjin-farmer-sample-game/01-setup-guide.md b/docs/02-guides/01-platform/05-enjin-farmer-sample-game/01-setup-guide.md deleted file mode 100644 index c3a1f7c..0000000 --- a/docs/02-guides/01-platform/05-enjin-farmer-sample-game/01-setup-guide.md +++ /dev/null @@ -1,200 +0,0 @@ ---- -title: "Enjin Farmer: Setup Guide" -sidebar_label: "Setup Guide" -slug: "setup-guide" -description: "Follow our step-by-step guide to set up a sample Unity game with full Enjin NFT integration. Learn how to configure a client, server, and wallet to mint, transfer, and manage blockchain assets in a hands-on project." ---- - -import GlossaryTerm from '@site/src/components/GlossaryTerm'; - -Welcome! This guide will walk you through setting up and running the Enjin Farm Game, a sample project demonstrating how to integrate Enjin's NFT technology into a Unity game. - -In this simple farming game, you'll plant seeds, harvest crops, and collect resources. Some resources are special and will be minted as NFTs directly to your in-game wallet. You can then view these NFTs in your inventory, them, or transfer them to an external wallet. - -### System Architecture - -The project consists of four main components that work together: - - - **[Game Client (Unity)](https://github.com/enjin/platform-sample-game-client-unity):** The game itself, where you play and interact with items. - - **[Game Server (.NET)](https://github.com/enjin/platform-sample-game-server):** A backend API, built on the [Enjin Platform C# SDK](https://github.com/enjin/platform-csharp-sdk), that the game client communicates with to handle all NFT-related actions like minting and transferring. - - **:** The cloud-based service that provides the core NFT infrastructure. - - **Wallet Daemon:** A secure application that manages a wallet on behalf of the game to automatically sign and approve transactions. - ------ - -## Prerequisites - -Before you begin, make sure you have the following installed: - - - ✅ **Unity Hub** with **Unity Editor version `6000.0.24f1`**. - - ✅ The **[.NET 9 SDK](https://dotnet.microsoft.com/download/dotnet/9.0)** for running the game server. - - ✅ **Git** for cloning the repositories. - - ✅ An **Enjin Platform account**. If you don't have one, you can create it [here](https://platform.beta.enjin.io/). - - ✅ Some cENJ tokens (can be acquired from the [built-in Canary faucet](/01-getting-started/04-using-the-enjin-platform.md#canary-faucet) in the Platform UI) - ------ - -## Step 1: Download Project Files - -First, you need to download the game client, the game server, and the Wallet Daemon. - -1. **Clone the Game Client:** Open a terminal or command prompt and run: - - ```bash - git clone https://github.com/enjin/platform-sample-game-client-unity.git - ``` - -2. **Clone the Game Server:** In the same terminal, run: - - ```bash - git clone https://github.com/enjin/platform-sample-game-server.git - ``` - -3. **Download the Wallet Daemon:** Download the prebuilt daemon for your operating system from [https://enj.in/daemon](https://enj.in/daemon) and extract it into a dedicated directory. - ------ - -## Step 2: Configure Enjin Services - -Next, you'll set up your Enjin Platform account and the Wallet Daemon. - -### Enjin Platform - -1. Log in to your [Enjin Platform](https://platform.beta.enjin.io/) account. -2. Head over to your [account settings page](https://platform.beta.enjin.io/settings). -3. Navigate to the **Daemon Wallet** section and create a new API Token. -4. Copy the **API Token**; you will need this in the next step. - -### Wallet Daemon - -The Wallet Daemon is the signer that approves your game server's transactions. It runs from the command line and is configured with a `.env` file. - -1. In the daemon directory you extracted, copy the `.env.example` file to `.env`. -2. Open `.env` and set the two required values: - - `PLATFORM_KEY`: The **API Token** you just copied from the Enjin Platform. - - `KEY_PASS`: A unique, high-entropy password used to encrypt the wallet seed. Store it somewhere safe — you'll need it every time the daemon starts. -3. Start the daemon — `./wallet-daemon` (or `.\wallet-daemon.exe` on Windows). On first run it generates a new wallet, writes the encrypted seed to `wallet.seed`, and prints an SS58 address for each network. -4. From the printed addresses, **copy the Canary Matrixchain address** — that's the network this sample uses. You'll need it in the next step. - -:::tip -For a detailed guide — including Docker, AWS, importing an existing seed, and backup guidance — see the [Wallet Daemon documentation](/01-getting-started/06-using-wallet-daemon.md). -::: - ------ - -## Step 3: Configure and Run the Game Server - -Now, let's set up the backend server that powers the game's NFT features. - -:::warning Before you run: .NET SDK + internet -The server targets .NET 9, so install the **[.NET 9 SDK](https://dotnet.microsoft.com/download/dotnet/9.0)** — it provides both the build tools and the .NET 9 runtime the server runs on. After installing, open a **new** terminal and confirm with `dotnet --list-sdks` (you should see a `9.x` entry). - -If you only have a newer SDK such as .NET 10, the build will succeed but `dotnet run` fails with `You must install or update .NET … version '9.0.0'`, because the .NET 9 **runtime** is missing. Either install the .NET 9 SDK (simplest), or run on the newer runtime with `dotnet run --roll-forward Major`. - -The first `dotnet run` restores the server's dependencies — including the [Enjin Platform C# SDK](https://www.nuget.org/packages/Enjin.Platform.Sdk) — from NuGet, so you need internet access. If restore fails with `NU1100: Unable to resolve …`, your machine has no usable NuGet source. Run `dotnet nuget list source`: if it says `No sources found` (or `nuget.org` is `[Disabled]`), add it with: - -```bash -dotnet nuget add source https://api.nuget.org/v3/index.json -n nuget.org -``` -::: - -1. Navigate into the game server directory you cloned: `cd platform-sample-game-server`. -2. Copy the `appsettings.Sample.json` file and rename the copy to `appsettings.Local.json` (this file is gitignored, so your secrets stay out of version control). -3. Open `appsettings.Local.json` and fill in the following values: - - `Jwt.Secret`: A long, random string (32+ characters). This is used for authenticating players. - - `Enjin.ApiToken`: Paste the **API Token** from your Enjin Platform account. - - `Enjin.DaemonWalletAddress`: Paste the daemon's **Canary Matrixchain** address you copied in the previous step. - - The remaining settings have sensible defaults in `appsettings.json` (for example, `Server.Port` defaults to `3000`), so you can leave them as-is for testing. -4. Launch the server for the first time by running `dotnet run`. - -The server will now connect to the Enjin Platform, create a new NFT collection for your game (or reuse an existing one), and create the NFT tokens for the in-game resources. This can take a minute or two on first run while it waits for the on-chain transactions to finalize. - -:::info **Important** -The server stores the **Collection ID** it bootstraps in a `state.json` file and reuses it on every restart, so you no longer need to copy it by hand — you'll stamp it onto the game client automatically in [Step 4](#1-stamp-the-collection-id-onto-the-nft-items). When you see `Now listening on: http://[::]:3000` (and `Application started`) in the logs, the server is ready. -::: - -:::note Windows firewall prompt -On Windows, the first time the server starts listening you may get a prompt to allow network access — click **Allow**. You don't need to restart the server afterwards; it keeps running and works right away. -::: - -Keep the server and the Wallet Daemon running in the background. - ------ - -## Step 4: Configure the Unity Game Client - -It's time to set up the Unity project and connect it to your game server. - -1. Open **Unity Hub**. -2. Click `Add` → `Add project from disk` and select the `platform-sample-game-client` folder you cloned earlier. -3. Open the project. -4. Once the project is open in the Unity Editor, you need to configure two things. - -#### 1. Stamp the Collection ID onto the NFT Items - -The game's three `Enjin Item` assets (`GemGreen`, `GoldCoin`, and `GoldCoinBlue`, found in `Assets/Enjin Integration/Scripts/Data/Items`) each need to know the on-chain **Collection ID** the server created. Rather than paste it by hand, the project ships an Editor menu that fetches it from your running server and stamps it onto all three assets for you. - - - Make sure your game server (from Step 3) is still running. - - In the Unity Editor menu bar, select **Enjin → Stamp Collection ID onto EnjinItem Assets**. - - Confirm the prompt. The Editor calls the server's `/api/setup/collection-id` endpoint and writes the returned ID onto every `EnjinItem` asset. - -:::note -Run this once after the server's first launch. You only need to run it again if the canary state ever resets and the server creates a new collection. -::: - -#### 2. Configure the connection to the Game Server - -:::note -If you are running the game server and client on the same machine, and you haven't changed the default port of 3000, you can skip this step. -::: - - - In the `Project` window, navigate to `Assets/Enjin Integration/Prefabs/`. - - Select the **EnjinManager** prefab. - - In the `Inspector` window, find the `Enjin API Service (Script)` component and configure the host property to your game server URL. If you are running the game server and client on the same machine, the default `http://localhost:3000` is correct. - -

- -

- ------ - -## Step 5: Play the Game! 🎮 - -You're all set up and ready to play. - -1. In the Unity Editor's `Project` window, navigate to `Assets/HappyHarvest/Scenes`. -2. Double click on the `Farm_Outdoor` scene. -3. Press the **Play** button at the top of the Unity Editor to launch the game. -4. Look at the **Console** window in the editor. You should see a log message: `Server connection successful (Health Check: OK)`. -

- -

- :::warning - If you see an error, double-check that your server is running and that the `Host` in the `EnjinManager` is correct. - ::: -5. In the game, click the **Menu** button (top-right), then **Login**. -

- -

-6. Enter an email and password and click **Login**. This will register a new user and create a managed wallet for your player on the Enjin Platform. -7. Close the menu and use the **W, A, S, D** keys to move your character. -8. Walk up to a crop and click on it to harvest it. Keep harvesting until a resource item pops out. -

- -

-9. Click on the resource item to collect it. This action tells the game server to mint that item as an NFT to your player's wallet. -10. From the inventory, you can click **Melt** to destroy the NFT or enter another wallet address in the **Transfer Recipient** field and click **Send** to send it to someone else. -

- -

-:::warning Keep your daemon wallet funded -New managed wallets start empty, so the server automatically drips a little cENJ (1 ENJ by default) from your **daemon wallet** to each new player wallet so it can pay the fees for melting and transferring. This means the daemon wallet itself needs cENJ — to create the collection, mint tokens, and fund new players. -To top up the daemon wallet for testing, use the [built-in Canary faucet](/01-getting-started/04-using-the-enjin-platform.md#canary-faucet) in the Platform UI. -::: - -:::info Understanding the code -To learn more about the implementation and dive deep into the game client and server code, continue to the [Enjin Farmer: Implementation Breakdown page](/02-guides/01-platform/05-enjin-farmer-sample-game/03-implementation-breakdown.md). -::: - -Happy farming! \ No newline at end of file diff --git a/docs/02-guides/01-platform/05-enjin-farmer-sample-game/02-unity.md b/docs/02-guides/01-platform/05-enjin-farmer-sample-game/02-unity.md new file mode 100644 index 0000000..a2cba15 --- /dev/null +++ b/docs/02-guides/01-platform/05-enjin-farmer-sample-game/02-unity.md @@ -0,0 +1,156 @@ +--- +title: "Enjin Farmer: Unity Client" +sidebar_label: "Unity Client" +slug: "unity" +description: "Set up and run the Unity client for the Enjin Farmer sample game, and dive into how the Unity client mints, melts, and transfers NFTs through the game server using the Enjin Platform." +--- + +import GlossaryTerm from '@site/src/components/GlossaryTerm'; + +This page covers the **Unity** client for the Enjin Farmer sample game. + +:::info Set up the server first +This page assumes the game server, Enjin Platform, and Wallet Daemon are already running. If not, complete the [Overview & Server Setup](/02-guides/01-platform/05-enjin-farmer-sample-game/01-overview.md) page first, then come back here. +::: + +----- + +## Prerequisites + +In addition to the [shared prerequisites](/02-guides/01-platform/05-enjin-farmer-sample-game/01-overview.md#prerequisites), the Unity client needs: + + - ✅ **Unity Hub** with **Unity Editor version `6000.0.24f1`**. + +----- + +## Step 1: Set Up the Unity Client + +It's time to set up the Unity project and connect it to your game server. + +1. **Clone the Game Client:** + + ```bash + git clone https://github.com/enjin/platform-sample-game-client-unity.git + ``` + +2. Open **Unity Hub**. +3. Click `Add` → `Add project from disk` and select the `platform-sample-game-client` folder you cloned earlier. +4. Open the project. +5. Once the project is open in the Unity Editor, you need to configure two things. + +#### 1. Stamp the Collection ID onto the NFT Items + +The game's three `Enjin Item` assets (`GemGreen`, `GoldCoin`, and `GoldCoinBlue`, found in `Assets/Enjin Integration/Scripts/Data/Items`) each need to know the on-chain **Collection ID** the server created. Rather than paste it by hand, the project ships an Editor menu that fetches it from your running server and stamps it onto all three assets for you. + + - Make sure your game server is still running. + - In the Unity Editor menu bar, select **Enjin → Stamp Collection ID onto EnjinItem Assets**. + - Confirm the prompt. The Editor calls the server's `/api/setup/collection-id` endpoint and writes the returned ID onto every `EnjinItem` asset. + +:::note +Run this once after the server's first launch. You only need to run it again if the canary state ever resets and the server creates a new collection. +::: + +#### 2. Configure the connection to the Game Server + +:::note +If you are running the game server and client on the same machine, and you haven't changed the default port of 3000, you can skip this step. +::: + + - In the `Project` window, navigate to `Assets/Enjin Integration/Prefabs/`. + - Select the **EnjinManager** prefab. + - In the `Inspector` window, find the `Enjin API Service (Script)` component and configure the host property to your game server URL. If you are running the game server and client on the same machine, the default `http://localhost:3000` is correct. + +

+ +

+ +----- + +## Step 2: Play the Game! 🎮 + +You're all set up and ready to play. + +1. In the Unity Editor's `Project` window, navigate to `Assets/HappyHarvest/Scenes`. +2. Double click on the `Farm_Outdoor` scene. +3. Press the **Play** button at the top of the Unity Editor to launch the game. +4. Look at the **Console** window in the editor. You should see a log message: `Server connection successful (Health Check: OK)`. +

+ +

+ :::warning + If you see an error, double-check that your server is running and that the `Host` in the `EnjinManager` is correct. + ::: +5. In the game, click the **Menu** button (top-right), then **Login**. +

+ +

+6. Enter an email and password and click **Login**. This will register a new user and create a managed wallet for your player on the Enjin Platform. +7. Close the menu and use the **W, A, S, D** keys to move your character. +8. Walk up to a crop and click on it to harvest it. Keep harvesting until a resource item pops out. +

+ +

+9. Click on the resource item to collect it. This action tells the game server to mint that item as an NFT to your player's wallet. +10. From the inventory, you can click **Melt** to destroy the NFT or enter another wallet address in the **Transfer Recipient** field and click **Send** to send it to someone else. +

+ +

+:::warning Keep your daemon wallet funded +New managed wallets start empty, so the server automatically drips a little cENJ (1 ENJ by default) from your **daemon wallet** to each new player wallet so it can pay the fees for melting and transferring. This means the daemon wallet itself needs cENJ — to create the collection, mint tokens, and fund new players. +To top up the daemon wallet for testing, use the [built-in Canary faucet](/01-getting-started/04-using-the-enjin-platform.md#canary-faucet) in the Platform UI. +::: + +:::info Understanding the code +To learn how the Unity client and game server work under the hood, see the [Implementation Breakdown](#implementation-breakdown) below (server-side details live on the [Overview](/02-guides/01-platform/05-enjin-farmer-sample-game/01-overview.md#server-implementation-breakdown) page). +::: + +Happy farming! + +----- + +## Implementation Breakdown + +The Unity client handles gameplay and offloads all blockchain operations to the game server. The server side — collection bootstrap, managed wallets, and the API endpoints the client calls — is documented on the [Overview](/02-guides/01-platform/05-enjin-farmer-sample-game/01-overview.md#server-implementation-breakdown) page. + +### Core Components + +The Enjin integration is managed by a few key scripts and a central prefab: + + * **`EnjinManager.prefab`**: The heart of the integration. This prefab is added to the `Farm_Outdoor` scene and configures the **Host URL** (e.g., `http://localhost:3000`) in the Inspector to connect to your game server. + * **[`EnjinManager.cs`](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/Core/EnjinManager.cs)**: A singleton controller that manages the player's session (auth token, wallet data) and exposes high-level methods like `MintToken()` for other game scripts to use. + * **[`EnjinApiService.cs`](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/API/EnjinApiService.cs)**: Handles all REST API communication with the game server using Unity's `UnityWebRequest`. + * **[`EnjinItem.cs`](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/Data/EnjinItem.cs)**: A `ScriptableObject` that represents the data of a blockchain item, such as its display name and its corresponding on-chain token ID. + * **[`StampCollectionIdMenu.cs`](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Editor/StampCollectionIdMenu.cs)**: An Editor utility that adds the **Enjin → Stamp Collection ID onto EnjinItem Assets** menu. It calls the server's `/api/setup/collection-id` endpoint and writes the returned ID onto every `EnjinItem` asset, so you don't have to paste it by hand. + * **UI Scripts** ([`BackpackUI.cs`](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/UI/BackpackUI.cs), [`BackpackItemController.cs`](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/UI/BackpackItemController.cs)): Scripts that manage the UI for viewing and interacting with the player's NFT inventory. + +### Initial Setup & Player Authentication + +1. **Health Check**: On launch, the client [calls the `/api/auth/health-check` endpoint](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/API/EnjinApiService.cs#L43) to ensure the server is available. +2. **Login/Register**: From the login screen, the player [clicks "Login"](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/HappyHarvest/Common/UI/SettingMenu/Script/SettingMenu.cs#L129), which calls the [`EnjinManager.Instance.RegisterAndLogin()` method](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/Core/EnjinManager.cs#L174). +3. **API Request**: This triggers `EnjinApiService` to [send a POST request to the `/api/auth/register` endpoint](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/API/EnjinApiService.cs#L72). +4. **Store Auth Token**: The server responds with a JWT authentication token. The client [saves this token locally using `PlayerPrefs`](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/Core/EnjinManager.cs#L208) and [loads it on subsequent launches](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/Core/EnjinManager.cs#L219) for a seamless experience. + +### In-Game NFT Interactions + +All blockchain actions are initiated by the client but securely executed by the server. + +#### Harvesting and Minting Tokens + +When a player [harvests a crop with the Hoe tool](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/HappyHarvest/Scripts/Items/Hoe.cs#L18), they have a chance to find a resource token. + +1. An `EnjinToken` GameObject [appears on the harvested tile](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/Core/EnjinManager.cs#L262). +2. When the player collects this GameObject, its [`InteractedWith()` method](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/Gameplay/EnjinToken.cs#L21) is triggered. +3. This calls [`EnjinItem.Collect()`](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/Data/EnjinItem.cs#L37), which in turn calls `EnjinManager.Instance.MintToken()`. +4. `EnjinManager` then uses `EnjinApiService` to [send a request to the `/api/token/mint` endpoint](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/API/EnjinApiService.cs#L97). + +#### Viewing the Wallet (Backpack UI) + +1. Clicking the backpack icon opens the inventory screen, managed by `BackpackUI.cs`. +2. The UI [calls `EnjinManager.Instance.GetManagedWalletTokens()`](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/UI/BackpackUI.cs#L117), which [sends a request to the `/api/wallet/get-tokens` endpoint](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/API/EnjinApiService.cs#L205). +3. The `BackpackUI` then [populates the view with the returned tokens](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/UI/BackpackUI.cs#L80). +4. The `BackpackUI` also [subscribes to the `EnjinManager.Instance.OnWalletUpdated` event](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/UI/BackpackUI.cs#L46) to automatically refresh the inventory after a token is [minted](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/Core/EnjinManager.cs#L116), [melted](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/Core/EnjinManager.cs#L132), or [transferred](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/Core/EnjinManager.cs#L148). + +#### Melting and Transferring Tokens + + * **Melting**: The player [clicks "Melt" in the backpack](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/UI/BackpackItemController.cs#L53). This flows through [`EnjinManager.MeltToken()`](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/Core/EnjinManager.cs#L125) and sends a request to the [`/api/token/melt` endpoint](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/API/EnjinApiService.cs#L126). + * **Transferring**: The player [clicks "Send"](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/UI/BackpackItemController.cs#L75), which flows through [`EnjinManager.TransferToken()`](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/Core/EnjinManager.cs#L141) and sends a request to the [`/api/token/transfer` endpoint](https://github.com/enjin/platform-sample-game-client-unity/blob/9101b08a7f7ea2a4685c315cfb55864a6be43a25/Assets/Enjin%20Integration/Scripts/API/EnjinApiService.cs#L155). diff --git a/docs/02-guides/01-platform/05-enjin-farmer-sample-game/03-godot.md b/docs/02-guides/01-platform/05-enjin-farmer-sample-game/03-godot.md new file mode 100644 index 0000000..c2429b9 --- /dev/null +++ b/docs/02-guides/01-platform/05-enjin-farmer-sample-game/03-godot.md @@ -0,0 +1,135 @@ +--- +title: "Enjin Farmer: Godot Client" +sidebar_label: "Godot Client" +slug: "godot" +description: "Set up and run the Godot client for the Enjin Farmer sample game, and dive into how the Godot client mints, melts, and transfers NFTs through the game server using the Enjin Platform." +--- + +import GlossaryTerm from '@site/src/components/GlossaryTerm'; + +This page covers the **Godot** client for the Enjin Farmer sample game. + +:::info Set up the server first +This page assumes the game server, Enjin Platform, and Wallet Daemon are already running. If not, complete the [Overview & Server Setup](/02-guides/01-platform/05-enjin-farmer-sample-game/01-overview.md) page first, then come back here. +::: + +----- + +## Prerequisites + +In addition to the [shared prerequisites](/02-guides/01-platform/05-enjin-farmer-sample-game/01-overview.md#prerequisites), the Godot client needs: + + - ✅ **[Godot 4.4+](https://godotengine.org/download)** (the standard build — the client needs no .NET; only the server does). + +----- + +## Step 1: Set Up the Godot Client + +1. **Clone the Game Client:** + + ```bash + git clone https://github.com/enjin/platform-sample-game-client-godot.git + ``` + +2. **Open the project in Godot.** Launch Godot 4.4+ and import the cloned `platform-sample-game-client-godot` folder, or from a terminal run: + + ```bash + godot4 --editor . + ``` + +#### 1. Stamp the Collection ID onto the NFT Items + +The game's three `EnjinItem` resources (`gem_green.tres`, `gold_coin.tres`, and `gold_coin_blue.tres` in `resources/items/`) each need the on-chain **Collection ID** the server created. The project ships an Editor tool that fetches it from your running server and stamps it onto all three resources for you. + + - Make sure your game server is still running. + - In the Godot Editor, select **Project → Tools → Stamp Collection ID onto EnjinItem Assets**. + - Confirm the server URL when prompted (defaults to `http://localhost:3000`). The tool calls the server's `/api/setup/collection-id` endpoint and writes the returned ID onto every `EnjinItem` resource. + +:::note +Run this once after the server's first launch. You only need to run it again if the canary state ever resets and the server creates a new collection. You can also edit the `.tres` files in `resources/items/` by hand if you prefer. +::: + +#### 2. Configure the connection to the Game Server + +:::note +If you are running the game server and client on the same machine with the default port `3000`, you can skip this step. +::: + +The client's server URL is defined by the `host` variable in [`scripts/enjin/api/enjin_api_service.gd`](https://github.com/enjin/platform-sample-game-client-godot/blob/52b336743cf3d5dd8f34399206bf457b6e214450/scripts/enjin/api/enjin_api_service.gd#L25), which defaults to `http://localhost:3000`. If your server runs elsewhere, update that value. + +----- + +## Step 2: Play the Game! 🎮 + +You're all set up and ready to play. + +1. With the project open in the Godot Editor, press **F5** (Run Project). On startup the client runs a health check against the server. Watch the editor's **Output** panel — you should see `[EnjinApiService] Health check OK against http://localhost:3000`. If it fails, double-check that your server is running and that the `host` value matches your server URL. +

+ +

+2. On the **Happy Harvest** main menu, enter an **Email** and **Password**, then click **Register / Login**. This registers a new player (or logs in an existing one) and creates a managed wallet for them on the Enjin Platform. +

+ +

+3. Once the managed wallet is ready, the menu shows **"Logged in - tokens enabled."** Click **Start** to enter the farm. +

+ +

+4. Move your character and **till the soil**. Tilling has a chance to reveal a resource item. +

+ +

+5. Collect the revealed item. This tells the game server to **mint** that item as an NFT to your player's wallet. +6. Press **B** to open the **backpack**. It displays your live on-chain wallet balances, keyed to your managed wallet address. From here you can **Melt** an NFT to destroy it, or enter a recipient address and **Transfer** it. +

+ +

+ +:::warning Keep your daemon wallet funded +New managed wallets start empty, so the server automatically drips a little cENJ (1 ENJ by default) from your **daemon wallet** to each new player wallet so it can pay the fees for melting and transferring. This means the daemon wallet itself needs cENJ — to create the collection, mint tokens, and fund new players. To top up the daemon wallet for testing, use the [built-in Canary faucet](/01-getting-started/04-using-the-enjin-platform.md#canary-faucet) in the Platform UI. +::: + +:::info Understanding the code +To learn how the Godot client and game server work under the hood, see the [Implementation Breakdown](#implementation-breakdown) below (server-side details live on the [Overview](/02-guides/01-platform/05-enjin-farmer-sample-game/01-overview.md#server-implementation-breakdown) page). +::: + +Happy farming! + +----- + +## Implementation Breakdown + +The Godot client handles gameplay and offloads all blockchain operations to the game server. The server side — collection bootstrap, managed wallets, and the API endpoints the client calls — is documented on the [Overview](/02-guides/01-platform/05-enjin-farmer-sample-game/01-overview.md#server-implementation-breakdown) page. + +### Core Components + +The Enjin integration lives under `scripts/enjin/` plus an editor addon: + + * **[`enjin_manager.gd`](https://github.com/enjin/platform-sample-game-client-godot/blob/52b336743cf3d5dd8f34399206bf457b6e214450/scripts/enjin/core/enjin_manager.gd)**: An autoload singleton that manages the player's session (auth token, wallet snapshot) and exposes high-level methods like `mint_token()`, `melt_token()`, and `transfer_token()` for the rest of the game. It emits `login_complete`, `logout_complete`, and `wallet_updated` signals, and persists the auth token to `user://enjin.cfg`. + * **[`enjin_api_service.gd`](https://github.com/enjin/platform-sample-game-client-godot/blob/52b336743cf3d5dd8f34399206bf457b6e214450/scripts/enjin/api/enjin_api_service.gd)**: Handles all REST communication with the game server using Godot's `HTTPRequest`. The server URL is the [`host` variable](https://github.com/enjin/platform-sample-game-client-godot/blob/52b336743cf3d5dd8f34399206bf457b6e214450/scripts/enjin/api/enjin_api_service.gd#L25) (defaults to `http://localhost:3000`). + * **[`enjin_item.gd`](https://github.com/enjin/platform-sample-game-client-godot/blob/52b336743cf3d5dd8f34399206bf457b6e214450/scripts/enjin/data/enjin_item.gd)**: A `Resource` describing a blockchain item — its display data and its on-chain collection/token ID. The three concrete items live in `resources/items/*.tres`. ([`platform_models.gd`](https://github.com/enjin/platform-sample-game-client-godot/blob/52b336743cf3d5dd8f34399206bf457b6e214450/scripts/enjin/data/platform_models.gd) holds the wallet/token response models.) + * **[`plugin.gd`](https://github.com/enjin/platform-sample-game-client-godot/blob/52b336743cf3d5dd8f34399206bf457b6e214450/addons/enjin_editor/plugin.gd)** (`addons/enjin_editor`): An Editor tool that adds the **Project → Tools → Stamp Collection ID onto EnjinItem Assets** menu. It calls the server's `/api/setup/collection-id` endpoint and writes the returned ID onto every `EnjinItem` resource, so you don't paste it by hand. + * **UI scripts** ([`backpack_ui.gd`](https://github.com/enjin/platform-sample-game-client-godot/blob/52b336743cf3d5dd8f34399206bf457b6e214450/scripts/enjin/ui/backpack_ui.gd), [`backpack_item_row.gd`](https://github.com/enjin/platform-sample-game-client-godot/blob/52b336743cf3d5dd8f34399206bf457b6e214450/scripts/enjin/ui/backpack_item_row.gd)): Drive the backpack screen (`scenes/ui/backpack_ui.tscn`) for viewing and acting on the player's NFT inventory. + * **[`enjin_token.gd`](https://github.com/enjin/platform-sample-game-client-godot/blob/52b336743cf3d5dd8f34399206bf457b6e214450/scripts/enjin/gameplay/enjin_token.gd)**: The world pickup (`scenes/enjin/enjin_token.tscn`) that, when collected, triggers a mint. + +### Initial Setup & Player Authentication + +1. **Health Check**: On startup, `enjin_api_service.gd` [calls `/api/auth/health-check`](https://github.com/enjin/platform-sample-game-client-godot/blob/52b336743cf3d5dd8f34399206bf457b6e214450/scripts/enjin/api/enjin_api_service.gd#L41) to confirm the server is reachable. +2. **Login/Register**: From the main menu the player registers or logs in, which calls [`EnjinManager.register_and_login()`](https://github.com/enjin/platform-sample-game-client-godot/blob/52b336743cf3d5dd8f34399206bf457b6e214450/scripts/enjin/core/enjin_manager.gd#L74). That posts to the [`/api/auth/register`](https://github.com/enjin/platform-sample-game-client-godot/blob/52b336743cf3d5dd8f34399206bf457b6e214450/scripts/enjin/api/enjin_api_service.gd#L57) endpoint (used for both register and login). +3. **Store Auth Token**: The server returns a JWT; the client persists it to `user://enjin.cfg` and reloads it on subsequent launches. + +### In-Game NFT Interactions + +All blockchain actions are initiated by the client and executed by the server. + +#### Tilling and Minting Tokens + +When the player tills soil, [`EnjinManager.randomly_reveal_token()`](https://github.com/enjin/platform-sample-game-client-godot/blob/52b336743cf3d5dd8f34399206bf457b6e214450/scripts/enjin/core/enjin_manager.gd#L183) may spawn an `enjin_token` pickup. Collecting it calls [`EnjinManager.mint_token()`](https://github.com/enjin/platform-sample-game-client-godot/blob/52b336743cf3d5dd8f34399206bf457b6e214450/scripts/enjin/core/enjin_manager.gd#L143), which posts to the server's `/api/token/mint` endpoint. The daemon signs it. + +#### Viewing the Wallet (Backpack UI) + +Opening the backpack (**B**) calls [`EnjinManager.get_managed_wallet_tokens()`](https://github.com/enjin/platform-sample-game-client-godot/blob/52b336743cf3d5dd8f34399206bf457b6e214450/scripts/enjin/core/enjin_manager.gd#L106), which hits [`/api/wallet/get-tokens`](https://github.com/enjin/platform-sample-game-client-godot/blob/52b336743cf3d5dd8f34399206bf457b6e214450/scripts/enjin/api/enjin_api_service.gd#L91) and refreshes the displayed balances. `backpack_ui.gd` listens for the manager's `wallet_updated` signal to refresh after a mint, melt, or transfer. + +#### Melting and Transferring Tokens + +From a backpack row (`backpack_item_row.gd`), **Melt** flows through [`EnjinManager.melt_token()`](https://github.com/enjin/platform-sample-game-client-godot/blob/52b336743cf3d5dd8f34399206bf457b6e214450/scripts/enjin/core/enjin_manager.gd#L151) to `/api/token/melt`, and **Transfer** flows through [`EnjinManager.transfer_token()`](https://github.com/enjin/platform-sample-game-client-godot/blob/52b336743cf3d5dd8f34399206bf457b6e214450/scripts/enjin/core/enjin_manager.gd#L159) to `/api/token/transfer`. Both are signed by the player's managed wallet on the server side. diff --git a/static/img/guides/enjin-farmer-sample-game/godot/godot-backpack.png b/static/img/guides/enjin-farmer-sample-game/godot/godot-backpack.png new file mode 100644 index 0000000..1f95473 Binary files /dev/null and b/static/img/guides/enjin-farmer-sample-game/godot/godot-backpack.png differ diff --git a/static/img/guides/enjin-farmer-sample-game/godot/godot-health-check.png b/static/img/guides/enjin-farmer-sample-game/godot/godot-health-check.png new file mode 100644 index 0000000..df4dd40 Binary files /dev/null and b/static/img/guides/enjin-farmer-sample-game/godot/godot-health-check.png differ diff --git a/static/img/guides/enjin-farmer-sample-game/godot/godot-logged-in.png b/static/img/guides/enjin-farmer-sample-game/godot/godot-logged-in.png new file mode 100644 index 0000000..1905726 Binary files /dev/null and b/static/img/guides/enjin-farmer-sample-game/godot/godot-logged-in.png differ diff --git a/static/img/guides/enjin-farmer-sample-game/godot/godot-main-menu.png b/static/img/guides/enjin-farmer-sample-game/godot/godot-main-menu.png new file mode 100644 index 0000000..47772d8 Binary files /dev/null and b/static/img/guides/enjin-farmer-sample-game/godot/godot-main-menu.png differ