Add module READMEs, .gitignore, and remove Bin/ from tracking

Add README.md for each library module documenting API, platform
backends, and usage. Add .gitignore for build artifacts. Remove
pre-built binaries from version control.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.gitignore

@@ -0,0 +1,5 @@
+Bin/
+obj/
+*.o
+*.a
+*.bin

ZNet/README.md

@@ -0,0 +1,42 @@
+# ZNet
+
+Event-driven UDP networking library for multiplayer games, built on top of
+libsst-net and enet.
+
+## Architecture
+
+- `ZNetServer` -- listens for connections, manages multiple peers
+- `ZNetClient` -- connects to a single server
+- `ZNetHost` -- shared base class for both
+- `ZNetPeer` -- represents a remote connection
+
+## Packet delivery
+
+Packets are created with `ZNetHost::CreatePacket()` and sent with either
+reliable or transient (fire-and-forget) delivery:
+
+- `ZNET_RELIABLE` -- guaranteed delivery with sequencing and ACK
+- `ZNET_TRANSIENT` -- unreliable, lowest latency
+
+Packets larger than MTU are automatically fragmented and reassembled.
+
+## Events
+
+Poll with `HasEvent()` / `GetNextEvent()`:
+
+| Event | Meaning |
+|---|---|
+| `ZNETEVENT_CONNECT` | Peer connected |
+| `ZNETEVENT_DISCONNECT` | Peer disconnected gracefully |
+| `ZNETEVENT_TIMEOUT` | Peer timed out |
+| `ZNETEVENT_DATA` | Data packet received |
+
+## Features
+
+- Bandwidth throttling (token bucket) via `ZNetBandwidthMeter`
+- Configurable MTU (512 -- 1500 bytes, with IPv4/IPv6 safe defaults)
+- Packet loss simulation for testing (`SetDropChance`)
+- Connection validation callback on server (`ZNetConnectCallback`)
+- Up to 4 listen sockets per server
+- Reference-counted packets
+- `ZNetUtil::ReaderForPacket()` / `WriterForPacket()` for easy serialization

ZTestSuite/README.md

@@ -0,0 +1,44 @@
+# ZTestSuite
+
+Unit test suite covering the libsst and ZUtil libraries.
+
+## Running
+
+```sh
+make ztestsuite
+./ZTestSuite.bin        # interactive menu
+./ZTestSuite.bin -n     # run all tests non-interactively
+./ZTestSuite.bin -r 5   # run test block #5
+./ZTestSuite.bin -c     # print total test count
+```
+
+## Test framework
+
+Custom lightweight framework (`ZUnitTest.hpp`):
+
+```cpp
+static const char* testExample() {
+    TASSERT(1 + 1 == 2, "math is broken");
+    return ZTEST_SUCCESS;
+}
+```
+
+Tests return an error string on failure or `ZTEST_SUCCESS` (empty string)
+on pass.
+
+## Coverage (48 test blocks, 60 test files)
+
+**Math** -- Vec2/3/4 and Mat22/33/44 in float/double/int/unsigned variants,
+geometry, transforms, safe arithmetic, endianness
+
+**Containers** -- ZArray, ZList, ZHashMap, ZRingBuffer, ZBasicString (with
+algorithm suites)
+
+**Memory** -- ZAlloc, ZAllocWindow, ZSlabAllocator, ZReferenceCounter,
+ZSmartPointer, ZWeakPointer
+
+**I/O** -- JSON, XML, INI readers/writers, binary data writer
+
+**Concurrency** -- threads, task streams
+
+**Utilities** -- assertions, ZName, ZRegistry, random generation, simplex noise

ZUtil/README.md

@@ -0,0 +1,45 @@
+# ZUtil
+
+C++ utility library providing RAII wrappers around the libsst C modules, plus
+custom containers, serialization, and logging.
+
+## Memory management
+- `ZAlloc` / `ZAllocWindow` -- tracked allocation with checkpoint support
+- `ZSlabAllocator` -- slab-based allocator
+- `ZSmartPointer<T>` (alias `ZPtr<T>`) -- thread-safe reference-counted smart pointer
+- `ZWeakPointer<T>` -- weak references
+- `ZReferenceCounter`, `ZReferenceBuffer`
+
+## Containers (ZSTL)
+- `ZArray` -- dynamic array with sort/search algorithms
+- `ZList` -- linked list with algorithms
+- `ZHashMap` -- hash table
+- `ZRingBuffer` -- circular buffer
+- `ZBasicString` / `ZString` -- string with algorithms
+- `ZName` -- immutable string with hash-cached comparison
+- `ZKVTree` -- hierarchical key-value tree (path-addressable)
+- `ZRegistry` -- thread-safe key-value store
+
+## Threading
+- `ZThread` -- base class with `run()` override and request marshaling
+- `ZMutex` / `ZLock` -- RAII mutex and scoped lock
+- `ZEvent`, `ZSemaphore`, `ZReadWriteLock` -- RAII sync wrappers
+- `ZTaskStream` -- multi-threaded task execution with `ZFuture<R,A>`
+
+## Serialization
+- `ZBinaryReader` / `ZBinaryWriter` -- abstract binary I/O
+- `ZBinaryBufferReader` / `ZBinaryBufferWriter` -- in-memory binary streams
+- `ZBinaryFileReader` / `ZBinaryFileWriter` -- file-backed binary streams
+- `ZXMLReader` / `ZXMLWriter` -- XML via ZKVTree
+- `ZJSONReader` / `ZJSONWriter` -- JSON via ZKVTree
+- `ZIniReader` / `ZIniWriter` -- INI format
+
+## Logging
+- `ZLog` -- thread-safe, multi-file logging with severity levels
+- Macros: `SystemLogError`, `SystemLogWarning`, `SystemLogInfo`, `SystemLogSpam`
+
+## Utilities
+- `ZRandomGenerator` -- PRNG wrapper with Gaussian support
+- `ZSimplexNoise` / `ZSimplexNoiseMap` -- noise generation
+- `ZAssert` -- debug/runtime assertion macros
+- `ZBitmap` -- bitmap data structure

libsst-atomic/README.md

@@ -0,0 +1,33 @@
+# libsst-atomic
+
+Cross-platform atomic operations implemented in hand-written assembly for
+lock-free programming.
+
+## API
+
+All functions operate on `volatile int*` or `volatile void**`:
+
+- **Add / AddPtr** -- atomic add (with optional return of new value)
+- **And / Or / Xor / Not** -- atomic bitwise ops (with optional return)
+- **Exchange / ExchangePtr** -- swap value, return old
+- **ExchangeAdd / ExchangeAddPtr** -- add, return old value
+- **CAS / CASPtr** -- compare-and-swap, return old value
+- **LoadAcquire / LoadAcquirePtr** -- load with acquire semantics
+- **StoreRelease / StoreReleasePtr** -- store with release semantics
+
+## Architecture support
+
+Each backend is a standalone `.asm` file:
+
+| File | Architecture | ABI |
+|---|---|---|
+| SST_Atomic_x86.asm | x86 (32-bit) | cdecl |
+| SST_Atomic_x86-64.asm | x86-64 | System V |
+| SST_Atomic_x86-64-win64.asm | x86-64 | Microsoft x64 |
+| SST_Atomic_arm.asm | ARMv6+ | ARM EABI |
+| SST_Atomic_ia64.asm | Itanium | IA-64 |
+| SST_Atomic_mips.asm | MIPS32R2+ | o32 |
+| SST_Atomic_mips64.asm | MIPS64R2+ | n64 |
+| SST_Atomic_ppc.asm | PowerPC 32 | SysV |
+| SST_Atomic_sparc.asm | SPARCv9 32 | SPARC |
+| SST_Atomic_sparc64.asm | SPARCv9 64 | SPARC |

libsst-concurrency/README.md

@@ -0,0 +1,30 @@
+# libsst-concurrency
+
+Cross-platform threading and synchronization primitives in C, with C++ RAII
+wrappers in ZUtil.
+
+## Primitives
+
+| Primitive | C API prefix | C++ wrapper |
+|---|---|---|
+| Threads | `SST_Concurrency_*Thread*` | `ZThread` |
+| Mutexes | `SST_Concurrency_*Mutex*` | `ZMutex` / `ZLock` |
+| Events | `SST_Concurrency_*Event*` | `ZEvent` |
+| Semaphores | `SST_Concurrency_*Semaphore*` | `ZSemaphore` |
+| Thread-local storage | `SST_Concurrency_*TLS*` | -- |
+| Read-write locks | `SST_Concurrency_*ReadWrite*` | `ZReadWriteLock` |
+| One-time init | `SST_Concurrency_ExecOnce` | -- |
+| Thread barriers | `SST_Concurrency_*ThreadBarrier*` | -- |
+
+## Platform backends
+
+| Primitive | POSIX | Win32 | Solaris | macOS |
+|---|---|---|---|---|
+| Thread | pthread | `_beginthreadex` | `thr_*` | pthread |
+| Mutex | `pthread_mutex_t` | `CRITICAL_SECTION` | `mutex_t` | pthread |
+| Event | `pthread_cond_t` | `CreateEvent` | `cond_t` | pthread |
+| Semaphore | `sem_t` | `CreateSemaphore` | `sema_t` | Custom (cond+mutex) |
+| TLS | `pthread_key_t` | `TlsAlloc` | `thr_keycreate` | pthread |
+
+Read-write locks and thread barriers use atomic spinlocks on all platforms
+(depends on libsst-atomic).

libsst-crypto/README.md

@@ -0,0 +1,19 @@
+# libsst-crypto
+
+Lightweight string hashing functions for hash tables and name interning.
+
+## Hash functions
+
+| Function | Output | Description |
+|---|---|---|
+| `SST_Crypto_HashDJB2` | 64-bit | djb2 hash variant |
+| `SST_Crypto_HashJ6` | 32-bit | Java 6 String hash |
+| `SST_Crypto_HashJCR2` | 64-bit | Collision-free up to length 8 for ASCII |
+| `SST_Crypto_HashSDBM` | 32-bit | sdbm hash (Berkeley DB) |
+| `SST_Crypto_HashCRC32` | 32-bit | CRC-32C checksum |
+
+All functions take `(const char* string, size_t len)`.
+
+Types: `SST_HashValue32` (`uint32_t`), `SST_HashValue64` (`uint64_t`).
+
+These are non-cryptographic hashes intended for fast lookups, not security.

libsst-glapi/README.md

@@ -0,0 +1,40 @@
+# libsst-glapi
+
+Thread-safe OpenGL 3.3 function loader with per-thread context management.
+
+## Usage
+
+```c
+#include <SST/SST_GLAPI.h>
+
+SST_GLAPI_InitForThread(NULL);  // NULL = platform default library
+
+// Standard GL calls work via macros:
+glClear(GL_COLOR_BUFFER_BIT);
+glDrawArrays(GL_TRIANGLES, 0, 3);
+
+SST_GLAPI_ShutdownForThread();
+```
+
+The macros in `SST_GLAPIMacros.h` dispatch through a thread-local
+`SST_GLAPI` struct containing 334 function pointers.
+
+## API
+
+- `SST_GLAPI_InitForThread(libName)` -- load GL library, resolve all symbols
+- `SST_GLAPI_ShutdownForThread()` -- release resources
+- `SST_GLAPI_GetThreadGLAPI()` -- get current thread's function table
+- `SST_GLAPI_CopyForThread(api)` -- install a custom function table
+
+## Platform backends
+
+| Platform | Library | Symbol resolution |
+|---|---|---|
+| Windows | opengl32.dll | `wglGetProcAddress` + `GetProcAddress` |
+| Linux/POSIX | libGL.so.1 | `glXGetProcAddressARB` |
+| macOS | OpenGL.framework | `dlsym` |
+
+## Code generation
+
+`parsegl.c` reads `gl33.txt` and generates `SST_GLAPIStruct.h`,
+`SST_GLAPIStruct.c`, and `SST_GLAPIMacros.h`.

libsst-math/README.md

@@ -0,0 +1,48 @@
+# libsst-math
+
+Type-generic linear algebra library in C, covering vectors, matrices,
+transforms, and geometric queries.
+
+## Vectors
+
+2D, 3D, and 4D vectors in four numeric types each:
+
+- `SST_Vec{2,3,4}{f,d,i,u}` -- float, double, int, unsigned
+
+Operations: add, subtract, multiply, divide, scale, dot, cross, magnitude,
+normalize, project, lerp, weighted sum, negate, abs, reciprocal, sqrt, rotate,
+min/max component, equality. Most have both output and in-place (`Local`)
+variants.
+
+A generic `SST_VectorNf_*` API handles arbitrary-dimension float vectors.
+
+## Matrices
+
+2x2, 3x3, and 4x4 matrices (column-major):
+
+- `SST_Mat{22,33,44}{f,d,i,u}`
+
+Operations: add, subtract, element-wise multiply, scalar multiply,
+matrix-matrix multiply, matrix-vector multiply, transpose, determinant,
+invert, LU decomposition and solve, orthonormality check.
+
+## Transforms (SST_Transform)
+
+4x4 float transform construction:
+
+- Translation, scale, shear
+- Euler rotation (X/Y/Z), quaternion rotation
+- LookAt / LookDir view matrices
+- Perspective and orthographic projection
+- Chained variants (`*C`) for composing onto existing matrices
+
+## Geometry (SST_Geo)
+
+- 2D/3D line segment intersection
+- Point-to-segment closest point and distance
+- Ray-triangle intersection with barycentric coordinates
+
+## Code generation
+
+`VectorN.py` and `MatrixNxN.py` generate the type-specialized `.c` files
+from templates.

libsst-net/README.md

@@ -0,0 +1,38 @@
+# libsst-net
+
+Cross-platform BSD-style socket abstraction in C.
+
+## API
+
+### Initialization
+- `SST_Net_Init()` / `SST_Net_Shutdown()` -- WinSock init on Windows, no-op on POSIX
+
+### Socket operations
+- `SST_Net_Socket()` -- create socket (TCP or UDP, IPv4 or IPv6)
+- `SST_Net_Bind()`, `SST_Net_Listen()`, `SST_Net_Accept()`, `SST_Net_Connect()`
+- `SST_Net_Send()` / `SST_Net_Recv()` -- stream I/O
+- `SST_Net_SendTo()` / `SST_Net_RecvFrom()` -- datagram I/O
+- `SST_Net_SetNonblock()` -- toggle non-blocking mode
+- `SST_Net_GetSockOpt()` / `SST_Net_SetSockOpt()`
+- `SST_Net_Close()`
+
+### Address management
+- `SST_Net_InitAddress()`, `SST_Net_SetAddressFromString()`
+- `SST_Net_GetAddressFamily()`, `SST_Net_GetAddressPort()`
+- `SST_Net_AddressCompare()`, `SST_Net_AddressIsLocalhost()`
+
+### I/O multiplexing
+- `SST_Net_Select()` -- fd_set-based (via `SST_NetSocketSet`)
+- `SST_Net_Poll()` -- poll-based (via `SST_NetPollDescriptorSet`)
+
+### DNS
+- `SST_Net_GetAddrInfo()` / `SST_Net_FreeAddrInfo()` -- forward lookup
+- `SST_Net_GetNameInfo()` -- reverse lookup
+
+## Platform backends
+
+- **Win32** -- Winsock2, `WSAPoll`, `InetPton`/`InetNtop`
+- **POSIX** -- standard BSD sockets, `poll()`, `inet_pton`/`inet_ntop`
+
+All platform-specific error codes map to a unified `SST_NetResult` enum
+(40+ codes).

libsst-os/README.md

@@ -0,0 +1,49 @@
+# libsst-os
+
+Cross-platform operating system abstractions in C.
+
+## Subsystems
+
+### Memory (`SST_Alloc`, `SST_SysMem`)
+- Aligned allocation/free, safe malloc/realloc with overflow checking
+- Page-level allocation, protection (`R/W/X`), and size queries
+
+### File I/O (`SST_File`)
+- Open, read, write, seek, flush, close
+- Async and sequential/random hints
+
+### File system (`SST_FileSys`)
+- Directory listing, create, remove
+
+### Memory-mapped files (`SST_Mmap`)
+- Create/destroy mappings, sync to disk
+
+### Dynamic libraries (`SST_DynLib`)
+- Load, symbol lookup, close
+- OS-specific name generation (`.dll` / `.so` / `.dylib`)
+
+### CPU info (`SST_CPU`, `SST_CPUCache`)
+- Physical/logical CPU counts, affinity get/set
+- Cache line size, data cache flush, instruction cache invalidate
+- Cache ops in per-architecture assembly (x86, ARM, IA-64, MIPS, PPC, SPARC)
+
+### Timing (`SST_Time`)
+- Microsecond, millisecond, and floating-point second resolution
+
+### Endian (`SST_Endian`)
+- Byte-swap 16/32/64, host-to-BE/LE conversion macros
+
+### User info (`SST_User`)
+- Username, real name, home directory
+
+### Safe arithmetic (`SST_SafeArithmetic`)
+- Overflow-checked add/multiply for all integer widths
+
+### Assertions (`SST_Assert`)
+- Debug and runtime assertion macros with pluggable handlers
+
+## Platform backends
+
+Each subsystem has separate `_Win32.c` and `_POSIX.c` implementations, with
+additional Solaris and macOS variants where needed. CPU cache operations are
+in per-architecture assembly files.

libsst-random/README.md

@@ -0,0 +1,36 @@
+# libsst-random
+
+Pseudorandom number generation and simplex noise in C.
+
+## PRNG algorithms
+
+| Type | Enum | State size |
+|---|---|---|
+| Mersenne Twister | `SST_PRNG_MERSENNE` | 624 x 32-bit |
+| CMWC | `SST_PRNG_CMWC` | 4096 x 32-bit |
+| SmallPRNG | `SST_PRNG_SMALLPRNG` | 4 x 32-bit |
+
+### Generic API
+
+```c
+SST_PRNG rng = SST_Random_CreatePRNGFromSeed(SST_PRNG_MERSENNE, 42);
+float  f = SST_Random_GetPRNGFloat(rng, 0.0f, 1.0f);
+int    i = SST_Random_GetPRNGInt(rng, 0, 100);
+SST_Random_DestroyPRNG(rng);
+```
+
+Each algorithm also has direct-access functions
+(`SST_Random_*SmallPRNG*`, `SST_Random_*CMWC*`).
+Array-fill variants are provided for batch generation.
+
+## Simplex noise
+
+1D through 4D simplex noise, returning values in [-1, 1]:
+
+- `SST_Random_MapSimplexNoise{1,2,3,4}D()`
+- Array variants: `SST_Random_MapSimplexNoise{1,2,3,4}DFromArray()`
+
+## C++ wrappers
+
+- `ZRandomGenerator` -- RAII wrapper with Gaussian distribution support
+- `ZSimplexNoise` -- RAII wrapper with `noise1`/`noise2`/`noise3`/`noise4`

libsst-wm/README.md

@@ -0,0 +1,40 @@
+# libsst-wm
+
+Cross-platform window management, input events, and OpenGL context creation.
+
+## API
+
+### Window management
+- `SST_WM_Init()` / `SST_WM_Shutdown()`
+- `SST_WM_CreateWindowOnScreen()` / `SST_WM_DestroyWindow()`
+- `SST_WM_SetWindowText()`, `SST_WM_GetWindowRect()`, `SST_WM_MoveWindowOnScreen()`, `SST_WM_ResizeWindow()`, `SST_WM_SetWindowState()`
+- `SST_WM_ShowDialogBox()` -- native message dialog
+
+### Display and video modes
+- `SST_WM_CreateDisplayTarget()` / `SST_WM_DestroyDisplayTarget()`
+- `SST_WM_CreateGraphicsEnumerator()` -- enumerate adapters, screens, video modes
+- `SST_WM_SetVideoModeOnScreen()` / `SST_WM_GetVideoModeOnScreen()`
+
+### Events
+- `SST_WM_GetEvent()` -- dequeue next input/window event
+- `SST_WM_SendUserEvent()` -- post custom event
+
+### OpenGL
+- `SST_WM_CreateOpenGLContext()` / `SST_WM_CreateSlaveOpenGLContext()` -- shared contexts for multi-threaded rendering
+- `SST_WM_BindOpenGLContext()`, `SST_WM_SwapOpenGLBuffers()`, `SST_WM_DestroyOpenGLContext()`
+
+### Software rendering
+- `SST_WM_EnableSoftwareRendering()` / `SST_WM_DisableSoftwareRendering()`
+- `SST_WM_LockBackbuffer()` / `SST_WM_UnlockBackbuffer()`
+
+## Platform backends
+
+| Backend | Windowing | GL context | Input |
+|---|---|---|---|
+| Win32 | Win32 API | WGL | Win32 messages |
+| Xlib | X11 | GLX | Xlib / XInput2 |
+| RaspPi | DispmanX | EGL (partial) | -- |
+| macOS | -- | -- | -- (stub) |
+
+Internally uses a driver function-table architecture; each backend registers
+its implementation at init time.