Merge pull request #3119 from rommapp/copilot/use-pico-8-cover-art

gantoine · web-flow · commit fcfb74a8a2f7 · 2026-03-11T21:22:36.000-04:00
feat: use PICO-8 built-in cover art from .p8.png cartridge files
diff --git a/backend/handler/filesystem/roms_handler.py b/backend/handler/filesystem/roms_handler.py
@@ -60,6 +60,10 @@
     )
 )
 
+# PICO-8 cartridges are often stored as PNG files
+PICO8_CARTRIDGE_EXTENSION = ".p8.png"
+
+
 # CHD (Compressed Hunks of Data) v5 format constants
 # See: https://github.com/mamedev/mame/blob/master/src/lib/util/chd.h
 CHD_SIGNATURE: Final = b"MComprHD"
@@ -728,3 +732,19 @@ async def rename_fs_rom(self, old_name: str, new_name: str, fs_path: str) -> Non
             await self.move_file_or_folder(
                 f"{fs_path}/{old_name}", f"{fs_path}/{new_name}"
             )
+
+    def get_pico8_cover_url(
+        self, platform_slug: str, fs_name: str, fs_path: str
+    ) -> str | None:
+        """Return a ``file://`` URL for a PICO-8 cartridge label, or ``None``.
+
+        PICO-8 ``.p8.png`` files are valid PNG images whose visual content *is*
+        the cartridge label/cover art.  When such a ROM is found we can use the
+        file itself as the cover instead of fetching one from an external source.
+        """
+        if platform_slug == UPS.PICO and fs_name.lower().endswith(
+            PICO8_CARTRIDGE_EXTENSION
+        ):
+            rom_path = self.validate_path(f"{fs_path}/{fs_name}")
+            return f"file://{rom_path}"
+        return None
diff --git a/backend/handler/scan_handler.py b/backend/handler/scan_handler.py
@@ -8,7 +8,7 @@
 from config.config_manager import config_manager as cm
 from endpoints.responses.rom import SimpleRomSchema
 from handler.database import db_platform_handler, db_rom_handler
-from handler.filesystem import fs_asset_handler, fs_firmware_handler
+from handler.filesystem import fs_asset_handler, fs_firmware_handler, fs_rom_handler
 from handler.filesystem.roms_handler import FSRom
 from handler.metadata import (
     meta_flashpoint_handler,
@@ -765,6 +765,16 @@ async def fetch_hasheous_rom(hasheous_rom: HasheousRom) -> HasheousRom:
             }
         )
 
+    # Use PICO-8 cartridge PNG as cover art if no cover is set.
+    # PICO-8 .p8.png files are valid PNG images whose visual content is the
+    # cartridge label, so the ROM file itself serves as the cover art.
+    if not rom_attrs.get("url_cover") and not rom_attrs.get("path_cover_s"):
+        pico8_url = fs_rom_handler.get_pico8_cover_url(
+            platform.slug, rom_attrs["fs_name"], rom_attrs["fs_path"]
+        )
+        if pico8_url:
+            rom_attrs["url_cover"] = pico8_url
+
     # If not found in any metadata source, we return the rom with the default values
     if (
         not rom_attrs.get("igdb_id")
diff --git a/backend/tests/endpoints/sockets/test_scan.py b/backend/tests/endpoints/sockets/test_scan.py
@@ -1,9 +1,13 @@
+from pathlib import Path
 from unittest.mock import Mock
 
 import pytest
 import socketio
 
+from config import LIBRARY_BASE_PATH
 from endpoints.sockets.scan import ScanStats, _should_scan_rom
+from handler.filesystem.roms_handler import FSRomsHandler
+from handler.metadata.base_handler import UniversalPlatformSlug as UPS
 from handler.scan_handler import ScanType
 from models.rom import Rom
 
@@ -244,3 +248,66 @@ def test_comprehensive_scenarios(
 
         result = _should_scan_rom(scan_type, rom, roms_ids, ["igdb"])
         assert result is expected
+
+
+class TestGetPico8CoverUrl:
+    """Tests for the PICO-8 cover art URL helper on FSRomsHandler."""
+
+    @pytest.fixture
+    def handler(self):
+        return FSRomsHandler()
+
+    def test_returns_file_url_for_pico8_cartridge(self, handler: FSRomsHandler):
+        url = handler.get_pico8_cover_url(
+            platform_slug=UPS.PICO,
+            fs_name="mygame.p8.png",
+            fs_path="pico/roms",
+        )
+        expected = f"file://{Path(LIBRARY_BASE_PATH).resolve() / 'pico/roms' / 'mygame.p8.png'}"
+        assert url == expected
+
+    def test_returns_none_for_non_pico8_platform(self, handler: FSRomsHandler):
+        url = handler.get_pico8_cover_url(
+            platform_slug="snes",
+            fs_name="mygame.p8.png",
+            fs_path="snes/roms",
+        )
+        assert url is None
+
+    def test_returns_none_for_plain_p8_text_file(self, handler: FSRomsHandler):
+        """Plain .p8 files are text-only and have no embedded PNG image."""
+        url = handler.get_pico8_cover_url(
+            platform_slug=UPS.PICO,
+            fs_name="mygame.p8",
+            fs_path="pico/roms",
+        )
+        assert url is None
+
+    def test_returns_none_for_unrelated_extension(self, handler: FSRomsHandler):
+        url = handler.get_pico8_cover_url(
+            platform_slug=UPS.PICO,
+            fs_name="mygame.zip",
+            fs_path="pico/roms",
+        )
+        assert url is None
+
+    def test_url_starts_with_file_scheme(self, handler: FSRomsHandler):
+        url = handler.get_pico8_cover_url(
+            platform_slug=UPS.PICO,
+            fs_name="cart.p8.png",
+            fs_path="pico/roms",
+        )
+        assert url is not None
+        assert url.startswith("file://")
+
+    def test_url_contains_fs_path_and_name(self, handler: FSRomsHandler):
+        fs_path = "pico/roms"
+        fs_name = "celeste.p8.png"
+        url = handler.get_pico8_cover_url(
+            platform_slug=UPS.PICO,
+            fs_name=fs_name,
+            fs_path=fs_path,
+        )
+        assert url is not None
+        assert fs_path in url
+        assert fs_name in url
