Merge pull request #3580 from rommapp/claude/youthful-wozniak-ocjhc0

feat(v2): interactive 3D box art on the game detail hero

Author: gantoine

backend/config/config_manager.py

@@ -73,6 +73,7 @@ class MetadataMediaType(enum.StrEnum):
     BEZEL = "bezel"
     BOX2D = "box2d"
     BOX2D_BACK = "box2d_back"
+    BOX2D_SIDE = "box2d_side"
     BOX3D = "box3d"
     MIXIMAGE = "miximage"
     MIXIMAGE_V2 = "miximage_v2"

backend/handler/metadata/ss_handler.py

@@ -183,6 +183,7 @@ class SSMetadataMedia(TypedDict):
     # Resources stored in filesystem
     bezel_path: str | None
     box2d_back_path: str | None
+    box2d_side_path: str | None
     box3d_path: str | None
     fanart_path: str | None
     miximage_path: str | None
@@ -244,6 +245,7 @@ def extract_media_from_ss_game(rom: Rom, game: SSGame) -> SSMetadataMedia:
         video_normalized_url=None,
         bezel_path=None,
         box2d_back_path=None,
+        box2d_side_path=None,
         box3d_path=None,
         fanart_path=None,
         miximage_path=None,
@@ -358,6 +360,10 @@ def extract_media_from_ss_game(rom: Rom, game: SSGame) -> SSMetadataMedia:
                 ss_media["box2d_side_url"] = strip_sensitive_query_params(
                     media["url"], SENSITIVE_KEYS
                 )
+                if MetadataMediaType.BOX2D_SIDE in preferred_media_types:
+                    ss_media["box2d_side_path"] = (
+                        f"{fs_resource_handler.get_media_resources_path(rom.platform_id, rom.id, MetadataMediaType.BOX2D_SIDE)}/box2d_side.png"
+                    )
             elif media.get("type") == "steamgrid" and not ss_media["steamgrid_url"]:
                 ss_media["steamgrid_url"] = strip_sensitive_query_params(
                     media["url"], SENSITIVE_KEYS

backend/tests/handler/metadata/test_ss_handler.py

@@ -208,6 +208,86 @@ def test_preferred_region_wins_over_cus(self):
         assert result["box2d_url"] is not None
         assert "box-2D(us)" in result["box2d_url"]
 
+    def _make_game_with_box_faces(self) -> SSGame:
+        """A game exposing all three box faces: front, back and spine."""
+        return cast(
+            SSGame,
+            {
+                "medias": [
+                    {
+                        "type": "box-2D",
+                        "parent": "jeu",
+                        "region": "us",
+                        "url": "https://screenscraper.example.com/box-2D",
+                        "crc": "aabbccdd",
+                        "md5": "deadbeef",
+                        "sha1": "cafebabe",
+                        "size": "12345",
+                        "format": "png",
+                    },
+                    {
+                        "type": "box-2D-back",
+                        "parent": "jeu",
+                        "region": "us",
+                        "url": "https://screenscraper.example.com/box-2D-back",
+                        "crc": "11223344",
+                        "md5": "feedface",
+                        "sha1": "baadf00d",
+                        "size": "23456",
+                        "format": "png",
+                    },
+                    {
+                        "type": "box-2D-side",
+                        "parent": "jeu",
+                        "region": "us",
+                        "url": "https://screenscraper.example.com/box-2D-side",
+                        "crc": "55667788",
+                        "md5": "0ddba11",
+                        "sha1": "f00dcafe",
+                        "size": "34567",
+                        "format": "png",
+                    },
+                ]
+            },
+        )
+
+    def test_box2d_side_path_set_when_in_config(self):
+        """When 'box2d_side' is in SCAN_MEDIA the spine is persisted locally."""
+        config = _make_config(scan_media=["box2d", "box2d_back", "box2d_side"])
+        rom = self._make_rom()
+        game = self._make_game_with_box_faces()
+
+        with (
+            patch("handler.metadata.ss_handler.cm.get_config", return_value=config),
+            patch(
+                "handler.metadata.ss_handler.fs_resource_handler.get_media_resources_path",
+                side_effect=lambda pid, rid, mt: f"roms/{pid}/{rid}/{mt.value}",
+            ),
+        ):
+            result = extract_media_from_ss_game(rom, game)
+
+        assert result["box2d_side_url"] is not None
+        assert "box-2D-side" in result["box2d_side_url"]
+        assert result["box2d_side_path"] == "roms/1/100/box2d_side/box2d_side.png"
+
+    def test_box2d_side_path_not_set_when_absent_from_config(self):
+        """Without 'box2d_side' in SCAN_MEDIA the spine URL is kept but not stored."""
+        config = _make_config(scan_media=["box2d", "box2d_back"])
+        rom = self._make_rom()
+        game = self._make_game_with_box_faces()
+
+        with (
+            patch("handler.metadata.ss_handler.cm.get_config", return_value=config),
+            patch(
+                "handler.metadata.ss_handler.fs_resource_handler.get_media_resources_path",
+                side_effect=lambda pid, rid, mt: f"roms/{pid}/{rid}/{mt.value}",
+            ),
+        ):
+            result = extract_media_from_ss_game(rom, game)
+
+        assert result["box2d_side_url"] is not None
+        assert result["box2d_side_path"] is None
+
     def _make_game_with_both_miximage_versions(self) -> SSGame:
         """A game that has both mixrbv1 and mixrbv2 (v1 listed first, matching SS API order)."""
         return cast(

examples/config.example.yml

@@ -133,6 +133,7 @@
 #     - video_normalized  # Normalized video (smaller file size than video)
 #     # Media used for batocera gamelist.xml export
 #     - box2d_back  # Back cover art
+#     - box2d_side  # Box spine (enables the interactive 3D box on detail pages)
 #     - logo  # Transparent logo
 #     # Other media assets (might be used in the future)
 #     - marquee  # Custom marquee

frontend/src/__generated__/models/RomSSMetadata.ts

@@ -8,6 +8,7 @@
   "age-rating": "Възрастова оценка",
   "all-styles": "Всички стилове",
   "backlogged": "В списъка",
+  "box3d-alt": "Въртяща се 3D кутия за {title}",
   "by": "от",
   "cant-copy-link": "Линкът не може да бъде копиран, копирай го ръчно",
   "collections": "Колекции",

frontend/src/locales/bg_BG/rom.json

@@ -8,6 +8,7 @@
   "age-rating": "Hodnocení věku",
   "all-styles": "Všechny styly",
   "backlogged": "Odloženo",
+  "box3d-alt": "Otočná 3D krabice pro {title}",
   "by": "od",
   "cant-copy-link": "Nelze zkopírovat odkaz do schránky, zkopírujte ručně",
   "collections": "Kolekce",

frontend/src/locales/cs_CZ/rom.json

@@ -8,6 +8,7 @@
   "age-rating": "Altersfreigabe",
   "all-styles": "Alle Stile",
   "backlogged": "Vorgemerkt",
+  "box3d-alt": "Drehbares 3D-Cover von {title}",
   "by": "nach",
   "cant-copy-link": "Link kann nicht in Zwischenablage kopiert werden. Bitte manuell kopieren.",
   "collections": "Sammlungen",

frontend/src/locales/de_DE/rom.json

@@ -8,6 +8,7 @@
   "age-rating": "Age rating",
   "all-styles": "All Styles",
   "backlogged": "Backlogged",
+  "box3d-alt": "Rotatable 3D box art for {title}",
   "by": "by",
   "cant-copy-link": "Can't copy link to clipboard, copy it manually",
   "collections": "Collections",

frontend/src/locales/en_GB/rom.json

@@ -8,6 +8,7 @@
   "age-rating": "Age rating",
   "all-styles": "All Styles",
   "backlogged": "Backlogged",
+  "box3d-alt": "Rotatable 3D box art for {title}",
   "by": "by",
   "cant-copy-link": "Can't copy link to clipboard, copy it manually",
   "collections": "Collections",