pyrat.src.Player

This file is part of the PyRat library. It is meant to be used as a library, and not to be executed directly.

Please import necessary elements using the following syntax:

from pyrat import

View Source

  1#####################################################################################################################################################
  2######################################################################## INFO #######################################################################
  3#####################################################################################################################################################
  4
  5"""
  6    This file is part of the PyRat library.
  7    It is meant to be used as a library, and not to be executed directly.
  8    Please import necessary elements using the following syntax:
  9        from pyrat import <element_name>
 10"""
 11
 12#####################################################################################################################################################
 13###################################################################### IMPORTS ######################################################################
 14#####################################################################################################################################################
 15
 16# External imports
 17from typing import *
 18from typing_extensions import *
 19from numbers import *
 20import abc
 21
 22# PyRat imports
 23from pyrat.src.Maze import Maze
 24from pyrat.src.GameState import GameState
 25from pyrat.src.enums import Action, PlayerSkin
 26
 27#####################################################################################################################################################
 28###################################################################### CLASSES ######################################################################
 29#####################################################################################################################################################
 30
 31class Player (abc.ABC):
 32
 33    """
 34        This class is abstract and cannot be instantiated.
 35        You should use one of the subclasses to create a maze, or create your own subclass.
 36
 37        A player is an agent that can play a PyRat game.
 38        The preprocessing method is called once at the beginning of the game.
 39        The turn method is called at each turn of the game.
 40        The postprocessing method is called once at the end of the game.
 41        Only the turn method is mandatory.
 42        If you want to keep track of some information between turns, you can define a constructor and add attributes to the object.
 43        Check examples to see how to do it properly.
 44    """
 45
 46    #############################################################################################################################################
 47    #                                                               MAGIC METHODS                                                               #
 48    #############################################################################################################################################
 49
 50    def __init__ ( self: Self,
 51                   name: Optional[str] = None,
 52                   skin: PlayerSkin = PlayerSkin.RAT
 53                 ) ->    Self:
 54
 55        """
 56            This function is the constructor of the class.
 57            When an object is instantiated, this method is called to initialize the object.
 58            This is where you should define the attributes of the object and set their initial values.
 59            In:
 60                * self: Reference to the current object.
 61                * name: Name of the player (if None, we take the name of the class).
 62                * skin: Skin of the player.
 63            Out:
 64                * A new instance of the class.
 65        """
 66
 67        # Debug
 68        assert isinstance(name, (str, type(None))) # Type check for the name
 69        assert isinstance(skin, PlayerSkin) # Type check for the skin
 70
 71        # Private attributes
 72        self.__name = name if name is not None else self.__class__.__name__
 73        self.__skin = skin
 74
 75    #############################################################################################################################################
 76    #                                                            ATTRIBUTE ACCESSORS                                                            #
 77    #############################################################################################################################################
 78
 79    @property
 80    def name ( self: Self,
 81             ) ->    str:
 82        
 83        """
 84            Getter for __name.
 85            In:
 86                * self: Reference to the current object.
 87            Out:
 88                * self.__name: The __name attribute.
 89        """
 90
 91        # Get the attribute
 92        return self.__name
 93
 94    #############################################################################################################################################
 95
 96    @property
 97    def skin ( self: Self,
 98             ) ->    PlayerSkin:
 99        
100        """
101            Getter for __skin.
102            In:
103                * self: Reference to the current object.
104            Out:
105                * self.__skin: The __skin attribute.
106        """
107
108        # Get the attribute
109        return self.__skin
110
111    #############################################################################################################################################
112 
113    @skin.setter
114    def skin ( self:  Self,
115               value: PlayerSkin
116             ) ->     None:
117        
118        """
119            Setter for __skin.
120            In:
121                * self:  Reference to the current object.
122                * value: New value for the __skin attribute.
123            Out:
124                * None.
125        """
126
127        # Set the attribute
128        self.__skin = value
129
130    #############################################################################################################################################
131    #                                                               PUBLIC METHODS                                                              #
132    #############################################################################################################################################
133
134    def preprocessing ( self:       Self,
135                        maze:       Maze,
136                        game_state: GameState
137                      ) ->          None:
138        
139        """
140            This method can optionally be implemented in the child classes.
141            It is called once at the beginning of the game.
142            It is typically given more time than the turn function, to perform complex computations.
143            In:
144                * self:       Reference to the current object.
145                * maze:       An object representing the maze in which the player plays.
146                * game_state: An object representing the state of the game.
147            Out:
148                * None.
149        """
150
151        # Debug
152        assert isinstance(maze, Maze) # Type check for the maze
153        assert isinstance(game_state, GameState) # Type check for the game state
154
155        # By default, this method does nothing unless implemented in the child classes
156        pass
157
158    #############################################################################################################################################
159
160    @abc.abstractmethod
161    def turn ( self:       Self,
162               maze:       Maze,
163               game_state: GameState
164             ) ->          Action:
165
166        """
167            This method is abstract and must be implemented in the child classes.
168            It is called at each turn of the game.
169            It returns an action to perform among the possible actions, defined in the Action enumeration.
170            In:
171                * self:       Reference to the current object.
172                * maze:       An object representing the maze in which the player plays.
173                * game_state: An object representing the state of the game.
174            Out:
175                * action: One of the possible actions.
176        """
177
178        # Debug
179        assert isinstance(maze, Maze) # Type check for the maze
180        assert isinstance(game_state, GameState) # Type check for the game state
181
182        # This method must be implemented in the child classes
183        # By default we raise an error
184        raise NotImplementedError("This method must be implemented in the child classes.")
185
186#############################################################################################################################################
187
188    def postprocessing ( self:       Self,
189                         maze:       Maze,
190                         game_state: GameState,
191                         stats:      Dict[str, Any],
192                       ) ->          None:
193
194        """
195            This method can optionally be implemented in the child classes.
196            It is called once at the end of the game.
197            It is not timed, and can be used to make some cleanup, analyses of the completed game, model training, etc.
198            In:
199                * self:       Reference to the current object.
200                * maze:       An object representing the maze in which the player plays.
201                * game_state: An object representing the state of the game.
202                * stats:      Statistics about the game.
203            Out:
204                * None.
205        """
206
207        # Debug
208        assert isinstance(maze, Maze) # Type check for the maze
209        assert isinstance(game_state, GameState) # Type check for the game state
210        assert isinstance(stats, dict) # Type check for the stats
211        assert all(isinstance(key, str) for key in stats.keys()) # Type check for the keys of the stats
212
213        # By default, this method does nothing unless implemented in the child classes
214        pass
215
216#####################################################################################################################################################
217#####################################################################################################################################################

class Player(abc.ABC): View Source

 32class Player (abc.ABC):
 33
 34    """
 35        This class is abstract and cannot be instantiated.
 36        You should use one of the subclasses to create a maze, or create your own subclass.
 37
 38        A player is an agent that can play a PyRat game.
 39        The preprocessing method is called once at the beginning of the game.
 40        The turn method is called at each turn of the game.
 41        The postprocessing method is called once at the end of the game.
 42        Only the turn method is mandatory.
 43        If you want to keep track of some information between turns, you can define a constructor and add attributes to the object.
 44        Check examples to see how to do it properly.
 45    """
 46
 47    #############################################################################################################################################
 48    #                                                               MAGIC METHODS                                                               #
 49    #############################################################################################################################################
 50
 51    def __init__ ( self: Self,
 52                   name: Optional[str] = None,
 53                   skin: PlayerSkin = PlayerSkin.RAT
 54                 ) ->    Self:
 55
 56        """
 57            This function is the constructor of the class.
 58            When an object is instantiated, this method is called to initialize the object.
 59            This is where you should define the attributes of the object and set their initial values.
 60            In:
 61                * self: Reference to the current object.
 62                * name: Name of the player (if None, we take the name of the class).
 63                * skin: Skin of the player.
 64            Out:
 65                * A new instance of the class.
 66        """
 67
 68        # Debug
 69        assert isinstance(name, (str, type(None))) # Type check for the name
 70        assert isinstance(skin, PlayerSkin) # Type check for the skin
 71
 72        # Private attributes
 73        self.__name = name if name is not None else self.__class__.__name__
 74        self.__skin = skin
 75
 76    #############################################################################################################################################
 77    #                                                            ATTRIBUTE ACCESSORS                                                            #
 78    #############################################################################################################################################
 79
 80    @property
 81    def name ( self: Self,
 82             ) ->    str:
 83        
 84        """
 85            Getter for __name.
 86            In:
 87                * self: Reference to the current object.
 88            Out:
 89                * self.__name: The __name attribute.
 90        """
 91
 92        # Get the attribute
 93        return self.__name
 94
 95    #############################################################################################################################################
 96
 97    @property
 98    def skin ( self: Self,
 99             ) ->    PlayerSkin:
100        
101        """
102            Getter for __skin.
103            In:
104                * self: Reference to the current object.
105            Out:
106                * self.__skin: The __skin attribute.
107        """
108
109        # Get the attribute
110        return self.__skin
111
112    #############################################################################################################################################
113 
114    @skin.setter
115    def skin ( self:  Self,
116               value: PlayerSkin
117             ) ->     None:
118        
119        """
120            Setter for __skin.
121            In:
122                * self:  Reference to the current object.
123                * value: New value for the __skin attribute.
124            Out:
125                * None.
126        """
127
128        # Set the attribute
129        self.__skin = value
130
131    #############################################################################################################################################
132    #                                                               PUBLIC METHODS                                                              #
133    #############################################################################################################################################
134
135    def preprocessing ( self:       Self,
136                        maze:       Maze,
137                        game_state: GameState
138                      ) ->          None:
139        
140        """
141            This method can optionally be implemented in the child classes.
142            It is called once at the beginning of the game.
143            It is typically given more time than the turn function, to perform complex computations.
144            In:
145                * self:       Reference to the current object.
146                * maze:       An object representing the maze in which the player plays.
147                * game_state: An object representing the state of the game.
148            Out:
149                * None.
150        """
151
152        # Debug
153        assert isinstance(maze, Maze) # Type check for the maze
154        assert isinstance(game_state, GameState) # Type check for the game state
155
156        # By default, this method does nothing unless implemented in the child classes
157        pass
158
159    #############################################################################################################################################
160
161    @abc.abstractmethod
162    def turn ( self:       Self,
163               maze:       Maze,
164               game_state: GameState
165             ) ->          Action:
166
167        """
168            This method is abstract and must be implemented in the child classes.
169            It is called at each turn of the game.
170            It returns an action to perform among the possible actions, defined in the Action enumeration.
171            In:
172                * self:       Reference to the current object.
173                * maze:       An object representing the maze in which the player plays.
174                * game_state: An object representing the state of the game.
175            Out:
176                * action: One of the possible actions.
177        """
178
179        # Debug
180        assert isinstance(maze, Maze) # Type check for the maze
181        assert isinstance(game_state, GameState) # Type check for the game state
182
183        # This method must be implemented in the child classes
184        # By default we raise an error
185        raise NotImplementedError("This method must be implemented in the child classes.")
186
187#############################################################################################################################################
188
189    def postprocessing ( self:       Self,
190                         maze:       Maze,
191                         game_state: GameState,
192                         stats:      Dict[str, Any],
193                       ) ->          None:
194
195        """
196            This method can optionally be implemented in the child classes.
197            It is called once at the end of the game.
198            It is not timed, and can be used to make some cleanup, analyses of the completed game, model training, etc.
199            In:
200                * self:       Reference to the current object.
201                * maze:       An object representing the maze in which the player plays.
202                * game_state: An object representing the state of the game.
203                * stats:      Statistics about the game.
204            Out:
205                * None.
206        """
207
208        # Debug
209        assert isinstance(maze, Maze) # Type check for the maze
210        assert isinstance(game_state, GameState) # Type check for the game state
211        assert isinstance(stats, dict) # Type check for the stats
212        assert all(isinstance(key, str) for key in stats.keys()) # Type check for the keys of the stats
213
214        # By default, this method does nothing unless implemented in the child classes
215        pass

This class is abstract and cannot be instantiated. You should use one of the subclasses to create a maze, or create your own subclass.

A player is an agent that can play a PyRat game. The preprocessing method is called once at the beginning of the game. The turn method is called at each turn of the game. The postprocessing method is called once at the end of the game. Only the turn method is mandatory. If you want to keep track of some information between turns, you can define a constructor and add attributes to the object. Check examples to see how to do it properly.

Player( name: Optional[str] = None, skin: pyrat.src.enums.PlayerSkin = <PlayerSkin.RAT: 'rat'>) View Source

51    def __init__ ( self: Self,
52                   name: Optional[str] = None,
53                   skin: PlayerSkin = PlayerSkin.RAT
54                 ) ->    Self:
55
56        """
57            This function is the constructor of the class.
58            When an object is instantiated, this method is called to initialize the object.
59            This is where you should define the attributes of the object and set their initial values.
60            In:
61                * self: Reference to the current object.
62                * name: Name of the player (if None, we take the name of the class).
63                * skin: Skin of the player.
64            Out:
65                * A new instance of the class.
66        """
67
68        # Debug
69        assert isinstance(name, (str, type(None))) # Type check for the name
70        assert isinstance(skin, PlayerSkin) # Type check for the skin
71
72        # Private attributes
73        self.__name = name if name is not None else self.__class__.__name__
74        self.__skin = skin

This function is the constructor of the class. When an object is instantiated, this method is called to initialize the object. This is where you should define the attributes of the object and set their initial values.

In:

self: Reference to the current object.

name: Name of the player (if None, we take the name of the class).

skin: Skin of the player.

Out:

A new instance of the class.

name: str View Source

80    @property
81    def name ( self: Self,
82             ) ->    str:
83        
84        """
85            Getter for __name.
86            In:
87                * self: Reference to the current object.
88            Out:
89                * self.__name: The __name attribute.
90        """
91
92        # Get the attribute
93        return self.__name

Getter for __name.

In:

self: Reference to the current object.

Out:

self.__name: The __name attribute.

skin: pyrat.src.enums.PlayerSkin View Source

 97    @property
 98    def skin ( self: Self,
 99             ) ->    PlayerSkin:
100        
101        """
102            Getter for __skin.
103            In:
104                * self: Reference to the current object.
105            Out:
106                * self.__skin: The __skin attribute.
107        """
108
109        # Get the attribute
110        return self.__skin

Getter for __skin.

In:

self: Reference to the current object.

Out:

self.__skin: The __skin attribute.

def preprocessing( self: typing_extensions.Self, maze: pyrat.src.Maze.Maze, game_state: pyrat.src.GameState.GameState) -> None: View Source

135    def preprocessing ( self:       Self,
136                        maze:       Maze,
137                        game_state: GameState
138                      ) ->          None:
139        
140        """
141            This method can optionally be implemented in the child classes.
142            It is called once at the beginning of the game.
143            It is typically given more time than the turn function, to perform complex computations.
144            In:
145                * self:       Reference to the current object.
146                * maze:       An object representing the maze in which the player plays.
147                * game_state: An object representing the state of the game.
148            Out:
149                * None.
150        """
151
152        # Debug
153        assert isinstance(maze, Maze) # Type check for the maze
154        assert isinstance(game_state, GameState) # Type check for the game state
155
156        # By default, this method does nothing unless implemented in the child classes
157        pass

This method can optionally be implemented in the child classes. It is called once at the beginning of the game. It is typically given more time than the turn function, to perform complex computations.

In:

self: Reference to the current object.

maze: An object representing the maze in which the player plays.

game_state: An object representing the state of the game.

Out:

None.

@abc.abstractmethod

def turn( self: typing_extensions.Self, maze: pyrat.src.Maze.Maze, game_state: pyrat.src.GameState.GameState) -> pyrat.src.enums.Action: View Source

161    @abc.abstractmethod
162    def turn ( self:       Self,
163               maze:       Maze,
164               game_state: GameState
165             ) ->          Action:
166
167        """
168            This method is abstract and must be implemented in the child classes.
169            It is called at each turn of the game.
170            It returns an action to perform among the possible actions, defined in the Action enumeration.
171            In:
172                * self:       Reference to the current object.
173                * maze:       An object representing the maze in which the player plays.
174                * game_state: An object representing the state of the game.
175            Out:
176                * action: One of the possible actions.
177        """
178
179        # Debug
180        assert isinstance(maze, Maze) # Type check for the maze
181        assert isinstance(game_state, GameState) # Type check for the game state
182
183        # This method must be implemented in the child classes
184        # By default we raise an error
185        raise NotImplementedError("This method must be implemented in the child classes.")

This method is abstract and must be implemented in the child classes. It is called at each turn of the game. It returns an action to perform among the possible actions, defined in the Action enumeration.

In:

self: Reference to the current object.

maze: An object representing the maze in which the player plays.

game_state: An object representing the state of the game.

Out:

action: One of the possible actions.

def postprocessing( self: typing_extensions.Self, maze: pyrat.src.Maze.Maze, game_state: pyrat.src.GameState.GameState, stats: Dict[str, typing_extensions.Any]) -> None: View Source

189    def postprocessing ( self:       Self,
190                         maze:       Maze,
191                         game_state: GameState,
192                         stats:      Dict[str, Any],
193                       ) ->          None:
194
195        """
196            This method can optionally be implemented in the child classes.
197            It is called once at the end of the game.
198            It is not timed, and can be used to make some cleanup, analyses of the completed game, model training, etc.
199            In:
200                * self:       Reference to the current object.
201                * maze:       An object representing the maze in which the player plays.
202                * game_state: An object representing the state of the game.
203                * stats:      Statistics about the game.
204            Out:
205                * None.
206        """
207
208        # Debug
209        assert isinstance(maze, Maze) # Type check for the maze
210        assert isinstance(game_state, GameState) # Type check for the game state
211        assert isinstance(stats, dict) # Type check for the stats
212        assert all(isinstance(key, str) for key in stats.keys()) # Type check for the keys of the stats
213
214        # By default, this method does nothing unless implemented in the child classes
215        pass

This method can optionally be implemented in the child classes. It is called once at the end of the game. It is not timed, and can be used to make some cleanup, analyses of the completed game, model training, etc.

In:

self: Reference to the current object.

maze: An object representing the maze in which the player plays.

game_state: An object representing the state of the game.

stats: Statistics about the game.

Out:

None.