Skip to main content

Users Guide

For Developers

This user guide is intended to help developers test their gaming implementations. Chia Network Inc will not host a version of this for users to play. Before following this guide, developers must install and set up the gaming system. See the Developers Guide for installation and setup instructions.

Session Persistence

Game sessions are not saved. If you refresh your browser or clear browser storage (localStorage, cache, etc.), your game session will be lost and you will need to create a new session. This can result in lost funds if a session is interrupted during gameplay. Do not refresh your browser or clear browser data while a game is in progress.

Funds Left On-Chain

When using a live WalletConnect instance, funds will be left on-chain after shutdown. Upon shutdown, a new game is created, leading to one game's worth of funds being left on-chain and not returned to users. For example, if the game stake is 10 mojo, then 10 mojos will remain on-chain after shutting down the session (once per lobby not per game). Use the simulator for development to avoid this issue. This is a high priority issue which we are working to fix ASAP.

Intro​

This guide walks through testing a Chia Gaming implementation with two players (Alice and Bob). The system uses coinset.org for blockchain data and WalletConnect for wallet transactions. Both services are required for gameplay.

Handshaking Timing

Each transaction block takes approximately 1 minute. The handshake requires 2 on-chain transactions to be observed, so expect several minutes of waiting time. The handshake status will be displayed on-screen, and completion results in the screen changing to the game screen.

Player 1: Alice​

  1. Visit the game server: Navigate to the game server URL.

    [Image placeholder: walletConnect Screen - calpoker-lobby.png]

    Screenshot from alpha - UI may change

  2. Connect with WalletConnect: Use WalletConnect to connect your Chia wallet to the game. For live WalletConnect testing, do not select "Simulator".

    Funds Left On-Chain

    When using a live WalletConnect instance, funds will be left on-chain after shutdown. Upon shutdown, a new game is created, leading to one game's worth of funds being left on-chain and not returned to users. For example, if the game stake is 10 mojo, then 10 mojos will remain on-chain after shutting down the session (once per lobby not per game). Use the simulator for development to avoid this issue.

  3. Check Your Light Wallet: You should see a "getWalletBalance" request in your Chia Light Wallet. Choose "remember this decision" and confirm the request.

  4. Start a New Room: Create a new game room and copy the invitation URL.

    [Image placeholder: Lobby Screen - calpoker-lobby.png]

    Screenshot from alpha - UI may change

  5. Send the Invitation URL to Bob: Share the room invitation URL with the second player (Bob).

Player 2: Bob​

  1. Paste URL: Paste the invitation URL into a browser that does not share session state with Alice (e.g., another computer, or an incognito/private window).

  2. Wait for Handshake: Wait until the handshake is complete. The handshake status will be displayed on-screen.

    [Image placeholder: Handshake in Progress - calpoker-handshake.png]

    Screenshot from alpha - UI may change

    Once complete, the screen will automatically change to the game lobby screen.

Handshaking Time

Handshaking on-chain takes a long time. Before the game starts, 3 nodes (player wallet nodes and coinset.org) have to observe 2 on-chain transactions (in order). Each blockchain peak takes approximately 1 minute, so expect several minutes of waiting time. The lobby may take a several minutes to appear for Bob.

Pending WalletConnect Requests

If the handshake seems to hang, check your Chia wallet for any pending WalletConnect requests. The wallet may have a request waiting for approval that needs to be confirmed before the handshake can proceed.

Gameplay​

Once both players are connected and the handshake is complete, you can begin playing. The current release includes California Poker, with Space Poker and Krunk coming in future releases.

Game Completion​

[Image placeholder: Game Completion - calpoker-completion.png]

Screenshot from alpha - UI may change

After a game completes, you'll see the results screen with options to start a new hand or end the session.

Troubleshooting​

For troubleshooting assistance, see the Troubleshooting Guide which includes both developer and user-facing troubleshooting information.

Known Issues​

For a complete list of known issues, see the Known Issues document.