18 | .. include:: ../../../docs/images/requirements_graphs/RecursiveHcraft-I6.html
19 |
20 | """
21 |
22 | from typing import List
23 |
24 | from hcraft.elements import Item
25 | from hcraft.env import HcraftEnv
26 | from hcraft.transformation import Transformation, Use, Yield, PLAYER
27 | from hcraft.task import GetItemTask
28 | from hcraft.world import world_from_transformations
29 |
30 | # gym is an optional dependency
31 | try:
32 | import gymnasium as gym
33 |
34 | gym.register(
35 | id="RecursiveHcraft-v1",
36 | entry_point="hcraft.examples.recursive:RecursiveHcraftEnv",
37 | )
38 |
39 | except ImportError:
40 | pass
41 |
42 |
43 | class RecursiveHcraftEnv(HcraftEnv):
44 | """RecursiveHcraft Environment"""
45 |
46 | def __init__(self, n_items: int = 6, **kwargs):
47 | items = [Item(str(i)) for i in range(n_items)]
48 | self.n_items = n_items
49 | transformations = self.build_transformations(items)
50 | world = world_from_transformations(transformations)
51 | if "purpose" not in kwargs:
52 | kwargs["purpose"] = GetItemTask(items[-1])
53 | super().__init__(
54 | world,
55 | name=f"RecursiveHcraft-I{n_items}",
56 | **kwargs,
57 | )
58 |
59 | def build_transformations(self, items: List[Item]) -> List[Transformation]:
60 | """Build transformations to make every item accessible.
61 |
62 | Args:
63 | items: List of items.
64 |
65 | Returns:
66 | List of transformations.
67 |
68 | """
69 | transformation = []
70 |
71 | for index, item in enumerate(items):
72 | inventory_changes = [Yield(PLAYER, item)]
73 | if index > 0:
74 | inventory_changes += [
75 | Use(PLAYER, items[item_id], consume=1) for item_id in range(index)
76 | ]
77 | new_recipe = Transformation(inventory_changes=inventory_changes)
78 | transformation.append(new_recipe)
79 |
80 | return transformation
81 |
--------------------------------------------------------------------------------
/src/hcraft/examples/minicraft/fourrooms.py:
--------------------------------------------------------------------------------
1 | from typing import Dict, List, TypeVar
2 |
3 | from hcraft.elements import Item, Zone
4 | from hcraft.task import GetItemTask
5 | from hcraft.transformation import Transformation, Use, Yield, PLAYER, CURRENT_ZONE
6 |
7 | from hcraft.examples.minicraft.minicraft import MiniCraftEnv
8 |
9 |
10 | MINICRAFT_NAME = "FourRooms"
11 | __doc__ = MiniCraftEnv.description(MINICRAFT_NAME, for_module_header=True)
12 |
13 |
14 | class MiniHCraftFourRooms(MiniCraftEnv):
15 | MINICRAFT_NAME = MINICRAFT_NAME
16 | __doc__ = MiniCraftEnv.description(MINICRAFT_NAME)
17 |
18 | SOUTH_WEST_ROOM = Zone("South-West")
19 | """South west room."""
20 |
21 | SOUTH_EAST_ROOM = Zone("South-East")
22 | """South east room."""
23 |
24 | NORTH_WEST_ROOM = Zone("North-West")
25 | """North west room."""
26 |
27 | NORTH_EAST_ROOM = Zone("North-East")
28 | """North east room."""
29 |
30 | GOAL = Item("goal")
31 | """Goal to reach."""
32 |
33 | def __init__(self, **kwargs) -> None:
34 | self.task = GetItemTask(self.GOAL)
35 |
36 | self.ROOMS = [
37 | self.SOUTH_WEST_ROOM,
38 | self.SOUTH_EAST_ROOM,
39 | self.NORTH_EAST_ROOM,
40 | self.NORTH_WEST_ROOM,
41 | ]
42 |
43 | super().__init__(
44 | self.MINICRAFT_NAME,
45 | start_zone=self.SOUTH_WEST_ROOM,
46 | purpose=self.task,
47 | **kwargs,
48 | )
49 |
50 | def build_transformations(self) -> List[Transformation]:
51 | find_goal = Transformation(
52 | "find-goal",
53 | inventory_changes=[Yield(CURRENT_ZONE, self.GOAL, max=0)],
54 | zone=self.NORTH_EAST_ROOM,
55 | )
56 |
57 | reach_goal = Transformation(
58 | "reach-goal",
59 | inventory_changes=[
60 | Use(CURRENT_ZONE, self.GOAL, consume=1),
61 | Yield(PLAYER, self.GOAL),
62 | ],
63 | )
64 |
65 | neighbors = _get_rooms_connections(self.ROOMS)
66 |
67 | moves = []
68 | for destination, neighbor_rooms in neighbors.items():
69 | for neighbor_room in neighbor_rooms:
70 | moves.append(
71 | Transformation(
72 | f"go-to-{destination.name}-from-{neighbor_room.name}",
73 | destination=destination,
74 | zone=neighbor_room,
75 | )
76 | )
77 |
78 | return [find_goal, reach_goal] + moves
79 |
80 |
81 | Room = TypeVar("Room")
82 |
83 |
84 | def _get_rooms_connections(rooms: List[Room]) -> Dict[Room, List[Room]]:
85 | neighbors = {}
86 | for room_id, destination in enumerate(rooms):
87 | neighbors[destination] = [rooms[room_id - 1], rooms[(room_id + 1) % len(rooms)]]
88 | return neighbors
89 |
--------------------------------------------------------------------------------
/tests/envs.py:
--------------------------------------------------------------------------------
1 | from typing import List
2 |
3 | from hcraft.elements import Item, Zone
4 | from hcraft.env import HcraftEnv
5 | from hcraft.transformation import Transformation, Use, Yield, PLAYER, CURRENT_ZONE
6 | from hcraft.world import world_from_transformations
7 |
8 |
9 | def classic_env(player=PLAYER, current_zone=CURRENT_ZONE, include_move=True):
10 | start_zone = Zone("start")
11 | other_zone = Zone("other_zone")
12 | zones = [start_zone, other_zone]
13 |
14 | transformations: List[Transformation] = []
15 | if include_move:
16 | move_to_other_zone = Transformation(
17 | "move_to_other_zone",
18 | destination=other_zone,
19 | zone=start_zone,
20 | )
21 | transformations.append(move_to_other_zone)
22 |
23 | wood = Item("wood")
24 |
25 | search_wood_restriction = {"zone": start_zone} if include_move else {}
26 | search_wood = Transformation(
27 | "search_wood",
28 | inventory_changes=[Yield(player, wood)],
29 | **search_wood_restriction,
30 | )
31 | transformations.append(search_wood)
32 |
33 | stone = Item("stone")
34 | search_stone = Transformation(
35 | "search_stone",
36 | inventory_changes=[Yield(player, stone)],
37 | )
38 | transformations.append(search_stone)
39 |
40 | plank = Item("plank")
41 | craft_plank = Transformation(
42 | "craft_plank",
43 | inventory_changes=[
44 | Use(player, wood, consume=1),
45 | Yield(player, plank, create=4),
46 | ],
47 | )
48 | transformations.append(craft_plank)
49 |
50 | table = Item("table")
51 | craft_table = Transformation(
52 | "craft_table",
53 | inventory_changes=[
54 | Use(player, plank, consume=4),
55 | Yield(current_zone, table),
56 | ],
57 | )
58 | transformations.append(craft_table)
59 |
60 | wood_house = Item("wood house")
61 | build_house = Transformation(
62 | "build_house",
63 | inventory_changes=[
64 | Use(player, plank, consume=32),
65 | Use(player, wood, consume=8),
66 | Yield(current_zone, wood_house),
67 | ],
68 | )
69 | transformations.append(build_house)
70 |
71 | items = [wood, stone, plank]
72 | zones_items = [table, wood_house]
73 | named_transformations = {t.name: t for t in transformations}
74 |
75 | start_zone = start_zone if include_move else None
76 | world = world_from_transformations(
77 | transformations=list(named_transformations.values()),
78 | start_zone=start_zone,
79 | )
80 | env = HcraftEnv(world)
81 | return env, world, named_transformations, start_zone, items, zones, zones_items
82 |
83 |
84 | def player_only_env():
85 | return classic_env(current_zone=PLAYER, include_move=False)
86 |
87 |
88 | def zone_only_env():
89 | return classic_env(player=CURRENT_ZONE)
90 |
--------------------------------------------------------------------------------
/src/hcraft/examples/minecraft/__init__.py:
--------------------------------------------------------------------------------
1 | """# MineHcraft: Inspired from the popular game Minecraft.
2 |
3 | 
4 |
5 | A rather large and complex requirements graph:
6 |
7 | .. include:: ../../../../docs/images/requirements_graphs/MineHcraft.html
8 |
9 | """
10 |
11 | from typing import Optional
12 |
13 | import hcraft.examples.minecraft.items as items
14 | from hcraft.examples.minecraft.env import ALL_ITEMS, MineHcraftEnv
15 |
16 | from hcraft.purpose import Purpose, RewardShaping
17 | from hcraft.task import GetItemTask
18 |
19 | MINEHCRAFT_GYM_ENVS = []
20 | __all__ = ["MineHcraftEnv"]
21 |
22 |
23 | # gym is an optional dependency
24 | try:
25 | import gymnasium as gym
26 |
27 | ENV_PATH = "hcraft.examples.minecraft.env:MineHcraftEnv"
28 |
29 | # Simple MineHcraft with no reward, only penalty on illegal actions
30 | gym.register(
31 | id="MineHcraft-NoReward-v1",
32 | entry_point=ENV_PATH,
33 | kwargs={"purpose": None},
34 | )
35 | MINEHCRAFT_GYM_ENVS.append("MineHcraft-NoReward-v1")
36 |
37 | # Get all items, place all zones_items and go everywhere
38 | gym.register(
39 | id="MineHcraft-v1",
40 | entry_point=ENV_PATH,
41 | kwargs={"purpose": "all"},
42 | )
43 | MINEHCRAFT_GYM_ENVS.append("MineHcraft-v1")
44 |
45 | def _to_camel_case(name: str):
46 | return "".join([subname.capitalize() for subname in name.split("_")])
47 |
48 | def _register_minehcraft_single_item(
49 | item: items.Item,
50 | name: Optional[str] = None,
51 | success_reward: float = 10.0,
52 | timestep_reward: float = -0.1,
53 | reward_shaping: RewardShaping = RewardShaping.REQUIREMENTS_ACHIVEMENTS,
54 | version: int = 1,
55 | ):
56 | purpose = Purpose(timestep_reward=timestep_reward)
57 | purpose.add_task(
58 | GetItemTask(item, reward=success_reward),
59 | reward_shaping=reward_shaping,
60 | )
61 | if name is None:
62 | name = _to_camel_case(item.name)
63 | gym_name = f"MineHcraft-{name}-v{version}"
64 | gym.register(
65 | id=gym_name,
66 | entry_point=ENV_PATH,
67 | kwargs={"purpose": purpose},
68 | )
69 | MINEHCRAFT_GYM_ENVS.append(gym_name)
70 |
71 | replacement_names = {
72 | items.COBBLESTONE: "Stone",
73 | items.IRON_INGOT: "Iron",
74 | items.GOLD_INGOT: "Gold",
75 | items.ENDER_DRAGON_HEAD: "Dragon",
76 | }
77 |
78 | for item in ALL_ITEMS:
79 | cap_item_name = "".join([part.capitalize() for part in item.name.split("_")])
80 | item_id = replacement_names.get(item, cap_item_name)
81 | _register_minehcraft_single_item(item, name=item_id)
82 |
83 |
84 | except ImportError:
85 | pass
86 |
--------------------------------------------------------------------------------
/src/hcraft/examples/minicraft/unlock.py:
--------------------------------------------------------------------------------
1 | from typing import List
2 |
3 | from hcraft.elements import Item, Zone
4 | from hcraft.task import PlaceItemTask
5 | from hcraft.transformation import Transformation, Use, Yield, PLAYER, CURRENT_ZONE
6 |
7 | from hcraft.examples.minicraft.minicraft import MiniCraftEnv
8 |
9 |
10 | MINICRAFT_NAME = "Unlock"
11 | __doc__ = MiniCraftEnv.description(MINICRAFT_NAME, for_module_header=True)
12 |
13 |
14 | class MiniHCraftUnlock(MiniCraftEnv):
15 | MINICRAFT_NAME = MINICRAFT_NAME
16 | __doc__ = MiniCraftEnv.description(MINICRAFT_NAME)
17 |
18 | START = Zone("start_room")
19 | """Start room."""
20 |
21 | KEY = Item("key")
22 | """Key used to unlock the door."""
23 |
24 | OPEN_DOOR = Item("open_door")
25 | """Open door between the two rooms."""
26 | LOCKED_DOOR = Item("locked_door")
27 | """Locked door between the two rooms, can be unlocked with a key."""
28 |
29 | def __init__(self, **kwargs) -> None:
30 | self.task = PlaceItemTask(self.OPEN_DOOR)
31 | super().__init__(
32 | self.MINICRAFT_NAME,
33 | purpose=self.task,
34 | start_zone=self.START,
35 | **kwargs,
36 | )
37 |
38 | def build_transformations(self) -> List[Transformation]:
39 | transformations = []
40 |
41 | search_for_key = Transformation(
42 | "search_for_key",
43 | inventory_changes=[
44 | Yield(CURRENT_ZONE, self.KEY, create=1, max=0),
45 | Yield(PLAYER, self.KEY, create=0, max=0),
46 | ],
47 | zone=self.START,
48 | )
49 | transformations.append(search_for_key)
50 |
51 | pickup = Transformation(
52 | "pickup_key",
53 | inventory_changes=[
54 | Use(CURRENT_ZONE, self.KEY, consume=1),
55 | Yield(PLAYER, self.KEY, create=1),
56 | ],
57 | )
58 | put_down = Transformation(
59 | "put_down_key",
60 | inventory_changes=[
61 | Use(PLAYER, self.KEY, consume=1),
62 | Yield(CURRENT_ZONE, self.KEY, create=1),
63 | ],
64 | )
65 | transformations += [pickup, put_down]
66 |
67 | search_for_door = Transformation(
68 | "search_for_door",
69 | inventory_changes=[
70 | Yield(CURRENT_ZONE, self.LOCKED_DOOR, max=0),
71 | Yield(CURRENT_ZONE, self.OPEN_DOOR, create=0, max=0),
72 | ],
73 | zone=self.START,
74 | )
75 | transformations.append(search_for_door)
76 |
77 | unlock_door = Transformation(
78 | "unlock_door",
79 | inventory_changes=[
80 | Use(PLAYER, self.KEY),
81 | Use(CURRENT_ZONE, self.LOCKED_DOOR, consume=1),
82 | Yield(CURRENT_ZONE, self.OPEN_DOOR, create=1),
83 | ],
84 | )
85 | transformations.append(unlock_door)
86 |
87 | return transformations
88 |
--------------------------------------------------------------------------------
/src/hcraft/examples/light_recursive.py:
--------------------------------------------------------------------------------
1 | """LightRecursive, a less recursive version of the RecursiveHcraft Environment.
2 |
3 | Item n requires one of each the k previous items (n-k to n-1).
4 |
5 | Example:
6 | >>> env = LightRecursiveHcraftEnv(n_items=4, n_required_previous=2)
7 | For example, if there is 5 items, the last item is 4.
8 | But 4 requires the 2 previous items: {3, 2}.
9 | And 3 requires the 2 previous items: {2, 1}.
10 | And 2 requires the 2 previous items: {1, 0}.
11 | And 1 requires the only previous items: {0}.
12 | Finally Item 0 can be obtained directly.
13 |
14 | Requirements graph (n_items=6, n_required_previous=2):
15 |
16 | .. include:: ../../../docs/images/requirements_graphs/LightRecursiveHcraft-K2-I6.html
17 |
18 | """
19 |
20 | from hcraft.elements import Item
21 | from hcraft.env import HcraftEnv
22 | from hcraft.task import GetItemTask
23 | from hcraft.transformation import PLAYER, Transformation, Use, Yield
24 | from hcraft.world import world_from_transformations
25 |
26 |
27 | from typing import List
28 |
29 |
30 | # gym is an optional dependency
31 | try:
32 | import gymnasium as gym
33 |
34 | gym.register(
35 | id="LightRecursiveHcraft-v1",
36 | entry_point="hcraft.examples.light_recursive:LightRecursiveHcraftEnv",
37 | )
38 |
39 | except ImportError:
40 | pass
41 |
42 |
43 | class LightRecursiveHcraftEnv(HcraftEnv):
44 | """LightRecursive environment."""
45 |
46 | def __init__(self, n_items: int = 6, n_required_previous: int = 2, **kwargs):
47 | self.n_items = n_items
48 | self.n_required_previous = n_required_previous
49 | if n_required_previous == 1:
50 | env_name = "LinearRecursiveHcraft"
51 | else:
52 | env_name = f"LightRecursiveHcraft-K{n_required_previous}-I{n_items}"
53 | items = [Item(str(i)) for i in range(n_items)]
54 | transformations = self._transformations(items)
55 | world = world_from_transformations(transformations)
56 | if "purpose" not in kwargs:
57 | kwargs["purpose"] = GetItemTask(items[-1])
58 | super().__init__(world, name=env_name, **kwargs)
59 |
60 | def _transformations(self, items: List[Item]) -> List[Transformation]:
61 | """Build recipes to make every item accessible.
62 |
63 | Args:
64 | items: List of items.
65 |
66 | Returns:
67 | List of craft recipes.
68 |
69 | """
70 | transformation = []
71 |
72 | for index, item in enumerate(items):
73 | low_id = max(0, index - self.n_required_previous)
74 | inventory_changes = [Yield(PLAYER, item)]
75 | if index > 0:
76 | inventory_changes += [
77 | Use(PLAYER, items[item_id], consume=1)
78 | for item_id in range(low_id, index)
79 | ]
80 |
81 | new_recipe = Transformation(inventory_changes=inventory_changes)
82 | transformation.append(new_recipe)
83 |
84 | return transformation
85 |
--------------------------------------------------------------------------------
/tests/examples/test_recursive.py:
--------------------------------------------------------------------------------
1 | import networkx as nx
2 | import pytest_check as check
3 | from hcraft.examples.light_recursive import LightRecursiveHcraftEnv
4 |
5 | from hcraft.examples.recursive import RecursiveHcraftEnv
6 | from tests.custom_checks import check_isomorphic
7 |
8 |
9 | def test_recursive_requirements_graph():
10 | n_items = 4
11 | expected_graph = nx.DiGraph()
12 | expected_graph.add_edge(0, 1)
13 | expected_graph.add_edge(0, 2)
14 | expected_graph.add_edge(0, 3)
15 | expected_graph.add_edge(1, 2)
16 | expected_graph.add_edge(1, 3)
17 | expected_graph.add_edge(2, 3)
18 |
19 | env = RecursiveHcraftEnv(n_items=n_items)
20 | check_isomorphic(env.world.requirements.graph, expected_graph)
21 |
22 |
23 | def test_solve_recursive():
24 | n_items = 4 # [0, 1, 2, 3]
25 | actions = [
26 | 0, # 0
27 | 1, # 1 < 0
28 | 0, # 0
29 | 2, # 2 < 0 + 1
30 | 0, # 0
31 | 1, # 1
32 | 0, # 0
33 | 3, # 3 < 0 + 1 + 2
34 | ]
35 |
36 | env = RecursiveHcraftEnv(n_items=n_items)
37 | env.reset()
38 | for action in actions:
39 | observation, _reward, terminated, _truncated, _info = env.step(action)
40 | # Should only see items because no zones
41 | check.equal(observation.shape, (n_items,))
42 |
43 | check.is_true(terminated)
44 |
45 |
46 | def test_light_recursive_requirements_graph():
47 | n_items = 6
48 | n_required_previous = 3
49 | env = LightRecursiveHcraftEnv(
50 | n_items=n_items,
51 | n_required_previous=n_required_previous,
52 | )
53 | expected_graph = nx.DiGraph()
54 | expected_graph.add_edge(0, 1)
55 |
56 | expected_graph.add_edge(0, 2)
57 | expected_graph.add_edge(1, 2)
58 |
59 | expected_graph.add_edge(0, 3)
60 | expected_graph.add_edge(1, 3)
61 | expected_graph.add_edge(2, 3)
62 |
63 | expected_graph.add_edge(1, 4)
64 | expected_graph.add_edge(2, 4)
65 | expected_graph.add_edge(3, 4)
66 |
67 | expected_graph.add_edge(2, 5)
68 | expected_graph.add_edge(3, 5)
69 | expected_graph.add_edge(4, 5)
70 |
71 | check_isomorphic(env.world.requirements.graph, expected_graph)
72 |
73 |
74 | def test_solve_light_recursive():
75 | n_items = 5 # [0, 1, 2, 3, 4]
76 | n_required_previous = 2
77 | actions = [
78 | 0, # 0
79 | 1, # 1 < 0
80 | 0, # 0
81 | 2, # 2 < 0 + 1
82 | 0, # 0
83 | 1, # 1
84 | 3, # 3 < 1 + 2
85 | 0, # 0
86 | 1, # 1
87 | 0, # 0
88 | 2, # 2 < 0 + 1
89 | 4, # 4 < 2 + 3
90 | ]
91 |
92 | env = LightRecursiveHcraftEnv(
93 | n_items=n_items,
94 | n_required_previous=n_required_previous,
95 | )
96 | env.reset()
97 | for action in actions:
98 | observation, _reward, terminated, _truncated, _info = env.step(action)
99 | # Should only see items because no zones
100 | check.equal(observation.shape, (n_items,))
101 |
102 | check.is_true(terminated)
103 |
--------------------------------------------------------------------------------
/src/hcraft/examples/treasure/env.py:
--------------------------------------------------------------------------------
1 | from pathlib import Path
2 | from typing import List
3 |
4 | from hcraft.elements import Item, Zone
5 | from hcraft.env import HcraftEnv
6 | from hcraft.purpose import GetItemTask
7 | from hcraft.transformation import Transformation, Use, Yield, PLAYER, CURRENT_ZONE
8 | from hcraft.world import world_from_transformations
9 |
10 |
11 | class TreasureEnv(HcraftEnv):
12 | """A simple environment used in for the env building tutorial."""
13 |
14 | TREASURE_ROOM = Zone("treasure_room")
15 | """Room containing the treasure."""
16 | KEY_ROOM = Zone("key_room")
17 | """Where all the keys are stored."""
18 | START_ROOM = Zone("start_room")
19 | """Where the player starts."""
20 |
21 | CHEST = Item("treasure_chest")
22 | """Treasure chest containing gold."""
23 | LOCKED_CHEST = Item("locked_chest")
24 | """Treasure chest containing gold ... but it's locked."""
25 | GOLD = Item("gold")
26 | """Gold! well the pixel version at least."""
27 | KEY = Item("key")
28 | """A key ... it can probably unlock things."""
29 |
30 | def __init__(self, **kwargs) -> None:
31 | transformations = self._build_transformations()
32 | world = world_from_transformations(
33 | transformations=transformations,
34 | start_zone=self.START_ROOM,
35 | start_zones_items={self.TREASURE_ROOM: [self.LOCKED_CHEST]},
36 | )
37 | world.resources_path = Path(__file__).parent / "resources"
38 | super().__init__(
39 | world, purpose=GetItemTask(self.GOLD), name="TreasureHcraft", **kwargs
40 | )
41 |
42 | def _build_transformations(self) -> List[Transformation]:
43 | TAKE_GOLD_FROM_CHEST = Transformation(
44 | "take-gold-from-chest",
45 | inventory_changes=[
46 | Use(CURRENT_ZONE, self.CHEST, consume=1),
47 | Yield(PLAYER, self.GOLD),
48 | ],
49 | )
50 |
51 | SEARCH_KEY = Transformation(
52 | "search-key",
53 | inventory_changes=[
54 | Yield(PLAYER, self.KEY, max=1),
55 | ],
56 | zone=self.KEY_ROOM,
57 | )
58 |
59 | UNLOCK_CHEST = Transformation(
60 | "unlock-chest",
61 | inventory_changes=[
62 | Use(PLAYER, self.KEY, 2),
63 | Use(CURRENT_ZONE, self.LOCKED_CHEST, consume=1),
64 | Yield(CURRENT_ZONE, self.CHEST),
65 | ],
66 | )
67 |
68 | MOVE_TO_KEY_ROOM = Transformation(
69 | "move-to-key_room",
70 | destination=self.KEY_ROOM,
71 | zone=self.START_ROOM,
72 | )
73 | MOVE_TO_TREASURE_ROOM = Transformation(
74 | "move-to-treasure_room",
75 | destination=self.TREASURE_ROOM,
76 | zone=self.START_ROOM,
77 | )
78 | MOVE_TO_START_ROOM = Transformation(
79 | "move-to-start_room",
80 | destination=self.START_ROOM,
81 | )
82 |
83 | return [
84 | TAKE_GOLD_FROM_CHEST,
85 | SEARCH_KEY,
86 | UNLOCK_CHEST,
87 | MOVE_TO_KEY_ROOM,
88 | MOVE_TO_TREASURE_ROOM,
89 | MOVE_TO_START_ROOM,
90 | ]
91 |
--------------------------------------------------------------------------------
/src/hcraft/__init__.py:
--------------------------------------------------------------------------------
1 | """
2 | .. include:: ../../README.md
3 |
4 | ## Custom purposes for agents in HierarchyCraft environments
5 |
6 | HierarchyCraft allows users to specify custom purposes (one or multiple tasks) for agents in their environments.
7 | This feature provides a high degree of flexibility and allows users to design environments that
8 | are tailored to specific applications or scenarios.
9 | This feature enables to study mutli-task or lifelong learning settings.
10 |
11 | See [`hcraft.purpose`](https://irll.github.io/HierarchyCraft/hcraft/purpose.html) for more details.
12 |
13 | ## Solving behavior for all tasks of most HierarchyCraft environments
14 |
15 | HierarchyCraft also includes solving behaviors that can be used to generate actions
16 | from observations that will complete most tasks in any HierarchyCraft environment, including user-designed.
17 | Solving behaviors are handcrafted, and may not work in some edge cases when some items are rquired in specific zones.
18 | This feature makes it easy for users to obtain a strong baseline in their custom environments.
19 |
20 | See [`hcraft.solving_behaviors`](https://irll.github.io/HierarchyCraft/hcraft/solving_behaviors.html) for more details.
21 |
22 | ## Visualizing the underlying hierarchy of the environment (requirements graph)
23 |
24 | HierarchyCraft gives the ability to visualize the hierarchy of the environment as a requirements graph.
25 | This graph provides a potentialy complex but complete representation of what is required
26 | to obtain each item or to go in each zone, allowing users to easily understand the structure
27 | of the environment and identify key items of the environment.
28 |
29 | For example, here is the graph of the 'MiniCraftUnlock' environment where the goal is to open a door using a key:
30 | 
31 |
32 |
33 | And here is much more complex graph of the 'MineHcraft' environment shown previously:
34 | 
35 |
36 | See [`hcraft.requirements`](https://irll.github.io/HierarchyCraft/hcraft/requirements.html) for more details.
37 |
38 | """
39 |
40 | import hcraft.state as state
41 | import hcraft.solving_behaviors as solving_behaviors
42 | import hcraft.purpose as purpose
43 | import hcraft.transformation as transformation
44 | import hcraft.requirements as requirements
45 | import hcraft.env as env
46 | import hcraft.examples as examples
47 | import hcraft.world as world
48 | import hcraft.planning as planning
49 |
50 | from hcraft.elements import Item, Stack, Zone
51 | from hcraft.transformation import Transformation
52 | from hcraft.env import HcraftEnv, HcraftState
53 | from hcraft.purpose import Purpose
54 | from hcraft.render.human import get_human_action, render_env_with_human
55 | from hcraft.task import GetItemTask, GoToZoneTask, PlaceItemTask
56 |
57 |
58 | __all__ = [
59 | "HcraftState",
60 | "Transformation",
61 | "Item",
62 | "Stack",
63 | "Zone",
64 | "HcraftEnv",
65 | "get_human_action",
66 | "render_env_with_human",
67 | "Purpose",
68 | "GetItemTask",
69 | "GoToZoneTask",
70 | "PlaceItemTask",
71 | "state",
72 | "transformation",
73 | "purpose",
74 | "solving_behaviors",
75 | "requirements",
76 | "world",
77 | "env",
78 | "planning",
79 | "examples",
80 | ]
81 |
--------------------------------------------------------------------------------
/src/hcraft/examples/minicraft/minicraft.py:
--------------------------------------------------------------------------------
1 | from pathlib import Path
2 |
3 | from typing import Optional, List, Dict, Union
4 | from abc import abstractmethod
5 |
6 | from hcraft.elements import Item, Stack, Zone
7 | from hcraft.transformation import Transformation
8 | from hcraft.env import HcraftEnv
9 |
10 | from hcraft.world import world_from_transformations
11 |
12 |
13 | class MiniCraftEnv(HcraftEnv):
14 | """Environments representing abstractions from
15 | [minigrid environments](https://minigrid.farama.org/environments/minigrid/).
16 | """
17 |
18 | MINICRAFT_NAME = None
19 |
20 | def __init__(
21 | self,
22 | minicraft_name: str,
23 | start_zone: Optional[Zone] = None,
24 | start_items: Optional[List[Union[Stack, Item]]] = None,
25 | start_zones_items: Optional[Dict[Zone, List[Union[Stack, Item]]]] = None,
26 | **kwargs,
27 | ) -> None:
28 | """
29 | Args:
30 | invalid_reward: Reward given to the agent for invalid actions.
31 | Defaults to -1.0.
32 | max_step: Maximum number of steps before episode truncation.
33 | If None, never truncates the episode. Defaults to None.
34 | render_window: Window using to render the environment with pygame.
35 | """
36 | self.MINICRAFT_NAME = minicraft_name
37 | transformations = self.build_transformations()
38 | world = world_from_transformations(
39 | transformations=transformations,
40 | start_zone=start_zone,
41 | start_items=start_items,
42 | start_zones_items=start_zones_items,
43 | )
44 | world.resources_path = Path(__file__).parent / "resources"
45 | super().__init__(world, name=f"MiniHCraft{self.MINICRAFT_NAME}", **kwargs)
46 |
47 | @abstractmethod
48 | def build_transformations(self) -> List[Transformation]:
49 | """Build transformations for this MiniCraft environment"""
50 | raise NotImplementedError
51 |
52 | @staticmethod
53 | def description(name: str, for_module_header: bool = False) -> str:
54 | """Docstring description of the MiniCraft environment."""
55 |
56 | minigrid_link = (
57 | "https://minigrid.farama.org/environments/minigrid/',
82 | f".. include:: {requirements_image}",
83 | "
",
84 | ]
85 | )
86 |
87 | template = "\n".join(doc_lines)
88 | return template.replace("
30 | .. include:: ../../../docs/images/requirements_graphs/TowerHcraft-H2-W3.html
31 |
32 |
33 | """
34 |
35 | from typing import List
36 |
37 | from hcraft.elements import Item
38 | from hcraft.env import HcraftEnv
39 | from hcraft.transformation import Transformation, Use, Yield, PLAYER
40 | from hcraft.world import world_from_transformations
41 | from hcraft.task import GetItemTask
42 |
43 | try:
44 | import gymnasium as gym
45 |
46 | gym.register(
47 | id="TowerHcraft-v1",
48 | entry_point="hcraft.examples.tower:TowerHcraftEnv",
49 | )
50 |
51 | except ImportError:
52 | pass
53 |
54 |
55 | class TowerHcraftEnv(HcraftEnv):
56 | """Tower, a tower-structured hierarchical Environment.
57 |
58 | Item of given layer requires all items of the previous.
59 | The goal is to obtain the last item on top of the tower.
60 |
61 | """
62 |
63 | def __init__(self, height: int = 2, width: int = 3, **kwargs):
64 | """
65 | Args:
66 | height (int): Number of layers of the tower (ignoring goal item).
67 | width (int): Number of items per layer.
68 | """
69 | self.height = height
70 | self.width = width
71 | n_items = self.height * self.width + 1
72 | self.items = [Item(str(i)) for i in range(n_items)]
73 | name = f"TowerHcraft-H{self.height}-W{self.width}"
74 | if not isinstance(kwargs.get("max_step"), int):
75 | if self.width == 1:
76 | kwargs["max_step"] = 1 + int(self.width * (self.height + 1))
77 | else:
78 | # 1 + w + w**2 + ... + w**h
79 | kwargs["max_step"] = 1 + int(
80 | (1 - self.width ** (self.height + 1)) / (1 - self.width)
81 | )
82 | transformations = self.build_transformations(self.items)
83 | world = world_from_transformations(transformations)
84 | if "purpose" not in kwargs:
85 | kwargs["purpose"] = GetItemTask(self.items[-1])
86 | super().__init__(world, name=name, **kwargs)
87 |
88 | def build_transformations(self, items: List[Item]) -> List[Transformation]:
89 | """Build transformations to make every item accessible.
90 |
91 | Args:
92 | items: List of items.
93 |
94 | Returns:
95 | List of craft recipes as transformations.
96 |
97 | """
98 | transformations = []
99 |
100 | # First layer recipes
101 | for first_layer_id in range(self.width):
102 | item = items[first_layer_id]
103 | new_recipe = Transformation(inventory_changes=[Yield(PLAYER, item)])
104 | transformations.append(new_recipe)
105 |
106 | # Tower recipes
107 | for layer in range(1, self.height):
108 | for item_layer_id in range(self.width):
109 | item_id = layer * self.width + item_layer_id
110 | item = items[item_id]
111 |
112 | inventory_changes = [Yield(PLAYER, item)]
113 |
114 | prev_layer_id = (layer - 1) * self.width
115 | for prev_item_id in range(self.width):
116 | required_item = items[prev_layer_id + prev_item_id]
117 | inventory_changes.append(Use(PLAYER, required_item, consume=1))
118 |
119 | new_recipe = Transformation(inventory_changes=inventory_changes)
120 | transformations.append(new_recipe)
121 |
122 | # Last item recipe
123 | last_item = items[-1]
124 | inventory_changes = [Yield(PLAYER, last_item)]
125 | last_layer_id = (self.height - 1) * self.width
126 | for prev_item_id in range(self.width):
127 | required_item = items[last_layer_id + prev_item_id]
128 | inventory_changes.append(Use(PLAYER, required_item, consume=1))
129 |
130 | new_recipe = Transformation(inventory_changes=inventory_changes)
131 | transformations.append(new_recipe)
132 |
133 | return transformations
134 |
--------------------------------------------------------------------------------
/src/hcraft/examples/minicraft/keycorridor.py:
--------------------------------------------------------------------------------
1 | from typing import List
2 |
3 | from hcraft.elements import Item, Zone
4 | from hcraft.task import GetItemTask
5 | from hcraft.transformation import Transformation, Use, Yield, PLAYER, CURRENT_ZONE
6 |
7 | from hcraft.examples.minicraft.minicraft import MiniCraftEnv
8 |
9 | MINICRAFT_NAME = "KeyCorridor"
10 | __doc__ = MiniCraftEnv.description(MINICRAFT_NAME, for_module_header=True)
11 |
12 |
13 | class MiniHCraftKeyCorridor(MiniCraftEnv):
14 | MINICRAFT_NAME = MINICRAFT_NAME
15 | __doc__ = MiniCraftEnv.description(MINICRAFT_NAME)
16 |
17 | START = Zone("start_room")
18 | """Start room."""
19 | KEY_ROOM = Zone("key_room")
20 | """Room containing a key."""
21 | LOCKED_ROOM = Zone("locked_room")
22 | """Room behind a locked door."""
23 |
24 | KEY = Item("key")
25 | """Key used to unlock locked door."""
26 | BALL = Item("ball")
27 | """Ball to pickup."""
28 | WEIGHT = Item("weight")
29 | """Weight of carried items."""
30 |
31 | OPEN_DOOR = Item("open_door")
32 | """Opened lockedroom door."""
33 | OPEN_KEY_DOOR = Item("blue_open_door")
34 | """Opened keyroom door."""
35 | CLOSED_KEY_DOOR = Item("blue_closed_door")
36 | """Closed keyroom door."""
37 | LOCKED_DOOR = Item("locked_door")
38 | """Locked door, can be unlocked with a key."""
39 |
40 | def __init__(self, **kwargs) -> None:
41 | self.task = GetItemTask(self.BALL)
42 | super().__init__(
43 | self.MINICRAFT_NAME,
44 | start_zone=self.START,
45 | start_zones_items={
46 | self.START: [self.CLOSED_KEY_DOOR, self.LOCKED_DOOR],
47 | self.LOCKED_ROOM: [self.BALL],
48 | },
49 | purpose=self.task,
50 | **kwargs,
51 | )
52 |
53 | def build_transformations(self) -> List[Transformation]:
54 | transformations = []
55 |
56 | # Ensure key cannot be created if anywhere else
57 | search_for_key = Transformation(
58 | "search_for_key",
59 | inventory_changes=[
60 | Yield(CURRENT_ZONE, self.KEY, create=1, max=0),
61 | Yield(PLAYER, self.KEY, create=0, max=0),
62 | Yield(self.START, self.KEY, create=0, max=0),
63 | Yield(self.KEY_ROOM, self.KEY, create=0, max=0),
64 | Yield(self.LOCKED_ROOM, self.KEY, create=0, max=0),
65 | ],
66 | zone=self.KEY_ROOM,
67 | )
68 | transformations.append(search_for_key)
69 |
70 | pickup = Transformation(
71 | "pickup_key",
72 | inventory_changes=[
73 | Use(CURRENT_ZONE, self.KEY, consume=1),
74 | Yield(PLAYER, self.KEY),
75 | Yield(PLAYER, self.WEIGHT, max=0),
76 | ],
77 | )
78 | put_down = Transformation(
79 | "put_down_key",
80 | inventory_changes=[
81 | Use(PLAYER, self.KEY, consume=1),
82 | Use(PLAYER, self.WEIGHT, consume=1),
83 | Yield(CURRENT_ZONE, self.KEY, create=1),
84 | ],
85 | )
86 | transformations += [pickup, put_down]
87 |
88 | open_door = Transformation(
89 | "open_door",
90 | inventory_changes=[
91 | Use(CURRENT_ZONE, self.CLOSED_KEY_DOOR, consume=1),
92 | Yield(CURRENT_ZONE, self.OPEN_KEY_DOOR, create=1),
93 | ],
94 | )
95 | transformations.append(open_door)
96 |
97 | move_to_key_room = Transformation(
98 | "move_to_key_room",
99 | destination=self.KEY_ROOM,
100 | inventory_changes=[Use(CURRENT_ZONE, self.OPEN_KEY_DOOR)],
101 | zone=self.START,
102 | )
103 | transformations.append(move_to_key_room)
104 |
105 | for from_zone in [self.KEY_ROOM, self.LOCKED_ROOM]:
106 | move_to_start_room = Transformation(
107 | f"move_to_start_room_from_{from_zone.name}",
108 | destination=self.START,
109 | zone=from_zone,
110 | )
111 | transformations.append(move_to_start_room)
112 |
113 | unlock_door = Transformation(
114 | "unlock_door",
115 | inventory_changes=[
116 | Use(PLAYER, self.KEY),
117 | Use(CURRENT_ZONE, self.LOCKED_DOOR, consume=1),
118 | Yield(CURRENT_ZONE, self.OPEN_DOOR, create=1),
119 | ],
120 | )
121 | transformations.append(unlock_door)
122 |
123 | move_to_locked_room = Transformation(
124 | "move_to_locked_room",
125 | destination=self.LOCKED_ROOM,
126 | inventory_changes=[Use(CURRENT_ZONE, self.OPEN_DOOR)],
127 | zone=self.START,
128 | )
129 | transformations.append(move_to_locked_room)
130 |
131 | pickup_ball = Transformation(
132 | "pickup_ball",
133 | inventory_changes=[
134 | Use(CURRENT_ZONE, self.BALL, consume=1),
135 | Yield(PLAYER, self.BALL),
136 | Yield(PLAYER, self.WEIGHT, max=0),
137 | ],
138 | )
139 | transformations.append(pickup_ball)
140 |
141 | return transformations
142 |
--------------------------------------------------------------------------------
/src/hcraft/examples/__init__.py:
--------------------------------------------------------------------------------
1 | """#HierarchyCraft environement examples.
2 |
3 | Here is the list of available HierarchyCraft environments examples.
4 |
5 | If you built one of your own, send us a pull request so we can add it to the list!
6 |
7 | ##Minecraft inspired
8 |
9 | See `hcraft.examples.minecraft` for more details.
10 | [CLI keyword: `minecraft`]
11 |
12 | | Gym name | Task description |
13 | |:---------------------------------|:-----------------------------------------------------------------------|
14 | | MineHcraft-NoReward-v1 | No task (Sandbox) |
15 | | MineHcraft-Stone-v1 | Get the cobblestone item mining it with a wooden pickaxe |
16 | | MineHcraft-Iron-v1 | Get the iron-ingot item smelting raw ore gathered with a stone pickage |
17 | | MineHcraft-Diamond-v1 | Get the diamond item mining it with an iron pickaxe |
18 | | MineHcraft-EnchantingTable-v1 | Craft the enchanting table from a book, obsidian and diamonds |
19 | | MineHcraft-Dragon-v1 | Get the ender-dragon-head by killing it in the ender |
20 | | MineHcraft-[name]-v1 | Get one of the Item of given `name` where Item is in env.world.items |
21 | | MineHcraft-v1 | Get all items at least once |
22 |
23 |
24 | ##Minigrid inspired
25 |
26 | [CLI keyword: `minicraft`]
27 |
28 | | Gym name | Documentation reference |
29 | |:---------------------------------|:------------------------------------------------|
30 | | MiniHCraftEmpty-v1 | `hcraft.examples.minicraft.empty` |
31 | | MiniHCraftFourRooms-v1 | `hcraft.examples.minicraft.fourrooms` |
32 | | MiniHCraftMultiRoom-v1 | `hcraft.examples.minicraft.multiroom` |
33 | | MiniHCraftCrossing-v1 | `hcraft.examples.minicraft.crossing` |
34 | | MiniHCraftKeyCorridor-v1 | `hcraft.examples.minicraft.keycorridor` |
35 | | MiniHCraftDoorKey-v1 | `hcraft.examples.minicraft.doorkey` |
36 | | MiniHCraftUnlock-v1 | `hcraft.examples.minicraft.unlock` |
37 | | MiniHCraftUnlockPickup-v1 | `hcraft.examples.minicraft.unlockpickup` |
38 | | MiniHCraftBlockedUnlockPickup-v1 | `hcraft.examples.minicraft.unlockpickupblocked` |
39 |
40 | ##Parametrised toy structures
41 | | Gym name | CLI name | Reference |
42 | |:---------------------------------|:------------------|:------------------------------------------------|
43 | | TowerHcraft-v1 | `tower` | `hcraft.examples.tower` |
44 | | RecursiveHcraft-v1 | `recursive` | `hcraft.examples.recursive` |
45 | | LightRecursiveHcraft-v1 | `light-recursive` | `hcraft.examples.light_recursive` |
46 |
47 | ##Stochastic parametrised toy structures
48 | | Gym name | CLI name | Reference |
49 | |:---------------------------------|:------------------|:------------------------------------------------|
50 | | RandomHcraft-v1 | `random` | `hcraft.examples.random_simple` |
51 |
52 | ##Other examples
53 | | Gym name | CLI name | Reference |
54 | |:---------------------------------|:------------------|:------------------------------------------------|
55 | | Treasure-v1 | `treasure` | `hcraft.examples.treasure` |
56 |
57 |
58 | """
59 |
60 | import hcraft.examples.minecraft as minecraft
61 | import hcraft.examples.minicraft as minicraft
62 | import hcraft.examples.random_simple as random_simple
63 | import hcraft.examples.recursive as recursive
64 | import hcraft.examples.light_recursive as light_recursive
65 | import hcraft.examples.tower as tower
66 | import hcraft.examples.treasure as treasure
67 |
68 |
69 | from hcraft.examples.minecraft import MineHcraftEnv, MINEHCRAFT_GYM_ENVS
70 | from hcraft.examples.minicraft import MINICRAFT_ENVS, MINICRAFT_GYM_ENVS
71 | from hcraft.examples.recursive import RecursiveHcraftEnv
72 | from hcraft.examples.light_recursive import LightRecursiveHcraftEnv
73 | from hcraft.examples.tower import TowerHcraftEnv
74 | from hcraft.examples.treasure import TreasureEnv
75 | from hcraft.examples.random_simple import RandomHcraftEnv
76 |
77 | EXAMPLE_ENVS = [
78 | MineHcraftEnv,
79 | *MINICRAFT_ENVS,
80 | TowerHcraftEnv,
81 | RecursiveHcraftEnv,
82 | LightRecursiveHcraftEnv,
83 | TreasureEnv,
84 | # RandomHcraftEnv,
85 | ]
86 |
87 | HCRAFT_GYM_ENVS = [
88 | *MINEHCRAFT_GYM_ENVS,
89 | *MINICRAFT_GYM_ENVS,
90 | "TowerHcraft-v1",
91 | "RecursiveHcraft-v1",
92 | "LightRecursiveHcraft-v1",
93 | "Treasure-v1",
94 | ]
95 |
96 |
97 | __all__ = [
98 | "minecraft",
99 | "minicraft",
100 | "recursive",
101 | "light_recursive",
102 | "tower",
103 | "treasure",
104 | "random_simple",
105 | "MineHcraftEnv",
106 | "RandomHcraftEnv",
107 | "LightRecursiveHcraftEnv",
108 | "RecursiveHcraftEnv",
109 | "TowerHcraftEnv",
110 | ]
111 |
--------------------------------------------------------------------------------
/docs/template/layout.css:
--------------------------------------------------------------------------------
1 | /*
2 | This CSS file contains all style definitions for the global page layout.
3 |
4 | When pdoc is embedded into other systems, it may be left out (or overwritten with an empty file) entirely.
5 | */
6 |
7 | /* Responsive Layout */
8 | html, body {
9 | width: 100%;
10 | height: 100%;
11 | }
12 |
13 | html, main {
14 | scroll-behavior: smooth;
15 | }
16 |
17 | body {
18 | background-color: var(--pdoc-background);
19 | }
20 |
21 | @media (max-width: 769px) {
22 | #navtoggle {
23 | cursor: pointer;
24 | position: absolute;
25 | width: 50px;
26 | height: 40px;
27 | top: 1rem;
28 | right: 1rem;
29 | border-color: var(--text);
30 | color: var(--text);
31 | display: flex;
32 | opacity: 0.8;
33 | }
34 |
35 | #navtoggle:hover {
36 | opacity: 1;
37 | }
38 |
39 | #togglestate + div {
40 | display: none;
41 | }
42 |
43 | #togglestate:checked + div {
44 | display: inherit;
45 | }
46 |
47 | main, header {
48 | padding: 2rem 3vw;
49 | }
50 |
51 | header + main {
52 | margin-top: -3rem;
53 | }
54 |
55 | .git-button {
56 | display: none !important;
57 | }
58 |
59 | nav input[type="search"] {
60 | /* don't overflow into menu button */
61 | max-width: 77%;
62 | }
63 |
64 | nav input[type="search"]:first-child {
65 | /* align vertically with the hamburger menu */
66 | margin-top: -6px;
67 | }
68 |
69 | nav input[type="search"]:valid ~ * {
70 | /* hide rest of the menu when search has contents */
71 | display: none !important;
72 | }
73 | }
74 |
75 | @media (min-width: 770px) {
76 | :root {
77 | --sidebar-width: clamp(12.5rem, 28vw, 22rem);
78 | }
79 |
80 | nav {
81 | position: fixed;
82 | overflow: auto;
83 | height: 100vh;
84 | width: var(--sidebar-width);
85 | }
86 |
87 | main, header {
88 | padding: 3rem 2rem 3rem calc(var(--sidebar-width) + 3rem);
89 | width: calc(54rem + var(--sidebar-width));
90 | max-width: 100%;
91 | }
92 |
93 | header + main {
94 | margin-top: -4rem;
95 | }
96 |
97 | #navtoggle {
98 | display: none;
99 | }
100 | }
101 |
102 | #togglestate {
103 | /*
104 | Don't do `display: none` here.
105 | When a mobile browser is not scrolled all the way to the top,
106 | clicking the label would insert the menu above the scrolling position
107 | and it would stay out of view. By making the checkbox technically
108 | visible it jumps up first and we always get the menu into view when clicked.
109 | */
110 | position: absolute;
111 | height: 0;
112 | /* height:0 isn't enough in Firefox, so we hide it extra well */
113 | opacity: 0;
114 | }
115 |
116 | /* Nav */
117 | nav.pdoc {
118 | --pad: clamp(0.5rem, 2vw, 1.75rem);
119 | --indent: 1.5rem;
120 | background-color: var(--nav-background);
121 | border-right: 1px solid var(--nav-border);
122 | box-shadow: 0 0 20px rgba(50, 50, 50, .2) inset;
123 | padding: 0 0 0 var(--pad);
124 | overflow-wrap: anywhere;
125 | scrollbar-width: thin; /* Scrollbar width on Firefox */
126 | scrollbar-color: var(--nav-border) transparent /* Scrollbar color on Firefox */
127 | }
128 |
129 | nav.pdoc::-webkit-scrollbar {
130 | width: .4rem; /* Scrollbar width on Chromium-based browsers */
131 | }
132 |
133 | nav.pdoc::-webkit-scrollbar-thumb {
134 | background-color: var(--accent2); /* Scrollbar color on Chromium-based browsers */
135 | }
136 |
137 | nav.pdoc > div {
138 | padding: var(--pad) 0;
139 | }
140 |
141 | nav.pdoc .module-list-button {
142 | display: inline-flex;
143 | align-items: center;
144 | color: var(--nav-text);
145 | border-color: var(--muted);
146 | margin-bottom: 1rem;
147 | }
148 |
149 | nav.pdoc .module-list-button:hover {
150 | border-color: var(--text);
151 | }
152 |
153 | nav.pdoc input[type=search] {
154 | display: block;
155 | outline-offset: 0;
156 | width: calc(100% - var(--pad));
157 | }
158 |
159 | nav.pdoc .logo {
160 | max-width: calc(100% - var(--pad));
161 | max-height: 35vh;
162 | display: block;
163 | margin: 0 auto 1rem;
164 | transform: translate(calc(-.5 * var(--pad)), 0);
165 | }
166 |
167 | nav.pdoc ul {
168 | list-style: none;
169 | padding-left: 0;
170 | }
171 |
172 | nav.pdoc > div > ul {
173 | /* undo padding here so that links span entire width */
174 | margin-left: calc(0px - var(--pad));
175 | }
176 |
177 | nav.pdoc li a {
178 | /* re-add padding (+indent) here */
179 | padding: .2rem 0 .2rem calc(var(--pad) + var(--indent));
180 | }
181 |
182 | nav.pdoc > div > ul > li > a {
183 | /* no padding for top-level */
184 | padding-left: var(--pad);
185 | }
186 |
187 | nav.pdoc li {
188 | transition: all 100ms;
189 | }
190 |
191 | nav.pdoc a, nav.pdoc {
192 | color: var(--nav-text);
193 | }
194 | nav.pdoc a:hover {
195 | background-color: var(--nav-hover);
196 | }
197 |
198 | nav.pdoc a {
199 | display: block;
200 | }
201 |
202 | nav.pdoc > h2:first-of-type {
203 | margin-top: 1.5rem;
204 | }
205 |
206 | nav.pdoc .class:before {
207 | content: "class ";
208 | color: var(--muted);
209 | }
210 |
211 | nav.pdoc .function:after {
212 | content: "()";
213 | color: var(--muted);
214 | }
215 |
216 | nav.pdoc footer:before {
217 | content: "";
218 | display: block;
219 | width: calc(100% - var(--pad));
220 | border-top: solid var(--accent2) 1px;
221 | margin-top: 1.5rem;
222 | padding-top: .5rem;
223 | }
224 |
225 | nav.pdoc footer {
226 | font-size: small;
227 | }
228 |
--------------------------------------------------------------------------------
/src/hcraft/solving_behaviors.py:
--------------------------------------------------------------------------------
1 | """# Solving behaviors
2 |
3 | HierarchyCraft environments comes with built-in solutions.
4 | For ANY task in ANY HierarchyCraft environment, a solving behavior can be given
5 | thanks to the fact that no feature extraction is required.
6 |
7 | This behavior can be called on the observation and will return relevant actions, like any agent.
8 |
9 | Solving behavior for any task can simply be obtained like this:
10 |
11 | ```python
12 | behavior = env.solving_behavior(task)
13 | action = behavior(observation)
14 | ```
15 |
16 | Solving behaviors can be used for imitation learning, as teacher or an expert policy.
17 |
18 | ## Example
19 |
20 | Let's get a DIAMOND in MineHcraft:
21 |
22 | ```python
23 | from hcraft.examples import MineHcraftEnv
24 | from hcraft.examples.minecraft.items import DIAMOND
25 | from hcraft.task import GetItemTask
26 |
27 | get_diamond = GetItemTask(DIAMOND)
28 | env = MineHcraftEnv(purpose=get_diamond)
29 | solving_behavior = env.solving_behavior(get_diamond)
30 |
31 | done = False
32 | observation, _info = env.reset()
33 | while not done:
34 | action = solving_behavior(observation)
35 | observation, _reward, terminated, truncated, _info = env.step(action)
36 | done = terminated or truncated
37 |
38 | assert terminated # Env is successfuly terminated
39 | assert get_diamond.is_terminated # DIAMOND has been obtained !
40 | ```
41 |
42 |
43 | """
44 |
45 | from typing import TYPE_CHECKING, Dict
46 |
47 | from hebg import Behavior
48 |
49 | from hcraft.behaviors.behaviors import (
50 | AbleAndPerformTransformation,
51 | GetItem,
52 | DropItem,
53 | PlaceItem,
54 | ReachZone,
55 | )
56 | from hcraft.requirements import RequirementNode, req_node_name
57 | from hcraft.task import GetItemTask, GoToZoneTask, PlaceItemTask, Task
58 |
59 |
60 | if TYPE_CHECKING:
61 | from hcraft.env import HcraftEnv
62 |
63 |
64 | def build_all_solving_behaviors(env: "HcraftEnv") -> Dict[str, "Behavior"]:
65 | """Return a dictionary of handcrafted behaviors to get each item, zone and property."""
66 | all_behaviors = {}
67 | all_behaviors = _reach_zones_behaviors(env, all_behaviors)
68 | all_behaviors = _get_item_behaviors(env, all_behaviors)
69 | all_behaviors = _drop_item_behaviors(env, all_behaviors)
70 | all_behaviors = _get_zone_item_behaviors(env, all_behaviors)
71 | all_behaviors = _do_transfo_behaviors(env, all_behaviors)
72 |
73 | empty_behaviors = []
74 | for name, behavior in all_behaviors.items():
75 | try:
76 | behavior.graph
77 | except ValueError:
78 | empty_behaviors.append(name)
79 | for name in empty_behaviors:
80 | all_behaviors.pop(name)
81 |
82 | # TODO: Use learning complexity instead for more generality
83 | requirements_graph = env.world.requirements.graph
84 |
85 | for behavior in all_behaviors.values():
86 | if isinstance(behavior, AbleAndPerformTransformation):
87 | behavior.complexity = 1
88 | continue
89 | if isinstance(behavior, GetItem):
90 | req_node = req_node_name(behavior.item, RequirementNode.ITEM)
91 | elif isinstance(behavior, DropItem):
92 | # TODO: this clearly is not general enough,
93 | # it would need requirements for non-accumulative to be fine
94 | req_node = req_node_name(behavior.item, RequirementNode.ITEM)
95 | elif isinstance(behavior, ReachZone):
96 | req_node = req_node_name(behavior.zone, RequirementNode.ZONE)
97 | elif isinstance(behavior, PlaceItem):
98 | req_node = req_node_name(behavior.item, RequirementNode.ZONE_ITEM)
99 | else:
100 | raise NotImplementedError
101 | behavior.complexity = requirements_graph.nodes[req_node]["level"]
102 | continue
103 |
104 | return all_behaviors
105 |
106 |
107 | def task_to_behavior_name(task: Task) -> str:
108 | """Get the behavior name that will solve the given task.
109 |
110 | Args:
111 | task: Task to be solved.
112 |
113 | Raises:
114 | NotImplementedError: If task is not supported yet.
115 |
116 | Returns:
117 | str: Name of the solving behavior.
118 | """
119 | if isinstance(task, GetItemTask):
120 | behavior_name = GetItem.get_name(task.item_stack.item)
121 | elif isinstance(task, GoToZoneTask):
122 | behavior_name = ReachZone.get_name(task.zone)
123 | elif isinstance(task, PlaceItemTask):
124 | behavior_name = PlaceItem.get_name(task.item_stack.item, task.zone)
125 | else:
126 | raise NotImplementedError
127 | return behavior_name
128 |
129 |
130 | def _reach_zones_behaviors(env: "HcraftEnv", all_behaviors: Dict[str, "Behavior"]):
131 | for zone in env.world.zones:
132 | behavior = ReachZone(zone, env, all_behaviors=all_behaviors)
133 | all_behaviors[behavior.name] = behavior
134 | return all_behaviors
135 |
136 |
137 | def _get_item_behaviors(env: "HcraftEnv", all_behaviors: Dict[str, "Behavior"]):
138 | for item in env.world.items:
139 | behavior = GetItem(item, env, all_behaviors=all_behaviors)
140 | all_behaviors[behavior.name] = behavior
141 | return all_behaviors
142 |
143 |
144 | def _drop_item_behaviors(env: "HcraftEnv", all_behaviors: Dict[str, "Behavior"]):
145 | for item in env.world.items:
146 | behavior = DropItem(item, env, all_behaviors=all_behaviors)
147 | all_behaviors[behavior.name] = behavior
148 | return all_behaviors
149 |
150 |
151 | def _get_zone_item_behaviors(env: "HcraftEnv", all_behaviors: Dict[str, "Behavior"]):
152 | for zone in [None] + env.world.zones: # Anywhere + in every specific zone
153 | for item in env.world.zones_items:
154 | behavior = PlaceItem(item, env, all_behaviors=all_behaviors, zone=zone)
155 | all_behaviors[behavior.name] = behavior
156 | return all_behaviors
157 |
158 |
159 | def _do_transfo_behaviors(env: "HcraftEnv", all_behaviors: Dict[str, "Behavior"]):
160 | for transfo in env.world.transformations:
161 | behavior = AbleAndPerformTransformation(
162 | env, transfo, all_behaviors=all_behaviors
163 | )
164 | all_behaviors[behavior.name] = behavior
165 | return all_behaviors
166 |
--------------------------------------------------------------------------------
/src/hcraft/task.py:
--------------------------------------------------------------------------------
1 | from abc import abstractmethod
2 | from typing import TYPE_CHECKING, List, Optional, Union
3 |
4 | import numpy as np
5 |
6 | from hcraft.elements import Item, Stack, Zone
7 |
8 | if TYPE_CHECKING:
9 | from hcraft.env import HcraftState
10 | from hcraft.world import World
11 |
12 |
13 | class Task:
14 | """Abstract base class for all HierarchyCraft tasks."""
15 |
16 | def __init__(self, name: str) -> None:
17 | self.name = name
18 | self.terminated = False
19 | self._terminate_player_items = None
20 | self._terminate_position = None
21 | self._terminate_zones_items = None
22 |
23 | def build(self, world: "World") -> None:
24 | """Build the task operation arrays based on the given world."""
25 | self._terminate_position = np.zeros(world.n_zones, dtype=np.int32)
26 | self._terminate_player_items = np.zeros(world.n_items, dtype=np.int32)
27 | self._terminate_zones_items = np.zeros(
28 | (world.n_zones, world.n_zones_items), dtype=np.int32
29 | )
30 |
31 | def is_terminal(self, state: "HcraftState") -> bool:
32 | """
33 | Returns whether the task is terminated.
34 | """
35 | if self.terminated:
36 | return True
37 | self.terminated = self._is_terminal(state)
38 | return self.terminated
39 |
40 | @abstractmethod
41 | def _is_terminal(self, state: "HcraftState") -> bool:
42 | """"""
43 |
44 | @abstractmethod
45 | def reward(self, state: "HcraftState") -> float:
46 | """
47 | Returns the reward for the given state.
48 | """
49 |
50 | def reset(self) -> None:
51 | """
52 | Reset the task termination.
53 | """
54 | self.terminated = False
55 |
56 | def __str__(self) -> str:
57 | return self.name
58 |
59 | def __repr__(self) -> str:
60 | return self.name
61 |
62 |
63 | class AchievementTask(Task):
64 | """Task giving a reward to the player only the first time achieved."""
65 |
66 | def __init__(self, name: str, reward: float):
67 | super().__init__(name)
68 | self._reward = reward
69 |
70 | @abstractmethod
71 | def _is_terminal(self, state: "HcraftState") -> bool:
72 | """
73 | Returns when the achievement is completed.
74 | """
75 |
76 | def reward(self, state: "HcraftState") -> float:
77 | if not self.terminated and self._is_terminal(state):
78 | return self._reward
79 | return 0.0
80 |
81 |
82 | class GetItemTask(AchievementTask):
83 | """Task of getting a given quantity of an item."""
84 |
85 | def __init__(self, item_stack: Union[Item, Stack], reward: float = 1.0):
86 | self.item_stack = _stack_item(item_stack)
87 | super().__init__(name=self.get_name(self.item_stack), reward=reward)
88 |
89 | def build(self, world: "World") -> None:
90 | super().build(world)
91 | item_slot = world.items.index(self.item_stack.item)
92 | self._terminate_player_items[item_slot] = self.item_stack.quantity
93 |
94 | def _is_terminal(self, state: "HcraftState") -> bool:
95 | return np.all(state.player_inventory >= self._terminate_player_items)
96 |
97 | @staticmethod
98 | def get_name(stack: Stack):
99 | """Name of the task for a given Stack"""
100 | quantity_str = _quantity_str(stack.quantity)
101 | return f"Get{quantity_str}{stack.item.name}"
102 |
103 |
104 | class GoToZoneTask(AchievementTask):
105 | """Task to go to a given zone."""
106 |
107 | def __init__(self, zone: Zone, reward: float = 1.0) -> None:
108 | super().__init__(name=self.get_name(zone), reward=reward)
109 | self.zone = zone
110 |
111 | def build(self, world: "World"):
112 | super().build(world)
113 | zone_slot = world.zones.index(self.zone)
114 | self._terminate_position[zone_slot] = 1
115 |
116 | def _is_terminal(self, state: "HcraftState") -> bool:
117 | return np.all(state.position == self._terminate_position)
118 |
119 | @staticmethod
120 | def get_name(zone: Zone):
121 | """Name of the task for a given Stack"""
122 | return f"Go to {zone.name}"
123 |
124 |
125 | class PlaceItemTask(AchievementTask):
126 | """Task to place a quantity of item in a given zone.
127 |
128 | If no zone is given, consider placing the item anywhere.
129 |
130 | """
131 |
132 | def __init__(
133 | self,
134 | item_stack: Union[Item, Stack],
135 | zone: Optional[Union[Zone, List[Zone]]] = None,
136 | reward: float = 1.0,
137 | ):
138 | item_stack = _stack_item(item_stack)
139 | self.item_stack = item_stack
140 | self.zone = zone
141 | super().__init__(name=self.get_name(item_stack, zone), reward=reward)
142 |
143 | def build(self, world: "World"):
144 | super().build(world)
145 | if self.zone is None:
146 | zones_slots = np.arange(self._terminate_zones_items.shape[0])
147 | else:
148 | zones_slots = np.array([world.slot_from_zone(self.zone)])
149 | zone_item_slot = world.zones_items.index(self.item_stack.item)
150 | self._terminate_zones_items[zones_slots, zone_item_slot] = (
151 | self.item_stack.quantity
152 | )
153 |
154 | def _is_terminal(self, state: "HcraftState") -> bool:
155 | if self.zone is None:
156 | return np.any(
157 | np.all(state.zones_inventories >= self._terminate_zones_items, axis=1)
158 | )
159 | return np.all(state.zones_inventories >= self._terminate_zones_items)
160 |
161 | @staticmethod
162 | def get_name(stack: Stack, zone: Optional[Zone]):
163 | """Name of the task for a given Stack and list of Zone"""
164 | quantity_str = _quantity_str(stack.quantity)
165 | zones_str = _zones_str(zone)
166 | return f"Place{quantity_str}{stack.item.name}{zones_str}"
167 |
168 |
169 | def _stack_item(item_or_stack: Union[Item, Stack]) -> Stack:
170 | if not isinstance(item_or_stack, Stack):
171 | item_or_stack = Stack(item_or_stack)
172 | return item_or_stack
173 |
174 |
175 | def _quantity_str(quantity: int):
176 | return f" {quantity} " if quantity > 1 else " "
177 |
178 |
179 | def _zones_str(zone: Optional[Zone]):
180 | if zone is None:
181 | return " anywhere"
182 | return f" in {zone.name}"
183 |
--------------------------------------------------------------------------------
/tests/test_tasks.py:
--------------------------------------------------------------------------------
1 | from dataclasses import dataclass
2 | from typing import Any
3 |
4 | import numpy as np
5 | import pytest
6 | import pytest_check as check
7 |
8 | from hcraft.elements import Item, Stack, Zone
9 | from hcraft.task import GetItemTask, GoToZoneTask, PlaceItemTask
10 | from hcraft.world import World
11 | from tests.custom_checks import check_np_equal
12 |
13 |
14 | @dataclass
15 | class DummyState:
16 | player_inventory: Any = None
17 | position: Any = None
18 | zones_inventories: Any = None
19 |
20 |
21 | def simple_world() -> World:
22 | return World(
23 | items=[Item("dirt"), Item("wood"), Item("stone"), Item("plank")],
24 | zones=[Zone("start"), Zone("other_zone")],
25 | zones_items=[Item("dirt"), Item("table"), Item("wood_house")],
26 | transformations=[],
27 | )
28 |
29 |
30 | class TestGetItem:
31 | @pytest.fixture(autouse=True)
32 | def setup_method(self):
33 | self.world = simple_world()
34 | self.task = GetItemTask(Stack(Item("wood"), 3), reward=5)
35 |
36 | def test_build(self):
37 | """should build expected operations arrays based on the given world."""
38 | self.task.build(self.world)
39 | check_np_equal(self.task._terminate_player_items, np.array([0, 3, 0, 0]))
40 |
41 | def test_build_with_item_only(self):
42 | """should build even if the item is given without a stack."""
43 | task = GetItemTask(Item("wood"), reward=5)
44 | task.build(self.world)
45 | check_np_equal(task._terminate_player_items, np.array([0, 1, 0, 0]))
46 |
47 | def test_terminate(self):
48 | """should terminate only when the player has more than wanted items."""
49 | self.task.build(self.world)
50 |
51 | state = DummyState(player_inventory=np.array([10, 2, 10, 10]))
52 | check.is_false(self.task.is_terminal(state))
53 | state = DummyState(player_inventory=np.array([0, 3, 0, 0]))
54 | check.is_true(self.task.is_terminal(state))
55 | state = DummyState(player_inventory=np.array([0, 4, 0, 0]))
56 | check.is_true(self.task.is_terminal(state))
57 |
58 | def test_reward(self):
59 | """should reward only the first time the task terminates."""
60 | self.task.build(self.world)
61 |
62 | state = DummyState(player_inventory=np.array([10, 2, 10, 10]))
63 | check.equal(self.task.reward(state), 0)
64 | state = DummyState(player_inventory=np.array([0, 4, 0, 0]))
65 | check.equal(self.task.reward(state), 5)
66 | self.task.terminated = True
67 | check.equal(self.task.reward(state), 0)
68 |
69 |
70 | class TestGoToZone:
71 | @pytest.fixture(autouse=True)
72 | def setup_method(self):
73 | self.world = simple_world()
74 | self.task = GoToZoneTask(Zone("other_zone"), reward=5)
75 |
76 | def test_build(self):
77 | """should build expected operations arrays based on the given world."""
78 | self.task.build(self.world)
79 | check_np_equal(self.task._terminate_position, np.array([0, 1]))
80 |
81 | def test_terminate(self):
82 | """should terminate only when the player is in the zone"""
83 | self.task.build(self.world)
84 |
85 | state = DummyState(position=np.array([1, 0]))
86 | check.is_false(self.task.is_terminal(state))
87 | state = DummyState(position=np.array([0, 1]))
88 | check.is_true(self.task.is_terminal(state))
89 |
90 | def test_reward(self):
91 | """should reward only the first time the task terminates."""
92 | self.task.build(self.world)
93 |
94 | state = DummyState(position=np.array([1, 0]))
95 | check.equal(self.task.reward(state), 0)
96 | state = DummyState(position=np.array([0, 1]))
97 | check.equal(self.task.reward(state), 5)
98 | self.task.terminated = True
99 | check.equal(self.task.reward(state), 0)
100 |
101 |
102 | class TestPlaceItem:
103 | @pytest.fixture(autouse=True)
104 | def setup_method(self):
105 | self.world = simple_world()
106 | self.task = PlaceItemTask(
107 | Stack(Item("wood_house"), 2), Zone("other_zone"), reward=5
108 | )
109 |
110 | def test_build(self):
111 | """should build expected operations arrays based on the given world."""
112 | self.task.build(self.world)
113 | expected_op = np.array([[0, 0, 0], [0, 0, 2]])
114 | check_np_equal(self.task._terminate_zones_items, expected_op)
115 |
116 | def test_build_with_item_only(self):
117 | """should build even if the item is given without a stack."""
118 | task = PlaceItemTask(Item("wood_house"), Zone("other_zone"), reward=5)
119 | task.build(self.world)
120 | expected_op = np.array([[0, 0, 0], [0, 0, 1]])
121 | check_np_equal(task._terminate_zones_items, expected_op)
122 |
123 | def test_build_no_zone(self):
124 | """should consider any zone if none is given."""
125 | task = PlaceItemTask(Stack(Item("wood_house"), 2), None, reward=5)
126 | task.build(self.world)
127 | expected_op = np.array([[0, 0, 2], [0, 0, 2]])
128 | check_np_equal(task._terminate_zones_items, expected_op)
129 |
130 | def test_terminate_specific_zone(self):
131 | """should terminate only when the given zone has more than wanted items."""
132 | self.task.build(self.world)
133 |
134 | state = DummyState(zones_inventories=np.array([[10, 10, 10], [10, 10, 0]]))
135 | check.is_false(self.task.is_terminal(state))
136 | state = DummyState(zones_inventories=np.array([[0, 0, 0], [0, 0, 2]]))
137 | check.is_true(self.task.is_terminal(state))
138 |
139 | def test_terminate_any_zone(self):
140 | """should terminate when any zone has more than wanted items."""
141 | task = PlaceItemTask(Stack(Item("wood_house"), 2), reward=5)
142 | task.build(self.world)
143 |
144 | state = DummyState(zones_inventories=np.array([[10, 10, 0], [10, 10, 0]]))
145 | check.is_false(task.is_terminal(state))
146 | state = DummyState(zones_inventories=np.array([[0, 0, 0], [0, 0, 2]]))
147 | check.is_true(task.is_terminal(state))
148 | state = DummyState(zones_inventories=np.array([[0, 0, 2], [0, 0, 0]]))
149 | check.is_true(task.is_terminal(state))
150 |
151 | def test_reward(self):
152 | """should reward only the first time the task terminates."""
153 | self.task.build(self.world)
154 |
155 | state = DummyState(zones_inventories=np.array([[10, 10, 10], [10, 10, 0]]))
156 | check.equal(self.task.reward(state), 0)
157 | state = DummyState(zones_inventories=np.array([[0, 0, 0], [0, 0, 2]]))
158 | check.equal(self.task.reward(state), 5)
159 | self.task.terminated = True
160 | check.equal(self.task.reward(state), 0)
161 |
--------------------------------------------------------------------------------
/src/hcraft/examples/minicraft/unlockpickupblocked.py:
--------------------------------------------------------------------------------
1 | from typing import List
2 |
3 | from hcraft.elements import Item, Zone
4 | from hcraft.task import GetItemTask
5 | from hcraft.transformation import Transformation, Use, Yield, PLAYER, CURRENT_ZONE
6 |
7 | from hcraft.examples.minicraft.minicraft import MiniCraftEnv
8 |
9 | MINICRAFT_NAME = "BlockedUnlockPickup"
10 | __doc__ = MiniCraftEnv.description(MINICRAFT_NAME, for_module_header=True)
11 |
12 |
13 | class MiniHCraftBlockedUnlockPickup(MiniCraftEnv):
14 | MINICRAFT_NAME = MINICRAFT_NAME
15 | __doc__ = MiniCraftEnv.description(MINICRAFT_NAME)
16 |
17 | START = Zone("start_room")
18 | """Start room."""
19 | BOX_ROOM = Zone("box_room")
20 | """Room with a box inside."""
21 |
22 | KEY = Item("key")
23 | """Key used to unlock the door."""
24 | BOX = Item("box")
25 | """Box to pickup."""
26 | BALL = Item("ball")
27 | """Ball blocking the door."""
28 | WEIGHT = Item("weight")
29 | """Weight of carried items, can only be less than 1."""
30 |
31 | OPEN_DOOR = Item("open_door")
32 | """Open door between the two rooms."""
33 | LOCKED_DOOR = Item("locked_door")
34 | """Locked door between the two rooms, can be unlocked with a key."""
35 | BLOCKED_DOOR = Item("blocked_door")
36 | """Open but blocked door between the two rooms."""
37 | BLOCKED_LOCKED_DOOR = Item("blocked_locked_door")
38 | """Locked and blocked door between the two rooms."""
39 |
40 | def __init__(self, **kwargs) -> None:
41 | self.task = GetItemTask(self.BOX)
42 | super().__init__(
43 | self.MINICRAFT_NAME,
44 | purpose=self.task,
45 | start_zone=self.START,
46 | **kwargs,
47 | )
48 |
49 | def build_transformations(self) -> List[Transformation]:
50 | transformations = []
51 |
52 | zones = (self.START, self.BOX_ROOM)
53 | items_in_zone = [(self.KEY, self.START), (self.BOX, self.BOX_ROOM)]
54 |
55 | for item, zone in items_in_zone:
56 | inventory_changes = [
57 | Yield(CURRENT_ZONE, item, create=1),
58 | # Prevent searching if already found
59 | Yield(PLAYER, item, create=0, max=0),
60 | ]
61 | # Prevent searching if item was placed elsewhere
62 | inventory_changes += [Yield(zone, item, create=0, max=0) for zone in zones]
63 | search_for_item = Transformation(
64 | f"search_for_{item.name}",
65 | inventory_changes=inventory_changes,
66 | zone=zone,
67 | )
68 | transformations.append(search_for_item)
69 |
70 | for item in (self.KEY, self.BOX, self.BALL):
71 | pickup = Transformation(
72 | f"pickup_{item.name}",
73 | inventory_changes=[
74 | Use(CURRENT_ZONE, item, consume=1),
75 | Yield(PLAYER, item, create=1),
76 | # WEIGHT prevents carrying more than one item
77 | Yield(PLAYER, self.WEIGHT, create=1, max=0),
78 | ],
79 | )
80 | put_down = Transformation(
81 | f"put_down_{item.name}",
82 | inventory_changes=[
83 | Use(PLAYER, item, consume=1),
84 | Yield(CURRENT_ZONE, item, create=1),
85 | # WEIGHT prevents carrying more than one item
86 | Use(PLAYER, self.WEIGHT, consume=1),
87 | ],
88 | )
89 | transformations += [pickup, put_down]
90 |
91 | search_for_door = Transformation(
92 | "search_for_door",
93 | inventory_changes=[
94 | Yield(self.START, self.BLOCKED_LOCKED_DOOR, create=1, max=0),
95 | Yield(self.START, self.BLOCKED_DOOR, create=0, max=0),
96 | Yield(self.START, self.LOCKED_DOOR, create=0, max=0),
97 | Yield(self.START, self.OPEN_DOOR, create=0, max=0),
98 | ],
99 | zone=self.START,
100 | )
101 | transformations.append(search_for_door)
102 |
103 | unblock_locked_door = Transformation(
104 | "unblock_locked_door",
105 | inventory_changes=[
106 | Yield(PLAYER, self.BALL, create=1),
107 | Yield(PLAYER, self.WEIGHT, create=1, max=0),
108 | Use(self.START, self.BLOCKED_LOCKED_DOOR, consume=1),
109 | Yield(self.START, self.LOCKED_DOOR, create=1),
110 | ],
111 | )
112 | transformations.append(unblock_locked_door)
113 |
114 | block_locked_door = Transformation(
115 | "block_locked_door",
116 | inventory_changes=[
117 | Use(PLAYER, self.BALL, consume=1),
118 | Use(PLAYER, self.WEIGHT, consume=1),
119 | Use(self.START, self.LOCKED_DOOR, consume=1),
120 | Yield(self.START, self.BLOCKED_LOCKED_DOOR, create=1),
121 | ],
122 | )
123 | transformations.append(block_locked_door)
124 |
125 | unlock_door = Transformation(
126 | "unlock_door",
127 | inventory_changes=[
128 | Use(PLAYER, self.KEY),
129 | Use(self.START, self.LOCKED_DOOR, consume=1),
130 | Yield(self.START, self.OPEN_DOOR, create=1),
131 | ],
132 | )
133 | transformations.append(unlock_door)
134 |
135 | block_door = Transformation(
136 | "block_door",
137 | inventory_changes=[
138 | Use(PLAYER, self.BALL, consume=1),
139 | Use(PLAYER, self.WEIGHT, consume=1),
140 | Use(self.START, self.OPEN_DOOR, consume=1),
141 | Yield(self.START, self.BLOCKED_DOOR, create=1),
142 | ],
143 | )
144 | transformations.append(block_door)
145 |
146 | unblock_door = Transformation(
147 | "unblock_door",
148 | inventory_changes=[
149 | Yield(PLAYER, self.BALL, create=1),
150 | Yield(PLAYER, self.WEIGHT, create=1, max=0),
151 | Use(self.START, self.BLOCKED_DOOR, consume=1),
152 | Yield(self.START, self.OPEN_DOOR, create=1),
153 | ],
154 | )
155 | transformations.append(unblock_door)
156 |
157 | move_to_box_room = Transformation(
158 | "move_to_box_room",
159 | destination=self.BOX_ROOM,
160 | inventory_changes=[Use(CURRENT_ZONE, self.OPEN_DOOR)],
161 | zone=self.START,
162 | )
163 | transformations.append(move_to_box_room)
164 |
165 | move_to_start_room = Transformation(
166 | "move_to_start_room",
167 | destination=self.START,
168 | zone=self.BOX_ROOM,
169 | )
170 | transformations.append(move_to_start_room)
171 |
172 | return transformations
173 |
--------------------------------------------------------------------------------