Stan44
e59a909c62
added Max z and min z. 3D chunk manager updated in onevict README updated to include bat build instructs. ChunkMark README updated Versioning updated to reflect current and past changes. Version: 0.1.8
161 lines
3.9 KiB
Markdown
161 lines
3.9 KiB
Markdown
# 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
|
||
```
|
||
|
||
--- |