Initial import

Author: lcacheux

.gitignore

@@ -0,0 +1,39 @@
+.gradle
+build/
+!gradle/wrapper/gradle-wrapper.jar
+!**/src/main/**/build/
+!**/src/test/**/build/
+
+### IntelliJ IDEA ###
+.idea/
+*.iws
+*.iml
+*.ipr
+out/
+!**/src/main/**/out/
+!**/src/test/**/out/
+
+### Eclipse ###
+.apt_generated
+.classpath
+.factorypath
+.project
+.settings
+.springBeans
+.sts4-cache
+bin/
+!**/src/main/**/bin/
+!**/src/test/**/bin/
+
+### NetBeans ###
+/nbproject/private/
+/nbbuild/
+/dist/
+/nbdist/
+/.nb-gradle/
+
+### VS Code ###
+.vscode/
+
+### Mac OS ###
+.DS_Store

README.md

@@ -0,0 +1,63 @@
+# GamePass Save Converter
+
+Tool to convert saves from Xbox GamePass games (or other Microsoft Store games) into a more standard and readable format
+(ie. compatible with other sources like Steam, Epic Game Store or GoG).
+
+Most of the time, saves from MS packages are just the same as for other stores with a specific renaming and index files.
+The original file names can be retrieved by parsing the containers.index and container.* files. As for now, GPSC only
+parse these files and rename the saves.
+
+This project has been partly inspired by [GP Save Converter](https://github.com/Fr33dan/GPSaveConverter), written in C#
+with a more user friendly interface for Windows, but which was unable to convert saves for games not listed in the
+application.
+
+## Build
+
+With a proper Java installation available, run:
+```
+./gradlew assemble
+```
+
+The application will be available into ```cli/build/distributions```.
+
+## Usage
+
+GPSC require Java 12 or higher (JDK or JRE).
+
+The command line tool have two commands :
+* _list_ will display details about all the files found in the save directory
+* _convert_ will copy and rename all the files with their more readable name
+
+Options:
+* _--path (or -p)_: Path to containers.index, or a directory with this file (default is current directory)
+* _--destination (or -d)_: Directory to write converted save, only for _convert_ command (default is ./output/)
+
+Example:
+```
+gpsc convert -p ./SomethingWeMade.TOEM_3b9evzcrg4em8/SystemAppData/wgs/000900000223B718_0000000000000000000000007E270A5A -d ./toem_save/
+```
+
+## FAQ
+
+### Where can I find the save for my Microsoft Store game ?
+Saves for Microsoft Store games are located under ```%USERPROFILE%\AppData\Local\Packages```. This directory contains a
+sub directory for each game, usually with a name composed of the editor, the game name and an identifying sequence
+(ie. ```SomethingWeMade.TOEM_3b9evzcrg4em8``` for TOEM). The save itself is located in a subdirectory under
+```SystemAppData\wgs```, in a directory with a long UID composed of numbers and letters.
+
+### Where can I find the save for my Steam/GoG/Epic version of the game ?
+It depends of the game since each one have its own way of storing save files. Have a look at the page of the game on
+[PC Gaming Wiki](https://www.pcgamingwiki.com/wiki/Home), or the "cloud saves" infos on [SteamDB](https://steamdb.info).
+
+### The converted save didn't worked with my Steam version of the game
+Many games keep a similar file format between Microsoft Store and other stores, but some have different naming and even
+sometimes different binary format, so using the save converted by GPSC might not work.
+
+### Will the use of the converted save unlock my Steam achievements ?
+It depends on how the game handle achievements. For some games, using a save with unlocked achievements and start the
+game will unlock all of them in a few seconds, for others, they unlock only at the moment you meet the expected
+requirements.
+
+### Why isn't there a GUI for GPSC ?
+I plan to work on a multiplatform GUI (using Compose Desktop) in the near future. For another application with a GUI,
+have a look at [GP Save Converter](https://github.com/Fr33dan/GPSaveConverter)

build.gradle.kts

@@ -0,0 +1,18 @@
+import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
+
+plugins {
+    kotlin("jvm") version "1.8.21"
+}
+
+repositories {
+    mavenCentral()
+}
+
+
+tasks.test {
+    useJUnitPlatform()
+}
+
+tasks.withType<KotlinCompile> {
+    kotlinOptions.jvmTarget = "1.8"
+}

cli/.gitignore

@@ -0,0 +1,42 @@
+.gradle
+build/
+!gradle/wrapper/gradle-wrapper.jar
+!**/src/main/**/build/
+!**/src/test/**/build/
+
+### IntelliJ IDEA ###
+.idea/modules.xml
+.idea/jarRepositories.xml
+.idea/compiler.xml
+.idea/libraries/
+*.iws
+*.iml
+*.ipr
+out/
+!**/src/main/**/out/
+!**/src/test/**/out/
+
+### Eclipse ###
+.apt_generated
+.classpath
+.factorypath
+.project
+.settings
+.springBeans
+.sts4-cache
+bin/
+!**/src/main/**/bin/
+!**/src/test/**/bin/
+
+### NetBeans ###
+/nbproject/private/
+/nbbuild/
+/dist/
+/nbdist/
+/.nb-gradle/
+
+### VS Code ###
+.vscode/
+
+### Mac OS ###
+.DS_Store

cli/build.gradle.kts

@@ -0,0 +1,29 @@
+plugins {
+    kotlin("jvm")
+    application
+}
+
+group = "net.cacheux.gpsc"
+version = "0.1"
+
+repositories {
+    mavenCentral()
+}
+
+application {
+    mainClass.set("MainKt")
+    applicationName = "gpsc"
+}
+
+dependencies {
+    implementation(kotlin("stdlib-jdk8"))
+    implementation(project(":lib"))
+    implementation("org.jetbrains.kotlinx:kotlinx-cli:0.3.5")
+
+    testImplementation(platform("org.junit:junit-bom:5.9.1"))
+    testImplementation("org.junit.jupiter:junit-jupiter")
+}
+
+tasks.test {
+    useJUnitPlatform()
+}

cli/src/main/kotlin/CliException.kt

@@ -0,0 +1 @@
+class CliException(message: String) : Exception(message)

cli/src/main/kotlin/common.kt

@@ -0,0 +1,33 @@
+import net.cacheux.gpsc.*
+import java.io.File
+import java.nio.BufferUnderflowException
+
+@Throws(CliException::class)
+fun getContainersIndexFile(path: String): File {
+    return with(File(path)) {
+        if (isDirectory) {
+            child(CONTAINERS_INDEX_FILENAME)
+                ?: throw CliException("$CONTAINERS_INDEX_FILENAME not found in path $path")
+        } else this
+    }
+}
+
+@Throws(CliException::class)
+fun File.entryList(entry: ContainersIndex.Entry, action: (Container.Entry, File) -> Unit) {
+    parentFile.child(entry.uuid)?.let { subdir ->
+        subdir.child(CONTAINER_PREFIX + entry.containerIndex)?.let { subcontainer ->
+            try {
+                val container = parseContainer(subcontainer)
+                container.entries.forEach {
+                    action(it, subdir)
+                }
+            } catch (e: BufferUnderflowException) {
+                throw CliException("Error parsing file ${subcontainer.name}")
+            }
+        }
+    } ?: throw CliException("File not found for UUID ${entry.uuid}")
+}
+
+fun File.child(name: String): File? {
+    return listFiles()?.firstOrNull { file -> file.name == name }
+}

cli/src/main/kotlin/convert.kt

@@ -0,0 +1,32 @@
+import net.cacheux.gpsc.parseContainersIndex
+import java.io.File
+import java.io.IOException
+import java.nio.BufferUnderflowException
+
+@Throws(CliException::class)
+fun convert(source: String, destination: String) {
+    val index = getContainersIndexFile(source)
+
+    File(destination).let { destDir ->
+        try {
+            parseContainersIndex(index).let { containers ->
+                if (!destDir.exists()) {
+                    destDir.mkdirs()
+                } else if (destDir.isFile) {
+                    throw CliException("Destination must be a directory")
+                }
+
+                containers.entries.forEach { entry ->
+                    val destPath = "${destDir.absolutePath}/${entry.entryName1}"
+                    index.entryList(entry) { it, dir ->
+                        dir.child(it.uuid)?.copyTo(File("${destPath}/${it.filename}"))
+                    }
+                }
+            }
+        } catch (e: BufferUnderflowException) {
+            throw CliException("Error parsing file ${index.name}")
+        } catch (e: IOException) {
+            throw CliException("Error writing file: ${e.message}")
+        }
+    }
+}

cli/src/main/kotlin/list.kt

@@ -0,0 +1,22 @@
+import net.cacheux.gpsc.parseContainersIndex
+import java.nio.BufferUnderflowException
+
+@Throws(CliException::class)
+fun list(path: String) {
+    val index = getContainersIndexFile(path)
+
+    try {
+        parseContainersIndex(index).let { containers ->
+            println("Game name: ${containers.gameName}")
+            println("Game ID:   ${containers.gameId}")
+            containers.entries.forEach { entry ->
+                println("Entry ${entry.uuid} : ${entry.entryName1} / ${entry.entryName2}")
+                index.entryList(entry) { it, _ ->
+                    println("- ${it.uuid} : ${it.filename}")
+                }
+            }
+        }
+    } catch (e: BufferUnderflowException) {
+        throw CliException("Error parsing ${index.name}")
+    }
+}

cli/src/main/kotlin/main.kt

@@ -0,0 +1,34 @@
+import kotlinx.cli.ArgParser
+import kotlinx.cli.ArgType
+import kotlinx.cli.default
+import kotlin.system.exitProcess
+
+enum class Commands {
+    LIST,
+    CONVERT
+}
+
+fun main(args: Array<String>) {
+    exitProcess(executeMain(args))
+}
+
+fun executeMain(args: Array<String>): Int {
+    val parser = ArgParser("gpsc")
+    val command by parser.argument(ArgType.Choice<Commands>(), description = "Command")
+    val path by parser.option(ArgType.String, shortName = "p", description = "Path").default(".")
+    val destination by parser.option(ArgType.String, shortName = "d", description = "Destination").default("./output/")
+
+    parser.parse(args)
+
+    try {
+        when (command) {
+            Commands.LIST -> list(path)
+            Commands.CONVERT -> convert(path, destination)
+        }
+    } catch (e: CliException) {
+        System.err.println("Error: ${e.message}")
+        return 1
+    }
+
+    return 0
+}