feat(ps1): Phase 1 EmuCore plugin, viewport, and session UI

CLAUDE.md

@@ -198,7 +198,7 @@ Three singletons manage core state. All run on the main thread. Access via `Clas
 ### PS1 formats (static) and runtime extraction (experimental)
 
 - **Static parsers** (`src/PS1/`): `PS1TMD`, `PS1TIM`, `PS1RSD`, `PS1PLY`, `PS1MAT` for known PlayStation mesh/texture formats.
-- **Runtime extraction** (`src/PS1/runtime/`, epic #412): `ENABLE_PS1_RIP` (OFF by default). When ON, `PS1RipManager` singleton coordinates emulator embedding, GPU/GTE capture, VRAM dumps, and reconstruction into Ogre meshes. Design doc: `src/PS1/PS1_RIP_DESIGN.md`. CI enables the flag on Linux test builds only. Sentry breadcrumbs use category `ps1.rip`.
+- **Runtime extraction** (`src/PS1/runtime/`, epic #412): `ENABLE_PS1_RIP` (OFF by default). When ON, `PS1RipManager` runs an `EmuCore` plugin from `<app>/PS1Cores/` on a worker thread; stub core `qtmesh_ps1core_stub` ships for CI/dev. Session UI: **Tools → Experimental → PS1 Runtime Ripper…** (`PS1RipSessionWindow`, `EmuViewport`). Design doc: `src/PS1/PS1_RIP_DESIGN.md`. CI enables the flag on Linux test builds only. Sentry breadcrumbs use category `ps1.rip`.
 
 ### Mesh Import/Export
 

CMakeLists.txt

@@ -271,6 +271,7 @@ option(ENABLE_PS1_RIP "Enable experimental PS1 runtime geometry extraction" OFF)
 if(ENABLE_PS1_RIP)
     add_definitions(-DENABLE_PS1_RIP)
     message(STATUS "PS1 runtime geometry extraction enabled (experimental)")
+    add_subdirectory(plugins/ps1core_stub)
 endif()
 ##############################################################
 #  Sentry crash reporting and analytics

plugins/ps1core_stub/CMakeLists.txt

@@ -0,0 +1,32 @@
+if(NOT ENABLE_PS1_RIP)
+    return()
+endif()
+
+set(PS1_RUNTIME_INCLUDE "${CMAKE_SOURCE_DIR}/src/PS1/runtime")
+
+add_library(qtmesh_ps1core_stub MODULE
+    StubEmuCore.cpp
+    StubEmuCorePlugin.cpp
+)
+
+target_include_directories(qtmesh_ps1core_stub PRIVATE
+    ${PS1_RUNTIME_INCLUDE}
+    ${CMAKE_CURRENT_SOURCE_DIR}
+)
+
+target_link_libraries(qtmesh_ps1core_stub PRIVATE Qt6::Core)
+
+set_target_properties(qtmesh_ps1core_stub PROPERTIES
+    PREFIX ""
+    LIBRARY_OUTPUT_DIRECTORY "${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/PS1Cores"
+    RUNTIME_OUTPUT_DIRECTORY "${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/PS1Cores"
+    ARCHIVE_OUTPUT_DIRECTORY "${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/PS1Cores"
+)
+
+if(BUILD_TESTS AND TARGET UnitTests)
+    add_dependencies(UnitTests qtmesh_ps1core_stub)
+endif()
+
+if(BUILD_QT_MESH_EDITOR AND TARGET ${CMAKE_PROJECT_NAME})
+    add_dependencies(${CMAKE_PROJECT_NAME} qtmesh_ps1core_stub)
+endif()

plugins/ps1core_stub/StubEmuCore.cpp

@@ -0,0 +1,83 @@
+#include "StubEmuCore.h"
+
+#include <QFileInfo>
+
+StubEmuCore::StubEmuCore()
+{
+    for (EmuFramebuffer &buf : m_buffers) {
+        buf.width = kWidth;
+        buf.height = kHeight;
+        buf.rgb24.resize(kWidth * kHeight * 3);
+    }
+    fillTestPattern(m_buffers[m_writeIndex]);
+}
+
+QString StubEmuCore::coreId() const
+{
+    return QStringLiteral("stub");
+}
+
+bool StubEmuCore::loadBios(const QString &biosPath)
+{
+    const QFileInfo info(biosPath);
+    if (!info.exists() || !info.isFile())
+        return false;
+    m_biosPath = info.absoluteFilePath();
+    return true;
+}
+
+bool StubEmuCore::loadIso(const QString &isoPath)
+{
+    const QFileInfo info(isoPath);
+    if (!info.exists() || !info.isFile())
+        return false;
+    m_isoPath = info.absoluteFilePath();
+    return true;
+}
+
+void StubEmuCore::runFrame()
+{
+    if (m_biosPath.isEmpty() || m_isoPath.isEmpty())
+        return;
+
+    EmuFramebuffer &buf = m_buffers[static_cast<size_t>(m_writeIndex)];
+    buf.frameIndex = ++m_frameIndex;
+    fillTestPattern(buf);
+
+    m_readIndex = m_writeIndex;
+    m_writeIndex = (m_writeIndex + 1) % 3;
+}
+
+void StubEmuCore::reset()
+{
+    m_frameIndex = 0;
+    fillTestPattern(m_buffers[m_writeIndex]);
+    m_readIndex = m_writeIndex;
+}
+
+const EmuFramebuffer &StubEmuCore::framebuffer() const
+{
+    return m_buffers[static_cast<size_t>(m_readIndex)];
+}
+
+void StubEmuCore::setHooks(EmuHooks *hooks)
+{
+    m_hooks = hooks;
+}
+
+void StubEmuCore::fillTestPattern(EmuFramebuffer &buf)
+{
+    const int w = buf.width;
+    const int h = buf.height;
+    auto *pixels = reinterpret_cast<uchar *>(buf.rgb24.data());
+    const quint8 phase = static_cast<quint8>(buf.frameIndex % 256);
+
+    for (int y = 0; y < h; ++y) {
+        for (int x = 0; x < w; ++x) {
+            const int i = (y * w + x) * 3;
+            pixels[i + 0] = static_cast<uchar>((x + phase) & 0xFF);
+            pixels[i + 1] = static_cast<uchar>((y + phase) & 0xFF);
+            pixels[i + 2] = static_cast<uchar>(((x ^ y) + phase) & 0xFF);
+        }
+    }
+}

plugins/ps1core_stub/StubEmuCore.h

@@ -0,0 +1,38 @@
+#ifndef STUBEMUCORE_H
+#define STUBEMUCORE_H
+
+#include "EmuCore.h"
+
+#include <QString>
+#include <array>
+
+/** Reference / CI core: validates BIOS+ISO paths and renders a test pattern (#415). */
+class StubEmuCore final : public EmuCore
+{
+public:
+    StubEmuCore();
+
+    QString coreId() const override;
+    bool loadBios(const QString &biosPath) override;
+    bool loadIso(const QString &isoPath) override;
+    void runFrame() override;
+    void reset() override;
+    const EmuFramebuffer &framebuffer() const override;
+    void setHooks(EmuHooks *hooks) override;
+
+private:
+    void fillTestPattern(EmuFramebuffer &buf);
+
+    static constexpr int kWidth = 320;
+    static constexpr int kHeight = 240;
+
+    QString m_biosPath;
+    QString m_isoPath;
+    EmuHooks *m_hooks = nullptr;
+    quint64 m_frameIndex = 0;
+    std::array<EmuFramebuffer, 3> m_buffers{};
+    int m_readIndex = 0;
+    int m_writeIndex = 1;
+};
+
+#endif // STUBEMUCORE_H

plugins/ps1core_stub/StubEmuCorePlugin.cpp

@@ -0,0 +1,12 @@
+#include "StubEmuCorePlugin.h"
+#include "StubEmuCore.h"
+
+QString StubEmuCorePlugin::pluginId() const
+{
+    return QStringLiteral("stub");
+}
+
+std::unique_ptr<EmuCore> StubEmuCorePlugin::createCore()
+{
+    return std::make_unique<StubEmuCore>();
+}

plugins/ps1core_stub/StubEmuCorePlugin.h

@@ -0,0 +1,18 @@
+#ifndef STUBEMUCOREPLUGIN_H
+#define STUBEMUCOREPLUGIN_H
+
+#include <QObject>
+#include "IEmuCorePlugin.h"
+
+class StubEmuCorePlugin : public QObject, public IEmuCorePlugin
+{
+    Q_OBJECT
+    Q_PLUGIN_METADATA(IID IEmuCorePlugin_iid FILE "ps1core_stub.json")
+    Q_INTERFACES(IEmuCorePlugin)
+
+public:
+    QString pluginId() const override;
+    std::unique_ptr<EmuCore> createCore() override;
+};
+
+#endif // STUBEMUCOREPLUGIN_H

plugins/ps1core_stub/ps1core_stub.json

@@ -0,0 +1,6 @@
+{
+    "Keys": [],
+    "MetaData": {
+        "description": "QtMeshEditor PS1 stub emulator core (test pattern)"
+    }
+}

src/CMakeLists.txt

@@ -554,6 +554,10 @@ if(BUILD_TESTS)
 
     ADD_DEPENDENCIES(UnitTests ui)
 
+    if(ENABLE_PS1_RIP)
+        add_dependencies(UnitTests qtmesh_ps1core_stub)
+    endif()
+
     # On macOS, create symlinks from Ogre plugin .framework bundles into the
     # UnitTests binary directory so that plugins.cfg (PluginFolder=../) can
     # find them.  The app bundle has these in Contents/MacOS/ via INSTALL

src/PS1/CMakeLists.txt

@@ -22,11 +22,23 @@ ${CMAKE_CURRENT_SOURCE_DIR}/PS1TIM.h
 
 if(ENABLE_PS1_RIP)
     list(APPEND SRC_FILES
+        ${CMAKE_CURRENT_SOURCE_DIR}/runtime/EmuCoreLoader.cpp
+        ${CMAKE_CURRENT_SOURCE_DIR}/runtime/EmuViewport.cpp
+        ${CMAKE_CURRENT_SOURCE_DIR}/runtime/PS1RipLegalityDialog.cpp
         ${CMAKE_CURRENT_SOURCE_DIR}/runtime/PS1RipManager.cpp
+        ${CMAKE_CURRENT_SOURCE_DIR}/runtime/PS1RipSessionWindow.cpp
         ${CMAKE_CURRENT_SOURCE_DIR}/runtime/PS1RipWorker.cpp
     )
     list(APPEND HEADER_FILES
+        ${CMAKE_CURRENT_SOURCE_DIR}/runtime/EmuCore.h
+        ${CMAKE_CURRENT_SOURCE_DIR}/runtime/EmuCoreLoader.h
+        ${CMAKE_CURRENT_SOURCE_DIR}/runtime/EmuFramebuffer.h
+        ${CMAKE_CURRENT_SOURCE_DIR}/runtime/EmuHooks.h
+        ${CMAKE_CURRENT_SOURCE_DIR}/runtime/EmuViewport.h
+        ${CMAKE_CURRENT_SOURCE_DIR}/runtime/IEmuCorePlugin.h
+        ${CMAKE_CURRENT_SOURCE_DIR}/runtime/PS1RipLegalityDialog.h
         ${CMAKE_CURRENT_SOURCE_DIR}/runtime/PS1RipManager.h
+        ${CMAKE_CURRENT_SOURCE_DIR}/runtime/PS1RipSessionWindow.h
         ${CMAKE_CURRENT_SOURCE_DIR}/runtime/PS1RipWorker.h
     )
 endif()

src/PS1/PS1_RIP_DESIGN.md

@@ -55,7 +55,13 @@ option(ENABLE_PS1_RIP "Enable experimental PS1 runtime geometry extraction" OFF)
 
 See epic #412 for phased issues (#413–#431).
 
+## Phase 1 status
+
+- `EmuCore` + `IEmuCorePlugin` + `EmuCoreLoader` landed (#415).
+- Stub plugin `plugins/ps1core_stub/` renders a 320×240 test pattern when BIOS+ISO paths validate.
+- `PS1RipSessionWindow` + `EmuViewport` + legality dialog (#416–#417) — keyboard/gamepad input still TODO.
+
 ## Open questions
 
-- Exact plugin ABI for `EmuCore` (#415).
+- mednafen-psx plugin build/integration (replace stub for real emulation).
 - BIOS / ISO first-run legality dialog copy (#417) — requires legal review before release.

src/PS1/runtime/EmuCore.h

@@ -0,0 +1,28 @@
+#ifndef EMUCORE_H
+#define EMUCORE_H
+
+#include "EmuFramebuffer.h"
+#include "EmuHooks.h"
+
+#include <QString>
+#include <memory>
+
+/**
+ * Abstract PS1 emulator core (#415). Implemented by dynamically loaded plugins
+ * under <app>/PS1Cores/ — never linked into the main QtMeshEditor binary.
+ */
+class EmuCore
+{
+public:
+    virtual ~EmuCore() = default;
+
+    virtual QString coreId() const = 0;
+    virtual bool loadBios(const QString &biosPath) = 0;
+    virtual bool loadIso(const QString &isoPath) = 0;
+    virtual void runFrame() = 0;
+    virtual void reset() = 0;
+    virtual const EmuFramebuffer &framebuffer() const = 0;
+    virtual void setHooks(EmuHooks *hooks) = 0;
+};
+
+#endif // EMUCORE_H

src/PS1/runtime/EmuCoreLoader.cpp

@@ -0,0 +1,79 @@
+#include "EmuCoreLoader.h"
+#include "IEmuCorePlugin.h"
+
+#include <QCoreApplication>
+#include <QDir>
+#include <QFileInfo>
+#include <QPluginLoader>
+
+namespace {
+
+QString bundleOrAppDir()
+{
+    return QCoreApplication::applicationDirPath();
+}
+
+QStringList pluginFileNames()
+{
+#if defined(Q_OS_WIN)
+    return {QStringLiteral("qtmesh_ps1core_stub.dll")};
+#elif defined(Q_OS_MACOS)
+    return {QStringLiteral("libqtmesh_ps1core_stub.dylib"),
+            QStringLiteral("qtmesh_ps1core_stub.dylib")};
+#else
+    return {QStringLiteral("libqtmesh_ps1core_stub.so"),
+            QStringLiteral("qtmesh_ps1core_stub.so")};
+#endif
+}
+
+} // namespace
+
+QStringList EmuCoreLoader::coreSearchPaths()
+{
+    QStringList paths;
+    const QString base = bundleOrAppDir();
+    paths << QDir(base).filePath(QStringLiteral("PS1Cores"));
+    paths << QDir(QCoreApplication::applicationDirPath()).filePath(QStringLiteral("PS1Cores"));
+    paths.removeDuplicates();
+    return paths;
+}
+
+std::unique_ptr<EmuCore> EmuCoreLoader::loadCore(QString *errorOut)
+{
+    const QStringList names = pluginFileNames();
+    for (const QString &dirPath : coreSearchPaths()) {
+        const QDir dir(dirPath);
+        if (!dir.exists())
+            continue;
+
+        for (const QString &fileName : names) {
+            const QString pluginPath = dir.filePath(fileName);
+            if (!QFileInfo::exists(pluginPath))
+                continue;
+
+            QPluginLoader loader(pluginPath);
+            QObject *instance = loader.instance();
+            if (!instance) {
+                if (errorOut)
+                    *errorOut = loader.errorString();
+                continue;
+            }
+
+            auto *plugin = qobject_cast<IEmuCorePlugin *>(instance);
+            if (!plugin) {
+                if (errorOut)
+                    *errorOut = QObject::tr("Plugin does not implement IEmuCorePlugin: %1").arg(pluginPath);
+                continue;
+            }
+
+            return plugin->createCore();
+        }
+    }
+
+    if (errorOut) {
+        *errorOut = QObject::tr(
+            "No PS1 emulator core found in PS1Cores/. "
+            "Build with ENABLE_PS1_RIP=ON to install the stub core.");
+    }
+    return nullptr;
+}

src/PS1/runtime/EmuCoreLoader.h

@@ -0,0 +1,19 @@
+#ifndef EMUCORELOADER_H
+#define EMUCORELOADER_H
+
+#include "EmuCore.h"
+
+#include <QString>
+#include <memory>
+
+/**
+ * Loads an EmuCore implementation from <app>/PS1Cores/*.so at runtime.
+ */
+class EmuCoreLoader
+{
+public:
+    static QStringList coreSearchPaths();
+    static std::unique_ptr<EmuCore> loadCore(QString *errorOut = nullptr);
+};
+
+#endif // EMUCORELOADER_H