Add full non-BabyAI MiniGrid support (#356)

## Description

This PR expands EnvPool's MiniGrid support from the `Empty` family to
the full non-BabyAI `MiniGrid-*` set in `minigrid==3.0.0`, using a pure
C++ backend.

It adds the missing MiniGrid task implementations, mission plumbing,
Python registrations, per-environment align coverage, deterministic
coverage, and documentation updates. It also fixes a couple of
header-level ODR/link issues that surfaced once the larger MiniGrid
binding target was linked together.

## Motivation and Context

EnvPool currently exposes only a small subset of upstream MiniGrid
registrations. This change brings the package much closer to upstream
coverage without routing task logic back through Python.

- [ ] I have raised an issue to propose this change
([required](https://envpool.readthedocs.io/en/latest/pages/contributing.html)
for new features and bug fixes)

## Types of changes

- [ ] Bug fix (non-breaking change which fixes an issue)
- [x] New feature (non-breaking change which adds core functionality)
- [x] New environment (non-breaking change which adds 3rd-party
environment)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation (update in the documentation)
- [ ] Example (update in the folder of example)

## Implemented Tasks

- [x] Add pure C++ implementations and registrations for all non-BabyAI
`MiniGrid-*` environments in `minigrid==3.0.0`.
- [x] Add MiniGrid align and deterministic coverage so every registered
environment is exercised against upstream behavior.
- [x] Update MiniGrid documentation and `make_test` coverage for the
expanded environment set.

## Checklist

- [ ] I have read the
[CONTRIBUTION](https://envpool.readthedocs.io/en/latest/pages/contributing.html)
guide (**required**)
- [x] My change requires a change to the documentation.
- [x] I have updated the tests accordingly (*required for a bug fix or a
new feature*).
- [x] I have updated the documentation accordingly.
- [ ] I have reformatted the code using `make format` (**required**)
- [ ] I have checked the code using `make lint` (**required**)
- [x] I have ensured `make bazel-test` pass. (**required**)

## Validation Notes

- `make bazel-test` passed on `dev`.
- `make lint` is still running on `dev`; at PR creation time it is down
to the final clang-tidy pass for
`envpool/minigrid/impl/minigrid_env.cc`.

Author: Trinkle23897

.clang-tidy

@@ -53,5 +53,5 @@ CheckOptions:
   - { key: readability-identifier-naming.StructCase,            value: CamelCase  }
   - { key: readability-identifier-naming.UnionCase,             value: CamelCase  }
   - { key: readability-identifier-naming.VariableCase,          value: lower_case }
-WarningsAsErrors: '*,-clang-diagnostic-deprecated-declarations'
+WarningsAsErrors: '*,-clang-diagnostic-bitwise-instead-of-logical,-clang-diagnostic-deprecated-declarations'
 HeaderFilterRegex: '/envpool/'

docs/env/minigrid.rst

@@ -4,15 +4,245 @@ Minigrid
 We use ``minigrid==3.0.0`` as the codebase.
 See https://github.com/Farama-Foundation/Minigrid/tree/v3.0.0
 
+EnvPool supports all non-BabyAI ``MiniGrid-*`` environments registered by
+upstream ``minigrid==3.0.0``. That is 75 task IDs in total. ``BabyAI-*``
+environments are not implemented.
+
+
+Options
+-------
+
+* ``task_id (str)``: see the available tasks below;
+* ``num_envs (int)``: how many environments you would like to create;
+* ``batch_size (int)``: the expected batch size for return result, default to
+  ``num_envs``;
+* ``num_threads (int)``: the maximum thread number for executing the actual
+  ``env.step``, default to ``batch_size``;
+* ``seed (int | Sequence[int])``: the environment seed. When a sequence is
+  provided, it must contain exactly one seed per environment. Default to
+  ``42``;
+* ``max_episode_steps (int)``: the maximum number of steps for one episode.
+  The default value depends on ``task_id`` and follows the upstream MiniGrid
+  registration.
+
+
+Observation Space
+-----------------
+
+Each MiniGrid observation contains:
+
+* ``obs["image"]``: a ``(agent_view_size, agent_view_size, 3)`` uint8 tensor
+  using the standard MiniGrid object/color/state encoding;
+* ``obs["direction"]``: the agent direction in ``[0, 3]``;
+* ``obs["mission"]``: a fixed-size uint8 byte buffer with length 96;
+* ``info["agent_pos"]``: the agent position in the full grid;
+* ``info["mission_id"]``: a stable integer ID when the mission comes from a
+  finite canonical set, otherwise ``-1``.
+
+Use ``envpool.minigrid.decode_mission(...)`` to decode the mission buffer back
+to a Python string:
+
+.. code-block:: python
+
+   import envpool
+   from envpool.minigrid import decode_mission
+
+   env = envpool.make_gymnasium("MiniGrid-DoorKey-8x8-v0", num_envs=1)
+   obs, info = env.reset()
+   mission = decode_mission(obs["mission"][0])
+
+
+Action Space
+------------
+
+Most tasks expose the standard MiniGrid discrete action space with values in
+``[0, 6]``:
+
+* ``0``: turn left
+* ``1``: turn right
+* ``2``: move forward
+* ``3``: pick up an object
+* ``4``: drop an object
+* ``5``: toggle / interact
+* ``6``: done
+
+``MiniGrid-Dynamic-Obstacles-*`` follows upstream and only uses the movement
+subset ``[0, 2]``.
+
+
+Available Tasks
+---------------
 
 Empty
------
+~~~~~
+
+* ``MiniGrid-Empty-5x5-v0``
+* ``MiniGrid-Empty-Random-5x5-v0``
+* ``MiniGrid-Empty-6x6-v0``
+* ``MiniGrid-Empty-Random-6x6-v0``
+* ``MiniGrid-Empty-8x8-v0``
+* ``MiniGrid-Empty-16x16-v0``
+
+DoorKey
+~~~~~~~
+
+* ``MiniGrid-DoorKey-5x5-v0``
+* ``MiniGrid-DoorKey-6x6-v0``
+* ``MiniGrid-DoorKey-8x8-v0``
+* ``MiniGrid-DoorKey-16x16-v0``
+
+DistShift
+~~~~~~~~~
+
+* ``MiniGrid-DistShift1-v0``
+* ``MiniGrid-DistShift2-v0``
+
+Crossing
+~~~~~~~~
+
+* ``MiniGrid-LavaCrossingS9N1-v0``
+* ``MiniGrid-LavaCrossingS9N2-v0``
+* ``MiniGrid-LavaCrossingS9N3-v0``
+* ``MiniGrid-LavaCrossingS11N5-v0``
+* ``MiniGrid-SimpleCrossingS9N1-v0``
+* ``MiniGrid-SimpleCrossingS9N2-v0``
+* ``MiniGrid-SimpleCrossingS9N3-v0``
+* ``MiniGrid-SimpleCrossingS11N5-v0``
+
+LavaGap
+~~~~~~~
+
+* ``MiniGrid-LavaGapS5-v0``
+* ``MiniGrid-LavaGapS6-v0``
+* ``MiniGrid-LavaGapS7-v0``
+
+Dynamic Obstacles
+~~~~~~~~~~~~~~~~~
+
+* ``MiniGrid-Dynamic-Obstacles-5x5-v0``
+* ``MiniGrid-Dynamic-Obstacles-Random-5x5-v0``
+* ``MiniGrid-Dynamic-Obstacles-6x6-v0``
+* ``MiniGrid-Dynamic-Obstacles-Random-6x6-v0``
+* ``MiniGrid-Dynamic-Obstacles-8x8-v0``
+* ``MiniGrid-Dynamic-Obstacles-16x16-v0``
+
+Fetch
+~~~~~
+
+* ``MiniGrid-Fetch-5x5-N2-v0``
+* ``MiniGrid-Fetch-6x6-N2-v0``
+* ``MiniGrid-Fetch-8x8-N3-v0``
+
+FourRooms
+~~~~~~~~~
+
+* ``MiniGrid-FourRooms-v0``
+
+GoToDoor
+~~~~~~~~
+
+* ``MiniGrid-GoToDoor-5x5-v0``
+* ``MiniGrid-GoToDoor-6x6-v0``
+* ``MiniGrid-GoToDoor-8x8-v0``
+
+GoToObject
+~~~~~~~~~~
+
+* ``MiniGrid-GoToObject-6x6-N2-v0``
+* ``MiniGrid-GoToObject-8x8-N2-v0``
+
+KeyCorridor
+~~~~~~~~~~~
+
+* ``MiniGrid-KeyCorridorS3R1-v0``
+* ``MiniGrid-KeyCorridorS3R2-v0``
+* ``MiniGrid-KeyCorridorS3R3-v0``
+* ``MiniGrid-KeyCorridorS4R3-v0``
+* ``MiniGrid-KeyCorridorS5R3-v0``
+* ``MiniGrid-KeyCorridorS6R3-v0``
+
+LockedRoom
+~~~~~~~~~~
+
+* ``MiniGrid-LockedRoom-v0``
+
+Memory
+~~~~~~
+
+* ``MiniGrid-MemoryS17Random-v0``
+* ``MiniGrid-MemoryS13Random-v0``
+* ``MiniGrid-MemoryS13-v0``
+* ``MiniGrid-MemoryS11-v0``
+* ``MiniGrid-MemoryS9-v0``
+* ``MiniGrid-MemoryS7-v0``
+
+MultiRoom
+~~~~~~~~~
+
+* ``MiniGrid-MultiRoom-N2-S4-v0``
+* ``MiniGrid-MultiRoom-N4-S5-v0``
+* ``MiniGrid-MultiRoom-N6-v0``
+
+ObstructedMaze
+~~~~~~~~~~~~~~
+
+* ``MiniGrid-ObstructedMaze-1Dl-v0``
+* ``MiniGrid-ObstructedMaze-1Dlh-v0``
+* ``MiniGrid-ObstructedMaze-1Dlhb-v0``
+* ``MiniGrid-ObstructedMaze-2Dl-v0``
+* ``MiniGrid-ObstructedMaze-2Dlh-v0``
+* ``MiniGrid-ObstructedMaze-2Dlhb-v0``
+* ``MiniGrid-ObstructedMaze-1Q-v0``
+* ``MiniGrid-ObstructedMaze-2Q-v0``
+* ``MiniGrid-ObstructedMaze-Full-v0``
+* ``MiniGrid-ObstructedMaze-2Dlhb-v1``
+* ``MiniGrid-ObstructedMaze-1Q-v1``
+* ``MiniGrid-ObstructedMaze-2Q-v1``
+* ``MiniGrid-ObstructedMaze-Full-v1``
+
+Playground
+~~~~~~~~~~
+
+* ``MiniGrid-Playground-v0``
+
+PutNear
+~~~~~~~
+
+* ``MiniGrid-PutNear-6x6-N2-v0``
+* ``MiniGrid-PutNear-8x8-N3-v0``
+
+RedBlueDoors
+~~~~~~~~~~~~
+
+* ``MiniGrid-RedBlueDoors-6x6-v0``
+* ``MiniGrid-RedBlueDoors-8x8-v0``
+
+Unlock
+~~~~~~
+
+* ``MiniGrid-Unlock-v0``
+
+UnlockPickup
+~~~~~~~~~~~~
+
+* ``MiniGrid-UnlockPickup-v0``
+
+BlockedUnlockPickup
+~~~~~~~~~~~~~~~~~~~
+
+* ``MiniGrid-BlockedUnlockPickup-v0``
+
+
+Validation
+----------
 
-Registered Configurations
+All registered MiniGrid task IDs are covered by:
 
-- `MiniGrid-Empty-5x5-v0`
-- `MiniGrid-Empty-Random-5x5-v0`
-- `MiniGrid-Empty-6x6-v0`
-- `MiniGrid-Empty-Random-6x6-v0`
-- `MiniGrid-Empty-8x8-v0`
-- `MiniGrid-Empty-16x16-v0`
+* ``//envpool/minigrid:minigrid_align_test`` for upstream behavioral
+  alignment. ``Dynamic Obstacles`` is aligned by transition replay rather than
+  by sharing the exact same RNG bitstream, because upstream NumPy uses
+  ``PCG64`` while EnvPool uses C++ ``mt19937``;
+* ``//envpool/minigrid:minigrid_deterministic_test`` for same-seed
+  determinism;
+* ``//envpool:make_test`` for top-level construction coverage through the
+  public ``envpool.make_*`` entry points.

docs/spelling_wordlist.txt

@@ -14,6 +14,8 @@ bazel
 bazelisk
 buildifier
 addlicense
+BabyAI
+bitstream
 ruff
 envpool
 th

envpool/core/dict.h

@@ -307,7 +307,7 @@ std::vector<Array> MakeArray(const std::tuple<Spec...>& specs) {
  * Dynamic version of MakeArray.
  * Takes a vector of `ShapeSpec`.
  */
-std::vector<Array> MakeArray(const std::vector<ShapeSpec>& specs) {
+inline std::vector<Array> MakeArray(const std::vector<ShapeSpec>& specs) {
   return {specs.begin(), specs.end()};
 }
 

envpool/core/env_spec.h

@@ -23,18 +23,18 @@
 #include "envpool/core/array.h"
 #include "envpool/core/dict.h"
 
-auto common_config = MakeDict(
+inline auto common_config = MakeDict(
     "num_envs"_.Bind(1), "batch_size"_.Bind(0), "num_threads"_.Bind(0),
     "max_num_players"_.Bind(1), "thread_affinity_offset"_.Bind(-1),
     "base_path"_.Bind(std::string("envpool")), "seed"_.Bind(42),
     "env_seed"_.Bind(std::vector<int>{}), "gym_reset_return_info"_.Bind(false),
     "max_episode_steps"_.Bind(std::numeric_limits<int>::max()));
 // Note: this action order is hardcoded in async_envpool Send function
 // and env ParseAction function for performance
-auto common_action_spec = MakeDict("env_id"_.Bind(Spec<int>({})),
-                                   "players.env_id"_.Bind(Spec<int>({-1})));
+inline auto common_action_spec = MakeDict(
+    "env_id"_.Bind(Spec<int>({})), "players.env_id"_.Bind(Spec<int>({-1})));
 // Note: this state order is hardcoded in async_envpool Recv function
-auto common_state_spec =
+inline auto common_state_spec =
     MakeDict("info:env_id"_.Bind(Spec<int>({})),
              "info:players.env_id"_.Bind(Spec<int>({-1})),
              "elapsed_step"_.Bind(Spec<int>({})), "done"_.Bind(Spec<bool>({})),

envpool/core/xla_template.h

@@ -60,6 +60,7 @@ struct CustomCall {
     if (!handle) {
       return xla_ffi::Unexpected(handle.error());
     }
+    // NOLINTNEXTLINE(performance-no-int-to-ptr)
     return reinterpret_cast<Class*>(
         static_cast<std::uintptr_t>(static_cast<std::int64_t>(*handle)));
   }

envpool/make_test.py

@@ -21,6 +21,7 @@
 from absl.testing import absltest
 
 import envpool
+import envpool.minigrid.registration  # noqa: F401
 
 
 class _MakeTest(absltest.TestCase):
@@ -120,8 +121,13 @@ def test_make_box2d(self) -> None:
         ])
 
     def test_make_minigrid(self) -> None:
-        self.assertIn("MiniGrid-Empty-5x5-v0", envpool.list_all_envs())
-        self.check_step(["MiniGrid-Empty-5x5-v0"])
+        task_ids = sorted(
+            task_id
+            for task_id in envpool.list_all_envs()
+            if task_id.startswith("MiniGrid-")
+        )
+        self.assertLen(task_ids, 75)
+        self.check_step(task_ids)
 
     def test_make_mujoco_gym(self) -> None:
         self.check_step([

envpool/minigrid/BUILD

@@ -22,17 +22,16 @@ package(default_visibility = ["//visibility:public"])
 cc_library(
     name = "minigrid_env",
     srcs = [
-        "impl/minigrid_empty_env.cc",
         "impl/minigrid_env.cc",
     ],
     hdrs = [
-        "empty.h",
-        "impl/minigrid_empty_env.h",
+        "minigrid.h",
         "impl/minigrid_env.h",
         "impl/utils.h",
     ],
     deps = [
         "//envpool/core:async_envpool",
+        "//envpool/core:py_envpool",
     ],
 )
 
@@ -49,7 +48,10 @@ py_library(
     name = "minigrid",
     srcs = ["__init__.py"],
     data = [":minigrid_envpool.so"],
-    deps = ["//envpool/python:api"],
+    deps = [
+        "//envpool/python:api",
+        requirement("numpy"),
+    ],
 )
 
 py_library(