Class SaveFileFormat

Namespace

KeenEyes.Serialization

Assembly

KeenEyes.Core.dll

Handles reading and writing .ksave container files.

public static class SaveFileFormat

Inheritance

object

SaveFileFormat

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

The .ksave format is a binary container that stores:

• Header with magic bytes, version, and flags
• Save slot metadata (JSON)
• Compressed world snapshot data
• Optional SHA256 checksum

File structure:

[Header: 16 bytes]
  - Magic: "KSAV" (4 bytes)
  - Version: uint16 (2 bytes)
  - Flags: uint16 (2 bytes)
  - MetadataLength: uint32 (4 bytes)
  - DataLength: uint32 (4 bytes)
[Metadata: variable]
  - JSON-encoded SaveSlotInfo
[Data: variable]
  - Compressed snapshot data
[Checksum: 32 bytes, optional]
  - SHA256 hash of compressed data

Fields

CurrentVersion

Current file format version.

public const ushort CurrentVersion = 1

Field Value

ushort

Extension

Default file extension for save files.

public const string Extension = ".ksave"

Field Value

string

Properties

Magic

Magic bytes identifying .ksave files.

public static ReadOnlySpan<byte> Magic { get; }

Property Value

ReadOnlySpan<byte>

Methods

IsValidFormat(byte[])

Checks if a byte array contains a valid .ksave file header.

public static bool IsValidFormat(byte[] data)

Parameters

data byte[]

The data to check.

Returns

bool

True if the data appears to be a .ksave file.

IsValidFormat(Stream)

Checks if a stream contains a valid .ksave file header.

public static bool IsValidFormat(Stream stream)

Parameters

stream Stream

The stream to check.

Returns

bool

True if the stream appears to be a .ksave file.

Read(byte[], bool)

Reads the complete save file from a byte array.

public static (SaveSlotInfo SlotInfo, byte[] SnapshotData) Read(byte[] data, bool validateChecksum = true)

Parameters

data byte[]

The save file data.

validateChecksum bool

Whether to validate the checksum if present.

Returns

(SaveSlotInfo SlotInfo, byte[] SnapshotData)

A tuple containing the slot info and decompressed snapshot data.

Read(Stream, bool)

Reads the complete save file including snapshot data.

public static (SaveSlotInfo SlotInfo, byte[] SnapshotData) Read(Stream stream, bool validateChecksum = true)

Parameters

stream Stream

The stream to read from.

validateChecksum bool

Whether to validate the checksum if present.

Returns

(SaveSlotInfo SlotInfo, byte[] SnapshotData)

A tuple containing the slot info and decompressed snapshot data.

Exceptions

InvalidDataException

Thrown when the file is invalid or corrupted.

ReadMetadata(byte[])

Reads save slot metadata from a byte array.

public static SaveSlotInfo ReadMetadata(byte[] data)

Parameters

data byte[]

The save file data.

Returns

SaveSlotInfo

The save slot metadata.

ReadMetadata(Stream)

Reads save slot metadata from a stream without loading the full snapshot.

public static SaveSlotInfo ReadMetadata(Stream stream)

Parameters

stream Stream

The stream to read from.

Returns

SaveSlotInfo

The save slot metadata, or null if the file is invalid.

Exceptions

InvalidDataException

Thrown when the file format is invalid.

Validate(byte[])

Validates a save file from a byte array.

public static SaveSlotInfo? Validate(byte[] data)

Parameters

data byte[]

The save file data.

Returns

SaveSlotInfo

The slot info with validation result, or null if completely invalid.

Validate(Stream)

Validates a save file without fully loading the snapshot data.

public static SaveSlotInfo? Validate(Stream stream)

Parameters

stream Stream

The stream to validate.

Returns

SaveSlotInfo

The slot info with validation result, or null if completely invalid.

Write(SaveSlotInfo, byte[], SaveSlotOptions)

Writes a save file to a byte array.

public static byte[] Write(SaveSlotInfo slotInfo, byte[] snapshotData, SaveSlotOptions options)

Parameters

slotInfo SaveSlotInfo

The save slot metadata.

snapshotData byte[]

The world snapshot data.

options SaveSlotOptions

Save options.

Returns

byte[]

The complete save file as a byte array.

Write(Stream, SaveSlotInfo, byte[], SaveSlotOptions)

Writes a save file to a stream.

public static void Write(Stream stream, SaveSlotInfo slotInfo, byte[] snapshotData, SaveSlotOptions options)

Parameters

stream Stream

The stream to write to.

slotInfo SaveSlotInfo

The save slot metadata.

snapshotData byte[]

The world snapshot data (binary or JSON bytes).

options SaveSlotOptions

Save options for compression and checksum settings.

Exceptions

ArgumentNullException

Thrown when any parameter is null.