SlipItIn/openwiki/domain/game-mechanics.md

type, title, description, tags

type	title	description	tags
Domain Model	Game Domain & State Models	Detailed domain model and state lifecycles for SlipItIn games, rounds, phrase decks, players, and challenges.	domain models state-machine entity-framework privacy

Game Domain & State Models

This page describes the core domain entities, relational schema, state machines, 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 the system architecture, defines state lifecycles executed by real-time game workflows, and maps domain classes in C# project files indexed in the source map (SlipItIn.Shared/Models/ and SlipItIn.Shared/DTOs/).

---

1. Entity Relationship Diagram (ERD)

The database schema is managed via Entity Framework Core (SlipItInDbContext) targeting PostgreSQL.

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"

---

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. Enumerations & State Lifecycles

Game Status (GameStatus)

stateDiagram-v2
    [*] --> Lobby: CreateGameAsync()
    Lobby --> InProgress: StartGameAsync() (Host only)
    InProgress --> Completed: All rounds finished
    Lobby --> Cancelled: Host cancels
    InProgress --> Cancelled: Session abort

• 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)

stateDiagram-v2
    [*] --> Waiting: StartGame / New Round
    Waiting --> Active: DealCardsAsync()
    Active --> Resolving: Challenge submitted
    Resolving --> Active: Challenge resolved
    Active --> Completed: Timer expires / All phrases used

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).

---

4. Data Transfer Objects (DTOs) & Data Privacy

To enforce security and data privacy (Architecture Overview), the backend exposes decoupled DTOs in SlipItIn.Shared/DTOs:

DTO	Visibility	Purpose & Content
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.