@etothepii/satisfactory-file-parser 0.4.13 → 0.4.15

package/LICENCE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 etotheepii
+Copyright (c) 2024 etothepii
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -8,8 +8,8 @@ This parser can read, modify and write:
 - Save Files `.sav`
 - Blueprint Files `.sbp`, `.sbpcfg`
 
-## Supported Versions
-The version support of the packages is indicated below.
+# Supported Versions
+The version support of the packages is indicated below. Some bugs might still be present, see Bug Reporting further down.
 
 Game Version Files of U5 and below are NOT supported.
 
@@ -18,31 +18,39 @@ Game Version Files of U5 and below are NOT supported.
 | <= U5          |  ❌                          |
 | U6 + U7        |  ✅ 0.0.1 - 0.0.34           |
 | U8             |  ✅ 0.1.20 - 0.3.7           |
-| U1.0           |  ✅ >= 0.4.13                |
+| U1.0           |  ✅ >= 0.4.14                |
 
-
-## Installation via npm
+# Installation via npm
 `npm install @etothepii/satisfactory-file-parser`
 
-## Usage of Save Parsing
+# Usage of Save Parsing
 
-I recommend parsing via stream, to save RAM. The binary data of the whole save will still be in memory, but the converted JSON won't.
-The returned `stream` is a readable WHATWG stream of type string.
+I recommend parsing via stream, to save RAM. The binary data of the whole save will still be in memory, but the converted JSON can be streamed. (You can of course keep reading the stream in memory).
+The returned `stream` is a readable WHATWG stream of type string and represents a `SatisfactorySave` object. this object can be serialized again.
 WHATWG is used by default by browsers. Node js can use them using `Writable.toWeb()` and `Writable.fromWeb()` for example.
 
 ```js
-const jsonFileStream = fs.createWriteStream(outJsonPath, { highWaterMark: 1024 * 1024 * 200 });  // your outgoing JSON stream. In this case directly to file.
-const whatwgWriteStream = Writable.toWeb(outJsonStream) as WritableStream<string>;               // convert the file stream to WHATWG-compliant stream
-
-const { stream, startStreaming } = ReadableStreamParser.CreateReadableStreamFromSaveToJson(savename, file, decompressedBody => {
+import * as fs from 'fs';
+import * as path from 'path';
+import { Writable } from 'stream';
+import { WritableStream } from 'stream/web';
+import { ReadableStreamParser } from '@etothepii/satisfactory-file-parser';
+
+const filepath = path.join(__dirname, 'MySave.sav');
+const file = fs.readFileSync(filepath);
+const outJsonPath = path.join(__dirname, 'MySave.json');
+const jsonFileStream = fs.createWriteStream(outJsonPath, { highWaterMark: 1024 * 1024 * 200 });     // your outgoing JSON stream. In this case directly to file.
+const whatwgWriteStream = Writable.toWeb(jsonFileStream) as WritableStream<string>;                  // convert the file stream to WHATWG-compliant stream
+
+const { stream, startStreaming } = ReadableStreamParser.CreateReadableStreamFromSaveToJson('MySave', file, decompressedBody => {
     console.log('on binary body data.');
 }, (progress: number, msg: string | undefined) => {
     // a callback for reporting progress as number [0,1]. Sometimes has a message.
-    console.log(`${new Date().toString()}: progress`, progress, msg);
+    console.log(`progress`, progress, msg);
 });
 
 stream.pipeTo(whatwgWriteStream);
-whatwgWriteStream.on('close', () => {
+jsonFileStream.on('close', () => {
     // write stream finished
 });
 
@@ -55,44 +63,49 @@ For example, when writing the header or when writing a chunk of the save body.
 The splitting in individual chunks enables you to more easily stream the binary data to somewhere else.
 ```js
 import * as fs from 'fs';
+import * as path from 'path';
 import { Parser } from "@etothepii/satisfactory-file-parser";
 
-let header: Uint8Array, bodyChunks: Uint8Array[] = [];
-Parser.WriteSave(save, binaryBeforeCompressed => {
+// save is your SatisfactorySave object to serialize. In this example i read it back in from a json file.
+const save = JSON.parse(fs.readFileSync(path.join(__dirname, 'MySave.json'), {encoding: 'utf-8'}));
+
+let fileHeader: Uint8Array;
+const bodyChunks: Uint8Array[] = [];
+Parser.WriteSave(save, binaryBeforeCompressed => { 
     console.log('on binary data before being compressed.');
 }, header => {
     console.log('on save header.');
-    header = header;
+    fileHeader = header;
 }, chunk => {
     console.log('on save body chunk.');
     bodyChunks.push(chunk);
 });
 
 // write complete sav file back to disk
-fs.writeFileSync('./MyModifiedSave.sav', Buffer.concat([header!, ...bodyChunks]));
+fs.writeFileSync('./MyModifiedSave.sav', Buffer.concat([fileHeader!, ...bodyChunks]));
 ```
 
 
-### Old Usage of Save Parsing. Deprecated.
+## Old Save Parsing. Deprecated.
 For reading a save file (`.sav`) and parse In-Memory, just pass a Buffer to the parser with the file content.
 ```js
 import * as fs from 'fs';
 import { Parser } from "@etothepii/satisfactory-file-parser";
 
 const file = fs.readFileSync('./MySave.sav') as Buffer;
-const parsedSave = Parser.ParseSaveFile(file);
+const parsedSave = Parser.ParseSaveFile('MySave', file);
 ```
 
 
-## Usage of Blueprint Parsing
-Blueprint parsing works very similiar. Note, that blueprints consist of 2 files. The `.sbp` main file and the config file `.sbpcfg`.
+# Usage of Blueprint Parsing
+Note, that blueprints consist of 2 files. The `.sbp` main file and the config file `.sbpcfg`.
 
 ```js
 import * as fs from 'fs';
 import { Parser } from "@etothepii/satisfactory-file-parser";
 
-const mainFile = fs.readFileSync('./MyBlueprint.sbp') as Buffer;
-const configFile = fs.readFileSync('./MyBlueprint.sbpcfg') as Buffer;
+const mainFile = fs.readFileSync('./MyBlueprint.sbp');
+const configFile = fs.readFileSync('./MyBlueprint.sbpcfg');
 const parsedBlueprint = Parser.ParseBlueprintFiles('MyBlueprint', mainFile, configFile);
 ```
 
@@ -101,7 +114,8 @@ Consequently, writing a blueprint into binary data works the same way with getti
 import * as fs from 'fs';
 import { Parser } from "@etothepii/satisfactory-file-parser";
 
-let mainFileHeader: Uint8Array, mainFileBodyChunks: Uint8Array[] = [];
+let mainFileHeader: Uint8Array;
+const mainFileBodyChunks: Uint8Array[] = [];
 const summary = Parser.WriteBlueprintFiles(blueprint, mainFileBinaryBeforeCompressed => {
     console.log('on main file binary data before being compressed.');
 }, header => {
@@ -116,13 +130,35 @@ const summary = Parser.WriteBlueprintFiles(blueprint, mainFileBinaryBeforeCompre
 fs.writeFileSync('./MyModifiedBlueprint.sbp', Buffer.concat([mainFileHeader!, ...mainFileBodyChunks]));
 
 // write .sbpcfg file back to disk, we get that data from the result of WriteBlueprintFiles
-fs.writeFileSync('./MyModifiedSave.sbpcfg', Buffer.from(summary.configFileBinary));
+fs.writeFileSync('./MyModifiedBlueprint.sbpcfg', Buffer.from(summary.configFileBinary));
 ```
 
-## License 
+# Bug Reports or Feedback
+So far this was just a private hobby project. But i figure some people actually use it.
+If you find a bug or have feedback about the parser, you can just hit me up on the satisfactory discord `etothepii`.
+
+# Changelog
+
+### [0.4.15] (2024-10-02)
+#### updated README
+* changelog document doesn't seem linkable, so it is in the readme for now.
+
+### [0.4.14] (2024-10-02)
+#### updated README
+* updated the code examples with more context
+
+### Internal renamings (won't affect you if you stick to the code examples)
+* improved the interface for abstract parser classes
+* extended some error log messages
+* added an additional check when parsing struct property InventoryItem, since ported saves often have a few more bytes.
+* changed function name `writeFloat()` to `writeFloat32()` of the save writer.
+* changed variable name `saveOrBlueprintIndicator` to `objectVersion` for objects, since the meaning of that number became now more clear.
+
+
+# License 
 MIT License
 
-Copyright (c) 2023 etothepii
+Copyright (c) 2024 etothepii
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/build/parser/byte/binary-readable.interface.d.ts

@@ -1,6 +1,5 @@
 import { BinaryOperable } from "./binary-operable.interface";
 export interface BinaryReadable extends BinaryOperable {
-    debug: boolean;
     skipBytes: (count?: number) => void;
     readBytes: (count: number) => Uint8Array;
     readByte: () => number;
@@ -17,6 +16,4 @@ export interface BinaryReadable extends BinaryOperable {
     readDouble: () => number;
     readString: () => string;
     getBufferProgress: () => number;
-    allocate: (count: number) => PromiseLike<void>;
-    getAmountAllocatedLeft: () => number;
 }

package/build/parser/byte/binary-writable.interface.d.ts

@@ -0,0 +1,20 @@
+import { BinaryOperable } from "./binary-operable.interface";
+export interface BinaryWritable extends BinaryOperable {
+    skipBytes: (count?: number) => void;
+    jumpTo(position: number): void;
+    writeByte: (value: number) => void;
+    writeBytes: (bytes: Uint8Array) => void;
+    writeBytesArray: (bytes: number[]) => void;
+    writeInt8: (value: number) => void;
+    writeUint8: (value: number) => void;
+    writeInt16: (value: number) => void;
+    writeUint16: (value: number) => void;
+    writeInt32: (value: number) => void;
+    writeUint32: (value: number) => void;
+    writeInt64: (value: bigint) => void;
+    writeUint64: (value: bigint) => void;
+    writeFloat32: (value: number) => void;
+    writeDouble: (value: number) => void;
+    writeString: (value: string) => void;
+    getBufferProgress: () => number;
+}

package/build/parser/byte/binary-writable.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/parser/byte/byte-reader.class.d.ts

@@ -4,7 +4,6 @@ export declare abstract class ByteReader implements BinaryReadable {
     protected bufferView: DataView;
     protected fileBuffer: ArrayBuffer;
     alignment: Alignment;
-    debug: boolean;
     protected currentByte: number;
     protected handledByte: number;
     protected maxByte: number;
@@ -27,8 +26,6 @@ export declare abstract class ByteReader implements BinaryReadable {
     readFloat32(): number;
     readDouble(): number;
     readString(): string;
-    allocate(count: number): Promise<void>;
-    getAmountAllocatedLeft: () => number;
     getBufferPosition: () => number;
     getBufferSlice: (begin: number, end: number | undefined) => ArrayBuffer;
     getBufferProgress: () => number;

package/build/parser/byte/byte-reader.class.js

@@ -4,11 +4,9 @@ exports.ByteReader = void 0;
 const alignment_enum_1 = require("./alignment.enum");
 class ByteReader {
     constructor(fileBuffer, alignment) {
-        this.debug = false;
         this.currentByte = 0;
         this.handledByte = 0;
         this.maxByte = 0;
-        this.getAmountAllocatedLeft = () => this.bufferView.byteLength - this.currentByte;
         this.getBufferPosition = () => this.currentByte;
         this.getBufferSlice = (begin, end) => this.bufferView.buffer.slice(begin, end);
         this.getBufferProgress = () => this.currentByte / this.bufferView.buffer.byteLength;
@@ -117,11 +115,5 @@ class ByteReader {
             throw error;
         }
     }
-    allocate(count) {
-        if (this.currentByte + count < this.bufferView.byteLength) {
-            console.warn('tried to allocate but there is not enough data left.');
-        }
-        return Promise.resolve();
-    }
 }
 exports.ByteReader = ByteReader;

package/build/parser/byte/byte-writer.class.d.ts

@@ -1,6 +1,7 @@
 import { Alignment } from "./alignment.enum";
-export declare abstract class ByteWriter {
-    protected alignment: Alignment;
+import { BinaryWritable } from './binary-writable.interface';
+export declare abstract class ByteWriter implements BinaryWritable {
+    alignment: Alignment;
     protected bufferArray: ArrayBuffer;
     protected bufferView: DataView;
     protected currentByte: number;
@@ -18,12 +19,14 @@ export declare abstract class ByteWriter {
     writeUint32(value: number): void;
     writeInt64(value: bigint): void;
     writeUint64(value: bigint): void;
-    writeFloat(value: number): void;
+    writeFloat32(value: number): void;
     writeDouble(value: number): void;
     writeString(value: string): void;
     static IsASCIICompatible: (value: string) => boolean;
     getBufferPosition: () => number;
     getBufferSlice: (start: number, end?: number) => ArrayBuffer;
+    getBufferLength: () => number;
+    getBufferProgress: () => number;
     writeBinarySizeFromPosition(lenIndicatorPos: number, start: number): void;
     protected extendBufferIfNeeded(countNeededBytes: number, factor?: number): void;
     protected truncateBuffer(): void;

package/build/parser/byte/byte-writer.class.js

@@ -6,6 +6,8 @@ class ByteWriter {
     constructor(alignment, bufferSize = 500) {
         this.getBufferPosition = () => this.currentByte;
         this.getBufferSlice = (start, end) => this.bufferArray.slice(start, end);
+        this.getBufferLength = () => this.bufferArray.byteLength;
+        this.getBufferProgress = () => this.currentByte / this.bufferArray.byteLength;
         this.alignment = alignment;
         this.bufferArray = new ArrayBuffer(bufferSize);
         this.bufferView = new DataView(this.bufferArray);
@@ -69,7 +71,7 @@ class ByteWriter {
         this.bufferView.setBigUint64(this.currentByte, value, this.alignment === alignment_enum_1.Alignment.LITTLE_ENDIAN);
         this.currentByte += 8;
     }
-    writeFloat(value) {
+    writeFloat32(value) {
         this.extendBufferIfNeeded(4);
         this.bufferView.setFloat32(this.currentByte, value, this.alignment === alignment_enum_1.Alignment.LITTLE_ENDIAN);
         this.currentByte += 4;

package/build/parser/satisfactory/blueprint/blueprint-reader.js

@@ -29,7 +29,7 @@ class BlueprintReader extends byte_reader_class_1.ByteReader {
         let itemTypeCount = reader.readInt32();
         const itemCosts = new Array(itemTypeCount).fill(['', 0]);
         for (let i = 0; i < itemTypeCount; i++) {
-            let indexOrWhat = reader.readInt32();
+            reader.readInt32();
             let itemPathName = reader.readString();
             let itemCount = reader.readInt32();
             itemCosts[i] = [itemPathName, itemCount];
@@ -37,7 +37,7 @@ class BlueprintReader extends byte_reader_class_1.ByteReader {
         let recipeCount = reader.readInt32();
         const recipeRefs = new Array(recipeCount).fill('');
         for (let i = 0; i < recipeCount; i++) {
-            let indexOrWhat = reader.readInt32();
+            reader.readInt32();
             const recipeName = reader.readString();
             recipeRefs[i] = recipeName;
         }
@@ -105,7 +105,7 @@ class BlueprintReader extends byte_reader_class_1.ByteReader {
         level_class_1.Level.ReadObjectHeaders(reader, objects, () => { });
         const someChecksumThing = reader.readInt32();
         BlueprintReader.ReadBlueprintObjectContents(reader, objects, 0);
-        const pos = reader.getBufferPosition();
+        reader.getBufferPosition();
         return objects;
     }
     static ReadBlueprintObjectContents(reader, objectsList, buildVersion) {
@@ -133,14 +133,14 @@ class BlueprintConfigReader extends byte_reader_class_1.ByteReader {
         this.parse = () => BlueprintConfigReader.ParseConfig(this);
     }
     static ParseConfig(reader) {
-        const unk = reader.readInt32();
+        const alwaysTwo = reader.readInt32();
         const description = reader.readString();
-        const unk3 = reader.readInt32();
-        const colorMaybe = util_types_1.col4.ParseRGBA(reader);
+        const iconID = reader.readInt32();
+        const color = util_types_1.col4.ParseRGBA(reader);
         return {
             description,
-            color: colorMaybe,
-            iconID: unk3
+            color,
+            iconID,
         };
     }
 }

package/build/parser/satisfactory/edit/edit-constants.d.ts

@@ -1630,9 +1630,11 @@ export declare const EDIT: {
             };
             readonly POWER_POLE_WALL_MK1: {
                 readonly TYPE_PATH: "/Game/FactoryGame/Buildable/Factory/PowerPoleWall/Build_PowerPoleWall.Build_PowerPoleWall_C";
+                readonly CLASS_NAME: "Build_PowerPoleWall_C";
             };
             readonly POWER_POLE_WALL_MK2: {
                 readonly TYPE_PATH: "/Game/FactoryGame/Buildable/Factory/PowerPoleWall/Build_PowerPoleWall_Mk2.Build_PowerPoleWall_Mk2_C";
+                readonly CLASS_NAME: "Build_PowerPoleWall_Mk2_C";
             };
         };
         readonly POWER_LINE: {