Did a big refactor of how the board holds information to allow for multiple markers occupying the same location.

Author: eriq-augustine

pacai/boards/__init__.py

@@ -0,0 +1,4 @@
+"""
+The `pacai.boards` package provides no actual code,
+but instead provides default game boards that can be used for this project.
+"""

pacai/core/__init__.py

@@ -0,0 +1,4 @@
+"""
+The `pacai.core` package provides the core game engine, infrastructure, and abstractions for creating games.
+This package contains no actual game logic or resources, just the infrastructure for running them.
+"""

pacai/core/action.py

@@ -3,11 +3,33 @@
 Default actions are provided, but custom actions can be easily created.
 """
 
+import typing
+
+import pacai.core.time
+
 class Action(str):
     """ An action that an agent is allowed to take. """
 
     pass
 
+class ActionRecord(typing.NamedTuple):
+    """
+    The result of requesting an action from an agent.
+    Aside from the action, this also includes timing and crashing information.
+    """
+
+    agent_index: int
+    """ The index of the agent making this action. """
+
+    action: Action
+    """ The action returned by the agent (or pacai.core.action.STOP on a crash). """
+
+    duration: pacai.core.time.Duration
+    """ The duration (in MS) the agent took to compute this action. """
+
+    crashed: bool
+    """ Whether or not the agent crashed (e.g., raised an exception) when computing this action. """
+
 NORTH = Action("north")
 EAST = Action("east")
 SOUTH = Action("south")

pacai/core/agent.py

@@ -43,14 +43,33 @@ def __init__(self, args: AgentArguments) -> None:
 
     @abc.abstractmethod
     def get_action(self, state: pacai.core.gamestate.GameState) -> pacai.core.action.Action:
+        """
+        Get an action for this agent given the current state of the game.
+        Agents may keep internal state, but the given state should be considered the source of truth.
+        Calls to this method may be subject to a timeout.
+        """
+
         pass
 
     @abc.abstractmethod
     def game_start(self, agent_index: int, suggested_seed: int, initial_state: pacai.core.gamestate.GameState) -> None:
+        """
+        Notify this agent that the game is about to start.
+        The provided agent index is the game's index/id for this agent.
+        The state represents the initial state of the game.
+        Any precomputation for this game should be done in this method.
+        Calls to this method may be subject to a timeout.
+        """
+
         pass
 
     @abc.abstractmethod
     def game_complete(self, final_state: pacai.core.gamestate.GameState) -> None:
+        """
+        Notify this agent that the game has concluded.
+        Agents should use this as an opportunity to make any final calculations and close any game-related resources.
+        """
+
         pass
 
 class Ticket(typing.NamedTuple):
@@ -79,24 +98,6 @@ def next(self, move_delay: int) -> 'Ticket':
             num_moves = self.num_moves + 1,
         )
 
-class ActionRecord(typing.NamedTuple):
-    """
-    The result of requesting an action from an agent.
-    Aside from the action, this also includes timing and crashing information.
-    """
-
-    agent_index: int
-    """ The index of the agent making this action. """
-
-    action: pacai.core.action.Action
-    """ The action returned by the agent (or pacai.core.action.STOP on a crash). """
-
-    duration: pacai.core.time.Duration
-    """ The duration (in MS) the agent took to compute this action. """
-
-    crashed: bool
-    """ Whether or not the agent crashed (e.g., raised an exception) when computing this action. """
-
 def load(arguments: AgentArguments) -> Agent:
     # TEST
     raise NotImplementedError()