Stingray.Tabletop 0.1.1

Stingray.Tabletop

Stingray.Tabletop is a comprehensive C# framework designed for building turn-based strategy and tabletop games. It provides a robust architecture for managing game state, player turns, phases, and action commands, allowing developers to focus on gameplay logic rather than boilerplate orchestration.

Features

• Centralized Orchestration: A GameEngine class that acts as the single source of truth and event dispatcher.
• Phase Management: Define distinct game phases (e.g., "Deployment", "Action", "Cleanup") with specific rules and transitions.
• Turn Order Strategies: Flexible turn management (Round Robin, Initiative-based, etc.) via TurnOrderManager.
• Command Pattern Architecture: All game actions are encapsulated as Commands, supporting:
  • Validation
  • Execution
  • History/Undo capability
  • Pre/Post-execution hooks
• State Management: Generic IGameState implementation to strongly type your board/game state.
• Event-Driven: Rich set of events (OnTurnStarted, OnPhaseChanged, OnPlayMade) for UI integration.
• Lifecycle Management: Hooks for Round Start/End, Game Start/End, and Phase Start/End.

Core Concepts

GameEngine

The heart of the library. It initializes managers, holds the current functionality state, and exposes events.

var engine = GameEngine.DefaultWithState<MyCustomGameState>();
engine.AddPlayer(new HumanPlayer("Player 1"));
engine.AddPhase(new DeploymentPhase());
engine.StartGame();

Commands

All player interactions are modeled as commands. This ensures that every modification to the game state is deliberate, validatable, and reversible (if supported).

public class MoveUnitCommand : CommandBase<MyGameState> {
    public override ICommandResult Execute(GameEngine engine, MyGameState state) {
        // Logic to move unit
        return CommandResult.Success();
    }
}

// executing a command
engine.SubmitPlay(new MoveUnitCommand(unitId, destination));

Phases

Games are often broken down into phases. The PhaseManager handles transitions between these states.

public class MainPhase : PhaseBase {
    public override string PhaseName => "Main Phase";
    
    public override void OnEnter(GameEngine engine) {
        // Setup phase specific logic
    }
}

Turn Order

The TurnOrderManager determines who acts next. You can implement ITurnOrderStrategy to define custom turn orders.

Getting Started

1. Define your Game State: Create a class implementing IGameState.
2. Define your Phases: Implement IPhase or extend PhaseBase.
3. Define Commands: Create commands for valid player actions.
4. Configure Engine:

   var engine = GameEngine
       .DefaultWithState<ChessGameState>()
       .AddPlayer(new Player("White"))
       .AddPlayer(new Player("Black"))
       .AddPhase(new MainPhase())
       .SetRoundConfig(new RoundConfig()); // Optional
   
   engine.StartGame();
   

Project Structure

• Commands/: Interfaces and base classes for the Command pattern.
• Phases/: Phase management and base classes.
• TurnOrder/: Strategies and management for turn sequencing.
• State/: Game state interfaces.
• Players/: Player abstraction.
• Rounds/: Round lifecycle configuration.
• EndConditions/: Logic to determine when the game ends.

Lifecycle Architecture

graph TD
    %% Global Orchestrator
    GE[Game Engine] --> StartGame
    
    subgraph RoundCycle [Round Lifecycle]
        direction TB
        StartGame --> R_Start(Start Round)
        R_Start --> R_Pre[Round PreExecuteCommands]
        R_Pre --> PhaseIter{Iterate Phases}
        
        subgraph PhaseCycle [Phase Lifecycle]
            direction TB
            P_Setup[Setup Called once on Init]
            
            PhaseIter -->|Enter Phase| P_Pre[Phase PreExecuteCommands]
            P_Pre --> P_Enter[OnEnter]
            P_Enter --> P_Loop{Game Loop / Tick}
            
            P_Loop -->|Submit Play| CmdStart
            
            subgraph CommandCycle [Allowed Commands]
                direction TB
                CmdStart(Command) --> C_Pre[PreExecuteCommand]
                C_Pre --> C_Exec[Execute]
                C_Exec --> C_Post[PostExecuteCommand]
            end
            
            C_Post --> P_Loop
            
            P_Loop -->|Phase Complete| P_Exit[OnExit]
            P_Exit --> P_Post[Phase PostExecuteCommands]
        end
        
        P_Post -->|Next Phase| PhaseIter
        PhaseIter -->|No More Phases| R_Post[Round PostExecuteCommands]
    end
    
    R_Post -->|Next Round| R_Start