{"id":17685473,"url":"https://github.com/nextgeniuspro/vfspp","last_synced_at":"2025-05-16T15:03:13.396Z","repository":{"id":45032170,"uuid":"62876792","full_name":"nextgeniuspro/vfspp","owner":"nextgeniuspro","description":"Virtual File System C++","archived":false,"fork":false,"pushed_at":"2025-04-22T11:38:09.000Z","size":340,"stargazers_count":311,"open_issues_count":2,"forks_count":47,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-05-16T15:02:19.717Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nextgeniuspro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-07-08T09:24:33.000Z","updated_at":"2025-05-15T07:08:03.000Z","dependencies_parsed_at":"2024-07-29T19:36:38.015Z","dependency_job_id":"3397b2d8-69fc-4140-9181-52efe96d38ca","html_url":"https://github.com/nextgeniuspro/vfspp","commit_stats":{"total_commits":35,"total_committers":2,"mean_commits":17.5,"dds":0.02857142857142858,"last_synced_commit":"74a82f62d8b65bc2a1c09d8165499d698fcd898a"},"previous_names":["nextgeniuspro/vfspp"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nextgeniuspro%2Fvfspp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nextgeniuspro%2Fvfspp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nextgeniuspro%2Fvfspp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nextgeniuspro%2Fvfspp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nextgeniuspro","download_url":"https://codeload.github.com/nextgeniuspro/vfspp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254553936,"owners_count":22090415,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-24T10:27:53.411Z","updated_at":"2025-05-16T15:03:13.338Z","avatar_url":"https://github.com/nextgeniuspro.png","language":"C++","readme":"# vfspp\n\nvfspp is a C++ Virtual File System header-only library that allows manipulation of files from memory, zip archives, or native filesystems as if they were part of a single native filesystem. This is particularly useful for game developers who want to use resources in the native filesystem during development and then pack them into an archive for distribution builds. The library is thread-safe, ensuring safe operations in multi-threaded environments. Note: This library requires C++17 or later.\n\n## Usage Example\n\n```C++\n// Register native filesystem during development or zip for distribution build\n\nIFileSystemPtr rootFS = nullptr;\n#if defined(DISTRIBUTION_BUILD)\n\trootFS = std::make_unique\u003cZipFileSystem\u003e(\"Resources.zip\");\n#else\n\trootFS = std::make_unique\u003cNativeFileSystem\u003e(GetBundlePath() + \"Resources\");\n#endif\n\nrootFS-\u003eInitialize();\n\nVirtualFileSystemPtr vfs(new VirtualFileSystem());\nvfs-\u003eAddFileSystem(\"/\", std::move(rootFS));\n```\n\nIt's often useful to have several mounted filesystems. For example:\n- \"/\" as your root native filesystem\n- \"/tmp\" as a memory filesystem for working with temporary files without disk operations\n- \"/resources\" as a zip filesystem with game resources\n\nHere's an example of how to set up multiple filesystems:\n\n```C++\n// add 'VFSPP_ENABLE_MULTITHREADING' preprocessor definition to enable thread-safe operations\n#define VFSPP_ENABLE_MULTITHREADING \n\nauto rootFS = std::make_unique\u003cNativeFileSystem\u003e(GetBundlePath() + \"Documents/\");\nauto zipFS = std::make_unique\u003cZipFileSystem\u003e(\"Resources.zip\");\nauto memFS = std::make_unique\u003cMemoryFileSystem\u003e();\n\nrootFS-\u003eInitialize();\nzipFS-\u003eInitialize();\nmemFS-\u003eInitialize();\n\nVirtualFileSystemPtr vfs(new VirtualFileSystem());\nvfs-\u003eAddFileSystem(\"/\", std::move(rootFS));\nvfs-\u003eAddFileSystem(\"/resources\", std::move(zipFS));\nvfs-\u003eAddFileSystem(\"/tmp\", std::move(memFS));\n\n// Example: Open a save file\nif (auto saveFile = vfs-\u003eOpenFile(FileInfo(\"/savefile.sav\"), IFile::FileMode::Read))\n{\n\tif (saveFile-\u003eIsOpened()) {\n\t\t// Parse game save\n\t\t// ...\n\t}\n}\n\n// Example: Work with a temporary file in memory\nif (auto userAvatarFile = vfs-\u003eOpenFile(FileInfo(\"/tmp/avatar.jpg\"), IFile::FileMode::ReadWrite))\n{\n\tif (userAvatarFile-\u003eIsOpened()) {\n\t\t// Load avatar from network and store it in memory\n\t\t// ...\n\t\tuserAvatarFile-\u003eWrite(data.data(), data.size());\n\t\tuserAvatarFile-\u003eClose();\n\t}\n}\n\n// Example: Load a resource from the zip file\nif (auto textureFile = vfs-\u003eOpenFile(FileInfo(\"/resources/background.pvr\"), IFile::FileMode::Read))\n{\n\tif (textureFile-\u003eIsOpened()) {\n\t\t// Create texture\n\t\t// ...\n\t}\n}\n```\n\n### Patching/DLC feature\n\nvfspp supports patching/DLC feature. You can mount multiple filesystems to the same alias and access files merged from all filesystems. For example, you can mount the base game filesystem and the patch filesystem. If the file is present in the patch filesystem, it will be used; otherwise, the file from the base game filesystem will be used. Search order performed from the last mounted filesystem to the first filesystem. The first filesystem mounted to the alias will be the default filesystem, so creating a new file will be created in the first 'base' filesystem.\n\n```C++\nIFileSystemPtr dlc1FS(new NativeFileSystem(\"../test-data/dlc1\"));\nIFileSystemPtr dlc2FS(new NativeFileSystem(\"../test-data/dlc2\"));\n\ndlc1FS-\u003eInitialize();\ndlc2FS-\u003eInitialize();\n\nvfs-\u003eAddFileSystem(\"/dlc\", dlc1FS);\n\t\nIFilePtr dlcFile = vfs-\u003eOpenFile(FileInfo(\"/dlc/file.txt\"), IFile::FileMode::Read);\nif (dlcFile \u0026\u0026 dlcFile-\u003eIsOpened()) {\n\tPrintFile(\"File /dlc/file.txt that exists in dlc1:\", dlcFile);\n\tdlcFile-\u003eClose();\n}\n\nvfs-\u003eAddFileSystem(\"/dlc\", dlc2FS);\n\ndlcFile = vfs-\u003eOpenFile(FileInfo(\"/dlc/file.txt\"), IFile::FileMode::Read);\nif (dlcFile \u0026\u0026 dlcFile-\u003eIsOpened()) {\n\tPrintFile(\"File /dlc/file.txt patched by dlc2:\", dlcFile);\n\tdlcFile-\u003eClose();\n}\n\nIFilePtr dlcFile1 = vfs-\u003eOpenFile(FileInfo(\"/dlc/file1.txt\"), IFile::FileMode::Read);\nif (dlcFile1 \u0026\u0026 dlcFile1-\u003eIsOpened()) {\n\tPrintFile(\"File /dlc/file1.txt that exists only in dlc1:\", dlcFile1);\n\tdlcFile1-\u003eClose();\n}\n\nIFilePtr dlcFile2 = vfs-\u003eOpenFile(FileInfo(\"/dlc/file2.txt\"), IFile::FileMode::Read);\nif (dlcFile2 \u0026\u0026 dlcFile2-\u003eIsOpened()) {\n\tPrintFile(\"File /dlc/file2.txt that exists only in dlc2:\", dlcFile2);\n\tdlcFile2-\u003eClose();\n}\n```\n\n## How To Integrate with cmake\n\n- Add vfspp as submodule to your project\n```bash\ngit submodule add https://github.com/nextgeniuspro/vfspp.git vendor/vfspp\n```\n- Update submodules to download dependencies\n```bash\ngit submodule update --init --recursive\n```\n- Add vfspp as subdirectory to your CMakeLists.txt\n```cmake \nadd_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/vendor/vfspp vfspp_build)\n```\n- Add vfspp as dependency to your target and set C++17 standard\n```cmake \ntarget_link_libraries(\u003cyour_project\u003e PRIVATE vfspp)\ntarget_compile_features(\u003cyour_project\u003e PRIVATE cxx_std_17)\n```\n- To add multi-threading support, add 'VFSPP_ENABLE_MULTITHREADING' preprocessor definition to your target\n```cmake\nadd_compile_definitions(VFSPP_ENABLE_MULTITHREADING)\n```\n\nSee examples/CMakeLists.txt for example of usage\n\n## How To Build Example #\n\n- Run cmake to generate project windows project files\n```bash\ncmake -B ./build -G \"Visual Studio 17 2022\" . -DBUILD_EXAMPLES=1\n``` \nor to generate Xcode project files\n```bash\ncmake -B ./build -G \"Xcode\" . -DBUILD_EXAMPLES=1\n```\n\n- Open generated project files and build the target `vfsppexample`","funding_links":[],"categories":["C++"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnextgeniuspro%2Fvfspp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnextgeniuspro%2Fvfspp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnextgeniuspro%2Fvfspp/lists"}