Cockatrice/libcockatrice_game/libcockatrice/game/game_event_handler.h

/**
 * @file game_event_handler.h
 * @ingroup GameLogic
 * @brief Game-level command sender and event dispatcher.
 *
 * GameEventHandler sends commands initiated by the local client to the server
 * and processes incoming game-wide events. It bridges the networking layer
 * (protobuf events received via AbstractClient) with the game model and UI
 * (GameState, PlayerManager, logging, widgets).
 *
 * Player-scoped events are forwarded to PlayerEventHandler instances, while
 * spectator and global game events are handled directly here.
 */

#ifndef COCKATRICE_GAME_EVENT_HANDLER_H
#define COCKATRICE_GAME_EVENT_HANDLER_H

#include "player/event_processing_options.h"

#include <QLoggingCategory>
#include <QObject>
#include <QPair>
#include <QString>
#include <QVector>
#include <libcockatrice/protocol/pb/event_leave.pb.h>
#include <qtmetamacros.h>

// IWYU pragma: keep
// GameEventContext, ServerInfo_Player and ServerInfo_User are passed by value
// to signals and slots, so the moc-generated code needs the complete types.
#include <libcockatrice/protocol/pb/game_event_context.pb.h>
#include <libcockatrice/protocol/pb/move_card_to_zone.pb.h>
#include <libcockatrice/protocol/pb/serverinfo_player.pb.h>
#include <libcockatrice/protocol/pb/serverinfo_user.pb.h>
#include <libcockatrice/utility/playmat_params.h>

class AbstractClient;
class AbstractGame;
class GameEventContainer;
class PendingCommand;
class PlayerLogic;
class Response;
class Event_GameStateChanged;
class Event_PlayerPropertiesChanged;
class Event_Join;
class Event_GameHostChanged;
class Event_GameClosed;
class Event_SetActivePlayer;
class Event_SetActivePhase;
class Event_GameSay;
class Event_Kicked;
class Event_ReverseTurn;
class Event_Ping;
class Event_PlayerOrderChanged;
class ServerInfo_PlayerProperties;
namespace google
{
namespace protobuf
{
class Message;
} // namespace protobuf
} // namespace google
template <typename T> class QList;

inline Q_LOGGING_CATEGORY(GameEventHandlerLog, "game_event_handler");

/**
 * @class GameEventHandler
 * @brief Central dispatcher for game-wide commands and events.
 *
 * This class owns no game state itself. Instead, it:
 * - Sends commands to the server on behalf of local players
 * - Receives and dispatches server-side game events
 * - Updates the game model indirectly via Player, GameState, and PlayerManager
 * - Emits high-level signals for UI updates and logging
 */
class GameEventHandler : public QObject
{
    Q_OBJECT

private:
    /** Pointer to the owning game instance. */
    AbstractGame *game;

public:
    /** @name Construction
     *  Lifecycle and ownership.
     *  @{
     */

    /**
     * @brief Construct a GameEventHandler.
     *
     * The handler is owned by the AbstractGame instance and uses it to
     * access the game state, players, and network clients.
     *
     * @param _game Owning game instance (also used as QObject parent).
     */
    explicit GameEventHandler(AbstractGame *_game);

    /** @} */

    /** @name Outgoing game commands
     *  Commands initiated locally and sent to the server.
     *
     * These methods construct and send protobuf commands corresponding
     * to user actions in the UI.
     *  @{
     */

    /** @brief Request advancing the game to the next turn. */
    void handleNextTurn();

    /** @brief Request reversing the current turn order. */
    void handleReverseTurn();

    /**
     * @brief Request a new seating / turn order.
     *
     * Only the game host (or a moderator) may do this before the game starts.
     *
     * @param playerNames Ordered list of player names. Ignored when randomize is true.
     * @param randomize Ask the server to shuffle the seats instead.
     */
    void handleSetPlayerOrder(const QList<QString> &playerNames, bool randomize);

    /** @brief Concede the game for the currently active local player. */
    void handleActiveLocalPlayerConceded();

    /** @brief Undo a previous concede for the active local player. */
    void handleActiveLocalPlayerUnconceded();

    /**
     * @brief Set the active phase of the game.
     *
     * Typically triggered by the active player selecting a new phase.
     *
     * @param phase Phase identifier.
     */
    void handleActivePhaseChanged(int phase);

    /** @brief Request untapping every permanent on the table. */
    void handleUntapAll();

    /** @brief Request drawing a single card. */
    void handleDrawCard();

    /** @brief Leave the current game session. */
    void handleGameLeft();

    /**
     * @brief Send a chat message to all players and spectators.
     *
     * @param chatMessage Message text.
     */
    void handleChatMessageSent(const QString &chatMessage);

    /**
     * @brief Delete an existing arrow.
     *
     * @param arrowId Unique identifier of the arrow to delete.
     */
    void handleArrowDeletion(int creatorId, int arrowId);
    void handleArrowDeletionFinished(const Response &response, int creatorId, int arrowId);

    /**
     * @brief Prepare a deck selection from its native deck list text.
     *
     * The returned command is not sent yet, so the caller can connect to
     * PendingCommand::finished before handing it to sendGameCommand().
     *
     * @param deckList Serialized deck list.
     * @return The pending command awaiting the deck download response.
     */
    PendingCommand *prepareDeckSelect(const QString &deckList);

    /**
     * @brief Prepare a deck selection for a deck stored on the server.
     *
     * The returned command is not sent yet, so the caller can connect to
     * PendingCommand::finished before handing it to sendGameCommand().
     *
     * @param deckId Server-side deck identifier.
     * @return The pending command awaiting the deck download response.
     */
    PendingCommand *prepareDeckSelectId(int deckId);

    /**
     * @brief Build the playmat command for a player without sending it.
     *
     * The returned command is not sent yet, so the caller can connect to
     * PendingCommand::finished before handing it to sendGameCommand().
     *
     * @param playmat Resolved playmat card and positioning parameters.
     * @return The pending command awaiting the playmat response.
     */
    PendingCommand *prepareSetPlaymat(const PlaymatInfo &playmat);

    /**
     * @brief Set a player's ready state.
     *
     * @param ready Whether the player is ready.
     * @param playerId Player the state applies to.
     */
    void sendReadyStart(bool ready, int playerId);

    /**
     * @brief Force-start the game, kicking every player who is not ready.
     *
     * @param playerId Player issuing the force start.
     */
    void sendForceStart(int playerId);

    /**
     * @brief Lock or unlock a player's sideboard.
     *
     * @param locked Whether the sideboard is locked.
     * @param playerId Player the lock applies to.
     */
    void sendSetSideboardLock(bool locked, int playerId);

    /**
     * @brief Send a player's sideboard plan.
     *
     * @param plan Cards to move between zones when leaving sideboarding.
     * @param playerId Player the plan belongs to.
     */
    void sendSetSideboardPlan(const QList<MoveCard_ToZone> &plan, int playerId);

    /** @} */

    /** @name Incoming event processing
     *  Entry points for server-sent events.
     *  @{
     */

    /**
     * @brief Process a container of game events received from the server.
     *
     * This is the main dispatch function for incoming game events.
     * Events are routed to spectator handlers, game-level handlers,
     * or forwarded to PlayerEventHandler instances as appropriate.
     *
     * @param cont Game event container from the server.
     * @param client Client that received the container.
     * @param options Processing flags (e.g. silent, replay).
     */
    void
    processGameEventContainer(const GameEventContainer &cont, AbstractClient *client, EventProcessingOptions options);

    /** @} */

    /** @name Command preparation helpers
     *  Internal helpers for building command containers.
     *  @{
     */

    /**
     * @brief Wrap a single protobuf command in a PendingCommand.
     *
     * @param cmd Protobuf command message.
     * @return Newly allocated PendingCommand (caller takes ownership).
     */
    PendingCommand *prepareGameCommand(const ::google::protobuf::Message &cmd);

    /**
     * @brief Wrap multiple protobuf commands in a single PendingCommand.
     *
     * Ownership of the messages in cmdList is transferred to the handler.
     *
     * @param cmdList List of protobuf command messages.
     * @return Newly allocated PendingCommand.
     */
    PendingCommand *prepareGameCommand(const QList<const ::google::protobuf::Message *> &cmdList);

    /** @} */

    /** @name Spectator event handlers
     *  Events originating from spectators.
     *  @{
     */

    /**
     * @brief Handle a spectator chat message.
     */
    void eventSpectatorSay(const Event_GameSay &event, int eventPlayerId, const GameEventContext &context);

    /**
     * @brief Handle a spectator leaving the game.
     */
    void eventSpectatorLeave(const Event_Leave &event, int eventPlayerId, const GameEventContext &context);

    /** @} */

    /** @name Game state event handlers
     *  Events that affect global game state.
     *  @{
     */

    /**
     * @brief Handle a full game state update from the server.
     *
     * Used during game startup, reconnection, and resynchronization.
     */
    void eventGameStateChanged(const Event_GameStateChanged &event, int eventPlayerId, const GameEventContext &context);

    /**
     * @brief Update card attachment relationships for all players.
     *
     * Called after a game state update to ensure attachments are resolved
     * consistently across all zones.
     */
    void processCardAttachmentsForPlayers(const Event_GameStateChanged &event);

    /** @brief Handle a change in game host. */
    void eventGameHostChanged(const Event_GameHostChanged &event, int eventPlayerId, const GameEventContext &context);

    /** @brief Handle the game being closed by the server. */
    void eventGameClosed(const Event_GameClosed &event, int eventPlayerId, const GameEventContext &context);

    /** @brief Handle a change of the active player. */
    void eventSetActivePlayer(const Event_SetActivePlayer &event, int eventPlayerId, const GameEventContext &context);

    /** @brief Handle a change of the active phase. */
    void eventSetActivePhase(const Event_SetActivePhase &event, int eventPlayerId, const GameEventContext &context);

    /** @brief Handle a turn reversal event. */
    void eventReverseTurn(const Event_ReverseTurn &event, int eventPlayerId, const GameEventContext &context);

    /** @brief Handle a change of the seating / turn order. */
    void
    eventPlayerOrderChanged(const Event_PlayerOrderChanged &event, int eventPlayerId, const GameEventContext &context);

    /** @brief Handle ping / latency updates. */
    void eventPing(const Event_Ping &event, int eventPlayerId, const GameEventContext &context);

    /** @} */

    /** @name Player lifecycle and property handlers
     *  Events related to players joining, leaving, or changing state.
     *  @{
     */

    /**
     * @brief Handle updates to a player's properties.
     *
     * Includes readiness, concede state, deck selection, sideboard lock,
     * and connection state changes.
     */
    void eventPlayerPropertiesChanged(const Event_PlayerPropertiesChanged &event,
                                      int eventPlayerId,
                                      const GameEventContext &context);

    /** @brief Handle a player or spectator joining the game. */
    void eventJoin(const Event_Join &event, int eventPlayerId, const GameEventContext &context);

    /** @brief Handle a player leaving the game. */
    void eventLeave(const Event_Leave &event, int eventPlayerId, const GameEventContext &context);

    /** @brief Handle the local player being kicked from the game. */
    void eventKicked(const Event_Kicked &event, int eventPlayerId, const GameEventContext &context);

    /**
     * @brief Convert a leave reason enum to a human-readable string.
     */
    QString getLeaveReason(Event_Leave::LeaveReason reason);

    /** @} */

public slots:
    /** @name Command dispatch slots
     *  Low-level command transmission.
     *  @{
     */

    /**
     * @brief Send a prepared PendingCommand.
     *
     * @param pend Pending command to send.
     * @param playerId Player whose client should send the command.
     */
    void sendGameCommand(PendingCommand *pend, int playerId = -1);

    /**
     * @brief Send a single protobuf command.
     *
     * @param command Protobuf command message.
     * @param playerId Player whose client should send the command.
     */
    void sendGameCommand(const ::google::protobuf::Message &command, int playerId = -1);

    /**
     * @brief Called when a PendingCommand finishes execution.
     *
     * Used to detect server-side errors such as chat flood protection.
     */
    void commandFinished(const Response &response);

    /** @} */

signals:
    /** @name Core state signals
     *  @{
     */

    void emitUserEvent();
    void containerProcessingStarted(GameEventContext context);
    void containerProcessingDone();
    void gameFlooded();
    void setContextJudgeName(QString judgeName);

    /** @} */

    /** @name Player and spectator signals
     *  @{
     */

    void addPlayerToAutoCompleteList(QString playerName);
    void localPlayerDeckSelected(PlayerLogic *localPlayer, int playerId, ServerInfo_Player playerInfo);
    void remotePlayerDeckSelected(QString deckList, int playerId, QString playerName);
    void remotePlayersDecksSelected(QVector<QPair<int, QPair<QString, QString>>> opponentDecks);
    void localPlayerSideboardLocked(int playerId, bool sideboardLocked);
    void localPlayerReadyStateChanged(int playerId, bool ready);

    /** @} */

    /** @name Game flow signals
     *  @{
     */

    void gameStopped();
    void gameClosed();
    void playerPropertiesChanged(const ServerInfo_PlayerProperties &prop, int playerId);
    void playerJoined(const ServerInfo_PlayerProperties &playerInfo);
    void playerLeft(int leavingPlayerId);
    void playerKicked();
    void spectatorJoined(const ServerInfo_PlayerProperties &spectatorInfo);
    void spectatorLeft(int leavingSpectatorId);
    void arrowDeleted(int creatorId, int arrowId);

    /** @} */

    /** @name Logging signals
     *  Signals consumed by MessageLogWidget.
     *  @{
     */

    void logSpectatorSay(ServerInfo_User userInfo, QString message);
    void logSpectatorLeave(QString name, QString reason);
    void logGameStart();
    void logReadyStart(PlayerLogic *player);
    void logNotReadyStart(PlayerLogic *player);
    void logDeckSelect(PlayerLogic *player, QString deckHash, int sideboardSize);
    void logSideboardLockSet(PlayerLogic *player, bool sideboardLocked);
    void logConnectionStateChanged(PlayerLogic *player, bool connected);
    void logJoinSpectator(QString spectatorName);
    void logJoinPlayer(PlayerLogic *player);
    void logLeave(PlayerLogic *player, QString reason);
    void logKicked();
    void logTurnReversed(PlayerLogic *player, bool reversed);
    void logTurnOrderChanged(QStringList playerNames, bool randomized);
    void logGameClosed();
    void logActivePlayer(PlayerLogic *activePlayer);
    void logActivePhaseChanged(int activePhase);
    void logConcede(int playerId);
    void logUnconcede(int playerId);

    /** @} */
};

#endif // COCKATRICE_GAME_EVENT_HANDLER_H