Here's a thorough breakdown of the **Tiled Perlin Noise** project for your chatbot's knowledge base: --- ## Project Overview **Tiled Perlin Noise** is a real-time procedural terrain/texture visualization tool written in Python. It implements Ken Perlin's gradient noise algorithm with a custom SHA-256-based hashing scheme to enable infinite, seamless, reproducible tiled worlds. The player navigates a 2D viewport and the world streams in around them dynamically. --- ## Architecture The project has two source files and a clean separation of concerns between noise generation and display/engine logic. ### `tile_noise_generator.py` — The Noise Engine This module handles all the math and image generation. Key components: **Hashing for Reproducibility** - A random seed (`ogseed`) is generated once per program run via `random.uniform`. - For every grid point, a string combining the seed and `(x, y)` coordinates is hashed with SHA-256. - A 64-bit slice of the digest is extracted and mapped into one of 8 direction vectors (0–7). This is the exact same lookup-table optimization Ken Perlin used in his reference implementation. - The hash approach means tiles can be unloaded and regenerated identically — it's deterministic for the session's seed. **Gradient Generation (`genGrid` + `genGrad`)** - `genGrid()` builds a `(sqrval+1) x (sqrval+1)` grid of direction indices for a given tile coordinate. - `genGrad()` is the performance-critical path. It uses NumPy `meshgrid` to build vectorized coordinate arrays for all pixels at once, avoiding a Python loop per pixel. - For each pixel it determines which grid cell it falls in, computes relative positions to all 4 corners (top-left, top-right, bottom-left, bottom-right), applies the direction vectors, runs a quintic fade function \(f(t) = 6t^5 - 15t^4 + 10t^3\) for smooth blending (zero first and second derivatives at endpoints), and bilinearly interpolates the four corner contributions. - Output is a grayscale PIL `Image`. **`Tile` Class** Holds all state for a single tile: position `(x, y)`, PIL image, RayLib image object, GPU texture handle, and flags: `intersects` (cursor is on this tile), `renderRange` (within draw distance), `expired` (too far away, should be culled). **`Chunk` Class** — Partially implemented stub for a future disk-persistence layer (saving/loading chunks to disk). Currently unused in practice; tiles are kept in memory and regenerated when revisited. **`PILtoRayLibObj()`** — Converts a PIL image into a RayLib-compatible `Image` struct (grayscale pixel data) for GPU upload. --- ### `display.py` — The Game Engine A classic three-thread game engine architecture: | Thread | Role | |---|---| | **Main thread** | Owns the OpenGL/GPU context. Runs the render loop, loads textures to GPU, draws tiles and HUD. | | **Update thread** | Handles input and tile boundary logic. Runs at a capped 100 TPS with delta-time regulation. | | **Loader threads (×2)** | Worker threads that pull coordinates off a queue and generate tile images asynchronously. | **Render Loop (`main` + `render`)** - Iterates `rendercoordlist` (a `dict` keyed by `(x, y)` tile coordinate). - Expired tiles: unloads their GPU texture and removes them from the dict. - In-range tiles: lazily uploads their image to GPU the first time they're drawn (`load_texture_from_image`), then draws them offset from a calculated center. - Highlights the tile under the cursor with a red border and coordinate label. - Draws a black fixed dot (world origin) and a red dot (player position). **Update Loop** - Delta time is computed in nanoseconds and clamped to prevent spiral-of-death on slow frames. - `inputHandler()` reads WASD for movement (speed scaled by delta time), SHIFT for 2× speed boost, SPACE to toggle small render mode (renders only the current tile — good for debugging). - `checkBounds()` determines which `(x, y)` tile the player is currently on, flags tiles inside the `(3, 2)` render rectangle as active, flags tiles outside the `(7, 6)` outer bounds as expired, and queues new tile coordinates for generation. **Chunk Loading Queue** - A `queue.Queue` (`renderloadqueue`) decouples the update thread (producer) from loader threads (consumers). - A `set` (`renderloadset`) prevents double-queuing the same coordinate while it's pending. - Each loader thread blocks on `queue.get()`, generates the tile with `genChunk()`, converts it to a RayLib image object, and places it in `rendercoordlist`. --- ## Key Technical Decisions & Interesting Details - **SHA-256 for noise hashing** — Unconventional but clever. SHA-256 gives excellent pseudo-randomness with no spatial correlation between nearby coordinates, and is extremely fast in modern hardware. This enables both reproducible seeded worlds and seamless tileable generation. - **NumPy vectorization over loops** — The gradient computation is done entirely in vectorized NumPy ops rather than per-pixel Python loops. Ross noted in the README that `np.vectorize` is not truly parallel (it's still a Python loop internally) and acknowledged a GPU compute shader would be the correct next step. - **GPU texture lifecycle** — Textures are only uploaded to the GPU when first rendered (lazy loading) and are explicitly unloaded when tiles expire, preventing VRAM leaks. - **Delta time movement** — Movement speed is multiplied by frame delta time so the player moves at a consistent pixels-per-second rate regardless of FPS. - **Thread safety** — A `s_print` utility wraps `print` with a `threading.Lock` for thread-safe logging. The `rendercoordlist` dict is shared across threads without an explicit lock (Python's GIL provides partial protection for dict operations, though this is a known caveat). --- ## File Summary | File | Purpose | |---|---| | `tile_noise_generator.py` | Perlin noise math, tile/chunk data structures, image generation | | `display.py` | Game engine: render loop, update loop, input, threading, chunk streaming | | `requirements.txt` | `pillow`, `numpy`, `raylib` (pyray) pinned versions | | `fadefunction.png` | Visualization of the quintic fade curve, referenced in README | | `DEMO.mp4` | Screen recording of the running application | | `README.md` | Project description and algorithm walkthrough | --- ## Controls | Key | Action | |---|---| | WASD | Move viewport | | SHIFT | Speed boost (2×) | | SPACE | Toggle small render mode (single tile only) | --- This should give your chatbot plenty of material to speak accurately about the Perlin noise project — covering the algorithm, architecture, design decisions, and what makes it technically interesting (SHA-256 hashing for tiling, multi-threaded streaming, GPU texture management, etc.).