# 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)

```bash
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:

```bash
# 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

```bash
dotnet build src/AdvChkSys/AdvChkSys.csproj
```

### Basic Usage

```csharp
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`](src/bindings/python/README.md) for usage.

---

## Documentation

- API documentation can be generated with [DocFX](https://dotnet.github.io/docfx/).
- XML documentation is included in the build.

---

## License

This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

---

## Acknowledgments

- Inspired by voxel engines and chunked world systems such as Minecraft.
- Uses [DocFX](https://dotnet.github.io/docfx/) for documentation generation.

---

## Contributing

Pull requests and issues are welcome! Please see [CONTRIBUTING.md](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:

```python
###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
```

---