steffen/marl-factory-grid
1
0
Fork 0
mirror of https://github.com/illiumst/marl-factory-grid.git synced 2025-07-05 17:11:35 +02:00
Code Issues Packages Projects Releases Wiki Activity

added documentation for environment entity and factory

Browse Source
This commit is contained in:
Joel Friedrich
2024-01-05 14:26:09 +01:00
parent 3cd5caed93
commit f35944cc55
5 changed files with 146 additions and 140 deletions
Download Patch File Download Diff File Expand all files Collapse all files

156
marl_factory_grid/environment/entity/entity.py
View File

@ -13,30 +13,28 @@ class Entity(Object, abc.ABC):
@property @property
def state(self): def state(self):
""" """
TODO Get the current status of the entity. Not to be confused with the Gamestate.
:return: status
:return:
""" """
return self._status or State(entity=self, identifier=c.NOOP, validity=c.VALID) return self._status or State(entity=self, identifier=c.NOOP, validity=c.VALID)
@property @property
def var_has_position(self): def var_has_position(self):
""" """
TODO Check if the entity has a position.
:return: True if the entity has a position, False otherwise.
:return: :rtype: bool
""" """
return self.pos != c.VALUE_NO_POS return self.pos != c.VALUE_NO_POS
@property @property
def var_is_blocking_light(self): def var_is_blocking_light(self):
""" """
TODO Check if the entity is blocking light.
:return: True if the entity is blocking light, False otherwise.
:return: :rtype: bool
""" """
try: try:
return self._collection.var_is_blocking_light or False return self._collection.var_is_blocking_light or False
@ -46,10 +44,10 @@ class Entity(Object, abc.ABC):
@property @property
def var_can_move(self): def var_can_move(self):
""" """
TODO Check if the entity can move.
:return: True if the entity can move, False otherwise.
:return: :rtype: bool
""" """
try: try:
return self._collection.var_can_move or False return self._collection.var_can_move or False
@ -59,10 +57,10 @@ class Entity(Object, abc.ABC):
@property @property
def var_is_blocking_pos(self): def var_is_blocking_pos(self):
""" """
TODO Check if the entity is blocking a position when standing on it.
:return: True if the entity is blocking a position, False otherwise.
:return: :rtype: bool
""" """
try: try:
return self._collection.var_is_blocking_pos or False return self._collection.var_is_blocking_pos or False
@ -72,10 +70,10 @@ class Entity(Object, abc.ABC):
@property @property
def var_can_collide(self): def var_can_collide(self):
""" """
TODO Check if the entity can collide.
:return: True if the entity can collide, False otherwise.
:return: :rtype: bool
""" """
try: try:
return self._collection.var_can_collide or False return self._collection.var_can_collide or False
@ -85,39 +83,40 @@ class Entity(Object, abc.ABC):
@property @property
def x(self): def x(self):
""" """
TODO Get the x-coordinate of the entity's position.
:return: The x-coordinate of the entity's position.
:return: :rtype: int
""" """
return self.pos[0] return self.pos[0]
@property @property
def y(self): def y(self):
""" """
TODO Get the y-coordinate of the entity's position.
:return: The y-coordinate of the entity's position.
:return: :rtype: int
""" """
return self.pos[1] return self.pos[1]
@property @property
def pos(self): def pos(self):
""" """
TODO Get the current position of the entity.
:return: The current position of the entity.
:return: :rtype: tuple
""" """
return self._pos return self._pos
def set_pos(self, pos) -> bool: def set_pos(self, pos) -> bool:
""" """
TODO Set the position of the entity.
:param pos: The new position.
:return: :type pos: tuple
:return: True if setting the position is successful, False otherwise.
""" """
assert isinstance(pos, tuple) and len(pos) == 2 assert isinstance(pos, tuple) and len(pos) == 2
self._pos = pos self._pos = pos
@ -126,10 +125,10 @@ class Entity(Object, abc.ABC):
@property @property
def last_pos(self): def last_pos(self):
""" """
TODO Get the last position of the entity.
:return: The last position of the entity.
:return: :rtype: tuple
""" """
try: try:
return self._last_pos return self._last_pos
@ -141,22 +140,49 @@ class Entity(Object, abc.ABC):
@property @property
def direction_of_view(self): def direction_of_view(self):
""" """
TODO Get the current direction of view of the entity.
:return: The current direction of view of the entity.
:return: :rtype: int
""" """
if self._last_pos != c.VALUE_NO_POS: if self._last_pos != c.VALUE_NO_POS:
return 0, 0 return 0, 0
else: else:
return np.subtract(self._last_pos, self.pos) return np.subtract(self._last_pos, self.pos)
def __init__(self, pos, bind_to=None, **kwargs):
"""
Abstract base class representing entities in the environment grid.
:param pos: The initial position of the entity.
:type pos: tuple
:param bind_to: Entity to which this entity is bound (Default: None)
:type bind_to: Entity or None
"""
super().__init__(**kwargs)
self._view_directory = c.VALUE_NO_POS
self._status = None
self._pos = pos
self._last_pos = pos
self._collection = None
if bind_to:
try:
self.bind_to(bind_to)
except AttributeError:
print(f'Objects of class "{self.__class__.__name__}" can not be bound to other entities.')
exit()
def move(self, next_pos, state): def move(self, next_pos, state):
""" """
TODO Move the entity to a new position.
:param next_pos: The next position to move the entity to.
:type next_pos: tuple
:param state: The current state of the environment.
:type state: marl_factory_grid.environment.state.Gamestate
:return: :return: True if the move is valid, False otherwise.
:rtype: bool
""" """
next_pos = next_pos next_pos = next_pos
curr_pos = self._pos curr_pos = self._pos
@ -172,43 +198,22 @@ class Entity(Object, abc.ABC):
# Bad naming... Was the same was the same pos, not moving.... # Bad naming... Was the same was the same pos, not moving....
return not_same_pos return not_same_pos
def __init__(self, pos, bind_to=None, **kwargs):
"""
Full Env Entity that lives on the environment Grid. Doors, Items, DirtPile etc...
TODO
:return:
"""
super().__init__(**kwargs)
self._view_directory = c.VALUE_NO_POS
self._status = None
self._pos = pos
self._last_pos = pos
self._collection = None
if bind_to:
try:
self.bind_to(bind_to)
except AttributeError:
print(f'Objects of class "{self.__class__.__name__}" can not be bound to other entities.')
exit()
def summarize_state(self) -> dict: def summarize_state(self) -> dict:
""" """
TODO Summarize the current state of the entity.
:return: A dictionary containing the name, x-coordinate, y-coordinate, and can_collide property of the entity.
:return: :rtype: dict
""" """
return dict(name=str(self.name), x=int(self.x), y=int(self.y), can_collide=bool(self.var_can_collide)) return dict(name=str(self.name), x=int(self.x), y=int(self.y), can_collide=bool(self.var_can_collide))
@abc.abstractmethod @abc.abstractmethod
def render(self): def render(self):
""" """
TODO Abstract method to render the entity.
:return: A rendering entity representing the entity's appearance in the environment.
:return: :rtype: marl_factory_grid.utils.utility_classes.RenderEntity
""" """
return RenderEntity(self.__class__.__name__.lower(), self.pos) return RenderEntity(self.__class__.__name__.lower(), self.pos)
@ -223,19 +228,22 @@ class Entity(Object, abc.ABC):
@property @property
def encoding(self): def encoding(self):
""" """
TODO Get the encoded representation of the entity.
:return: The encoded representation.
:return: :rtype: int
""" """
return c.VALUE_OCCUPIED_CELL return c.VALUE_OCCUPIED_CELL
def change_parent_collection(self, other_collection): def change_parent_collection(self, other_collection):
""" """
TODO Change the parent collection of the entity.
:param other_collection: The new parent collection.
:type other_collection: marl_factory_grid.environment.collections.Collection
:return: :return: True if the change is successful, False otherwise.
:rtype: bool
""" """
other_collection.add_item(self) other_collection.add_item(self)
self._collection.delete_env_object(self) self._collection.delete_env_object(self)
@ -245,9 +253,9 @@ class Entity(Object, abc.ABC):
@property @property
def collection(self): def collection(self):
""" """
TODO Get the parent collection of the entity.
:return: The parent collection.
:return: :rtype: marl_factory_grid.environment.collections.Collection
""" """
return self._collection return self._collection

51
marl_factory_grid/environment/entity/object.py
View File

@ -12,17 +12,15 @@ class Object:
@property @property
def bound_entity(self): def bound_entity(self):
""" """
TODO Returns the entity to which this object is bound.
:return: The bound entity.
:return:
""" """
return self._bound_entity return self._bound_entity
@property @property
def var_can_be_bound(self) -> bool: def var_can_be_bound(self) -> bool:
""" """
TODO
Indicates if it is possible to bind this object to another Entity or Object. Indicates if it is possible to bind this object to another Entity or Object.
:return: Whether this object can be bound. :return: Whether this object can be bound.
@ -35,30 +33,27 @@ class Object:
@property @property
def observers(self) -> set: def observers(self) -> set:
""" """
TODO Returns the set of observers for this object.
:return: Set of observers.
:return:
""" """
return self._observers return self._observers
@property @property
def name(self): def name(self):
""" """
TODO Returns a string representation of the object's name.
:return: The name of the object.
:return:
""" """
return f'{self.__class__.__name__}[{self.identifier}]' return f'{self.__class__.__name__}[{self.identifier}]'
@property @property
def identifier(self): def identifier(self):
""" """
TODO Returns the unique identifier of the object.
:return: The unique identifier.
:return:
""" """
if self._str_ident is not None: if self._str_ident is not None:
return self._str_ident return self._str_ident
@ -67,23 +62,19 @@ class Object:
def reset_uid(self): def reset_uid(self):
""" """
TODO Resets the unique identifier counter for this class.
:return: True if the reset was successful.
:return:
""" """
self._u_idx = defaultdict(lambda: 0) self._u_idx = defaultdict(lambda: 0)
return True return True
def __init__(self, str_ident: Union[str, None] = None, **kwargs): def __init__(self, str_ident: Union[str, None] = None, **kwargs):
""" """
Generell Objects for Organisation and Maintanance such as Actions etc... General Objects for Organisation and Maintenance such as Actions, etc.
TODO :param str_ident: A string identifier for the object.
:return: None
:param str_ident:
:return:
""" """
self._status = None self._status = None
self._bound_entity = None self._bound_entity = None
@ -147,28 +138,28 @@ class Object:
def bind_to(self, entity): def bind_to(self, entity):
""" """
TODO Binds the object to a specified entity.
:param entity: The entity to bind to.
:return: :return: The validity of the binding.
""" """
self._bound_entity = entity self._bound_entity = entity
return c.VALID return c.VALID
def belongs_to_entity(self, entity): def belongs_to_entity(self, entity):
""" """
TODO Checks if the object belongs to a specified entity.
:param entity: The entity to check against.
:return: :return: True if the object belongs to the entity, False otherwise.
""" """
return self._bound_entity == entity return self._bound_entity == entity
def unbind(self): def unbind(self):
""" """
TODO Unbinds the object from its current entity.
:return: :return: The entity that the object was previously bound to.
""" """
previously_bound = self._bound_entity previously_bound = self._bound_entity
self._bound_entity = None self._bound_entity = None

37
marl_factory_grid/environment/entity/util.py
View File

@ -4,7 +4,7 @@ from marl_factory_grid.environment.entity.object import Object
########################################################################## ##########################################################################
# ####################### Objects and Entitys ########################## # # ####################### Objects and Entities ########################## #
########################################################################## ##########################################################################
@ -12,10 +12,11 @@ class PlaceHolder(Object):
def __init__(self, *args, fill_value=0, **kwargs): def __init__(self, *args, fill_value=0, **kwargs):
""" """
TODO A placeholder object that can be used as an observation during training. It is designed to be later replaced
with a meaningful observation that wasn't initially present in the training run.
:param fill_value: The default value to fill the placeholder observation (Default: 0)
:return: :type fill_value: Any
""" """
super().__init__(*args, **kwargs) super().__init__(*args, **kwargs)
self._fill_value = fill_value self._fill_value = fill_value
@ -23,20 +24,20 @@ class PlaceHolder(Object):
@property @property
def var_can_collide(self): def var_can_collide(self):
""" """
TODO Indicates whether this placeholder object can collide with other entities. Always returns False.
:return: False
:return: :rtype: bool
""" """
return False return False
@property @property
def encoding(self): def encoding(self):
""" """
TODO Get the fill value representing the placeholder observation.
:return: The fill value
:return: :rtype: Any
""" """
return self._fill_value return self._fill_value
@ -54,10 +55,10 @@ class GlobalPosition(Object):
@property @property
def encoding(self): def encoding(self):
""" """
TODO Get the encoded representation of the global position based on whether normalization is enabled.
:return: The encoded representation of the global position
:return: :rtype: tuple[float, float] or tuple[int, int]
""" """
if self._normalized: if self._normalized:
return tuple(np.divide(self._bound_entity.pos, self._shape)) return tuple(np.divide(self._bound_entity.pos, self._shape))
@ -66,10 +67,14 @@ class GlobalPosition(Object):
def __init__(self, agent, level_shape, *args, normalized: bool = True, **kwargs): def __init__(self, agent, level_shape, *args, normalized: bool = True, **kwargs):
""" """
TODO A utility class representing the global position of an entity in the environment.
:param agent: The agent entity to which the global position is bound.
:return: :type agent: marl_factory_grid.environment.entity.agent.Agent
:param level_shape: The shape of the environment level.
:type level_shape: tuple[int, int]
:param normalized: Indicates whether the global position should be normalized (Default: True)
:type normalized: bool
""" """
super(GlobalPosition, self).__init__(*args, **kwargs) super(GlobalPosition, self).__init__(*args, **kwargs)
self.bind_to(agent) self.bind_to(agent)

5
marl_factory_grid/environment/entity/wall.py
View File

@ -7,10 +7,7 @@ class Wall(Entity):
def __init__(self, *args, **kwargs): def __init__(self, *args, **kwargs):
""" """
TODO A class representing a wall entity in the environment.
:return:
""" """
super().__init__(*args, **kwargs) super().__init__(*args, **kwargs)

37
marl_factory_grid/environment/factory.py
View File

@ -24,47 +24,48 @@ class Factory(gym.Env):
@property @property
def action_space(self): def action_space(self):
""" """
TODO The action space defines the set of all possible actions that an agent can take in the environment.
:return: Action space
:return: :rtype: gym.Space
""" """
return self.state[c.AGENT].action_space return self.state[c.AGENT].action_space
@property @property
def named_action_space(self): def named_action_space(self):
""" """
TODO Returns the named action space for agents.
:return: Named action space
:return: :rtype: dict[str, dict[str, list[int]]]
""" """
return self.state[c.AGENT].named_action_space return self.state[c.AGENT].named_action_space
@property @property
def observation_space(self): def observation_space(self):
""" """
TODO The observation space represents all the information that an agent can receive from the environment at a given
time step.
:return: Observation space.
:return: :rtype: gym.Space
""" """
return self.obs_builder.observation_space(self.state) return self.obs_builder.observation_space(self.state)
@property @property
def named_observation_space(self): def named_observation_space(self):
""" """
TODO Returns the named observation space for the environment.
:return: Named observation space.
:return: :rtype: (dict, dict)
""" """
return self.obs_builder.named_observation_space(self.state) return self.obs_builder.named_observation_space(self.state)
@property @property
def params(self) -> dict: def params(self) -> dict:
""" """
FIXME LAGEGY FIXME LEGACY
:return: :return:
@ -80,10 +81,14 @@ class Factory(gym.Env):
def __init__(self, config_file: Union[str, PathLike], custom_modules_path: Union[None, PathLike] = None, def __init__(self, config_file: Union[str, PathLike], custom_modules_path: Union[None, PathLike] = None,
custom_level_path: Union[None, PathLike] = None): custom_level_path: Union[None, PathLike] = None):
""" """
TODO Initializes the marl-factory-grid as Gym environment.
:param config_file: Path to the configuration file.
:return: :type config_file: Union[str, PathLike]
:param custom_modules_path: Path to custom modules directory. (Default: None)
:type custom_modules_path: Union[None, PathLike]
:param custom_level_path: Path to custom level file. (Default: None)
:type custom_level_path: Union[None, PathLike]
""" """
self._config_file = config_file self._config_file = config_file
self.conf = FactoryConfigParser(self._config_file, custom_modules_path) self.conf = FactoryConfigParser(self._config_file, custom_modules_path)