Fix MetaDrive dependency for 3.1.0 release

docs/simulators.rst

@@ -31,6 +31,19 @@ You can install it with:
 
 Scenic supports both 2D and 3D rendering modes for MetaDrive simulations.
 
+.. note::
+
+   MetaDrive **0.4.3** (the current PyPI release) does **not** support Python 3.12/3.13.
+   It also has known issues on macOS Apple Silicon (M-series) with 3D rendering and a
+   braking issue where vehicles may not come to a complete stop.
+
+   To use Python 3.12+ **and** get the fixes for the macOS/braking issues, install
+   MetaDrive from the GitHub repo:
+
+   .. code-block:: console
+
+      python -m pip install "metadrive-simulator @ git+https://github.com/metadriverse/metadrive.git@main"
+
 Scenic uses OpenDRIVE maps, while MetaDrive relies on SUMO maps. Scenic provides corresponding SUMO maps for OpenDRIVE maps under the :file:`assets/maps/CARLA` directory.
 Additionally, you can convert your own OpenDRIVE maps to SUMO maps using the `netconvert <https://sumo.dlr.de/docs/Networks/Import/OpenDRIVE.html>`_ tool.
 To avoid setting the SUMO map manually, name it the same as your OpenDRIVE file and place it in the same directory.

pyproject.toml

@@ -56,7 +56,7 @@ guideways = [
 	'pyproj ~= 3.3; python_version >= "3.10"',
 ]
 metadrive = [
-	"metadrive-simulator@git+https://github.com/metadriverse/metadrive.git@85e5dadc6c7436d324348f6e3d8f8e680c06b4db",
+	"metadrive-simulator >= 0.4.3",
 	"sumolib >= 1.21.0",
 ]
 test = [	# minimum dependencies for running tests (used for tox virtualenvs)
@@ -67,7 +67,7 @@ test = [	# minimum dependencies for running tests (used for tox virtualenvs)
 test-full = [  # like 'test' but adds dependencies for optional features
 	"scenic[test]",       # all dependencies from 'test' extra above
 	"scenic[guideways]",  # for running guideways modules
-	"scenic[metadrive]",
+	'scenic[metadrive]; python_version < "3.12"',  # MetaDrive not on PyPI for Py3.12+ yet; use GitHub (see docs)
 	"astor >= 0.8.1",
 	'carla >= 0.9.12; python_version <= "3.10" and (platform_system == "Linux" or platform_system == "Windows")',
 	"dill",

tests/simulators/metadrive/test_metadrive.py

@@ -1,3 +1,5 @@
+from importlib.metadata import PackageNotFoundError, distribution, version
+import json
 import math
 import os
 from urllib.error import URLError
@@ -28,6 +30,29 @@
 WINDOW_ERR = "Could not open window"
 
 
+def metadrive_installed_from_git():
+    # Git installs still report version "0.4.3"; PEP 610 direct_url.json lets us tell PyPI vs GitHub.
+    try:
+        direct = distribution("metadrive-simulator").read_text("direct_url.json")
+    except PackageNotFoundError:
+        return False
+    if not direct:
+        return False
+    try:
+        return "vcs_info" in json.loads(direct)
+    except json.JSONDecodeError:
+        return False
+
+
+metadrive_pkg_version = version("metadrive-simulator")
+
+xfail_md_brake_bug = pytest.mark.xfail(
+    metadrive_pkg_version == "0.4.3" and not metadrive_installed_from_git(),
+    reason="Known MetaDrive 0.4.3 (PyPI) braking/handbrake bug; install MetaDrive from GitHub for the fix.",
+    strict=False,
+)
+
+
 # Helper to run a simulation but skip cleanly on CI.
 # MetaDrive (Panda3D) tries to open a window on GitHub runners
 # and fails with "Could not open window", while Newtonian (pygame) works fine.
@@ -96,6 +121,7 @@ def test_throttle(getMetadriveSimulator):
     assert speeds[len(speeds) // 2][1] < speeds[-1][1]
 
 
+@xfail_md_brake_bug
 def test_brake(getMetadriveSimulator):
     simulator, openDrivePath, sumoPath = getMetadriveSimulator("Town01")
     code = f"""
@@ -170,6 +196,7 @@ def test_reverse_and_brake(getMetadriveSimulator):
     assert finalSpeed == pytest.approx(0.0, abs=0.5)
 
 
+@xfail_md_brake_bug
 def test_handbrake(getMetadriveSimulator):
     simulator, openDrivePath, sumoPath = getMetadriveSimulator("Town01")
     code = f"""