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

Namespaces
AdvChkSys
AdvChkSys.Chunk
AdvChkSys.Manager
AdvChkSys.Interfaces
AdvChkSys.Events
AdvChkSys.Resources
AdvChkSys.Constraints
AdvChkSys.Serialization
AdvChkSys.Threading
AdvChkSys.Util
AdvChkSys (Root)
public static class AdvChkSys
Entry point and static facade for the AdvChkSys library.

Properties
string Version
The current version of the AdvChkSys library.
Methods
WorldConstraints CreateDefaultConstraints()
Creates a new WorldConstraints object with default settings.

ChunkManager2D<byte> Create2DManager(WorldConstraints? constraints = null)
Creates a new 2D chunk manager with optional constraints.

ChunkManager3D<byte> Create3DManager(WorldConstraints? constraints = null)
Creates a new 3D chunk manager with optional constraints.

bool SelfTest()
Performs a basic self-test of the AdvChkSys core functionality. Returns true if all core systems are operational.

AdvChkSys.Chunk
public class Chunk2D<T> : IChunk
Represents a 2D chunk of data in the world. Supports all-air singleton for memory efficiency and chunk array pooling.

Constructors
Chunk2D(int x, int y, int width, int height, bool isAllAir = false)
Static Methods
Chunk2D<T> AllAir(int x, int y, int width, int height)
Returns a singleton all-air chunk for the given size and position.
Properties
int X
The chunk's X position in chunk-space coordinates.

int Y
The chunk's Y position in chunk-space coordinates.

int Width
The width of the chunk (in cells/tiles/units).

int Height
The height of the chunk (in cells/tiles/units).

Dictionary<string, object> Metadata
Metadata dictionary for arbitrary chunk information (e.g., biome, tags).

bool IsAllAir
Returns true if this chunk is the all-air singleton.

Indexers
T this[int localX, int localY]
Gets or sets the value at the given local chunk coordinates.
Methods
void Fill(T value)
Fills the chunk with a specified value (no-op for all-air).

T[,]? GetDataArray()
Returns the underlying data array (for pooling).

void ReleaseDataArray()
Releases the data array back to the pool (for chunk manager).

public class Chunk3D<T> : IChunk
Represents a 3D chunk of data in the world. Perspective-agnostic and supports arbitrary data types and metadata.

Constructors
Chunk3D(int x, int y, int z, int width, int height, int depth)
Properties
int X
The chunk's X position in chunk-space coordinates.

int Y
The chunk's Y position in chunk-space coordinates.

int Z
The chunk's Z position in chunk-space coordinates.

int Width
The width of the chunk (in cells/tiles/units).

int Height
The height of the chunk (in cells/tiles/units).

int Depth
The depth of the chunk (in cells/tiles/units).

Dictionary<string, object> Metadata
Metadata dictionary for arbitrary chunk information (e.g., biome, tags).

Indexers
T this[int localX, int localY, int localZ]
Gets or sets the value at the given local chunk coordinates.
Methods
void Fill(T value)
Fills the chunk with a specified value.
AdvChkSys.Manager
public class ChunkManager2D<T> : IChunkManager
Manages 2D chunks in memory. Handles loading, unloading, and access. Uses an LRU cache for memory efficiency.

Constructors
ChunkManager2D(WorldConstraints? constraints = null, int capacity = 4096)
Methods
bool IsChunkLoaded(int x, int y)
Returns true if the chunk at (x, y) is loaded.

Chunk2D<T>? GetChunk(int x, int y)
Gets the chunk at (x, y) if loaded, or null if not.

Chunk2D<T> LoadOrCreateChunk(int x, int y, int width, int height)
Loads or creates a chunk at (x, y) with the given size.

Task<Chunk2D<T>> LoadOrCreateChunkAsync(int x, int y, int width, int height)
Loads or creates a chunk asynchronously.

bool UnloadChunk(int x, int y)
Unloads (removes) the chunk at (x, y) if loaded.

Task<bool> UnloadChunkAsync(int x, int y)
Unloads the chunk asynchronously.

IEnumerable<Chunk2D<T>> GetAllChunks()
Enumerates all loaded chunks.

public class ChunkManager3D<T> : IChunkManager
Manages 3D chunks in memory. Handles loading, unloading, and access.

Constructors
ChunkManager3D(WorldConstraints? constraints = null, int capacity = 4096)
Methods
bool IsChunkLoaded(int x, int y, int z)
Returns true if the chunk at (x, y, z) is loaded.

Chunk3D<T>? GetChunk(int x, int y, int z)
Gets the chunk at (x, y, z) if loaded, or null if not.

Chunk3D<T> LoadOrCreateChunk(int x, int y, int z, int width, int height, int depth)
Loads or creates a chunk at (x, y, z) with the given size.

bool UnloadChunk(int x, int y, int z)
Unloads (removes) the chunk at (x, y, z) if loaded.

IEnumerable<Chunk3D<T>> GetAllChunks()
Enumerates all loaded chunks.

AdvChkSys.Interfaces
public interface IChunk
Represents a generic chunk in the world. Provides basic properties for position, size, and metadata.

Properties
int X { get; }
int Y { get; }
int Width { get; }
int Height { get; }
Dictionary<string, object> Metadata { get; }
public interface IChunkManager
Interface for managing chunks in memory. Provides methods for loading, unloading, and accessing chunks.

Methods
bool IsChunkLoaded(int x, int y)
IChunk? GetChunk(int x, int y)
IChunk LoadOrCreateChunk(int x, int y, int width, int height)
bool UnloadChunk(int x, int y)
IEnumerable<IChunk> GetAllChunks()
AdvChkSys.Events
public static class ChunkEvents
Provides events for chunk lifecycle operations such as loading, unloading, saving, and more. Thread-safe event subscription and invocation.

Events
event Action<IChunk> ChunkLoaded
Occurs when a chunk has been loaded into memory.

event Action<IChunk> ChunkLoading
Occurs when a chunk is about to be loaded into memory.

event Action<IChunk> ChunkUnloading
Occurs when a chunk is about to be unloaded from memory.

event Action<IChunk> ChunkUnloaded
Occurs when a chunk has been unloaded from memory.

event Action<IChunk> ChunkSaving
Occurs when a chunk is about to be saved.

event Action<IChunk> ChunkSaved
Occurs when a chunk has been saved.

Methods
void OnChunkLoading(IChunk chunk)
Raises the ChunkLoading event.

void OnChunkLoaded(IChunk chunk)
Raises the ChunkLoaded event.

void OnChunkUnloading(IChunk chunk)
Raises the ChunkUnloading event.

void OnChunkUnloaded(IChunk chunk)
Raises the ChunkUnloaded event.

void OnChunkSaving(IChunk chunk)
Raises the ChunkSaving event.

void OnChunkSaved(IChunk chunk)
Raises the ChunkSaved event.

AdvChkSys.Resources
public static class ChunkResourceManager
Manages allocation and release of chunk resources in memory. Can be extended to track resource usage, pooling, or implement custom memory strategies.

Methods
void AllocateChunk(IChunk chunk)
Called when a chunk is allocated/loaded into memory. Tracks the chunk and can be extended for pooling or resource limits.

void ReleaseChunk(IChunk chunk)
Called when a chunk is released/unloaded from memory. Removes the chunk from tracking and can be extended for pooling or cleanup.

int AllocatedChunkCount
Gets the current number of allocated chunks.

void Clear()
Clears all tracked chunks (for diagnostics or shutdown).

AdvChkSys.Constraints
public class WorldConstraints
Represents constraints and limits for the chunk world. Can be used to restrict world size, chunk counts, and other resource limits.

Properties
int? MinChunkX
The minimum allowed chunk X coordinate (inclusive).

int? MaxChunkX
The maximum allowed chunk X coordinate (inclusive).

int? MinChunkY
The minimum allowed chunk Y coordinate (inclusive).

int? MaxChunkY
The maximum allowed chunk Y coordinate (inclusive).

int? MaxLoadedChunks
The maximum number of chunks allowed to be loaded in memory at once.

Methods
bool IsWithinBounds(int chunkX, int chunkY)
Checks if the given chunk coordinates are within the allowed world bounds.

bool IsWithinChunkLimit(int loadedChunkCount)
Checks if the current number of loaded chunks is within the allowed limit.

AdvChkSys.Serialization
public static class ChunkSerializer
Provides serialization and deserialization for chunk instances. Supports Chunk2D<T> and Chunk3D<T> with primitive types (e.g., byte, int, float).

Methods
byte[] Serialize2D<T>(Chunk2D<T> chunk) where T : struct
Serializes a Chunk2D<T> to a byte array.

Chunk2D<T> Deserialize2D<T>(byte[] data) where T : struct
Deserializes a Chunk2D<T> from a byte array.

byte[] Serialize3D<T>(Chunk3D<T> chunk) where T : struct
Serializes a Chunk3D<T> to a byte array.

Chunk3D<T> Deserialize3D<T>(byte[] data) where T : struct
Deserializes a Chunk3D<T> from a byte array.

AdvChkSys.Threading
public static class ChunkTaskScheduler
Provides utilities for running chunk-related tasks asynchronously. Supports scheduling, cancellation, and custom task options.

Methods
Task RunAsync(Action action, CancellationToken cancellationToken = default)
Runs the given action asynchronously on the thread pool.

Task<TResult> RunAsync<TResult>(Func<TResult> func, CancellationToken cancellationToken = default)
Runs the given function asynchronously and returns a result.

Task RunAsync(Func<Task> func, CancellationToken cancellationToken = default)
Runs the given asynchronous function.

Task<TResult> RunAsync<TResult>(Func<Task<TResult>> func, CancellationToken cancellationToken = default)
Runs the given asynchronous function and returns a result.

AdvChkSys.Util
public class LRUCache<TKey, TValue> where TKey : notnull
Thread-safe LRU (Least Recently Used) cache. Used for chunk memory management.

Constructors
LRUCache(int capacity)
Methods
bool TryGet(TKey key, out TValue value)
Tries to get a value by key and marks it as recently used.

void Add(TKey key, TValue value, Action<TKey, TValue>? onEvict = null)
Adds a value to the cache, evicting the least recently used if over capacity.

bool Remove(TKey key, out TValue? value)
Removes a value by key.

Properties
IEnumerable<TValue> Values
Enumerates all values in the cache.

int Count
Gets the number of items in the cache.

Python Bindings (src/bindings/python/advchksys.py)
Provides Python access to AdvChkSys via .NET interop.

Functions
get_version()
Returns the AdvChkSys library version.

create_2d_manager(constraints=None)
Creates a 2D chunk manager (byte type).

create_3d_manager(constraints=None)
Creates a 3D chunk manager (byte type).

create_constraints(min_x=None, max_x=None, min_y=None, max_y=None, max_loaded=None)
Creates a WorldConstraints object.

Summary
AdvChkSys provides a modular, high-performance, and extensible API for chunked world management in .NET, with robust support for memory pooling, resource tracking, event hooks, serialization, constraints, and async operations. It is suitable for games, simulations, and any application requiring efficient spatial partitioning and management of large worlds.