RenPy: Support RPA-2.0 (closes #18)

Author: refaim

CLAUDE.md

@@ -0,0 +1,65 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build Commands
+
+**IMPORTANT: This project ONLY builds on Windows with MSVC toolchain. Do not attempt to build on Linux.**
+
+This project uses CMake with vcpkg for dependency management and requires Visual Studio 2017+ on Windows:
+
+```bash
+# Configure build (requires VCPKG_ROOT environment variable)
+cmake --preset x64-release  # or x86-release
+
+# Build all modules
+cmake --build build/x64-release
+
+# Run tests
+cd build/x64-release && ctest
+
+# Package for distribution
+cd build/x64-release && cpack --config CPackConfig.cmake -C RelWithDebInfo
+```
+
+Build presets available: `x64-release`, `x64-debug`, `x86-release`, `x86-debug`
+
+## Development Guidelines
+
+This project uses **C++23** and follows KISS (Keep It Simple, Stupid) and DRY (Don't Repeat Yourself) principles.
+
+**Avoid magic numbers** - use named constants instead.
+
+## Architecture Overview
+
+This project implements Observer plugin modules for FAR Manager that handle exotic archive formats. The codebase follows a plugin architecture where each module implements the Observer API to support different archive formats.
+
+### Core Components
+
+- **API Layer** (`src/api.h`, `src/dll.cpp`): Implements the Observer plugin API with standard functions like `OpenStorage`, `CloseStorage`, `GetItem`, `ExtractItem`
+- **Archive Wrapper** (`src/archive.h`, `src/archive.cpp`): Provides a unified interface that wraps format-specific extractors
+- **Extractor Interface** (`src/modules/extractor.h`): Defines the abstract interface that all format extractors must implement
+
+### Module Structure
+
+Each supported format has its own module under `src/modules/`:
+- `renpy/`: RenPy visual novel archives (.rpa files) with pickle support
+- `zanzarah/`: Zanzarah game archives (.pak files)  
+- `rpgmaker/`: RPG Maker archives (in development)
+
+Each module contains:
+- Format-specific implementation (e.g., `renpy.cpp`)
+- Module definition file (`.def`) for DLL exports
+- Configuration file (`observer_user.ini`)
+
+### Data Flow
+
+1. FAR Manager loads the module DLL via `LoadSubModule()`
+2. `OpenStorage()` creates an archive wrapper with format-specific extractor
+3. `PrepareFiles()` scans and indexes archive contents
+4. `GetItem()` provides file metadata for FAR's file browser
+5. `ExtractItem()` handles actual file extraction with progress callbacks
+
+### Testing Framework
+
+Located in `src/tests/` with a custom framework (`framework/observer.h`) that simulates the Observer API for testing archive operations without requiring FAR Manager.

src/archive.cpp

@@ -34,7 +34,6 @@ namespace archive
             throw std::runtime_error("Failed to open file");
         }
         stream_->exceptions(std::ifstream::failbit | std::ifstream::badbit);
-        stream_->seekg(std::ssize(signature));
 
         return extractor_->get_archive_info(data);
     }

src/modules/renpy/renpy.cpp

@@ -2,6 +2,7 @@
 #include "pickle.h"
 
 #include <fstream>
+#include <functional>
 
 #include <zstr.hpp>
 
@@ -17,7 +18,7 @@ namespace extractor
 
     std::vector<std::byte> extractor::get_signature() noexcept
     {
-        const std::string str = "RPA-3.0 ";
+        const std::string str = "RPA-";
         std::vector<std::byte> signature(str.size());
         std::memcpy(signature.data(), str.data(), str.size());
         return signature;
@@ -43,11 +44,43 @@ namespace extractor
         return result;
     }
 
+    std::pair<int64_t, std::function<std::pair<int64_t, int64_t>(int64_t, int64_t)> > parse_header(
+        std::ifstream &stream)
+    {
+        std::string version_check(3, '\0');
+        stream.seekg(static_cast<std::streamoff>(extractor::get_signature().size()));
+        stream.read(version_check.data(), 3);
+
+        if (version_check == "2.0") {
+            stream.seekg(static_cast<std::streamoff>(std::string("RPA-2.0 ").length()));
+            const auto index_offset = read_int64(stream);
+            return {
+                index_offset, [](int64_t offset, int64_t length)
+                {
+                    return std::make_pair(offset, length);
+                }
+            };
+        }
+
+        if (version_check == "3.0") {
+            stream.seekg(static_cast<std::streamoff>(std::string("RPA-3.0 ").length()));
+            const auto index_offset = read_int64(stream);
+            const auto encryption_key = read_int64(stream);
+            return {
+                index_offset, [encryption_key](int64_t offset, int64_t length)
+                {
+                    return std::make_pair(offset ^ encryption_key, length ^ encryption_key);
+                }
+            };
+        }
+
+        throw std::runtime_error("Unsupported RPA version");
+    }
+
     // ReSharper disable once CppMemberFunctionMayBeStatic
     std::vector<std::unique_ptr<file> > extractor::list_files(std::ifstream &stream) // NOLINT(*-convert-member-functions-to-static)
     {
-        const auto index_offset = read_int64(stream);
-        const auto encryption_key = read_int64(stream);
+        const auto [index_offset, decoder] = parse_header(stream);
 
         stream.seekg(index_offset);
 
@@ -75,8 +108,8 @@ namespace extractor
                 throw std::logic_error("Expected at least 2 elements in tuple");
             }
 
-            const auto offset = props[0]->as_int64() ^ encryption_key;
-            const auto body_size = props[1]->as_int64() ^ encryption_key;
+            const auto [offset, body_size] = decoder(props[0]->as_int64(), props[1]->as_int64());
+
             auto header = std::string();
             if (props.size() >= 3) {
                 if (props[2]->get_type() != pickle::value::type::none) {

src/modules/rpgmaker/rpgmaker.cpp

@@ -43,6 +43,8 @@ namespace extractor
     // ReSharper disable once CppMemberFunctionMayBeStatic
     std::vector<std::unique_ptr<file> > extractor::list_files(std::ifstream &stream) // NOLINT(*-convert-member-functions-to-static)
     {
+        stream.seekg(static_cast<std::streamoff>(get_signature().size()));
+
         std::vector<std::unique_ptr<file> > files;
         const uint32_t magic = read_u32(stream) * 9 + 3;
         while (true) {

src/modules/zanzarah/zanzarah.cpp

@@ -53,6 +53,8 @@ namespace extractor
     // ReSharper disable once CppMemberFunctionMayBeStatic
     std::vector<std::unique_ptr<file> > extractor::list_files(std::ifstream &stream) // NOLINT(*-convert-member-functions-to-static)
     {
+        stream.seekg(static_cast<std::streamoff>(get_signature().size()));
+
         auto files = std::vector<std::unique_ptr<file> >();
         files.reserve(read_positive_int32(stream));
 

src/tests/framework/tools/.gitignore

@@ -0,0 +1 @@
+/.venv

src/tests/framework/tools/.python-version

@@ -0,0 +1 @@
+3.13

src/tests/framework/make_listing.py src/tests/framework/tools/make_listing.pysrc/tests/framework/make_listing.py renamed to src/tests/framework/tools/make_listing.py

@@ -0,0 +1,9 @@
+[project]
+name = "observer"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "xxhash>=3.5.0",
+]