Skip to content

Commit 7d621a8

Browse files
noracaminoracami
committed
📝 Add game flow and game states documentation
1 parent 7b5d5b4 commit 7d621a8

File tree

8 files changed

+558
-0
lines changed

8 files changed

+558
-0
lines changed

‎docs/README.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Split Game Documentation
2+
3+
Welcome to the Split Game documentation. This directory contains comprehensive documentation about the architecture and design of the Split game application.
4+
5+
## Architecture Documentation
6+
7+
For a detailed overview of the system architecture with Mermaid diagrams, see the [Architecture Overview](architecture_overview.md).
8+
9+
The architecture documentation includes:
10+
11+
- [Models and Relationships](models.md)
12+
- [System Architecture](system_architecture.md)
13+
- [Game Flow](game_flow.md)
14+
- [Game States](game_states.md)
15+
- [API Endpoints](api_endpoints.md)
16+
- [Real-time Communication Channels](realtime_channels.md)
17+
18+
## Game Rules
19+
20+
Split (also known as Battle Sheep) is a board game where players compete to control territory on a hexagonal grid.
21+
22+
### Preparation
23+
24+
- Each player starts with 16 sheep.
25+
- Players take turns placing map tiles. (Not supported in Sprint 1)
26+
- Players take turns placing their sheep on empty spaces at the edge of the map.
27+
28+
### How to Play
29+
30+
1. A player selects one of their stacks of sheep that isn't surrounded.
31+
- A stack must have at least two sheep.
32+
- A stack is surrounded if all adjacent spaces are occupied by other sheep or the edge of the map.
33+
- If all of a player's sheep are surrounded, their turn is skipped.
34+
2. The player moves 1 to (N-1) sheep from the stack in any direction until they encounter another sheep or the edge of the map.
35+
- N is the number of sheep in the stack.
36+
- The sheep must move at least one space.
37+
3. Play passes to the next player.
38+
39+
### How to Win
40+
41+
- The game ends when no player can move any sheep.
42+
- The player who occupies the most spaces on the map wins.
43+
- If multiple players occupy the same number of spaces, the player with the largest group of sheep wins.
44+
- If the largest groups are also tied, the players share the victory.
45+
46+
## Project Links
47+
48+
- Frontend Repository: https://github.com/side-project-at-SPT/split-front
49+
- API Documentation: https://side-project-at-spt.github.io/split-rails/
50+
- Project Board: https://miro.com/app/board/uXjVK7A5iEI=

‎docs/api_endpoints.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# API Endpoints
2+
3+
This diagram illustrates the API endpoints structure of the Split game application, showing the available routes for interacting with the system.
4+
5+
```mermaid
6+
graph TD
7+
API[API v1]
8+
9+
API --> Users[Users]
10+
API --> Rooms[Rooms]
11+
API --> Games[Games]
12+
API --> Bots[Bots]
13+
14+
Users --> CreateUser[POST /users]
15+
Users --> LoginAsVisitor[POST /users/login-as-visitor]
16+
Users --> LoginViaGaas[POST /users/login-via-gaas-token]
17+
Users --> GetMe[GET /me]
18+
19+
Rooms --> ListRooms[GET /rooms]
20+
Rooms --> GetRoom[GET /rooms/:id]
21+
Rooms --> CreateRoom[POST /rooms]
22+
Rooms --> CloseRoom[POST /rooms/:id/close]
23+
Rooms --> KnockKnock[GET /rooms/:id/knock-knock]
24+
Rooms --> AddAI[POST /rooms/:id/ai_players]
25+
26+
Games --> GetGame[GET /games/:id]
27+
Games --> CreateGame[POST /rooms/:id/game]
28+
Games --> EndGame[DELETE /rooms/:id/game]
29+
Games --> PlaceStack[POST /games/:id/place-stack]
30+
Games --> SplitStack[POST /games/:id/split-stack]
31+
Games --> InitMap[POST /games/:id/init-map-automatically]
32+
```
33+
34+
## API Endpoints Description
35+
36+
### User Management
37+
38+
- **POST /api/v1/users**: Create a new user
39+
- **POST /api/v1/users/login-as-visitor**: Login as a visitor (guest user)
40+
- **POST /api/v1/users/login-via-gaas-token**: Login using a GaaS (Game as a Service) token
41+
- **GET /api/v1/me**: Get current user information
42+
43+
### Room Management
44+
45+
- **GET /api/v1/rooms**: List all available rooms
46+
- **GET /api/v1/rooms/:id**: Get details of a specific room
47+
- **POST /api/v1/rooms**: Create a new room
48+
- **POST /api/v1/rooms/:id/close**: Close a room
49+
- **GET /api/v1/rooms/:id/knock-knock**: Get a token to subscribe to a room's channel
50+
- **POST /api/v1/rooms/:id/ai_players**: Add an AI player to a room
51+
52+
### Game Management
53+
54+
- **GET /api/v1/games/:id**: Get details of a specific game
55+
- **POST /api/v1/rooms/:id/game**: Create a new game in a room
56+
- **DELETE /api/v1/rooms/:id/game**: End a game in a room
57+
- **POST /api/v1/games/:id/place-stack**: Place a stack on the board
58+
- **POST /api/v1/games/:id/split-stack**: Split a stack and move it
59+
- **POST /api/v1/games/:id/init-map-automatically**: Initialize the game map automatically
60+
61+
### Bot Management
62+
63+
- **GET /api/v1/bots**: List all bots
64+
- **POST /api/v1/bots**: Create a new bot
65+
- **GET /api/v1/bots/:id**: Get details of a specific bot
66+
- **PUT /api/v1/bots/:id**: Update a bot
67+
- **DELETE /api/v1/bots/:id**: Delete a bot
68+
69+
The API follows RESTful principles and is organized around the main resources of the application: users, rooms, games, and bots. The endpoints provide the necessary operations to manage these resources and interact with the game system.

‎docs/architecture_overview.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Split Game Architecture Documentation
2+
3+
This documentation provides a comprehensive overview of the Split game application architecture through a series of Mermaid diagrams. Each diagram focuses on a specific aspect of the system.
4+
5+
## Table of Contents
6+
7+
1. [Models and Relationships](models.md) - Class diagram showing the data models and their relationships
8+
2. [System Architecture](system_architecture.md) - Overview of the system components and how they interact
9+
3. [Game Flow](game_flow.md) - Sequence diagram illustrating the flow of a typical game session
10+
4. [Game States](game_states.md) - State diagram showing the different states a game can be in
11+
5. [API Endpoints](api_endpoints.md) - Structure of the API endpoints for interacting with the system
12+
6. [Real-time Communication Channels](realtime_channels.md) - WebSocket channels for real-time updates
13+
14+
## About the Split Game
15+
16+
Split (also known as Battle Sheep) is a board game where players compete to control territory on a hexagonal grid. The game is implemented as a web application using Ruby on Rails for the backend and a separate frontend repository.
17+
18+
### Key Features
19+
20+
- User authentication and session management
21+
- Room-based multiplayer system
22+
- Real-time game updates using WebSockets
23+
- AI players
24+
- Game state tracking and validation
25+
- RESTful API for frontend integration
26+
27+
### Technology Stack
28+
29+
- **Backend**: Ruby on Rails
30+
- **Database**: PostgreSQL
31+
- **Real-time Communication**: Action Cable (WebSockets)
32+
- **Caching and Pub/Sub**: Redis
33+
- **Frontend**: Separate repository (https://github.com/side-project-at-SPT/split-front)
34+
35+
## How to Use This Documentation
36+
37+
Each diagram file focuses on a specific aspect of the system. You can navigate between them to understand different parts of the architecture:
38+
39+
- Start with the **System Architecture** for a high-level overview
40+
- Explore the **Models and Relationships** to understand the data structure
41+
- Review the **Game Flow** and **Game States** to understand the gameplay mechanics
42+
- Check the **API Endpoints** and **Real-time Communication Channels** to understand how the frontend interacts with the backend
43+
44+
These diagrams are designed to help developers understand the system architecture and make it easier to maintain and extend the application.

‎docs/game_flow.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Game Flow
2+
3+
This sequence diagram illustrates the flow of a typical game session in the Split application, from room creation to game completion.
4+
5+
```mermaid
6+
sequenceDiagram
7+
participant User as User
8+
participant Room as Room
9+
participant Game as Game
10+
participant GameStep as GameStep
11+
12+
User->>Room: Create Room
13+
User->>Room: Join Room
14+
User->>Room: Ready
15+
Room->>Room: Check if all players ready
16+
Room->>Game: Start New Game
17+
Game->>GameStep: Initialize Map
18+
19+
loop Game Play
20+
Game->>User: Current Player's Turn
21+
alt Place Stack Phase
22+
User->>Game: Place Stack
23+
Game->>GameStep: Create Place Stack Step
24+
else Split Stack Phase
25+
User->>Game: Split Stack
26+
Game->>GameStep: Create Split Stack Step
27+
end
28+
Game->>Game: Next Player
29+
end
30+
31+
Game->>Game: Check Game End Condition
32+
Game->>Game: Close Game
33+
```
34+
35+
## Game Flow Explanation
36+
37+
### Room Setup Phase
38+
39+
1. **Create Room**: A user creates a new room
40+
2. **Join Room**: Other users join the room
41+
3. **Ready**: Users mark themselves as ready to play
42+
4. **Check Ready Status**: The room checks if all players are ready
43+
5. **Start Game**: When all players are ready, a new game is started
44+
45+
### Game Initialization
46+
47+
6. **Initialize Map**: The game board is initialized with the hexagonal grid
48+
49+
### Game Play Loop
50+
51+
7. **Player Turns**: The game cycles through player turns
52+
- In the **Place Stack Phase**, players place their initial stacks on the board
53+
- In the **Split Stack Phase**, players split their stacks and move them across the board
54+
8. **Next Player**: After each move, the turn passes to the next player
55+
56+
### Game Conclusion
57+
58+
9. **Check End Condition**: The game checks if any player can make a valid move
59+
10. **Close Game**: When no more moves are possible, the game ends
60+
61+
This flow represents the core gameplay loop of the Split game, following the rules outlined in the README. The game progresses from the initial setup phase through the placement of sheep stacks and then into the main gameplay of splitting and moving stacks until no more valid moves are possible.

‎docs/game_states.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Game States
2+
3+
This state diagram illustrates the different states a game can be in and the transitions between these states in the Split application.
4+
5+
```mermaid
6+
stateDiagram-v2
7+
[*] --> RoomCreated
8+
RoomCreated --> WaitingForPlayers
9+
WaitingForPlayers --> PlayersReady: All players ready
10+
PlayersReady --> GameStarting: Countdown
11+
GameStarting --> BuildMapPhase: Initialize map
12+
BuildMapPhase --> PlaceStackPhase: Map initialized
13+
PlaceStackPhase --> SplitStackPhase: All stacks placed
14+
SplitStackPhase --> GameOver: No more valid moves
15+
SplitStackPhase --> SplitStackPhase: Player makes move
16+
GameOver --> WaitingForPlayers: Start new game
17+
WaitingForPlayers --> [*]: Close room
18+
```
19+
20+
## Game State Descriptions
21+
22+
### Room States
23+
24+
- **RoomCreated**: Initial state when a room is first created
25+
- **WaitingForPlayers**: Room is open and waiting for players to join and get ready
26+
- **PlayersReady**: All players in the room have marked themselves as ready
27+
- **GameStarting**: Countdown period before the game actually starts
28+
29+
### Game Phase States
30+
31+
- **BuildMapPhase**: The game board is being initialized
32+
- **PlaceStackPhase**: Players are placing their initial stacks on the board
33+
- **SplitStackPhase**: Main gameplay phase where players split and move their stacks
34+
- **GameOver**: The game has ended because no more valid moves are possible
35+
36+
### State Transitions
37+
38+
- **All players ready**: Triggered when all players in a room mark themselves as ready
39+
- **Countdown**: A short countdown period before the game starts
40+
- **Map initialized**: The game board has been set up
41+
- **All stacks placed**: All players have placed their initial stacks
42+
- **Player makes move**: A player splits and moves a stack during their turn
43+
- **No more valid moves**: No player can make a valid move, ending the game
44+
- **Start new game**: Players choose to start a new game in the same room
45+
- **Close room**: The room is closed, ending the session
46+
47+
This state diagram helps visualize the progression of a game session from room creation through the different game phases to completion, and potentially starting a new game or closing the room.

‎docs/models.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# Models and Relationships
2+
3+
This diagram illustrates the data models in the Split game application and their relationships. The application follows a standard Rails ActiveRecord pattern with models representing game entities.
4+
5+
```mermaid
6+
classDiagram
7+
class Visitor {
8+
+name: string
9+
+password_digest: string
10+
+preferences: jsonb
11+
+role: enum [admin, user, guest, ai]
12+
+encode_jwt()
13+
+read_preferences()
14+
+nickname()
15+
+ready?()
16+
+ready!()
17+
+unready!()
18+
+character()
19+
+owner_of?(room)
20+
+knock_knock(room)
21+
}
22+
23+
class Room {
24+
+name: string
25+
+owner_id: integer
26+
+closed_at: datetime
27+
+generate_players(seed)
28+
+start_new_game(seed)
29+
+closed?()
30+
+close()
31+
+ready_to_start?()
32+
+start_in_seconds()
33+
+countdown_game_start(seconds)
34+
+countdown()
35+
+status()
36+
+full?()
37+
}
38+
39+
class VisitorsRoom {
40+
+ready: boolean
41+
+character: string
42+
+ready!()
43+
+unready!()
44+
}
45+
46+
class Game {
47+
+room_id: integer
48+
+is_finished: boolean
49+
+players: jsonb
50+
+current_player_index: integer
51+
+current_player()
52+
+close()
53+
+on_going?()
54+
+finished?()
55+
+game_phase()
56+
+valid_position?(params)
57+
+pastures()
58+
+place_stack(target_x, target_y)
59+
+split_stack(origin_x, origin_y, target_x, target_y, target_amount)
60+
+game_config()
61+
+game_data(step)
62+
}
63+
64+
class GameStep {
65+
+game_id: integer
66+
+step_number: integer
67+
+step_type: enum [initialize_map_by_system, place_pasture, place_stack, split_stack, game_over]
68+
+game_phase: enum [build_map, place_stack, split_stack, game_over, game_interrupted]
69+
+pastures: jsonb
70+
+action: jsonb
71+
+author()
72+
+action_name()
73+
+to_grid()
74+
+from_grid()
75+
}
76+
77+
class Bot {
78+
+name: string
79+
+visitor_id: integer
80+
+generate_player()
81+
+join_room(room)
82+
}
83+
84+
class AiPlayer {
85+
+bot_id: integer
86+
+player_id: integer
87+
+nickname()
88+
}
89+
90+
Visitor "1" -- "1" VisitorsRoom : has_one
91+
Room "1" -- "*" VisitorsRoom : has_many
92+
VisitorsRoom "1" -- "1" Visitor : belongs_to
93+
VisitorsRoom "1" -- "1" Room : belongs_to
94+
Visitor "1" -- "1" Room : through VisitorsRoom
95+
Room "1" -- "*" Game : has_many
96+
Game "1" -- "*" GameStep : has_many
97+
Bot "1" -- "*" AiPlayer : has_many
98+
Visitor "1" -- "*" Bot : has_many as owner
99+
AiPlayer "1" -- "1" Visitor : belongs_to as player
100+
AiPlayer "1" -- "1" Bot : belongs_to
101+
```
102+
103+
## Key Model Relationships
104+
105+
- **Visitor**: Represents users in the system with different roles (admin, user, guest, ai)
106+
- **Room**: A virtual room where players gather to play games
107+
- **VisitorsRoom**: Join table connecting visitors to rooms with additional attributes like ready status
108+
- **Game**: Represents a game session with its state and players
109+
- **GameStep**: Records each step/move in a game with detailed information
110+
- **Bot**: Represents an AI bot that can play the game
111+
- **AiPlayer**: Join table connecting bots to visitor records that represent AI players
112+
113+
The diagram shows how these models are interconnected, forming the foundation of the Split game application's data structure.

0 commit comments

Comments
 (0)