MauryDev.KoGaMa.Utils 1.0.0

MauryDev.KoGaMa.Utils

A specialized utility library designed for parsing, unpacking, and managing binary data associated with KoGaMa world objects and runtime events. This project focuses on high-performance binary deserialization using a custom Big Endian implementation.

🚀 Technical Specifications

• Framework: .NET 10.0
• Language: C# 14.0
• Architecture: Binary Stream Processing

📁 Project Structure

🛠️ Memory Management (/Memory)

Low-level primitives for handling binary data streams.

• BytePacker: A wrapper around Stream and BinaryReader that ensures data is read in Big Endian format. It includes helper methods for Int32, Int16, Single, Double, and specialized 7-bit encoded integers for strings.
• ByteUnpacker: The counterpart to BytePacker, allowing the creation of binary streams in Big Endian format.

📦 KoGaMa Data Models (/KoGaMaData)

High-level representations of game world entities.

• Handler: The main entry point for deserializing a full data set. It coordinates the reading of prototype data, world objects, links, and runtime events.
• MVWorldObject: Represents an object instance in the world, containing transformation data (Position, Rotation, Scale), IDs, and dynamic RuntimeData stored as HashTables.
• MVPrototypeData & MVCube: Define the geometric blueprints of objects. MVCube includes logic for handling shared corner and material data to optimize space.
• MVLink & MVObjectLink: Manage connections between different world objects.
• IntVector: A lightweight struct for 3D integer coordinates.

⚡ Runtime Event System (/KoGaMaData)

A factory-based system for processing dynamic game events.

• BaseRuntimeEvent: Abstract base class for all events, providing common properties like EventType and Position.
• RuntimeEventFactory: Implements the Factory Pattern to instantiate the correct event class (e.g., ExplosionEvent or SingleCubeFineGrainedEvent) based on a type identifier read from the stream.
• RuntimeEventType & RuntimeEventObjectType: Enums that categorize the vast array of possible game events.

📚 Collections & Extensions (/KoGaMaData/Collections)

Specialized logic for complex data structures.

• BytePackerExtensions: Extends BytePacker to support the reading of complex HashTables and generic arrays. It uses HashtableDataType to determine how to deserialize values dynamically.
• HashtableDataType: Defines the supported types within a binary HashTable (Int32, Single, String, Boolean, Nested HashTables, etc.).

🛠️ Usage Example

Reading World Data

using MauryDev.KoGaMa.Utils.Memory;
using MauryDev.KoGaMa.Utils.KoGaMaData;

// Open the binary stream
using var stream = File.OpenRead("world.dat");
var packer = new BytePacker(stream);
var handler = new Handler(packer);

// Parse all data
handler.Read();

Reading a Custom HashTable

using MauryDev.KoGaMa.Utils.KoGaMaData.Collections;

// Assuming bp is an instance of BytePacker
Dictionary<object, object> data = bp.ReadHashTableFromBytePacker();

📝 Key Implementation Details

• Endianness: The project strictly adheres to Big Endian for numeric types to maintain compatibility with the target data source.
• Memory Efficiency: Uses ReadOnlySpan<byte> in BytePacker to minimize allocations during numeric reads.
• Extensibility: The RuntimeEventFactory allows for easy addition of new event types by adding a new enum member and updating the switch expression.