AdvChkSys/README.md

AdvChkSys

AdvChkSys is a high-performance, extensible chunked world management library for .NET, designed for games, simulations, and voxel engines. It provides efficient memory management, chunk loading/unloading, resource tracking, event hooks, serialization, and optional constraints for 2D and 3D chunk-based worlds.

---

Features

• 2D and 3D Chunk Management
  Efficient, thread-safe managers for 2D and 3D chunks with support for custom data types.

• Memory Efficiency
  LRU caching, array pooling, and all-air chunk singletons minimize memory usage and maximize performance.

• Resource Tracking
  Built-in resource manager tracks allocated chunks and supports diagnostics and pooling.

• Event System
  Thread-safe events for chunk lifecycle: loading, unloading, saving, and more.

• World Constraints
  Optional constraints for world size and loaded chunk limits.

• Serialization
  Fast binary serialization/deserialization for chunk data.

• Async Utilities
  Helpers for running chunk tasks asynchronously.

• Python/.NET Interop
  Python bindings for scripting and integration.

---

Getting Started

Requirements

• .NET Standard 2.1 or later

Building

You can build the project using the included build script or directly with dotnet CLI:

Using build.bat (Windows)

build.bat [options]

Available options:

• --all: Build for all platforms, including benchmarks and NuGet package
• --windows: Build for Windows (default)
• --linux: Build for Linux
• --mac: Build for macOS
• --benchmarks: Build the ChunkMark benchmarking tool
• --nuget: Create a NuGet package
• --docs: Generate documentation
• --debug: Build in Debug configuration (Release is default)

Examples:

# Build for all platforms
build.bat --all

# Build for Windows and Linux
build.bat --windows --linux

# Build benchmarks in debug mode
build.bat --benchmarks --debug

Using dotnet CLI

dotnet build src/AdvChkSys/AdvChkSys.csproj

Basic Usage

using AdvChkSys;
using AdvChkSys.Manager;

// Create a 2D chunk manager
var manager2D = AdvChkSys.AdvChkSys.Create2DManager();

// Create or load a chunk
var chunk = manager2D.LoadOrCreateChunk(0, 0, 32, 32);

// Set a cell value
chunk[0, 0] = 42;

// Unload a chunk
manager2D.UnloadChunk(0, 0);

---

Python Bindings

Python bindings are available in src/bindings/python/.
See src/bindings/python/README.md for usage.

---

Documentation

• API documentation can be generated with DocFX.
• XML documentation is included in the build.

---

License

This project is licensed under the MIT License. See LICENSE for details.

---

Acknowledgments

• Inspired by voxel engines and chunked world systems such as Minecraft.
• Uses DocFX for documentation generation.

---

Contributing

Pull requests and issues are welcome! Please see CONTRIBUTING.md if available, or open an issue to discuss your ideas.

---

System Requirements

• Windows, Linux, or macOS operating system
• .NET 5.0 or higher
• Sufficient memory for the requested benchmark parameters (e.g., 3D benchmark with 1024 chunks of size 384×384×384 would require approximately 54-60 GB of RAM) (e.g., 3D benchmark with 1000 chunks of size 32×32×32 would require approximately 125 MB of RAM)
• Math for 1024 chunks at a size of 384x384x384.

Memory Calculation

For 1024 chunks at a size of 384×384×384:

###Py used for COLORING###
# Calculate cells per chunk
cells_per_chunk = 384 × 384 × 384 = 56,623,104 cells

# Calculate total bytes
total_bytes = cells_per_chunk × 1024 chunks = 57,972,964,416 bytes

# Convert to GB
total_GB = total_bytes / 1024 / 1024 / 1024 = 54.2 GB

# Add 5-20% overhead for metadata, references, and system overhead
final_estimate = 54.2 GB × (1.05 to 1.20) = 56.9 to 65.0 GB

---