:py:mod:`socha.api.networking.game_client`
==========================================

.. py:module:: socha.api.networking.game_client

.. autoapi-nested-parse::

   This module handles the communication with the api and the students' logic.



Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   socha.api.networking.game_client.IClientHandler
   socha.api.networking.game_client.GameClient




.. py:class:: IClientHandler


   .. py:attribute:: history
      :type: List[List[Union[socha._socha.GameState, socha.api.protocol.protocol.Error, socha.api.protocol.protocol.Result]]]
      :value: []

      

   .. py:method:: calculate_move() -> socha._socha.Move

      Calculates a move that the logic wants the server to perform in the game room.


   .. py:method:: on_update(state: socha._socha.GameState) -> None

      If the server _send an update on the current state of the game this method is called.
      :param state: The current state that server sent.


   .. py:method:: on_game_over(roomMessage: socha.api.protocol.protocol.Result) -> None

      If the game has ended the server will _send a result message.
      This method will call if this happens.

      :param roomMessage: The Result the server has sent.


   .. py:method:: on_error(logMessage: str) -> None

      If error occurs,
      for instance when the logic sent a move that is not rule conform,
      the server will _send an error message and closes the connection.
      If this happens, this method is called.

      :param logMessage: The message, that server sent.


   .. py:method:: on_room_message(data) -> None

      If the server sends a message that cannot be handheld by anny other method,
      this will be called.

      :param data: The data the Server sent.


   .. py:method:: on_game_prepared(message) -> None

      If the game has been prepared by the server this method will be called.

      :param message: The message that server sends with the response.


   .. py:method:: on_game_joined(room_id) -> None

      If the client has successfully joined a game room this method will be called.

      :param room_id: The room id the client has joined.


   .. py:method:: on_game_left() -> None

      If the server left the room, this method will be called.
      If the client is running on survive mode it'll be running until shut downed manually.


   .. py:method:: while_disconnected(player_client: GameClient) -> None

      The client loop will keep calling this method while there is no active connection to a game server.
      This can be used to do tasks after a game is finished and the server left.
      Please be aware, that the client has to be shut down manually if it is in survive mode.

      :type player_client: The player client in which the logic is integrated.
      :return: True if the client should shut down. False if the client should continue to run.


   .. py:method:: on_create_game(game_client: GameClient) -> None

      This method will be called if the client is in admin mode and the client has authenticated with the server.
      The client can now create a game.

      :param game_client: The client that is in admin mode.


   .. py:method:: on_prepared(game_client: GameClient, room_id: str, reservations: List[str]) -> None

      This method will be called if the client is in admin mode and the client has created a game.

      :param game_client: The client that is in admin mode.
      :param room_id: The room id of the game.
      :param reservations: The reservations of the game.


   .. py:method:: on_observed(game_client: GameClient, room_id: str)

      This method will be called if the client is in admin mode and the client is observing a game.

      :param game_client: The client that is in admin mode.
      :param room_id: The room id of the game.


   .. py:method:: while_waiting() -> None

      This method will be called while the client is waiting for the server to send a new message.
      This method is running threaded, which will be terminated without warning if the client receives a new message.



.. py:class:: GameClient(host: str, port: int, handler: IClientHandler, reservation: str, room_id: str, password: str, auto_reconnect: bool, survive: bool, headless: bool)


   Bases: :py:obj:`socha.api.networking.xml_protocol_interface.XMLProtocolInterface`

   The PlayerClient handles all incoming and outgoing objects accordingly to their types.

   .. py:method:: join_game()


   .. py:method:: join_game_room(room_id: str)


   .. py:method:: join_game_with_reservation(reservation: str)


   .. py:method:: authenticate(password: str)


   .. py:method:: create_game(player_1: socha.api.protocol.protocol.Slot, player_2: socha.api.protocol.protocol.Slot, game_type: str, pause: bool)


   .. py:method:: observe(room_id: str)


   .. py:method:: cancel(room_id: str)


   .. py:method:: step(room_id: str)


   .. py:method:: pause(room_id: str, pause: bool)


   .. py:method:: send_message_to_room(room_id: str, message)


   .. py:method:: _on_object(message)

      Process various types of messages related to a game.

      Args:
          message: The message object containing information about the game.

      Returns:
          None


   .. py:method:: _on_move_request(room_id)


   .. py:method:: _on_state(message)


   .. py:method:: start()

      Starts the client loop.


   .. py:method:: join() -> None

      Tries to join a game with a connected server. It uses the reservation, or room id to join.
      If they are not present it joins just without, as fallback.


   .. py:method:: _handle_left()


   .. py:method:: _client_loop()

      The client loop is the main loop, where the client waits for messages from the server
      and handles them accordingly.


   .. py:method:: stop()

      Disconnects from the server and stops the client loop.