Documentation

marl_factory_grid/modules/doors/actions.py

@@ -1,16 +1,18 @@
 from typing import Union
 
 from marl_factory_grid.environment.actions import Action
+from marl_factory_grid.modules.doors import constants as d
 from marl_factory_grid.modules.doors.entitites import Door
-from marl_factory_grid.modules.doors import constants as d, rewards as r
-from marl_factory_grid.environment import constants as c
 from marl_factory_grid.utils.results import ActionResult
 
 
 class DoorUse(Action):
 
     def __init__(self, **kwargs):
-        super().__init__(d.ACTION_DOOR_USE, r.USE_DOOR_VALID, r.USE_DOOR_FAIL, **kwargs)
+        """
+        Attempts to interact with door (open/close it) and returns an action result if successful.
+        """
+        super().__init__(d.ACTION_DOOR_USE, d.REWARD_USE_DOOR_VALID, d.REWARD_USE_DOOR_FAIL, **kwargs)
 
     def do(self, entity, state) -> Union[None, ActionResult]:
         # Check if agent really is standing on a door:
@@ -26,6 +28,6 @@ class DoorUse(Action):
             except AttributeError:
                 pass
         if not valid:
-            # When he doesn't stand necxxt to a door tell me.
+            # When he doesn't stand next to a door tell me.
             state.print(f'{entity.name} just tried to use a door at {entity.pos}, but there is none.')
         return self.get_result(valid, entity)

marl_factory_grid/modules/doors/constants.py

@@ -16,3 +16,7 @@ STATE_OPEN              = 'open'                # Identifier to compare door-is-
 
 # Actions
 ACTION_DOOR_USE         = 'use_door'            # Identifier for door-action
+
+# Rewards
+REWARD_USE_DOOR_VALID: float = -0.00            # Reward for successful door use
+REWARD_USE_DOOR_FAIL: float = -0.01             # Reward for unsuccessful door use

marl_factory_grid/modules/doors/entitites.py

@@ -1,3 +1,5 @@
+from typing import Union
+
 from marl_factory_grid.environment.entity.entity import Entity
 from marl_factory_grid.utils import Result
 from marl_factory_grid.utils.utility_classes import RenderEntity
@@ -16,6 +18,9 @@ class DoorIndicator(Entity):
         return []
 
     def __init__(self, *args, **kwargs):
+        """
+        Is added around a door for agents to see.
+        """
         super().__init__(*args, **kwargs)
         self.__delattr__('move')
 
@@ -39,22 +44,38 @@ class Door(Entity):
         return d.VALUE_CLOSED_DOOR if self.is_closed else d.VALUE_OPEN_DOOR
 
     @property
-    def str_state(self):
+    def str_state(self) -> str:
+        """
+        Internal Usage
+        """
         return 'open' if self.is_open else 'closed'
 
     @property
-    def is_closed(self):
+    def is_closed(self) -> bool:
         return self._state == d.STATE_CLOSED
 
     @property
-    def is_open(self):
+    def is_open(self) -> bool:
         return self._state == d.STATE_OPEN
 
     @property
     def time_to_close(self):
+        """
+        :returns: The time it takes for the door to close.
+        :rtype: float
+        """
         return self._time_to_close
 
     def __init__(self, *args, closed_on_init=True, auto_close_interval=10, **kwargs):
+        """
+        A door entity that can be opened or closed by agents or rules.
+
+        :param closed_on_init: Whether the door spawns as open or closed.
+        :type closed_on_init: bool
+
+        :param auto_close_interval: after how many steps should the door automatically close itself,
+        :type auto_close_interval: int
+        """
         self._state = d.STATE_CLOSED
         super(Door, self).__init__(*args, **kwargs)
         self._auto_close_interval = auto_close_interval
@@ -73,14 +94,17 @@ class Door(Entity):
         name, state = 'door_open' if self.is_open else 'door_closed', 'blank'
         return RenderEntity(name, self.pos, 1, 'none', state, self.u_int + 1)
 
-    def use(self):
+    def use(self) -> bool:
+        """
+        Internal usage
+        """
         if self._state == d.STATE_OPEN:
             self._close()
         else:
             self._open()
         return c.VALID
 
-    def tick(self, state):
+    def tick(self, state) -> Union[Result, None]:
         # Check if no entity is standing in the door
         if len(state.entities.pos_dict[self.pos]) <= 2:
             if self.is_open and self.time_to_close:
@@ -97,23 +121,38 @@ class Door(Entity):
             self._reset_timer()
             return Result(f"{d.DOOR}_reset", c.VALID, entity=self)
 
-    def _open(self):
+    def _open(self) -> bool:
+        """
+        Internal Usage
+        """
         self._state = d.STATE_OPEN
         self._reset_timer()
         return True
 
-    def _close(self):
+    def _close(self) -> bool:
+        """
+        Internal Usage
+        """
         self._state = d.STATE_CLOSED
         return True
 
-    def _decrement_timer(self):
+    def _decrement_timer(self) -> bool:
+        """
+        Internal Usage
+        """
         self._time_to_close -= 1
         return True
 
-    def _reset_timer(self):
+    def _reset_timer(self) -> bool:
+        """
+        Internal Usage
+        """
         self._time_to_close = self._auto_close_interval
         return True
 
     def reset(self):
+        """
+        Internal Usage
+        """
         self._close()
         self._reset_timer()

marl_factory_grid/modules/doors/groups.py

@@ -1,6 +1,9 @@
+from typing import List
+
 from marl_factory_grid.environment.groups.collection import Collection
 from marl_factory_grid.modules.doors import constants as d
 from marl_factory_grid.modules.doors.entitites import Door
+from marl_factory_grid.utils import Result
 
 
 class Doors(Collection):
@@ -13,16 +16,18 @@ class Doors(Collection):
         return True
 
     def __init__(self, *args, **kwargs):
+        """
+        A collection of doors that can tick and reset all doors.
+        """
         super(Doors, self).__init__(*args, can_collide=True, **kwargs)
 
-    def tick_doors(self, state):
+    def tick_doors(self, state) -> List[Result]:
         results = list()
         for door in self:
             assert isinstance(door, Door)
             tick_result = door.tick(state)
             if tick_result is not None:
                 results.append(tick_result)
-        # TODO: Should return a Result object, not a random dict.
         return results
 
     def reset(self):

marl_factory_grid/modules/doors/rewards.py

@@ -1,2 +0,0 @@
-USE_DOOR_VALID: float = -0.00
-USE_DOOR_FAIL: float = -0.01