feat(pose-lib): sub-slice D-Project — .poselib sidecar persistence

src/PoseLibrary.cpp

@@ -14,6 +14,11 @@
 #include "SentryReporter.h"
 
 #include <QCoreApplication>
+#include <QFile>
+#include <QJsonArray>
+#include <QJsonDocument>
+#include <QJsonObject>
+#include <QSaveFile>
 #include <QThread>
 
 #include <OgreBone.h>
@@ -304,6 +309,147 @@
     }
 }
 
+namespace {
+
+// Schema string written into / verified out of the sidecar JSON.
+// Bump when the format changes incompatibly so loadPoseLibrary can
+// reject older files cleanly.
+constexpr const char* kPoseLibSchemaV1 = "qtmesheditor.poselib.v1";
+
+} // namespace
+
+bool PoseLibrary::savePoseLibrary(Ogre::Entity* entity, const QString& filePath) const
+{
+    assertMainThread();
+    if (!entity || filePath.isEmpty()) return false;
+    auto entIt = m_byEntity.constFind(entity);
+    if (entIt == m_byEntity.constEnd()) return false;
+    if (entIt->order.isEmpty()) return false;
+
+    QJsonArray poses;
+    for (const QString& name : entIt->order) {
+        auto poseIt = entIt->byName.constFind(name);
+        if (poseIt == entIt->byName.constEnd()) continue;
+        QJsonObject bones;
+        for (auto bIt = poseIt->cbegin(); bIt != poseIt->cend(); ++bIt) {
+            const auto& trs = bIt.value();
+            QJsonObject bone;
+            bone["t"] = QJsonArray{ trs.translate.x, trs.translate.y, trs.translate.z };
+            bone["r"] = QJsonArray{ trs.rotation.w, trs.rotation.x,
+                                     trs.rotation.y, trs.rotation.z };
+            bone["s"] = QJsonArray{ trs.scale.x, trs.scale.y, trs.scale.z };
+            bones[bIt.key()] = bone;
+        }
+        QJsonObject poseObj;
+        poseObj["name"] = name;
+        poseObj["bones"] = bones;
+        poses.append(poseObj);
+    }
+
+    QJsonObject root;
+    root["schema"] = kPoseLibSchemaV1;
+    root["poses"] = poses;
+
+    // QSaveFile gives atomic write: temp file + rename on commit, so
+    // a power loss / kill -9 mid-write doesn't leave a half-written
+    // sidecar that loadPoseLibrary later rejects.
+    QSaveFile file(filePath);
+    if (!file.open(QIODevice::WriteOnly | QIODevice::Truncate)) return false;
+    if (file.write(QJsonDocument(root).toJson(QJsonDocument::Indented)) < 0) {
+        file.cancelWriting();
+        return false;
+    }
+    if (!file.commit()) return false;
+
+    SentryReporter::addBreadcrumb("scene.anim.pose",
+        QStringLiteral("save library to '%1' (%2 poses)")
+            .arg(filePath).arg(entIt->order.size()));
+    return true;
+}
+
+bool PoseLibrary::loadPoseLibrary(Ogre::Entity* entity, const QString& filePath)
+{
+    assertMainThread();
+    if (!entity || filePath.isEmpty()) return false;
+    QFile file(filePath);
+    if (!file.open(QIODevice::ReadOnly)) return false;
+    const QByteArray bytes = file.readAll();
+    file.close();
+    QJsonParseError parseError{};
+    const QJsonDocument doc = QJsonDocument::fromJson(bytes, &parseError);
+    if (parseError.error != QJsonParseError::NoError) return false;
+    if (!doc.isObject()) return false;
+    const QJsonObject root = doc.object();
+    if (root.value("schema").toString() != QString::fromLatin1(kPoseLibSchemaV1))
+        return false;
+    const QJsonArray poses = root.value("poses").toArray();
+
+    // Wipe the existing per-entity entry — the file is canonical
+    // for this load. Partial overlay would be confusing UX (which
+    // pose wins on name collision?), so we go with replacement.
+    m_byEntity.remove(entity);
+    auto& store = m_byEntity[entity];
+
+    auto readVec3 = [](const QJsonArray& a, const Ogre::Vector3& def) -> Ogre::Vector3 {
+        if (a.size() != 3) return def;
+        return Ogre::Vector3(static_cast<Ogre::Real>(a[0].toDouble()),
+                             static_cast<Ogre::Real>(a[1].toDouble()),
+                             static_cast<Ogre::Real>(a[2].toDouble()));
+    };
+    auto readQuat = [](const QJsonArray& a, const Ogre::Quaternion& def) -> Ogre::Quaternion {
+        if (a.size() != 4) return def;
+        return Ogre::Quaternion(static_cast<Ogre::Real>(a[0].toDouble()),
+                                static_cast<Ogre::Real>(a[1].toDouble()),
+                                static_cast<Ogre::Real>(a[2].toDouble()),
+                                static_cast<Ogre::Real>(a[3].toDouble()));
+    };
+
+    for (const QJsonValue& p : poses) {
+        const QJsonObject pObj = p.toObject();
+        const QString name = pObj.value("name").toString();
+        if (name.isEmpty()) continue;
+        PoseSnapshot snapshot;
+        const QJsonObject bones = pObj.value("bones").toObject();
+        for (auto it = bones.constBegin(); it != bones.constEnd(); ++it) {
+            const QJsonObject boneObj = it.value().toObject();
+            BonePoseSnapshot trs;
+            trs.translate = readVec3(boneObj.value("t").toArray(),
+                                      Ogre::Vector3::ZERO);
+            trs.rotation = readQuat(boneObj.value("r").toArray(),
+                                     Ogre::Quaternion::IDENTITY);
+            trs.scale = readVec3(boneObj.value("s").toArray(),
+                                  Ogre::Vector3(1, 1, 1));
+            snapshot.insert(it.key(), trs);
+        }
+        store.byName.insert(name, snapshot);
+        store.order.append(name);
+    }
+
+    SentryReporter::addBreadcrumb("scene.anim.pose",
+        QStringLiteral("load library from '%1' (%2 poses)")
+            .arg(filePath).arg(store.order.size()));
+    emit posesChanged(entity);
+    return true;
+}
+
+bool PoseLibrary::savePoseLibraryForSelection(const QString& filePath) const
+{
+    auto* sel = SelectionSet::getSingleton();
+    if (!sel) return false;
+    auto ents = sel->getResolvedEntities();
+    if (ents.isEmpty()) return false;
+    return savePoseLibrary(ents.first(), filePath);
+}
+
+bool PoseLibrary::loadPoseLibraryForSelection(const QString& filePath)
+{
+    auto* sel = SelectionSet::getSingleton();
+    if (!sel) return false;
+    auto ents = sel->getResolvedEntities();
+    if (ents.isEmpty()) return false;
+    return loadPoseLibrary(ents.first(), filePath);
+}
+
 bool PoseLibrary::savePoseForSelection(const QString& name)
 {
     auto* sel = SelectionSet::getSingleton();

src/PoseLibrary.h

@@ -85,6 +85,27 @@ class PoseLibrary : public QObject
     /// All pose names on `entity` in save-order.
     QStringList listPoses(Ogre::Entity* entity) const;
 
+    /// Persist this entity's pose library to a `.poselib` sidecar
+    /// JSON file. Returns false on write error (path unwritable,
+    /// no entity, no poses to save). The file format is
+    /// `qtmesheditor.poselib.v1` — see `loadPoseLibrary` for the
+    /// shape contract. Side-by-side with the source asset is the
+    /// recommended location so the library follows the asset
+    /// through version control.
+    Q_INVOKABLE bool savePoseLibrary(Ogre::Entity* entity, const QString& filePath) const;
+
+    /// Load a `.poselib` sidecar JSON file and replace this
+    /// entity's in-memory library with its contents. Returns false
+    /// on read / parse error (file missing, JSON malformed, schema
+    /// mismatch). Existing poses on the entity are wiped first so
+    /// the result reflects the file 1:1 (no partial-overlay).
+    /// Emits `posesChanged` so the Inspector / dope-sheet refresh.
+    Q_INVOKABLE bool loadPoseLibrary(Ogre::Entity* entity, const QString& filePath);
+
+    /// Selection wrappers — same pattern as save/apply/delete.
+    Q_INVOKABLE bool savePoseLibraryForSelection(const QString& filePath) const;
+    Q_INVOKABLE bool loadPoseLibraryForSelection(const QString& filePath);
+
     /// Mirror a saved pose across the YZ plane (X = symmetry axis,
     /// the convention every common rig follows). Reads `srcName`
     /// from the library on `entity`, flips each bone's TRS by:

src/PoseLibrary_test.cpp

@@ -8,6 +8,8 @@
 #include "TestHelpers.h"
 #include "commands/PoseLibraryCommands.h"
 
+#include <QTemporaryDir>
+
 #include <OgreBone.h>
 #include <OgreEntity.h>
 #include <OgreSkeleton.h>
@@ -212,6 +214,113 @@ TEST_F(PoseLibrarySceneTest, ForgetEntityDropsEverythingForThatEntity) {
     EXPECT_FALSE(lib->forgetEntity(entity));
 }
 
+// ─── Slice D-Project — .poselib sidecar persistence ─────────────────
+
+TEST_F(PoseLibrarySceneTest, SaveAndLoadLibraryRoundTripsViaSidecar) {
+    QTemporaryDir tmp;
+    ASSERT_TRUE(tmp.isValid());
+    const QString path = tmp.path() + "/test.poselib";
+
+    Ogre::Entity* entity = createAnimatedTestEntity("PoseLib_Sidecar");
+    ASSERT_NE(entity, nullptr);
+    auto* skel = entity->getSkeleton();
+    auto* lib = PoseLibrary::instance();
+
+    skel->getBone(0)->setPosition(Ogre::Vector3(3, 0, 0));
+    ASSERT_TRUE(lib->savePose(entity, QStringLiteral("Pose1")));
+    skel->getBone(0)->setPosition(Ogre::Vector3(0, 5, 0));
+    ASSERT_TRUE(lib->savePose(entity, QStringLiteral("Pose2")));
+
+    EXPECT_TRUE(lib->savePoseLibrary(entity, path));
+
+    // Wipe the in-memory library and reload from disk.
+    lib->forgetEntity(entity);
+    EXPECT_TRUE(lib->listPoses(entity).isEmpty());
+
+    EXPECT_TRUE(lib->loadPoseLibrary(entity, path));
+    QStringList names = lib->listPoses(entity);
+    ASSERT_EQ(names.size(), 2);
+    EXPECT_EQ(names[0], QStringLiteral("Pose1"));
+    EXPECT_EQ(names[1], QStringLiteral("Pose2"));
+
+    // Apply the first pose to confirm TRS round-tripped.
+    skel->getBone(0)->setPosition(Ogre::Vector3::ZERO);
+    lib->applyPose(entity, QStringLiteral("Pose1"));
+    EXPECT_FLOAT_EQ(skel->getBone(0)->getPosition().x, 3.0f);
+    EXPECT_FLOAT_EQ(skel->getBone(0)->getPosition().y, 0.0f);
+}
+
+TEST_F(PoseLibrarySceneTest, SaveLibraryRejectsEmptyLibraryOrInvalidPath) {
+    Ogre::Entity* entity = createAnimatedTestEntity("PoseLib_SidecarReject");
+    ASSERT_NE(entity, nullptr);
+    auto* lib = PoseLibrary::instance();
+
+    QTemporaryDir tmp;
+    const QString validPath = tmp.path() + "/empty.poselib";
+
+    // No poses saved yet → false (don't write an empty library file).
+    EXPECT_FALSE(lib->savePoseLibrary(entity, validPath));
+
+    // Empty path → false.
+    ASSERT_TRUE(lib->savePose(entity, QStringLiteral("X")));
+    EXPECT_FALSE(lib->savePoseLibrary(entity, QString()));
+
+    // Null entity → false.
+    EXPECT_FALSE(lib->savePoseLibrary(nullptr, validPath));
+}
+
+TEST_F(PoseLibrarySceneTest, LoadLibraryRejectsMissingFileAndBadSchema) {
+    Ogre::Entity* entity = createAnimatedTestEntity("PoseLib_SidecarLoadReject");
+    ASSERT_NE(entity, nullptr);
+    auto* lib = PoseLibrary::instance();
+
+    QTemporaryDir tmp;
+    // Missing file
+    EXPECT_FALSE(lib->loadPoseLibrary(entity, tmp.path() + "/nope.poselib"));
+
+    // Bad JSON
+    {
+        const QString p = tmp.path() + "/bad.poselib";
+        QFile f(p); ASSERT_TRUE(f.open(QIODevice::WriteOnly));
+        f.write("{ this is not JSON");
+        f.close();
+        EXPECT_FALSE(lib->loadPoseLibrary(entity, p));
+    }
+
+    // Valid JSON, wrong schema string
+    {
+        const QString p = tmp.path() + "/wrongschema.poselib";
+        QFile f(p); ASSERT_TRUE(f.open(QIODevice::WriteOnly));
+        f.write("{\"schema\": \"wrong\", \"poses\": []}");
+        f.close();
+        EXPECT_FALSE(lib->loadPoseLibrary(entity, p));
+    }
+}
+
+TEST_F(PoseLibrarySceneTest, LoadLibraryWipesExistingPosesFirst) {
+    QTemporaryDir tmp;
+    Ogre::Entity* entity = createAnimatedTestEntity("PoseLib_SidecarWipe");
+    ASSERT_NE(entity, nullptr);
+    auto* lib = PoseLibrary::instance();
+
+    // Build a sidecar with one pose "FromFile".
+    ASSERT_TRUE(lib->savePose(entity, QStringLiteral("FromFile")));
+    const QString path = tmp.path() + "/one.poselib";
+    ASSERT_TRUE(lib->savePoseLibrary(entity, path));
+
+    // Add a different in-memory pose that's NOT in the file.
+    lib->forgetEntity(entity);
+    ASSERT_TRUE(lib->savePose(entity, QStringLiteral("InMemoryOnly")));
+    EXPECT_EQ(lib->listPoses(entity).size(), 1);
+
+    // Load wipes "InMemoryOnly" and replaces with file's "FromFile".
+    EXPECT_TRUE(lib->loadPoseLibrary(entity, path));
+    QStringList names = lib->listPoses(entity);
+    ASSERT_EQ(names.size(), 1);
+    EXPECT_EQ(names[0], QStringLiteral("FromFile"));
+    EXPECT_FALSE(lib->hasPose(entity, QStringLiteral("InMemoryOnly")));
+}
+
 // ─── Slice D4 — bone name flip + mirror pose ─────────────────────────
 
 TEST(PoseLibraryStandalone, FlipBoneName_MixamoLowercaseSuffix) {