# 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

```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.

---

## Project Structure

```
advchksys/
  src/
    AdvChkSys/
      Chunk/
      Manager/
      Constraints/
      Events/
      Interfaces/
      Resources/
      Serialization/
      Threading/
      Util/
      AdvChkSys.csproj
  bindings/
    python/
    godot/
  tests/
    AdvChkSys.Tests/
  README.md
  LICENSE
```

---

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

---