Update environment creation tutorial with accurate obs/action space usage

docs/code_examples/aec_rps.py

@@ -60,29 +60,38 @@ def __init__(self, render_mode=None):
         The init method takes in environment arguments and
          should define the following attributes:
         - possible_agents
-        - action_spaces
-        - observation_spaces
+        - render_mode
+
+        Note: as of v1.18.1, the action_spaces and observation_spaces attributes are deprecated.
+        Spaces should be defined in the action_space() and observation_space() methods.
+        If these methods are not overridden, spaces will be inferred from self.observation_spaces/action_spaces, raising a warning.
+
         These attributes should not be changed after initialization.
         """
         self.possible_agents = ["player_" + str(r) for r in range(2)]
+
+        # optional: a mapping between agent name and ID
         self.agent_name_mapping = dict(
             zip(self.possible_agents, list(range(len(self.possible_agents))))
         )
 
-        # gymnasium spaces are defined and documented here: https://gymnasium.farama.org/api/spaces/
+        # optional: we can define the observation and action spaces here as attributes to be used in their corresponding methods
         self._action_spaces = {agent: Discrete(3) for agent in self.possible_agents}
         self._observation_spaces = {
             agent: Discrete(4) for agent in self.possible_agents
         }
         self.render_mode = render_mode
 
-    # this cache ensures that same space object is returned for the same agent
-    # allows action space seeding to work as expected
+    # Observation space should be defined here.
+    # lru_cache allows observation and action spaces to be memoized, reducing clock cycles required to get each agent's space.
+    # If your spaces change over time, remove this line (disable caching).
     @functools.lru_cache(maxsize=None)
     def observation_space(self, agent):
         # gymnasium spaces are defined and documented here: https://gymnasium.farama.org/api/spaces/
         return Discrete(4)
 
+    # Action space should be defined here.
+    # If your spaces change over time, remove this line (disable caching).
     @functools.lru_cache(maxsize=None)
     def action_space(self, agent):
         return Discrete(3)

docs/code_examples/parallel_rps.py

@@ -61,23 +61,32 @@ def __init__(self, render_mode=None):
         """
         The init method takes in environment arguments and should define the following attributes:
         - possible_agents
-        - action_spaces
-        - observation_spaces
+        - render_mode
+
+        Note: as of v1.18.1, the action_spaces and observation_spaces attributes are deprecated.
+        Spaces should be defined in the action_space() and observation_space() methods.
+        If these methods are not overridden, spaces will be inferred from self.observation_spaces/action_spaces, raising a warning.
+
         These attributes should not be changed after initialization.
         """
         self.possible_agents = ["player_" + str(r) for r in range(2)]
+
+        # optional: a mapping between agent name and ID
         self.agent_name_mapping = dict(
             zip(self.possible_agents, list(range(len(self.possible_agents))))
         )
         self.render_mode = render_mode
 
-    # this cache ensures that same space object is returned for the same agent
-    # allows action space seeding to work as expected
+    # Observation space should be defined here.
+    # lru_cache allows observation and action spaces to be memoized, reducing clock cycles required to get each agent's space.
+    # If your spaces change over time, remove this line (disable caching).
     @functools.lru_cache(maxsize=None)
     def observation_space(self, agent):
         # gymnasium spaces are defined and documented here: https://gymnasium.farama.org/api/spaces/
         return Discrete(4)
 
+    # Action space should be defined here.
+    # If your spaces change over time, remove this line (disable caching).
     @functools.lru_cache(maxsize=None)
     def action_space(self, agent):
         return Discrete(3)