🐛 📝 Fix env.py example documentation

src/hcraft/env.py

@@ -30,7 +30,7 @@
 For now, we only have two items we can simply build using the Item class from `hcraft.world`:
 
 ```python
-from hcraft.elements import Item
+from hcraft import Item
 
 CHEST = Item("treasure_chest")
 GOLD = Item("gold")
@@ -47,7 +47,7 @@
 
 TAKE_GOLD_FROM_CHEST = Transformation(
     inventory_changes=[
-        Use(CURRENT_ZONE, CHEST),
+        Use(CURRENT_ZONE, CHEST, consume=1),
         Yield(PLAYER, GOLD),
     ]
 )
@@ -62,7 +62,7 @@
 Like items, zones are created with a Zone object from `hcraft.world`:
 
 ```python
-from hcraft.elements import Zone
+from hcraft import Zone
 
 TREASURE_ROOM = Zone("treasure_room")
 ```
@@ -77,12 +77,12 @@
 We can simply build a world from a list of transformations:
 
 ```python
-from hcraft.elements import world_from_transformations
+from hcraft.world import world_from_transformations
 
 WORLD = world_from_transformations(
     transformations=[TAKE_GOLD_FROM_CHEST],
     start_zone=TREASURE_ROOM,
-    start_zones_items={TREASURE_ROOM: [CHEST]}
+    start_zones_items={TREASURE_ROOM: [CHEST]},
 )
 ```
 
@@ -95,15 +95,15 @@
 we simply need to pass our `WORLD` to HcraftEnv from `hcraft.env`:
 
 ```python
-from hcraftnv import HcraftEnv
+from hcraft import HcraftEnv
 
 env = HcraftEnv(WORLD)
 ```
 
 We can already render it in the GUI:
 
 ```python
-from hcraft.render.human import render_env_with_human
+from hcraft import render_env_with_human
 
 render_env_with_human(env)
 ```
@@ -188,7 +188,7 @@
 Also, let's add a time limit to spice things up.
 
 ```python
-from hcraft.elements import world_from_transformations
+from hcraft.world import world_from_transformations
 
 WORLD_2 = world_from_transformations(
     transformations=[
@@ -211,11 +211,28 @@
 For now, our environment is a bit ... ugly.
 Text is cool, but images are better !
 
-For example, we can use cool
-[2D assets from Pixel_Poem on itch.io](https://pixel-poem.itch.io/dungeon-assetpuck)
+For that, we need to give our world a ressource path where images are located.
 
-We simply have to put them into a folder like so:
+To simplify our case, we can use the already built folder under the treasure example:
+
+```python
+from pathlib import Path
+import hcraft
+
+WORLD_2.resources_path = Path(hcraft.__file__).parent.joinpath(
+    "examples", "treasure", "resources"
+)
+render_env_with_human(env)
+```
+And we now have cool images for items !
+
+Under the hood, this can simply be replicated by getting some assets.
+(Like those previous [2D assets from Pixel_Poem on itch.io](https://pixel-poem.itch.io/dungeon-assetpuck)
+)
+
+We then simply put them into a folder like so, with matching names for items and zones:
 ```bash
+cwd
 ├───myscript.py
 ├───resources
 │   ├───items
@@ -227,21 +244,13 @@
 │   └───font.ttf
 ```
 
-To simplify our case, we can use the already built folder under the treasure example:
+And setting that path as the world's ressources_path:
 
 ```python
-import os
-import hcraft
-
-resources_path = Path(hcraft.__file__).parent.joinpath(
-    "examples", "treasure", "resources"
-)
-env = HcraftEnv(
-    WORLD_2, purpose=get_gold_task, resources_path=resources_path, max_step=7
-)
+WORLD_2.resources_path = Path("resources")
 render_env_with_human(env)
 ```
-And we now have cool images for items !
+
 Try to do the same with zones and change the font aswell!
 
 ![](../../docs/images/TreasureEnvV2.png)
@@ -252,7 +261,7 @@
 you should pack it up into a class and inherit HcraftEnv directly like so:
 
 ```python
-.. include:: examples/treasure/__init__.py
+.. include:: examples/treasure/env.py
 ```
 
 That's it for this small customized env if you want more, be sure to check Transformation

src/hcraft/examples/treasure/__init__.py

@@ -8,106 +8,19 @@
 
 """
 
-from pathlib import Path
-from typing import List
+from hcraft.examples.treasure.env import TreasureEnv
 
-from hcraft.elements import Item, Zone
-from hcraft.env import HcraftEnv
-from hcraft.purpose import GetItemTask
-from hcraft.transformation import Transformation, Use, Yield, PLAYER, CURRENT_ZONE
-from hcraft.world import world_from_transformations
+__all__ = ["TreasureEnv"]
 
 # gym is an optional dependency
 try:
     import gym
 
     gym.register(
         id="Treasure-v1",
-        entry_point="hcraft.examples.treasure:TreasureEnv",
+        entry_point="hcraft.examples.treasure.env:TreasureEnv",
     )
 
 
 except ImportError:
     pass
-
-
-class TreasureEnv(HcraftEnv):
-    """A simple environment used in for the env building tutorial."""
-
-    TREASURE_ROOM = Zone("treasure_room")
-    """Room containing the treasure."""
-    KEY_ROOM = Zone("key_room")
-    """Where all the keys are stored."""
-    START_ROOM = Zone("start_room")
-    """Where the player starts."""
-
-    CHEST = Item("treasure_chest")
-    """Treasure chest containing gold."""
-    LOCKED_CHEST = Item("locked_chest")
-    """Treasure chest containing gold ... but it's locked."""
-    GOLD = Item("gold")
-    """Gold! well the pixel version at least."""
-    KEY = Item("key")
-    """A key ... it can probably unlock things."""
-
-    def __init__(self, **kwargs) -> None:
-        transformations = self._build_transformations()
-        world = world_from_transformations(
-            transformations=transformations,
-            start_zone=self.START_ROOM,
-            start_zones_items={self.TREASURE_ROOM: [self.LOCKED_CHEST]},
-        )
-        world.resources_path = Path(__file__).parent / "resources"
-        super().__init__(
-            world, purpose=GetItemTask(self.GOLD), name="TreasureHcraft", **kwargs
-        )
-
-    def _build_transformations(self) -> List[Transformation]:
-        TAKE_GOLD_FROM_CHEST = Transformation(
-            "take-gold-from-chest",
-            inventory_changes=[
-                Use(CURRENT_ZONE, self.CHEST, consume=1),
-                Yield(PLAYER, self.GOLD),
-            ],
-        )
-
-        SEARCH_KEY = Transformation(
-            "search-key",
-            inventory_changes=[
-                Yield(PLAYER, self.KEY, max=1),
-            ],
-            zone=self.KEY_ROOM,
-        )
-
-        UNLOCK_CHEST = Transformation(
-            "unlock-chest",
-            inventory_changes=[
-                Use(PLAYER, self.KEY, 2),
-                Use(CURRENT_ZONE, self.LOCKED_CHEST, consume=1),
-                Yield(CURRENT_ZONE, self.CHEST),
-            ],
-        )
-
-        MOVE_TO_KEY_ROOM = Transformation(
-            "move-to-key_room",
-            destination=self.KEY_ROOM,
-            zone=self.START_ROOM,
-        )
-        MOVE_TO_TREASURE_ROOM = Transformation(
-            "move-to-treasure_room",
-            destination=self.TREASURE_ROOM,
-            zone=self.START_ROOM,
-        )
-        MOVE_TO_START_ROOM = Transformation(
-            "move-to-start_room",
-            destination=self.START_ROOM,
-        )
-
-        return [
-            TAKE_GOLD_FROM_CHEST,
-            SEARCH_KEY,
-            UNLOCK_CHEST,
-            MOVE_TO_KEY_ROOM,
-            MOVE_TO_TREASURE_ROOM,
-            MOVE_TO_START_ROOM,
-        ]

src/hcraft/examples/treasure/env.py

@@ -0,0 +1,90 @@
+from pathlib import Path
+from typing import List
+
+from hcraft.elements import Item, Zone
+from hcraft.env import HcraftEnv
+from hcraft.purpose import GetItemTask
+from hcraft.transformation import Transformation, Use, Yield, PLAYER, CURRENT_ZONE
+from hcraft.world import world_from_transformations
+
+
+class TreasureEnv(HcraftEnv):
+    """A simple environment used in for the env building tutorial."""
+
+    TREASURE_ROOM = Zone("treasure_room")
+    """Room containing the treasure."""
+    KEY_ROOM = Zone("key_room")
+    """Where all the keys are stored."""
+    START_ROOM = Zone("start_room")
+    """Where the player starts."""
+
+    CHEST = Item("treasure_chest")
+    """Treasure chest containing gold."""
+    LOCKED_CHEST = Item("locked_chest")
+    """Treasure chest containing gold ... but it's locked."""
+    GOLD = Item("gold")
+    """Gold! well the pixel version at least."""
+    KEY = Item("key")
+    """A key ... it can probably unlock things."""
+
+    def __init__(self, **kwargs) -> None:
+        transformations = self._build_transformations()
+        world = world_from_transformations(
+            transformations=transformations,
+            start_zone=self.START_ROOM,
+            start_zones_items={self.TREASURE_ROOM: [self.LOCKED_CHEST]},
+        )
+        world.resources_path = Path(__file__).parent / "resources"
+        super().__init__(
+            world, purpose=GetItemTask(self.GOLD), name="TreasureHcraft", **kwargs
+        )
+
+    def _build_transformations(self) -> List[Transformation]:
+        TAKE_GOLD_FROM_CHEST = Transformation(
+            "take-gold-from-chest",
+            inventory_changes=[
+                Use(CURRENT_ZONE, self.CHEST, consume=1),
+                Yield(PLAYER, self.GOLD),
+            ],
+        )
+
+        SEARCH_KEY = Transformation(
+            "search-key",
+            inventory_changes=[
+                Yield(PLAYER, self.KEY, max=1),
+            ],
+            zone=self.KEY_ROOM,
+        )
+
+        UNLOCK_CHEST = Transformation(
+            "unlock-chest",
+            inventory_changes=[
+                Use(PLAYER, self.KEY, 2),
+                Use(CURRENT_ZONE, self.LOCKED_CHEST, consume=1),
+                Yield(CURRENT_ZONE, self.CHEST),
+            ],
+        )
+
+        MOVE_TO_KEY_ROOM = Transformation(
+            "move-to-key_room",
+            destination=self.KEY_ROOM,
+            zone=self.START_ROOM,
+        )
+        MOVE_TO_TREASURE_ROOM = Transformation(
+            "move-to-treasure_room",
+            destination=self.TREASURE_ROOM,
+            zone=self.START_ROOM,
+        )
+        MOVE_TO_START_ROOM = Transformation(
+            "move-to-start_room",
+            destination=self.START_ROOM,
+        )
+
+        return [
+            TAKE_GOLD_FROM_CHEST,
+            SEARCH_KEY,
+            UNLOCK_CHEST,
+            MOVE_TO_KEY_ROOM,
+            MOVE_TO_TREASURE_ROOM,
+            MOVE_TO_START_ROOM,
+        ]

tests/test_env.py

@@ -15,7 +15,7 @@
 from tests.envs import classic_env, player_only_env, zone_only_env
 
 
-class TestCratingEnv:
+class TestCreatingEnv:
     @pytest.fixture(autouse=True)
     def setup_method(self):
         (