UESaveTool

A Node.js implementation for deserializing and converting GVAS/.sav files to JSON and vice-versa.

Usage

You must have Node.js Version 16.7.0+ installed.
Download/Clone this entire repo by clicking on the Code button above.

Convert Between .sav and .json

node ./usavetool.js [mode: -sav-to-json, -json-to-sav] [input path] [output path?]

Pipe output to another script

node ./uesavetool.js [mode] [input] | my-script

Adding to your project

First things first:

npm install uesavetool

Also set type as module in package.json. Only ESModules are supported currently.

{
  "type": "module"
}

Using Gvas class for deserialization

import * as fs from 'fs'
import { Gvas, Serializer } from 'uesavetool'

fs.readFile(sav-path, (err, buf) => {
    if(err) throw err;

    const gvas = new Gvas();
    const serial = new Serializer(buf);
    gvas.deserialize(serial);
    
    // manipulate gvas here

    fs.writeFile(json-path, JSON.stringify(gvas), (err) => {
        if(err) throw err;
    })
})

Using Gvas class for serialization

import * as fs from 'fs';
import { Gvas } from 'uesavetool';

fs.readFile(json-path, 'utf8', (err, data) => {
    if(err) throw err;

    const gvas = Gvas.from(JSON.parse(data));

    // manipulate gvas here

    fs.writeFile(sav-path, gvas.serialize(), (err) => {
        if(err) throw err;
    })
})

Implementation Notes

If you want to expand functionality of this tool, you should follow the design patterns implemented within:

• All Properties extend from the Property class which has 4 functions: get Size(),deserialize(), serialize(), and static from()
• Properties are in charge of serializing/deserializing themselves due to the unique formatting for each property
• Use the Serializer class to read/write data on it's internal Buffer
• Never instantiate a Property with new outside of a constructor or it's own from function, instead, you should use the PropertyFactory.create() static function, which passes an object argument to the from() function implemented within the specified property type
• For integration in other projects, you should use the Gvas class, which has 4 functions: get Size(), deserialize(), serialize(), and static from()
• deserialize() accepts a Serializer as an argument, and returns the Gvas instance
• Properties' names must be exactly the same as in the .sav
• Array properties are implementation dependent due to unique serialization
• Size calcualated by get Size() is NOT written to the serialized data buffer. That value is usually, but not always, the total size of the property/properties within the current Property.

Adding a new Property type

AnotherPropery.js

import { 
    Property,
    PropertyFactory,
    Serializer
} from 'uesavetool'

export class AnotherProperty extends Property {
    constructor() {
        super();
        // Attributes specific to this property type
        // Use this.Property for it's value(s)
    }
    get Size() {
        // Calculate number of bytes for serialization. Including this.Name and this.Type
        // Each string attribute will have a 4-byte size followed by that actual string
        let size = this.Name + 4;
        size += this.Type + 4;
        // this.Property may be another `Property` with it's own `Size` getter
        return size;
    }
    deserialize(serial, size) {
        // Serial is a `Serialzer` to make this easier
        // If `size` is passed, use `serial.tell < (start_offset + size)` as a loop condition
        // Do not deserialize this.Name, this.Type or the serialized Size here.
        // This function is called from the parent Property which already deserializes them
        // The Size that is deserialized here is not the same as this.Size
        return this;
    }
    serialize() {
        let serial = Serializer.alloc(this.Size);
        serial.writeString(this.Name);
        serial.writeString(this.Type);
        serial.writeInt32(/* this.Property size in bytes */)
        serial.seek(/* padding length */)
        // serialize this.Property
        return serial.Data;
    }
    static from(obj) {
        let prop = new AnotherProperty();
        prop.Name = obj.Name
        prop.Type = obj.Type
        if(obj.Property) {
            // If this.Property is a value
            prop.Property = obj.Property

            // If this.Property is a `Property`
            prop.Property = PropertyFactory.create(obj.Property);
        }
        return prop;
    }
}

index.js

import { PropertyFactory } from 'uesavetool'
import { AnotherProperty } from './AnotherProperty.js'

PropertyFactory.Properties['AnotherProperty'] = AnotherProperty;

export { AnotherProperty }

Adding a new Array type

Essentially the same as adding a new Property type, but since ArrayProperty.StoredPropertyType will be a normal Property name, adding to PropertyFactory is different. Also Size will ONLY include the size of it's properties.

index.js

import { PropertyFactory } from 'uesavetool'
import { AnotherProperty } from './AnotherProperty.js'
import { AnotherPropertyArray } from './AnotherPropertyArray.js'

PropertyFactory.Properties['AnotherPropertyArray'] = AnotherPropertyArray //Needed if `Type` string ends with "Array" after being stored
PropertyFactory.Arrays['AnotherProperty'] = AnotherPropertyArray //

export { AnotherPropertyArray }

Notes on PropertyFactory.js

PropertyFactory will automatically trim null-terminating characters from strings. The name of the Property type will be in the .sav in utf8

Anotomy of a Property in a GVAS

Sizes are in Little-Endian, so the first byte read is the least significant. Strings are null-terminating. The following example is an StrProperty type.

| | Bytes | Value |:----------------------|:------------------------------------------|:------------------ | Name Size | 0D 00 00 00 | 13 bytes | Name | 53 61 76 65 53 6C 6F 74 4E 61 6D 65 00 | "SaveSlotName\0" | Type Size | 0C 00 00 00 | 12 bytes | Type | 53 74 72 50 72 6F 70 65 72 74 79 00 | "StrProperty\0" | Property Size | 0E 00 00 00 | 14 bytes | Padding | 00 00 00 00 00 | 5 null characters | Property Value Size | 0A 00 00 00 | 10 bytes | Property Value | 47 61 6D 65 53 74 61 74 65 00 | "GameState\0"

Padding is different for most properties. Some properties contain a StoredPropertyType value, such as the StructProperty and ArrayProperty. The Tuple does not exist in a GVAS, instead, Tuple was written to encapsulate lists of properties within the StructProperty and Gvas.Properties. A Tuple is used whenever the string None appears within the file and marks the end of a list of properties.

Disclaimer

THIS SCRIPT WAS BUILT FOR THE BPM: BULLETS PER MINUTE COMMUNITY, BUT THIS MAY PROVE USEFUL FOR OTHER UE-BASED GAMES. IT IS NOT GUARANTEED TO WORK FOR ALL UE GAME SAVES.

Verification Tools

HxD Freeware Hex Editor

https://mh-nexus.de/en/hxd/

Notepad++

https://notepad-plus-plus.org/

Credits

GVAS Converter

https://github.com/13xforever/gvas-converter

UeSaveSerializer

https://gist.github.com/Rob7045713/2f838ad66237f87c86d5396af573b71c