Skip to content

Commit 77745ea

Browse files
BrandtH22BrandtH22
authored
Merge pull request #890 from Chia-Network/include-gaming-info
Include gaming info
2 parents 5aace49 + c1edac8 commit 77745ea

File tree

9 files changed

+1098
-0
lines changed

9 files changed

+1098
-0
lines changed

‎docs/guides/chia-gaming/gaming-california-poker-rules.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
slug: /guides/gaming-california-poker-rules
3+
title: California Poker Rules
4+
---
5+
6+
## Objective
7+
8+
California Poker is a card game where players exchange cards and compete to make the best five-card poker hand. Each player receives 8 cards with all 16 cards visible to both players, selects 4 to swap with the other player, and keeps the other 4. The player who can make the best five-card poker hand from their 8 cards after swapping wins.
9+
10+
## Setup
11+
12+
- Each player receives 8 cards, all shown face up
13+
- Cards are displayed sorted in rank order
14+
15+
## Gameplay
16+
17+
### Card Selection Phase
18+
19+
1. Both players view their 8 cards simultaneously and can see their opponents cards
20+
2. Each player selects 4 cards to keep
21+
3. The 4 cards not selected are automatically swapped with the opponent
22+
4. Players wait for their opponent to complete their selection
23+
24+
### Hand Evaluation
25+
26+
After cards swap:
27+
28+
- Each player now has 8 cards (4 they kept + 4 received from opponent)
29+
- Each player constructs the best possible five-card poker hand from their 8 cards
30+
- Standard poker hand rankings apply (see Hand Rankings below)
31+
32+
### Determining the Winner
33+
34+
The player with the highest-ranking five-card poker hand wins the hand.
35+
36+
## Hand Rankings
37+
38+
From highest to lowest:
39+
40+
1. **Royal Flush**: A, K, Q, J, 10, all of the same suit
41+
2. **Straight Flush**: Five consecutive cards of the same suit
42+
3. **Four of a Kind**: Four cards of the same rank
43+
4. **Full House**: Three cards of the same rank plus two other cards of the same rank
44+
5. **Flush**: Five cards of the same suit (not in sequence)
45+
6. **Straight**: Five consecutive cards of different suits
46+
7. **Three of a Kind**: Three cards of the same rank
47+
8. **Two Pair**: Two different pairs of same rank cards
48+
9. **One Pair**: Two cards of the same rank
49+
10. **High Card**: When no other hand is made, the highest card wins
50+
51+
## Game Flow
52+
53+
1. **Cards Shown**: Both players view their 8 cards
54+
2. **Card Selection**: Each player picks 4 cards to swap
55+
3. **Wait for Opponent**: Wait for opponent to complete selection (may be skipped if opponent finishes first)
56+
4. **Results Shown**: Winner is determined and results displayed
57+
5. **Next Hand or End**: Options to start a new hand or end the session
58+
6. **End Session**: Session may end due to:
59+
- Playing on-chain
60+
- Insufficient balance (yours or opponent's)
61+
- You or opponent declined to continue

‎docs/guides/chia-gaming/gaming-developers-guide.md‎

Lines changed: 315 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,315 @@
1+
---
2+
slug: /guides/gaming-developers-guide
3+
title: Developers Guide
4+
---
5+
6+
:::warning Alpha Release
7+
8+
This is an **alpha release** of the Chia Gaming system. The codebase is subject to change, and breaking changes may occur in future versions. Use this system for development and testing purposes.
9+
10+
:::
11+
12+
:::danger Funds Left On-Chain
13+
14+
**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.**
15+
16+
:::
17+
18+
:::note Easy Developer Config Coming Soon
19+
20+
The easy developer configuration is still in development. Currently, parameters need to be manually coded. See the [Manual Configuration](#manual-configuration) section below for details.
21+
22+
:::
23+
24+
## Intro
25+
26+
This guide covers the development, testing, and deployment process for the Chia Gaming system. The system consists of two Docker images: the lobby server and the game code server.
27+
28+
To follow this guide, you will need:
29+
30+
- Linux operating system
31+
- Docker (latest version recommended)
32+
- Chia 2.5.7 (for WalletConnect testing)
33+
- Access to the [chia-gaming repository](https://github.com/Chia-Network/chia-gaming)
34+
35+
For game rules and mechanics, see:
36+
37+
- [California Poker Rules](/guides/gaming-california-poker-rules)
38+
- [Space Poker Rules](/guides/gaming-space-poker-rules) (coming soon)
39+
- [Krunk Rules](/guides/gaming-krunk-rules) (coming soon)
40+
41+
For information about becoming a gaming partner, see the [Gaming Partner RFP](/guides/gaming-partner-rfp).
42+
43+
## Dependencies and Setup
44+
45+
### Developer Dependencies
46+
47+
- **Operating System**: Linux
48+
- **Containerization**: Docker (latest version recommended)
49+
- **Chia Wallet**: Chia 2.5.7 (only needed for live WalletConnect testing/playthroughs, not required for simulator testing)
50+
- **Codebase**: Access to the [chia-gaming repository](https://github.com/Chia-Network/chia-gaming) or the [Docker images](https://github.com/Chia-Network/chia-gaming/releases)
51+
- **Testing (Optional)**: Firefox or Chrome, and their respective Selenium drivers for running automated tests
52+
53+
### User Dependencies
54+
55+
- **Chia Wallet**: Chia 2.5.7 (light wallet, full node not required)
56+
- **Blockchain Data**: The backend connects to coinset.org for blockchain data. Users' wallets perform transaction spends via WalletConnect. Both services are required for gameplay.
57+
58+
:::tip Common Issues
59+
60+
For common setup issues and solutions (Docker version, permissions, etc.), see the [Known Issues](/guides/gaming-known-issues) document.
61+
62+
:::
63+
64+
## Development Workflow
65+
66+
### Setup and Build
67+
68+
1. **Get the Codebase**: Choose one of the following options:
69+
70+
**Option A: Clone the Repository**:
71+
72+
```bash
73+
git clone https://github.com/Chia-Network/chia-gaming.git
74+
cd chia-gaming
75+
```
76+
77+
**Option B: Use Docker Images from Releases**:
78+
Download the Docker images from the [chia-gaming releases page](https://github.com/Chia-Network/chia-gaming/releases).
79+
80+
2. **Install Dependencies**: Ensure all developer dependencies (Linux, Docker, Chia 2.5.7) are installed and configured.
81+
82+
3. **Manual Configuration (Optional)**: If you need to customize network settings, WalletConnect project info, ports, or domain, see the [Manual Configuration](#manual-configuration) section below.
83+
84+
4. **Build Docker Images**:
85+
86+
```bash
87+
./build-docker-images.sh
88+
```
89+
90+
This command automatically configures both Docker images, compiles any new code within those images, and then launches both the lobby server and game code server.
91+
92+
:::note Port Configuration
93+
94+
Ports are manually coded in the `build-docker-images.sh` and `run-docker-demo.sh` scripts. The default ports are:
95+
- **Port 3000**: Frontend web interface (game UI)
96+
- **Port 3001**: Lobby server API
97+
- **Port 5800**: Simulator service
98+
99+
To change ports, edit these scripts directly.
100+
101+
:::
102+
103+
5. **Run Docker Images** (if not automatically started):
104+
105+
```bash
106+
./run-docker-demo.sh
107+
```
108+
109+
Note: The build command automatically runs this once complete.
110+
111+
### Making Code Changes
112+
113+
:::note Repository Required
114+
115+
To make code changes, you must have cloned the repository (Option A from the Setup and Build section). Code changes cannot be made when using Docker images from releases (Option B).
116+
117+
:::
118+
119+
1. **Edit Source Code**: Make your changes to the codebase.
120+
121+
2. **Rebuild Docker Images**: After making changes, rebuild the Docker images:
122+
123+
```bash
124+
./build-docker-images.sh
125+
```
126+
127+
This will recompile your changes and restart the services.
128+
129+
3. **Test Changes**: Use the simulator (recommended) or live WalletConnect to test your modifications.
130+
131+
### Testing
132+
133+
:::note Simulator Recommended
134+
135+
For development, it is recommended to use the simulator for testing game logic without interacting with a real WalletConnect instance.
136+
137+
:::
138+
139+
**Using Simulator (Recommended for Development):**
140+
141+
1. Navigate to the game server URL (typically `http://localhost:3000`)
142+
2. Enable the simulator option in the UI
143+
3. Create a room and copy the generated room link
144+
4. Open a different web browser, user profile, or incognito/private window
145+
5. Paste the room link to join as the second player using the simulator
146+
147+
**Using Live WalletConnect (Advanced Testing):**
148+
149+
:::danger Funds Left On-Chain
150+
151+
**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.**
152+
153+
:::
154+
155+
:::important Two Separate Wallet Instances Required
156+
157+
When testing with live WalletConnect (not simulator), you **must** use two different Chia wallet instances. You cannot use the same wallet or installation for both players. The easiest approach is to deploy the gaming system to a URL accessible by both computers and use two different systems (computers) with separate wallet installations.
158+
159+
:::
160+
161+
1. Deploy the gaming system to a URL accessible by both computers (does not need to be publicly accessible; local network, VPN, or other private network setup is sufficient)
162+
2. Use two different computers or systems, each with its own Chia wallet installation
163+
3. Each player connects their separate wallet via WalletConnect
164+
4. Follow the standard game flow with both players using their respective wallets
165+
166+
### Viewing Logs
167+
168+
View Docker container logs for debugging:
169+
170+
```bash
171+
# View all container logs
172+
docker ps # Get container IDs
173+
docker logs <container-id>
174+
175+
# Follow logs in real-time
176+
docker logs -f <container-id>
177+
```
178+
179+
### Running Individual Services
180+
181+
For development, you may want to run services separately. See the repository documentation:
182+
183+
- **Lobby Server**: See the [Lobby Server documentation](https://github.com/Chia-Network/chia-gaming/blob/main/resources/nginx/LOBBY.md) for running the lobby service individually
184+
- **Game Server**: See the [Game Server documentation](https://github.com/Chia-Network/chia-gaming/blob/main/resources/nginx/GAME.md) for running the game service individually
185+
186+
## Verification
187+
188+
After building and launching the system, verify it's working correctly:
189+
190+
1. **Check Docker Containers**: Ensure both containers are running:
191+
192+
```bash
193+
docker ps
194+
```
195+
196+
You should see containers for both the lobby server and game server.
197+
198+
2. **Test with Simulator**:
199+
- Navigate to `http://localhost:3000` (or your configured port)
200+
- Enable simulator mode
201+
- Create a room and test the connection
202+
203+
3. **Test with Live WalletConnect**:
204+
- Connect a Chia wallet via WalletConnect
205+
- Verify the connection is established
206+
- Test creating a room
207+
208+
4. **Check Network Connectivity**: Ensure the backend can reach coinset.org:
209+
```bash
210+
# For mainnet
211+
curl https://coinset.org
212+
# For testnet
213+
curl https://testnet11.api.coinset.org
214+
```
215+
216+
## Deploy to Production
217+
218+
:::warning Config Directory Not Yet Available
219+
220+
The config directory feature is not yet implemented. This is a [known issue](/guides/gaming-known-issues#easy-developer-configuration-not-available). Currently, you must manually update configuration values in the codebase as described in the [Manual Configuration](#manual-configuration) section.
221+
222+
:::
223+
224+
1. **Manual Configuration**: Update all necessary production-specific configurations manually in the codebase (e.g., live network settings, correct ports, production domain).
225+
226+
2. **Build Images**: Build the production Docker images:
227+
228+
```bash
229+
./build-docker-images.sh
230+
```
231+
232+
3. **Launch Images**: Launch the built Docker images on your production server(s).
233+
234+
:::note Distribution
235+
236+
Each image (lobby server and game code server) can be launched on separate physical or virtual servers. Once the config directory feature is available, you'll be able to update the relevant server address parameters through configuration files.
237+
238+
:::
239+
240+
## Manual Configuration
241+
242+
:::warning Manual Configuration Required
243+
244+
The easy developer configuration is still in development. Currently, developers must manually update various parameters in the codebase before building and deploying.
245+
246+
:::
247+
248+
### Network Updates
249+
250+
To configure the network settings (e.g., switching to testnet), update the following files:
251+
252+
1. **agg_sig_additional change to testnet constant**:
253+
- File: `src/common/constants.rs`
254+
- Location: Line 32
255+
- Update the `AGG_SIG_ME_ADDITIONAL_DATA` constant to the testnet value. Replace the mainnet array with:
256+
```rust
257+
pub const AGG_SIG_ME_ADDITIONAL_DATA: [u8; 32] = [
258+
0xe3, 0xb0, 0xc4, 0x42, 0x98, 0xfc, 0x1c, 0x14, 0x9a, 0xfb, 0xf4, 0xc8, 0x99, 0x6f, 0xb9, 0x24,
259+
0x27, 0xae, 0x41, 0xe4, 0x64, 0x9b, 0x93, 0x4c, 0xa4, 0x95, 0x99, 0x1b, 0x78, 0x52, 0xb8, 0x55,
260+
];
261+
```
262+
- [View in repository](https://github.com/Chia-Network/chia-gaming/blob/e716262cdf907e007af26c137a90f50d25ffa344/src/common/constants.rs#L32)
263+
264+
2. **chain_id to testnet**:
265+
- File: `resources/gaming-fe/src/constants/env.ts`
266+
- Location: Line 3
267+
- Update the `chain_id` to testnet: `chia:testnet`
268+
- [View in repository](https://github.com/Chia-Network/chia-gaming/blob/e716262cdf907e007af26c137a90f50d25ffa344/resources/gaming-fe/src/constants/env.ts#L3)
269+
270+
3. **coinset URL for testnet**:
271+
- Update **all instances** of `coinset.org` to the testnet endpoint: `https://testnet11.api.coinset.org`
272+
- This includes (but is not limited to):
273+
- File: `resources/nginx/game.conf` (Content Security Policy header, line 17)
274+
- File: `resources/lobby-service/src/index.ts` (Content Security Policy header, line 48)
275+
- Any other files that reference `coinset.org`
276+
- [View examples in repository](https://github.com/Chia-Network/chia-gaming/blob/e716262cdf907e007af26c137a90f50d25ffa344/resources/nginx/game.conf#L17)
277+
278+
### WalletConnect Project Info Updates
279+
280+
To configure WalletConnect settings, you'll need to obtain a WalletConnect Project ID. For registration and troubleshooting, refer to the [WalletConnect documentation](https://walletconnect.com) and your WalletConnect account dashboard.
281+
282+
Once you have your Project ID, update the following:
283+
284+
1. **Project ID**:
285+
- File: `resources/gaming-fe/src/constants/env.ts`
286+
- Location: Line 1
287+
- Update the WalletConnect project ID with your registered Project ID
288+
- [View in repository](https://github.com/Chia-Network/chia-gaming/blob/e716262cdf907e007af26c137a90f50d25ffa344/resources/gaming-fe/src/constants/env.ts#L1)
289+
290+
2. **Project Info**:
291+
- File: `resources/gaming-fe/src/constants/wallet-connect.ts`
292+
- Location: Line 52
293+
- Update the WalletConnect project information with your project details
294+
- [View in repository](https://github.com/Chia-Network/chia-gaming/blob/e716262cdf907e007af26c137a90f50d25ffa344/resources/gaming-fe/src/constants/wallet-connect.ts#L52)
295+
296+
### Ports and Domain Updates
297+
298+
**Default Ports:**
299+
300+
The default Docker configuration exposes the following ports:
301+
302+
- **Port 3000**: Frontend web interface (game UI)
303+
- **Port 3001**: Lobby server API
304+
- **Port 5800**: Simulator service
305+
306+
:::note Port Configuration
307+
308+
Ports are manually coded in the Docker build and run commands within `build-docker-images.sh` and `run-docker-demo.sh`. To change ports, edit these scripts directly.
309+
310+
:::
311+
312+
For production deployments, ports and domain should be configured via the methods documented in the repository:
313+
314+
- **Game Server**: See the [Game Server documentation](https://github.com/Chia-Network/chia-gaming/blob/main/resources/nginx/GAME.md#using-the-archive-and-script) for configuring ports and domain
315+
- **Lobby Server**: See the [Lobby Server documentation](https://github.com/Chia-Network/chia-gaming/blob/main/resources/nginx/LOBBY.md#using-the-archive-and-script) for configuring ports and domain

0 commit comments

Comments
 (0)