213 lines
9.1 KiB
Markdown
213 lines
9.1 KiB
Markdown
---
|
|
type: Domain Model
|
|
title: Game Domain & State Models
|
|
description: Detailed domain model and state lifecycles for SlipItIn games, rounds, phrase decks, players, challenges, and client offline action queue.
|
|
tags: [domain, models, state-machine, entity-framework, privacy, offline-queue]
|
|
openwiki:
|
|
roles: [domain]
|
|
change_kinds: [public-api, lifecycle]
|
|
source_paths: [SlipItIn.Shared/Models/Game.cs, SlipItIn.Shared/Models/Player.cs, SlipItIn/Models/QueuedGameAction.cs, SlipItIn.Shared/DTOs/GameStateDto.cs]
|
|
symbols: [Game, Player, PlayerCard, SlipChallenge, QueuedGameAction, GameStateDto, PlayerHandDto]
|
|
validation_commands: ["dotnet build SlipItIn.Shared/SlipItIn.Shared.csproj"]
|
|
---
|
|
|
|
# Game Domain & State Models
|
|
|
|
This page describes the core domain entities, relational schema, state machines, offline action queue models, and data transfer objects (DTOs) that form the foundation of the SlipItIn game engine.
|
|
|
|
The domain model [is secured by data privacy models defined in](/openwiki/architecture/overview.md) the system architecture, [defines state lifecycles executed by](/openwiki/workflows/slip-and-challenge.md) real-time game workflows, and [maps domain classes in C# project files indexed in](/openwiki/source-map.md) the source map (`SlipItIn.Shared/Models/`, `SlipItIn.Shared/DTOs/`, and `SlipItIn/Models/`).
|
|
|
|
---
|
|
|
|
## 1. Entity Relationship Diagram (ERD)
|
|
|
|
The backend database schema is managed via Entity Framework Core (`SlipItInDbContext`) targeting PostgreSQL.
|
|
|
|
```mermaid
|
|
erDiagram
|
|
User {
|
|
int Id PK
|
|
string Username
|
|
string Email
|
|
string PasswordHash
|
|
bool IsActive
|
|
}
|
|
Game {
|
|
int Id PK
|
|
string LobbyCode
|
|
int HostId FK
|
|
GameStatus Status
|
|
int MaxPlayers
|
|
int RoundDurationSeconds
|
|
}
|
|
Player {
|
|
int Id PK
|
|
int UserId FK
|
|
int GameId FK
|
|
int Score
|
|
bool IsReady
|
|
string ConnectionId
|
|
}
|
|
Phrase {
|
|
int Id PK
|
|
string Text
|
|
int CreatorId FK
|
|
bool IsActive
|
|
}
|
|
GameRound {
|
|
int Id PK
|
|
int GameId FK
|
|
int RoundNumber
|
|
RoundStatus Status
|
|
}
|
|
PlayerCard {
|
|
int Id PK
|
|
int PlayerId FK
|
|
int PhraseId FK
|
|
int GameRoundId FK
|
|
bool IsUsed
|
|
}
|
|
SlipChallenge {
|
|
int Id PK
|
|
int GameRoundId FK
|
|
int ChallengingPlayerId FK
|
|
int TargetPlayerId FK
|
|
int TargetCardId FK
|
|
ChallengeStatus Status
|
|
}
|
|
|
|
User ||--o{ Game : hosts
|
|
User ||--o{ Player : participates_as
|
|
User ||--o{ Phrase : creates
|
|
Game ||--o{ Player : contains
|
|
Game ||--o{ GameRound : has
|
|
Player ||--o{ PlayerCard : holds
|
|
Phrase ||--o{ PlayerCard : used_in
|
|
GameRound ||--o{ PlayerCard : active_in
|
|
GameRound ||--o{ SlipChallenge : contains
|
|
Player ||--o{ SlipChallenge : challenges
|
|
Player ||--o{ SlipChallenge : target_of
|
|
PlayerCard ||--o{ SlipChallenge : targeted_by
|
|
```
|
|
*Entity Relationship Diagram showing relational database schema for users, games, players, phrases, cards, rounds, and challenges.*
|
|
|
|
---
|
|
|
|
## 2. Core Domain Entities (`SlipItIn.Shared/Models`)
|
|
|
|
### `User`
|
|
Represents an authenticated account.
|
|
* **Properties**: `Id`, `Username`, `Email`, `PasswordHash` (BCrypt), `CreatedAt`, `IsActive`.
|
|
* **Relations**: Navigation properties to created `Game` instances, player entries (`Players`), and created phrases (`Phrases`).
|
|
|
|
### `Game`
|
|
Represents a multiplayer game session / lobby.
|
|
* **Properties**: `Id`, `LobbyCode` (6-char alphanumeric), `HostId`, `Status` (`GameStatus`), `CreatedAt`, `StartedAt`, `EndedAt`, `MaxPlayers` (default 8), `RoundDurationSeconds` (30-60s).
|
|
* **Relations**: `Host` (`User`), `Players` (`ICollection<Player>`), `Rounds` (`ICollection<GameRound>`).
|
|
|
|
### `Player`
|
|
Represents a user's participation inside a specific `Game`.
|
|
* **Properties**: `Id`, `UserId`, `GameId`, `Score`, `SuccessfulSlips`, `FailedSlips`, `JoinedAt`, `IsReady`, `ConnectionId` (active SignalR connection ID).
|
|
* **Relations**: `User`, `Game`, `Cards` (`ICollection<PlayerCard>`).
|
|
|
|
### `Phrase`
|
|
Represents a secret phrase or sentence created for the game deck.
|
|
* **Properties**: `Id`, `Text`, `CreatorId`, `CreatedAt`, `IsActive`.
|
|
* **Relations**: `Creator` (`User`), `PlayerCards` (`ICollection<PlayerCard>`).
|
|
|
|
### `GameRound`
|
|
Tracks a distinct round within a game.
|
|
* **Properties**: `Id`, `GameId`, `RoundNumber`, `Status` (`RoundStatus`), `StartedAt`, `EndedAt`.
|
|
* **Relations**: `Game`, `ActiveCards` (`ICollection<PlayerCard>`), `Challenges` (`ICollection<SlipChallenge>`).
|
|
|
|
### `PlayerCard`
|
|
Represents a specific phrase card dealt to a player for a round.
|
|
* **Properties**: `Id`, `PlayerId`, `PhraseId`, `GameRoundId`, `IsUsed` (boolean flag set when player submits slip), `AssignedAt`.
|
|
* **Relations**: `Player`, `Phrase`, `GameRound`.
|
|
|
|
### `SlipChallenge`
|
|
Represents an accusation made by one player against another player's submitted slip.
|
|
* **Properties**: `Id`, `GameRoundId`, `ChallengingPlayerId`, `TargetPlayerId`, `TargetCardId`, `Status` (`ChallengeStatus`), `CreatedAt`, `ResolvedAt`.
|
|
* **Relations**: `GameRound`, `ChallengingPlayer`, `TargetPlayer`, `TargetCard`.
|
|
|
|
---
|
|
|
|
## 3. Client State & Offline Action Queue Models (`SlipItIn/Models`)
|
|
|
|
### `QueuedGameAction`
|
|
Represents a game action (such as `SubmitSlip` or `ChallengeSlip`) initiated on the client while offline (`!SignalRService.IsConnected`).
|
|
* **Properties**:
|
|
* `Method`: Target SignalR hub method name (e.g. `"SubmitSlip"`, `"ChallengeSlip"`).
|
|
* `ArgumentsJson`: JSON serialized array of method arguments.
|
|
* `CreatedAtUtc`: Timestamp recording when the action was taken.
|
|
* **Lifecycle**: Enqueued into `Preferences` via `GameStateService.EnqueueActionAsync()`, replayed sequentially upon reconnection via `GameStateService.FlushQueuedActionsAsync()`, and removed from storage.
|
|
|
|
---
|
|
|
|
## 4. Enumerations & State Lifecycles
|
|
|
|
### Game Status (`GameStatus`)
|
|
```mermaid
|
|
stateDiagram-v2
|
|
[*] --> Lobby: CreateGameAsync()
|
|
Lobby --> InProgress: StartGameAsync() (Host only)
|
|
InProgress --> Completed: All rounds finished
|
|
Lobby --> Cancelled: Host cancels
|
|
InProgress --> Cancelled: Session abort
|
|
```
|
|
*State diagram illustrating lifecycle transitions of a game session from lobby creation to completion or cancellation.*
|
|
|
|
* **`Lobby`**: Waiting for players to join and set ready status.
|
|
* **`InProgress`**: Active gameplay with dealt cards and active rounds.
|
|
* **`Completed`**: Game finished, final scores tallied.
|
|
* **`Cancelled`**: Lobby or game terminated early.
|
|
|
|
### Round Status (`RoundStatus`)
|
|
```mermaid
|
|
stateDiagram-v2
|
|
[*] --> Waiting: StartGame / New Round
|
|
Waiting --> Active: DealCardsAsync()
|
|
Active --> Resolving: Challenge submitted
|
|
Resolving --> Active: Challenge resolved
|
|
Active --> Completed: Timer expires / All phrases used
|
|
```
|
|
*State diagram illustrating round lifecycles from card dealing to challenge resolution.*
|
|
|
|
### Challenge Status (`ChallengeStatus`)
|
|
* **`Pending`**: Accusation registered, awaiting response from the accused player.
|
|
* **`Approved`**: Accusation confirmed (the phrase was indeed an invalid slip). The card remains with the accused player.
|
|
* **`Rejected`**: Accusation rejected (the slip was legitimate). As a penalty, the card is transferred to the accuser's hand (`PlayerCard.PlayerId = ChallengingPlayerId`).
|
|
|
|
---
|
|
|
|
## 5. Data Transfer Objects (DTOs) & Data Privacy
|
|
|
|
To enforce security and data privacy ([Architecture Overview](/openwiki/architecture/overview.md)), the backend exposes decoupled DTOs in `SlipItIn.Shared/DTOs`:
|
|
|
|
| DTO | Visibility | Purpose & Content |
|
|
|---|---|---|
|
|
| `LoginRequestDto` | Direct REST | Credentials for authentication: `Email`, `Password`. |
|
|
| `RegisterRequestDto` | Direct REST | Account creation details: `Username`, `Email`, `Password`. |
|
|
| `AuthResponseDto` | Direct REST | JWT Access Token, Expiration, Username, Email. |
|
|
| `GameStateDto` | Broadcast (Group) | Public lobby/game status: `GameId`, `LobbyCode`, `Status`, `CurrentRound`, `RoundTimeRemaining`, `Players` (`PlayerInfoDto` array containing `PlayerId`, `Username`, `Score`, `IsReady`, and `CardCount`). **No card text.** |
|
|
| `PlayerHandDto` | Unicast (Client) | Private hand data sent strictly to the card owner: `PlayerId`, `Cards` (`PlayerCardDto` array containing `CardId`, `PhraseId`, `Text`, `IsUsed`). |
|
|
| `SlipChallengeDto` | Unicast / Group | Challenge notification: `ChallengeId`, `ChallengingPlayerId`, `TargetPlayerId`, `TargetCardId`, `Status`, `CreatedAt`. |
|
|
|
|
---
|
|
|
|
## 6. Guidance for Future Agents & Developers
|
|
|
|
- **When to Consult**: Consult this page when adding domain attributes, extending DTOs, adding new game state statuses, or modifying offline action serialization.
|
|
- **Invariants**:
|
|
- `PlayerCard.IsUsed` transitions from `false` to `true` upon `SubmitSlip` and cannot be reverted without server intervention.
|
|
- `QueuedGameAction.ArgumentsJson` must store arguments in the exact order and type expected by `GameHub` methods.
|
|
- **Primary Source Files**:
|
|
- `SlipItIn.Shared/Models/Game.cs`
|
|
- `SlipItIn.Shared/Models/PlayerCard.cs`
|
|
- `SlipItIn.Shared/DTOs/GameStateDto.cs`
|
|
- `SlipItIn/Models/QueuedGameAction.cs`
|
|
- **Minimal Validation Command**:
|
|
```bash
|
|
dotnet build SlipItIn.Shared/SlipItIn.Shared.csproj
|
|
```
|