|
1 | | -> **All projects made with passion** 💙 |
2 | | -
|
3 | | -Your support helps us continue developing and maintaining these projects. Consider sponsoring! |
4 | | - |
5 | | -<iframe src="https://github.com/sponsors/abduznik/card" title="Sponsor abduznik" height="225" width="600" style="border: 0;"></iframe> |
6 | | - |
7 | | -# OmniSave |
8 | | - |
9 | | -OmniSave v0.2.0 is a lightweight, portable game save synchronization tool for Windows, specifically designed to run reliably under **Wine**, **CrossOver**, and **GameHub** (Winlator/Box64) environments. |
10 | | - |
11 | | -It acts as a "Launch Wrapper" that automates the process of fetching your saves from a portable location (like a USB drive or a cloud-synced folder), launching the game, and then backing up your progress immediately after you finish playing. |
12 | | - |
13 | | -## How It Works |
14 | | - |
15 | | -OmniSave "fakes" a local installation by redirecting your save files. It ensures that the game always finds your saves in the expected system directory (like `Documents` or `AppData`), even when your actual data lives on a portable drive. |
16 | | - |
17 | | -### 1. Storage Architecture |
18 | | -The wrapper bridges the gap between your portable storage and the system's local save directory. |
19 | | - |
20 | | -```mermaid |
21 | | -flowchart LR |
22 | | - Portable[(Portable Drive / Cloud)] |
23 | | - Local[(Local System Path)] |
24 | | - Game{Game Process} |
25 | | -
|
26 | | - Portable <==>|"1. Sync Saves"| Local |
27 | | - Local <-->|"2. Native I/O"| Game |
28 | | - |
29 | | - classDef storage fill:#2d3436,color:#dfe6e9,stroke:#636e72 |
30 | | - class Local,Portable storage |
31 | | -``` |
32 | | - |
33 | | -### 2. Execution Lifecycle |
34 | | -OmniSave manages the entire gaming session from start to finish. |
35 | | - |
36 | | -```mermaid |
37 | | -flowchart TD |
38 | | - Start([Launch OmniSave]) --> Pull[Pre-Sync: Remote to Local] |
39 | | - Pull --> Exec[Execute Game & Args] |
40 | | - Exec --> Poll{Poll Process List} |
41 | | - Poll -- "Running" --> Poll |
42 | | - Poll -- "Exited" --> Push[Post-Sync: Local to Remote] |
43 | | - Push --> End([Cleanup & Exit]) |
44 | | -
|
45 | | - classDef action fill:#00b894,color:#fff,stroke:#55efc4 |
46 | | - class Pull,Push action |
47 | | -``` |
48 | | - |
49 | | -## Inspiration & Goals |
50 | | - |
51 | | -Inspired by the **PortableApps** philosophy, OmniSave fixes the issue of modern games having "hard-coded" save paths. By using a Sync-Launch-Sync cycle, it allows you to carry your entire gaming session on a single folder/drive across different machines without manual file management. |
52 | | - |
53 | | -## Verified Compatibility |
54 | | - |
55 | | -OmniSave has been tested and verified across various hardware and software environments: |
56 | | -- **Windows 10 Gaming PC**: Native performance and file system handling. |
57 | | -- **MacBook Neo (macOS)**: Running via **CrossOver** and **Wine** translation layers. |
58 | | -- **Samsung S25 Ultra**: Running through **GameHub** (Winlator/Box64) mobile environments. |
59 | | - |
60 | | -## Key Features |
61 | | - |
62 | | -- **Sync-Launch-Sync Architecture**: Ensures your local environment is up-to-date before playing and your remote backup is updated after. |
63 | | -- **Process Polling**: Unlike standard wrappers that wait for a process handle, OmniSave polls the system memory. This allows it to stay alive even if the game launcher (like Rockstar Launcher) detaches or spawns background child processes. |
64 | | -- **Launch Arguments Support**: Pass arbitrary boot flags (like `-nobattleye` or `-windowed`) directly to the game. |
65 | | -- **Path Resolution**: Supports `~/` expansion for user profile directories and `./` for relative portable paths. |
66 | | -- **Mutex Locking**: Prevents multiple instances from running simultaneously to avoid save corruption. |
67 | | - |
68 | | -## Configuration (`omnisave.ini`) |
69 | | - |
70 | | -Place `omnisave.ini` in the same directory as `OmniSave.exe`. |
71 | | - |
72 | | -```ini |
73 | | -[OmniSave] |
74 | | -; The executable name to launch and monitor |
75 | | -Launch_Command=GTA5.exe |
76 | | - |
77 | | -; Optional command line arguments |
78 | | -Launch_Args=-nobattleye |
79 | | - |
80 | | -; The local path where the game expects saves (supports ~/) |
81 | | -Local_Path=~/Documents/Rockstar Games/GTA V |
82 | | - |
83 | | -; The remote path for backups (supports ./) |
84 | | -Remote_Path=./portable_saves/GTA_V |
85 | | -``` |
86 | | - |
87 | | -## Roadmap |
88 | | - |
89 | | -- **Safety Enhancements**: Implementing atomic file writes and integrity checks during sync to prevent data loss on sudden power-off. |
90 | | -- Linux/Steam Deck Support: Native Linux builds with automated Proton Prefix detection. Since each game on Linux/Proton lives in its own isolated folder (compatdata), OmniSave will automate the path discovery for these environments. |
91 | | - |
92 | | -## Testing |
93 | | - |
94 | | -OmniSave uses the [Unity](https://github.com/ThrowTheSwitch/Unity) test framework and a platform abstraction layer to allow unit testing on non-Windows systems. |
95 | | - |
96 | | -### Running Tests Locally |
97 | | - |
98 | | -To run the unit tests on macOS or Linux: |
99 | | - |
100 | | -```bash |
101 | | -make test |
102 | | -``` |
103 | | - |
104 | | -This will: |
105 | | -1. Clone the Unity framework into `vendor/`. |
106 | | -2. Compile the core logic with a mock platform layer. |
107 | | -3. Run the test suite and report results. |
108 | | - |
109 | | -### CI/CD |
110 | | - |
111 | | -All pushes and pull requests are automatically tested via GitHub Actions on Ubuntu, verifying both the unit tests and the MinGW cross-compilation for Windows. |
112 | | - |
113 | | -## Build Instructions |
114 | | - |
115 | | -Built using MinGW-w64 for cross-platform compatibility. |
116 | | - |
117 | | -```bash |
118 | | -make clean && make |
119 | | -``` |
120 | | - |
121 | | -## Changelog |
122 | | - |
123 | | -### v0.2.0 |
124 | | -- **Safety Fix**: Replaced `strncpy` with `snprintf` in path expansion to ensure proper null-termination. |
125 | | -- **Robustness Fix**: Increased internal command-line buffer to 4096 characters to prevent truncation during launch. |
126 | | -- **New Feature**: Atomic file writes via temporary `.omnitmp` files. |
127 | | -- **New Feature**: Deletion propagation support (Local -> Remote) during post-sync. |
128 | | -- **Testing**: Added buffer safety and null-termination unit tests. |
129 | | - |
130 | | -### v0.1.0 |
131 | | -- Initial release with Sync-Launch-Sync architecture. |
132 | | -- Process polling support for launcher compatibility. |
133 | | -- Unit testing framework integration. |
134 | | - |
135 | | -## License |
136 | | -MIT |
0 commit comments